BlackVue Sync

Synchronizes recordings from a BlackVue dashcam with a local directory over a LAN.

BlackVue dashcams expose an HTTP server that can be used to download all recordings. This project downloads only recordings that are not already downloaded, optionally limiting downloads in a local directory to a date range.

A typical setup would be a periodic cron job or a Docker container running on a local server.

Features

• Portable runtimes:
  • A single, self-contained Python script with no third-party dependencies. It can be copied and run anywhere, either manually or periodically.
  • A docker image that runs periodically via an internal cron job. Supports amd64 (Intel), arm64 (Apple Silicon, Raspberry Pi 4+) and armv7 (Raspberry Pi 2/3).
• Smart: Only downloads recordings that haven't already been downloaded.
• Resilient: If a download interrupts for whatever reason, the script resumes where it left off the next time it runs. This is especially useful for possibly unreliable Wi-Fi connections from a garage.
• Hands-off: Optionally retains recordings for a set amount of time. Outdated recordings are automatically removed.
• Cron-friendly: Only one process is allowed to run at any given time for a specific download destination.
• Safe: Stops executing if the destination disk is almost full.
• Friendly error reporting: Communicates a range of known error conditions with sensible verbosity.

Prerequisites

Software

• Python 3.9+ or Docker.
• Sufficient disk space on a file system local to the script. Plan for about 5GB/hr per camera.
• BlackVue Viewer or a media player to view the recordings.

Hardware

A cloud-enabled BlackVue dashcam must be connected via Wi-Fi to the local network with a static IP address.

The dashcam must be kept powered for some time after the vehicle is turned off. BlackVue offers hardwiring kits and batteries.

The camera should stay active for a period sufficiently long for recordings to be downloaded. Consult the dashcam manual for the bit rate for your chosen image quality, and compare it with the download speed reported by BlackVue Sync.

Example with a DR750S-2CH recording with two cameras at the highest quality setting and a good but conservative download speed:

# dashcam bitrates
dashcam_bitrate_front = 12Mbps
dashcam_bitrate_back = 10Mbps
dashcam_bitrate = dashcam_bitrate_front + dashcam_bitrate_back

download_speed = 20Mbps

# hours on the timer for every hour of recording
ratio = dashcam_bitrate / download_speed => 1.1

Verifying Connectivity

For illustration purposes, all examples assume that the camera is reachable at the dashcam.example.net address. A static numeric IP address works just as well.

A quick way to verify that the dashcam is online is by using curl.

$ curl http://dashcam.example.net/blackvue_vod.cgi
v:1.00
n:/Record/20181026_135003_PF.mp4,s:1000000
n:/Record/20181026_140658_PF.mp4,s:1000000
n:/Record/20181026_140953_PF.mp4,s:1000000
...
$

Another way is by browsing to: http://dashcam.example.net/blackvue_vod.cgi.

Usage

Installation

BlackVue Sync is a single script, and can be obtained in a number of ways:

• uv: Run with uvx blackvuesync <args>, or install with uv tool install blackvuesync and run with blackvuesync <args>.
• Pip: Install with pip install blackvuesync and run with blackvuesync <args>.
• Direct: Download from GitHub, save to the desired location, and either run it with python3 blackvuesync.py <args>, or mark it executable and run it with blackvuesync.py <args>.
• Docker Hub: The Docker image can be pulled with docker pull acolomba/blackvuesync.

The interactive instructions assume a uv or Pip installation.

Manual Usage

The dashcam address is the only required parameter. The --dry-run option makes it so that the script communicates what it would do without actually doing anything. Example:

blackvuesync dashcam.example.net --dry-run

It's also possible to specify a destination directory other than the current directory with --destination:

blackvuesync dashcam.example.net --destination /data/dashcam --dry-run

A retention period can be indicated with the --keep option. Recordings prior to the retention period will be removed from the destination directory. Accepted units are d for days and w for weeks. If no unit is indicated, days are assumed.

blackvuesync dashcam.example.net --destination /data/dashcam --keep 2w --dry-run

A typical invocation would be:

blackvuesync dashcam.example.net --destination /data/dashcam --keep 2w

Other options:

• --grouping: Groups downloaded recordings in directories according to different schemes. Grouping speeds up loading recordings in the BlackVue Viewer app. The supported groupings are:
  • daily: By day, e.g. 2018-10-26;
  • weekly: By week, with the directory indicating the date of that week's monday, e.g. 2018-10-22;
  • monthly: By month, e.g. 2018-10;
  • yearly: By year, e.g. 2018;
  • none: No grouping, the default.
• --priority: Downloads recordings with different priorities: date downloads oldest to newest; rdate downloads newest to oldest; type downloads manual, event (all types), normal and (non-event) parking recordings in that order. Defaults to date.
• --max-used-disk: Downloads stop once the specified used disk percentage threshold is reached. Defaults to 90 (i.e. 90%.)
• --timeout: Sets a timeout for establishing a connection to the dashcam, in seconds. Defaults to 10.0 seconds.
• --retry-failed-after: Sets the minimum elapsed time before retrying a failed download. Accepted units are s for seconds, h for hours, d for days and w for weeks. If no unit is indicated, days are assumed. Defaults to 1d.
• --skip-metadata: Skips downloading metadata file types. Takes a string of characters: t for thumbnail (.thm), 3 for accelerometer (.3gf), g for GPS (.gps). For example, --skip-metadata t3g skips all metadata files, downloading only the .mp4 video recordings.
• --include: Downloads only recordings matching the given codes. Each code is a recording type letter optionally followed by a camera direction letter, comma-separated. For example, --include P,NF downloads all Parking recordings and Normal Front recordings. See the table below for valid codes.
• --exclude: Excludes recordings matching the given codes, same format as --include. Takes priority over --include. For example, --include N,E --exclude NR downloads all Normal and Event recordings except Normal Rear.
• --quiet: Quiets down output messages, except for unexpected errors. Takes precedence over --verbose.
• --verbose: Increases verbosity. Can be specified multiple times to indicate additional verbosity.

Recording type and direction codes

Recording type codes:

| Code | Type | | ---- | ---- | | N | Normal | | E | Event | | P | Parking | | M | Manual | | I | Impact | | O | Overspeed | | A | Acceleration | | T | Cornering | | B | Braking | | R | Geofence (R) | | X | Geofence (X) | | G | Geofence (G) | | D | DMS (D) | | L | DMS (L) | | Y | DMS (Y) | | F | DMS (F) |

Direction codes:

| Code | Direction | | ---- | --------- | | F | Front | | R | Rear | | I | Interior | | O | Optional |

Unattended Usage

Plain cron

The script can run periodically by setting up a cron job on UNIX systems.

Simple example with crontab for a hypothetical media user:

*/15 * * * * /home/media/bin/blackvuesync.py dashcam.example.net --keep 2w --destination /data/dashcam --cron

The --cron option changes the logging level with the assumption that the output may be emailed. When this option