Skip to content

About

This is a python project focused on easy viewing of dashcam video files.

Resources

Readme
GPL-3.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

DashCam Viewer

⚠️ AI-Generated Software Disclaimer

This application was primarily generated using Claude Code, an AI coding assistant by Anthropic.

Background: I needed a tool to view my dashcam footage but lacked the time and skills to properly develop a usable dashcam video viewer from scratch. Instead of struggling through it manually, I turned to AI to accomplish this task and create a reasonably functional viewer.

Important Notes:

  • Even this README file is AI-generated
  • This software may contain bugs, issues, and imperfections
  • Don't expect perfection - this is a functional tool, not production-grade software
  • You are welcome to improve upon it and contribute enhancements
  • Do not expect me to actively maintain or fix issues - use at your own risk

If you need a reliable, well-tested dashcam viewer, consider looking for professionally developed alternatives. If you just need something that works reasonably well for basic viewing, this might do the job.

Overview

A desktop application for viewing dual dashcam footage (front/rear) with synchronized GPS data visualization on an interactive map.

What It Does

DashCam Viewer is designed to work with dashcams that record:

  • Dual video streams (front and rear cameras)
  • GPS metadata embedded in video files
  • Video segments (typically 1-minute clips)

The application provides synchronized playback of both camera views with real-time GPS position tracking on an interactive map.

Features

Core Features

  • Dual Video Playback: Side-by-side synchronized front and rear camera views
  • Fullscreen Mode: Press the fullscreen button on either video to view fullscreen (preserves playback state)
  • GPS Visualization: Real-time GPS position tracking on OpenStreetMap
  • Speed & Direction Display: Shows vehicle speed (MPH) and heading
  • Seamless Navigation: Automatically chains video segments within a trip
  • Trip Detection: Automatically groups videos into trips based on time gaps
  • Timeline Scrubber: Visual timeline for the complete trip

Playback Controls

  • Play/Pause
  • Stop
  • Skip forward/backward (±5 seconds)
  • Next/Previous video segment
  • Variable playback speed (0.25x - 20x)
  • Audio volume control (audio only plays at 1x speed)
  • Timeline seeking
  • Click-and-hold video for temporary 2x speed boost

Map Features

  • OpenStreetMap integration via Leaflet.js
  • Real-time position marker synchronized with video
  • Route path visualization for the entire trip
  • Directional marker showing vehicle heading
  • Auto-zoom to fit route bounds

Visual Overlays

  • Play/Pause indicators
  • Skip forward/backward indicators
  • Speed change indicators with click-and-hold boost (2.00x >>)
  • Dynamic sizing based on window size

Video File Format

The application expects video files with the following naming convention:

YYYY_MMDD_HHMMSS_###A.MP4  (Front camera)
YYYY_MMDD_HHMMSS_###B.MP4  (Rear camera)

Example:

2025_1109_075140_793A.MP4  (Front)
2025_1109_075140_793B.MP4  (Rear)

Files must contain GPS metadata (extractable via ExifTool) including:

  • GPS coordinates (latitude/longitude)
  • GPS speed
  • GPS track (heading/direction)
  • Timestamps

Installation

Windows Installation

Step 1: Install Python

  1. Download Python 3.8 or newer from https://www.python.org/downloads/
  2. Important: During installation, check "Add Python to PATH"
  3. Click "Install Now"
  4. Verify installation by opening Command Prompt and typing: 
    python --version

Step 2: Install ExifTool

  1. Download ExifTool from https://exiftool.org/
    • Get the "Windows Executable" version
  2. Extract the downloaded ZIP file
  3. Rename exiftool(-k).exe to exiftool.exe
  4. Move exiftool.exe and the exiftool_files folder to C:\Windows\System32\ (requires admin privileges) (Or to another location and add the location to your PATH.)
  5. Verify installation by opening Command Prompt and typing: 
    exiftool -ver

Step 3: Download DashCam Viewer

  1. Download this repository:
    • Click the green "Code" button on GitHub
    • Select "Download ZIP"
  2. Extract the ZIP file to a location like C:\DashCamViewer

Step 4: Run the Installation Script

  1. Open the DashCamViewer folder
  2. Double-click install_windows.bat
  3. Wait for the installation to complete
  4. The script will:
    • Create a Python virtual environment
    • Install all required packages
    • Create a desktop shortcut

Step 5: Launch the Application

  • Option 1: Double-click the DashCam Viewer shortcut on your desktop
  • Option 2: Double-click launch_windows.bat in the DashCamViewer folder
  • Option 3: Double-click launch.vbs for a silent launch (no console window)

Linux Installation

Step 1: Install Python

Most Linux distributions come with Python pre-installed. Verify by opening a terminal:

python3 --version

If Python is not installed:

Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip python3-venv

Fedora:

sudo dnf install python3 python3-pip

Arch:

sudo pacman -S python python-pip

Step 2: Install ExifTool

Ubuntu/Debian:

sudo apt update
sudo apt install libimage-exiftool-perl

Fedora:

sudo dnf install perl-Image-ExifTool

Arch:

sudo pacman -S perl-image-exiftool

Verify installation:

exiftool -ver

Step 3: Download DashCam Viewer

Option 1: Using Git

git clone https://github.com/Mourty/DashCamViewer.git
cd DashCamViewer

Option 2: Download ZIP

  1. Download the ZIP from GitHub
  2. Extract it: unzip DashCamViewer-main.zip
  3. Navigate to folder: cd DashCamViewer-main

Step 4: Run the Installation Script

chmod +x install_linux.sh
./install_linux.sh

The script will:

  • Create a Python virtual environment
  • Install all required packages
  • Create a desktop launcher (if on a desktop environment)

Step 5: Launch the Application

Option 1: Use the desktop launcher (if created)

  • Look for "DashCam Viewer" in your application menu

Option 2: Run the launch script

./launch_linux.sh

Option 3: Manual launch

source venv/bin/activate
python src/main.py

Usage

Getting Started

  1. Launch the application using one of the methods above
  2. Click "Select Folder" to choose a directory containing your dashcam videos
  3. The app will automatically:
    • Detect front/rear camera pairs
    • Extract GPS metadata from each video
    • Group videos into trips (based on time gaps)
  4. Select a trip from the list on the left
  5. Use the playback controls to navigate through your footage
  6. Watch the GPS position update in real-time on the map

Keyboard Shortcuts

  • Space: Play/Pause
  • Escape: Exit fullscreen mode

Tips

  • Fullscreen viewing: Double-click any video to enter fullscreen mode
  • Quick 2x boost: Click and hold on video for temporary 2x playback speed
  • Speed control: Use the speed slider for persistent speed changes (0.25x - 20x)
  • Audio sync: Audio only plays at 1x speed; at other speeds, audio will desync
  • Trip navigation: Use Next/Previous buttons to jump between video segments
  • Timeline scrubbing: Drag the timeline slider to jump to any point in the trip

Known Issues

Audio Playback Speed

  • Issue: Audio always plays at 1x speed regardless of video playback speed setting
  • Cause: pygame.mixer doesn't support variable tempo/speed
  • Impact: When using playback speeds other than 1x, audio will desync from video
  • Workaround: Keep playback at 1x speed when audio synchronization is important

General Warnings

  • As mentioned in the disclaimer, this is AI-generated software
  • Expect bugs, edge cases, and occasional unexpected behavior
  • GPS accuracy depends on your dashcam's GPS hardware quality
  • Large video files or long trips may impact performance

Project Structure

DashCamViewer/
├── src/
│   ├── main.py                    # Application entry point
│   ├── gui/                       # GUI components
│   │   ├── main_window.py         # Main application window
│   │   ├── video_player.py        # Single video player widget
│   │   ├── dual_video_player.py   # Dual synchronized video player
│   │   ├── fullscreen_video_widget.py  # Fullscreen view
│   │   ├── audio_player.py        # Audio playback handler
│   │   ├── map_widget.py          # GPS map display (Leaflet.js)
│   │   ├── playback_controls.py   # Playback controls widget
│   │   └── svg_icons.py           # SVG icon definitions
│   └── core/                      # Core business logic
│       ├── models.py              # Data models (GPSPoint, VideoPair, Trip)
│       ├── gps_parser.py          # GPS metadata extraction
│       ├── video_manager.py       # Video file handling
│       ├── trip_detector.py       # Trip segmentation logic
│       └── preferences.py         # User preferences/settings
├── install_windows.bat            # Windows installation script
├── install_linux.sh               # Linux installation script
├── launch_windows.bat             # Windows launcher
├── launch_linux.sh                # Linux launcher
├── launch.vbs                     # Windows silent launcher
├── requirements.txt               # Python dependencies
└── README.md                      # This file (also AI-generated)

Technical Details

Technology Stack

  • GUI Framework: PyQt6
  • Video Playback: OpenCV (cv2) for frame rendering
  • Audio Playback: pygame.mixer with ffmpeg extraction
  • GPS Extraction: PyExifTool (wrapper for ExifTool)
  • Mapping: Leaflet.js 1.9.4 via PyQt6-WebEngine
  • Base Map: OpenStreetMap tile server
  • Data Processing: NumPy, SciPy

GPS Data

  • Speed Units: Converted from km/h to MPH for display
  • Direction: GPS Track (0-360°, 0=North, 90=East, etc.)
  • Update Frequency: Typically 1 Hz (one GPS point per second)

State Management

  • Fullscreen mode uses a VideoPlayerState dataclass to preserve:
    • Play/pause state
    • Current frame position
    • Playback speed
    • Volume level
    • Current trip and segment

Troubleshooting

Application Won't Start

Windows:

  • Ensure Python is in PATH (reinstall Python and check "Add Python to PATH")
  • Try running install_windows.bat again
  • Check that all dependencies installed without errors

Linux:

  • Ensure you have Python 3.8+ installed (python3 --version)
  • Activate the virtual environment: source venv/bin/activate
  • Try reinstalling: ./install_linux.sh

GPS Data Not Showing

  • Verify ExifTool is installed: Run exiftool -ver in terminal/command prompt
  • Ensure your video files contain GPS metadata
  • Check that your video files follow the naming convention

Videos Not Playing

  • Ensure OpenCV is installed properly
  • Check that your video codec is supported (MP4 with H.264 is recommended)
  • Try reinstalling requirements: pip install -r requirements.txt

Audio Issues

  • pygame must be installed for audio playback
  • Audio files are extracted to a temporary location using ffmpeg
  • Ensure ffmpeg is available (usually included with opencv-python)

Contributing

While I (the original creator) may not actively maintain this project, contributions are welcome:

  1. Fork the repository
  2. Create a feature branch
  3. Make your improvements
  4. Submit a pull request

Feel free to:

  • Fix bugs
  • Add new features
  • Improve documentation
  • Optimize performance
  • Add tests

Just don't expect me to review quickly or merge immediately. This is a community-driven project at this point.

License

This is a personal project created with AI assistance. Use at your own risk.

License: GNU General Public License v3.0

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program (see LICENSE file). If not, see https://www.gnu.org/licenses/.

Why GPL v3? This project uses PyQt6, which is licensed under GPL v3. To comply with PyQt6's licensing requirements, this entire project must also be GPL v3. This ensures the software remains free and open source forever.

Acknowledgments

  • Claude Code by Anthropic - for generating most of this codebase
  • OpenStreetMap contributors - for the mapping tiles
  • ExifTool by Phil Harvey - for GPS metadata extraction
  • PyQt6 - for the GUI framework
  • OpenCV - for video processing
  • The open-source community - for all the underlying libraries

Final Notes

Remember: This is AI-generated software created to solve a specific need. It works reasonably well for its intended purpose, but it's not perfect. Use it, improve it, fork it, or ignore it - the choice is yours!

If you find it useful despite its imperfections, great! If not, there are likely more polished alternatives out there.

Happy dashcam viewing! 🚗📹

About

This is a python project focused on easy viewing of dashcam video files.

Resources

Readme
GPL-3.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages