blackvuesync 2.0__py3-none-any.whl

blackvuesync-2.0.dist-info/METADATA

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: blackvuesync
+Version: 2.0
+Summary: Synchronize recordings from BlackVue dashcams to a local directory
+Author-email: Alessandro Colomba <angelo@colomba.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/acolomba/blackvuesync
+Project-URL: Repository, https://github.com/acolomba/blackvuesync
+Project-URL: Issues, https://github.com/acolomba/blackvuesync/issues
+Keywords: blackvue,dashcam,sync,backup
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Topic :: System :: Archiving :: Backup
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: COPYING
+Provides-Extra: dev
+Requires-Dist: behave~=1.2; extra == "dev"
+Requires-Dist: black~=25.11; extra == "dev"
+Requires-Dist: Flask~=3.1; extra == "dev"
+Requires-Dist: mypy~=1.14; extra == "dev"
+Requires-Dist: pre-commit~=4.3; extra == "dev"
+Requires-Dist: PyHamcrest~=2.1; extra == "dev"
+Requires-Dist: pytest~=8.3; extra == "dev"
+Requires-Dist: pytest-cov~=7.0; extra == "dev"
+Requires-Dist: python-lsp-server~=1.14; extra == "dev"
+Requires-Dist: requests~=2.32; extra == "dev"
+Requires-Dist: ruff~=0.9; extra == "dev"
+Dynamic: license-file
+
+# BlackVue Sync
+
+[![CI](https://github.com/acolomba/blackvuesync/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/acolomba/blackvuesync/actions/workflows/ci.yml)
+[![Build Docker image](https://github.com/acolomba/blackvuesync/actions/workflows/docker-build.yml/badge.svg?branch=main)](https://github.com/acolomba/blackvuesync/actions/workflows/docker-build.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=acolomba_blackvuesync&metric=alert_status)](https://sonarcloud.io/summary/overall?id=acolomba_blackvuesync)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=acolomba_blackvuesync&metric=coverage)](https://sonarcloud.io/summary/overall?id=acolomba_blackvuesync)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=acolomba_blackvuesync&metric=bugs)](https://sonarcloud.io/summary/overall?id=acolomba_blackvuesync)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=acolomba_blackvuesync&metric=code_smells)](https://sonarcloud.io/summary/overall?id=acolomba_blackvuesync)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=acolomba_blackvuesync&metric=sqale_rating)](https://sonarcloud.io/summary/overall?id=acolomba_blackvuesync)
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=acolomba_blackvuesync&metric=reliability_rating)](https://sonarcloud.io/summary/overall?id=acolomba_blackvuesync)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=acolomba_blackvuesync&metric=security_rating)](https://sonarcloud.io/summary/overall?id=acolomba_blackvuesync)
+
+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](https://github.com/acolomba/blackvuesync/blob/master/blackvuesync.py) with no third-party dependencies. It can be copied and run anywhere, either [manually](#manual-usage) or [periodically](#unattended-usage).
+  * A [docker image](#docker) 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](https://www.python.org/) 3.9+ or [Docker](https://docs.docker.com/).
+* Sufficient disk space on a file system local to the script. Plan for about 5GB/hr per camera.
+* [BlackVue Viewer](https://blackvue.com/kr/download/) or a media player to view the recordings.
+
+### Hardware
+
+A cloud-enabled [BlackVue](https://www.blackvue.com/) 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](https://blackvue.com/product-tag/battery/) and [batteries](https://blackvue.com/product-tag/battery/).
+
+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:
+
+```calca
+# 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`.
+
+```sh
+$ 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](https://docs.astral.sh/uv/)**: Run with `uvx blackvuesync <args>`, or install with `uv tool install blackvuesync` and run with `blackvuesync <args>`.
+* **[Pip](https://pypi.org/project/pip/):** Install with `pip install blackvuesync` and run with `blackvuesync <args>`.
+* **Direct:** [Download from GitHub](https://raw.githubusercontent.com/acolomba/blackvuesync/refs/heads/main/blackvuesync.py), 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>`.
+
+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:
+
+```sh
+blackvuesync dashcam.example.net --dry-run
+```
+
+It's also possible to specify a destination directory other than the current directory with `--destination`:
+
+```sh
+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.
+
+```sh
+blackvuesync dashcam.example.net --destination /data/dashcam --keep 2w --dry-run
+```
+
+A typical invocation would be:
+
+```sh
+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.
+* `--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.
+
+### Unattended Usage
+
+#### Plain cron
+
+The script can run periodically by setting up a [cron](https://en.wikipedia.org/wiki/Cron) job on UNIX systems.
+
+Simple example with crontab for a hypothetical `media` user:
+
+```crontab
+*/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 is enabled, the script only produces logs when it downloads recordings and when it encounters unexpected errors. One would typically see an email only after driving or when something goes wrong.
+
+Note that if the dashcam is unreachable for whatever reason, in `--cron` mode no output is generated, since this is an expected condition whenever the dashcam is away from the local network.
+
+If cron jobs overlap, the script recognizes that another instance is currently running via a lock file on the destination directory. For the lock to work correctly, the destination directory must be on a local filesystem relative to the script.
+
+#### NAS
+
+Many NAS systems allow running commands periodically at set intervals.
+
+##### openmediavault
+
+The [openmediavault](http://www.openmediavault.org/) NAS solution allows running [scheduled jobs](https://openmediavault.readthedocs.io/en/latest/administration/general/cron.html) with support for mail notifications.
+
+Example:
+
+![openmediavault Scheduled Job](https://raw.githubusercontent.com/acolomba/blackvuesync/master/docs/images/cron-example-openmediavault.png)
+
+#### Docker
+
+##### Overview
+
+The [acolomba/blackvuesync](https://hub.docker.com/r/acolomba/blackvuesync/) docker image sets up a cron job internal to the container that runs the synchronization operation every 15 minutes.
+
+##### Quick Start
+
+It's a good idea to do a single, interactive dry run first with verbose logging:
+
+```sh
+docker run -it --rm \
+    -e ADDRESS=dashcam.example.net \
+    -v $PWD:/recordings \
+    -e DRY_RUN=1 \
+    -e VERBOSE=1 \
+    -e RUN_ONCE=1 \
+    --name blackvuesync \
+acolomba/blackvuesync
+```
+
+Once that works, a typical invocation would be similar to:
+
+```sh
+docker run -d --restart unless-stopped \
+    -v /data/dashcam:/recordings \
+    -e ADDRESS=dashcam.example.net \
+    -e PUID=$(id -u) \
+    -e PGID=$(id -g) \
+    -e TZ="America/New_York" \
+    -e KEEP=2w \
+    --name blackvuesync \
+acolomba/blackvuesync
+```
+
+##### Docker Compose
+
+[Docker Compose](https://docs.docker.com/compose/) may offer an easier, more repeatable and extensible option for running a BlackVueSync Docker container.
+
+After downloading the Docker [Compose file](https://raw.githubusercontent.com/acolomba/blackvuesync/main/docker-compose.yml) and editing its values as desired, BlackVueSync can be started with:
+
+```sh
+docker-compose up -d
+```
+
+OR, depending on the Docker version:
+
+```sh
+docker compose up -d
+```
+
+##### Reference
+
+These options are required for the docker image to operate correctly:
+
+* The `/recordings` volume mapped to the desired destination of the downloaded recordings.
+* The `ADDRESS` parameter set to the dashcam address.
+* The `PUID` and `PGID` parameters set to the desired destination directory's user id and group id.
+* The `TZ` parameter set to the same [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) as the dashcam. Note that BlackVue dashcams do not respect Daylight Savings Time, so their clock needs to be adjusted periodically.
+
+Other parameters:
+
+* `GROUPING`: Groups downloaded recordings in directories, `daily`, `weekly`, `monthly`, `yearly` and `none` are supported. (Default: `none`.)
+* `KEEP`: Sets the retention period of downloaded recordings. Recordings prior to the retention period will be removed from the destination. Accepted units are `d` for days and `w` for weeks. If no unit is indicated, days are assumed. (Default: empty, meaning recordings are kept forever.)
+* `PRIORITY`: Sets the priority to download recordings. Pick `date` to download from oldest to newest; pick `rdate` to download from newset to oldest; pick `type` to download manual, event (all types), normal and (non-event) parking recordings in that order. Defaults to `date`.
+* `MAX_USED_DISK`: If set to a percentage value, stops downloading if the amount of used disk space exceeds the indicated percentage value.  (Default: `90`, i.e. 90%.)
+* `TIMEOUT`: If set to a float value, sets the timeout in seconds for connecting to the dashcam. (Default: `10.0` seconds.)
+* `VERBOSE`: If set to a number greater than zero, increases logging verbosity. (Default: `0`.)
+* `QUIET`: If set to any value, quiets down logs: only unexpected errors will be logged. (Default: empty.)
+* `CRON`: Set by default, makes it so downloads of normal recordings and unexpected error conditions are logged. Can be set to `""` to disable.
+* `DRY_RUN`: If set to any value, makes it so that the script communicates what it would do without actually doing anything. (Default: empty.)
+* `RUN_ONCE`: If set to any value, the docker image runs the sync operation once and exits without setting up the cron job. (Default: empty. Not supported in Docker Compose.)
+
+## License
+
+This project is licensed under the MIT License - see the [COPYING](COPYING) file for details
+
+Copyright 2018-2026 [Alessandro Colomba](https://github.com/acolomba)

blackvuesync-2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+blackvuesync.py,sha256=zuqaM0efaDVDQsdcvLVonq0sPCDW0qN_D19glVJWp88,31505
+blackvuesync-2.0.dist-info/licenses/COPYING,sha256=62rRn5EEnnhpc40RvkeFskxpUXBJa-hhexMdoPhXnl0,1088
+blackvuesync-2.0.dist-info/METADATA,sha256=Y3AJt-nD0aB91HNC60VBoPfV_tTWFGYrg_MbqW3MImQ,14724
+blackvuesync-2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+blackvuesync-2.0.dist-info/entry_points.txt,sha256=N20WR55b3HhumtX8LJDqn8KyoqZib7L6OjcGLBc5IZQ,51
+blackvuesync-2.0.dist-info/top_level.txt,sha256=dCQPIgB4Zz9KRErjB7KU5x_CCq3j62_XKuKXM1VWapA,13
+blackvuesync-2.0.dist-info/RECORD,,

blackvuesync-2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

blackvuesync-2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+blackvuesync = blackvuesync:main

blackvuesync-2.0.dist-info/licenses/COPYING

@@ -0,0 +1,14 @@
+Copyright 2018 Alessandro Colomba (https://github.com/acolomba)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

blackvuesync-2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+blackvuesync

blackvuesync.py

@@ -0,0 +1,912 @@
+#!/usr/bin/env python3
+"""
+Synchronizes recordings from a BlackVue dashcam with a local directory over a LAN.
+https://github.com/acolomba/blackvuesync
+"""
+
+from __future__ import annotations
+
+# Copyright 2018-2026 Alessandro Colomba (https://github.com/acolomba)
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+# documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+# persons to whom the Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+# Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+__version__ = "2.0"
+
+import argparse
+import datetime
+import errno
+import fcntl
+import glob
+import http.client
+import logging
+import os
+import re
+import shutil
+import socket
+import stat
+import sys
+import time
+import urllib
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass
+
+# logging
+logging.basicConfig(format="%(asctime)s: %(levelname)s %(message)s")
+
+# root logger
+logger = logging.getLogger()
+
+# cron logger (remains active in cron mode)
+cron_logger = logging.getLogger("cron")
+
+
+def set_logging_levels(verbosity: int, is_cron_mode: bool) -> None:
+    """sets up the logging levels according to the desired verbosity and operation mode"""
+    if verbosity == -1:
+        logger.setLevel(logging.ERROR)
+        cron_logger.setLevel(logging.ERROR)
+    elif verbosity == 0:
+        logger.setLevel(logging.ERROR if is_cron_mode else logging.WARN)
+        cron_logger.setLevel(logging.INFO if is_cron_mode else logging.WARN)
+    elif verbosity == 1:
+        logger.setLevel(logging.INFO)
+        cron_logger.setLevel(logging.INFO)
+    else:
+        logger.setLevel(logging.DEBUG)
+        cron_logger.setLevel(logging.DEBUG)
+
+
+def flush_logs() -> None:
+    """flushes all logging handlers"""
+    for handler in logging.root.handlers:
+        handler.flush()
+
+
+# max disk usage percent
+max_disk_used_percent = None
+
+# socket timeout
+socket_timeout = None
+
+# indicator that we're doing a dry run
+dry_run = None
+
+# session key reserved for test isolation
+session_key: str | None = None
+
+# keep and cutoff date; only recordings from this date on are downloaded and kept
+keep_re = re.compile(r"""(?P<range>\d+)(?P<unit>[dw]?)""")
+cutoff_date: datetime.date | None = None
+
+# errno codes for unavailable dashcam
+dashcam_unavailable_errno_codes = (
+    errno.EHOSTDOWN,  # host is down
+    errno.EHOSTUNREACH,  # host is unreachable
+    errno.ENETUNREACH,  # network is unreachable
+    errno.ETIMEDOUT,  # connection timed out
+)
+
+# for unit testing
+today = datetime.date.today()
+
+
+def calc_cutoff_date(keep: str) -> datetime.date:
+    """given a retention period, calculates the date before which files should be deleted"""
+
+    if (keep_match := re.fullmatch(keep_re, keep)) is None:
+        raise RuntimeError("KEEP must be in the format <number>[dw]")
+
+    keep_range = int(keep_match.group("range"))
+
+    if keep_range < 1:
+        raise RuntimeError("KEEP must be greater than one.")
+
+    keep_unit = keep_match.group("unit") or "d"
+
+    if keep_unit == "d" or keep_unit is None:
+        keep_range_timedelta = datetime.timedelta(days=keep_range)
+    elif keep_unit == "w":
+        keep_range_timedelta = datetime.timedelta(weeks=keep_range)
+    else:
+        # this indicates a coding error
+        raise RuntimeError(f"unknown KEEP unit : {keep_unit}")
+
+    return today - keep_range_timedelta
+
+
+@dataclass(frozen=True)
+class Recording:
+    """represents a recording from the dashcam; the dashcam serves the list of video recording filenames (front and rear)"""
+
+    filename: str
+    base_filename: str
+    group_name: str | None
+    datetime: datetime.datetime
+    type: str
+    direction: str
+
+
+# dashcam recording filename regular expression
+#
+# references:
+# - https://support.blackvue.com.au/hc/en-us/articles/13301776266895-Video-File-Naming
+# N: Normal
+# E: Event
+# P: Parking motion detection
+# M: Manual
+# I: Parking impact
+# O: Overspeed
+# A: Hard acceleration
+# T: Hard cornering
+# B: Hard braking
+# R: Geofence-enter (Fleet)
+# X: Geofence-exit (Fleet)
+# G: Geofence-pass (Fleet)
+# D: Drowsiness (DMS)
+# L: Distraction (DMS)
+# Y: Seatbelt not detected (DMS)
+# F: Driver undetected (DMS)
+#
+# F: Front camera
+# R: Rear camera
+# I: Interior camera
+# O: Optional camera
+#
+# L or S: upload flag, Substream or Live
+filename_re = re.compile(
+    r"""(?P<base_filename>(?P<year>\d\d\d\d)(?P<month>\d\d)(?P<day>\d\d)
+    _(?P<hour>\d\d)(?P<minute>\d\d)(?P<second>\d\d))
+    _(?P<type>[NEPMIOATBRXGDLYF])
+    (?P<direction>[FRIO])
+    (?P<upload>[LS]?)
+    \.(?P<extension>mp4)""",
+    re.VERBOSE,
+)
+
+
+def to_recording(filename: str, grouping: str) -> Recording | None:
+    """extracts recording information from a filename"""
+    if (filename_match := re.fullmatch(filename_re, filename)) is None:
+        return None
+
+    year = int(filename_match.group("year"))
+    month = int(filename_match.group("month"))
+    day = int(filename_match.group("day"))
+    hour = int(filename_match.group("hour"))
+    minute = int(filename_match.group("minute"))
+    second = int(filename_match.group("second"))
+    recording_datetime = datetime.datetime(year, month, day, hour, minute, second)
+
+    recording_base_filename = filename_match.group("base_filename")
+    recording_group_name = get_group_name(recording_datetime, grouping)
+    recording_type = filename_match.group("type")
+    recording_direction = filename_match.group("direction")
+
+    return Recording(
+        filename,
+        recording_base_filename,
+        recording_group_name,
+        recording_datetime,
+        recording_type,
+        recording_direction,
+    )
+
+
+# pattern of a recording filename as returned in each line from from the dashcam index page
+file_line_re = re.compile(r"n:/Record/(?P<filename>.*\.mp4),s:1000000\r\n")
+
+
+def get_filenames(file_lines: list[str]) -> list[str]:
+    """extracts the recording filenames from the lines returned by the dashcam index page"""
+    filenames = []
+    for file_line in file_lines:
+        # the first line is "v:1.00", which won't match, so we skip it
+        if file_line_match := re.fullmatch(file_line_re, file_line):
+            filenames.append(file_line_match.group("filename"))
+
+    return filenames
+
+
+def get_dashcam_filenames(base_url: str) -> list[str]:
+    """gets the recording filenames from the dashcam"""
+    try:
+        url = urllib.parse.urljoin(base_url, "blackvue_vod.cgi")
+        request = urllib.request.Request(url)
+        if session_key:
+            request.add_header("X-Session-Key", session_key)
+
+        response = urllib.request.urlopen(request)
+
+        response_status_code = response.getcode()
+        if response_status_code != 200:
+            raise RuntimeError(
+                f"Error response from : {base_url} ; status code : {response_status_code}"
+            )
+
+        charset = response.info().get_param("charset", "UTF-8")
+        file_lines = [x.decode(charset) for x in response.readlines()]
+
+        return get_filenames(file_lines)
+    except urllib.error.URLError as e:
+        if isinstance(e.reason, OSError) and (
+            isinstance(e.reason, TimeoutError)
+            or e.reason.errno in dashcam_unavailable_errno_codes
+        ):
+            raise UserWarning(f"Dashcam unavailable : {e}") from e
+
+        raise RuntimeError(
+            f"Cannot obtain list of recordings from dashcam at address : {base_url}; error : {e}"
+        ) from e
+    except socket.timeout as e:
+        raise UserWarning(
+            f"Timeout communicating with dashcam at address : {base_url}; error : {e}"
+        ) from e
+    except http.client.RemoteDisconnected as e:
+        raise UserWarning(
+            f"Dashcam disconnected without a response; address : {base_url}; error : {e}"
+        ) from e
+
+
+def get_group_name(recording_datetime: datetime.datetime, grouping: str) -> str | None:
+    """determines the group name for a given recording according to the indicated grouping"""
+    if grouping == "daily":
+        return recording_datetime.date().isoformat()
+
+    if grouping == "weekly":
+        recording_date = recording_datetime.date()
+
+        # day of the week (mon = 0, ..., sun = 6)
+        recording_weekday = recording_date.weekday()
+        recording_weekday_delta = datetime.timedelta(days=recording_weekday)
+        recording_mon_date = recording_date - recording_weekday_delta
+        return recording_mon_date.isoformat()
+
+    if grouping == "monthly":
+        return recording_datetime.date().strftime("%Y-%m")
+
+    if grouping == "yearly":
+        return recording_datetime.date().strftime("%Y")
+
+    return None
+
+
+# download speed units for conversion to a natural representation
+speed_units = [(1000000, "Mbps"), (1000, "Kbps"), (1, "bps")]
+
+
+def to_natural_speed(speed_bps: int) -> tuple[int, str]:
+    """returns a natural representation of a given download speed in bps as an scalar+unit tuple (base 10)"""
+    for speed_unit_multiplier, speed_unit_name in speed_units:
+        if speed_bps > speed_unit_multiplier:
+            return int(speed_bps / speed_unit_multiplier), speed_unit_name
+
+    return 0, "bps"
+
+
+def format_natural_speed(speed_bps: int | None) -> str:
+    """formats download speed in bps as a human-readable string like ' (123Mbps)', or empty string if None"""
+    if not speed_bps:
+        return ""
+
+    speed_value, speed_unit = to_natural_speed(speed_bps)
+    return f" ({speed_value}{speed_unit})"
+
+
+def get_filepath(destination: str, group_name: str | None, filename: str) -> str:
+    """constructs a path for a recording file from the destination, group name and filename (or glob pattern)"""
+    if group_name:
+        return os.path.join(destination, group_name, filename)
+    return os.path.join(destination, filename)
+
+
+def download_file(
+    base_url: str, filename: str, destination: str, group_name: str | None
+) -> tuple[bool, int | None]:
+    """downloads a file from the dashcam to the destination directory; returns whether data was transferred"""
+    # if we have a group name, we may not have ensured it exists yet
+    if group_name:
+        group_filepath = os.path.join(destination, group_name)
+        ensure_destination(group_filepath)
+
+    destination_filepath = get_filepath(destination, group_name, filename)
+
+    if os.path.exists(destination_filepath):
+        logger.debug("Ignoring already downloaded file : %s", filename)
+        return False, None
+
+    temp_filepath = os.path.join(destination, f".{filename}")
+    if os.path.exists(temp_filepath):
+        logger.debug("Found incomplete download : %s", temp_filepath)
+
+    if dry_run:
+        logger.debug("DRY RUN Would download file : %s", filename)
+        return True, None
+
+    try:
+        url = urllib.parse.urljoin(base_url, f"Record/{filename}")
+
+        start = time.perf_counter()
+        try:
+            # request
+            request = urllib.request.Request(url)
+            if session_key:
+                request.add_header("X-Session-Key", session_key)
+
+            # downloads file
+            with urllib.request.urlopen(request) as response:
+                headers = response.info()
+                size = headers.get("Content-Length")
+
+                # writes response to temp file
+                with open(temp_filepath, "wb") as f:
+                    f.write(response.read())
+        finally:
+            end = time.perf_counter()
+            elapsed_s = end - start
+
+        os.rename(temp_filepath, destination_filepath)
+
+        speed_bps = int(10.0 * float(size) / elapsed_s) if size else None
+        speed_str = format_natural_speed(speed_bps)
+        logger.debug("Downloaded file : %s%s", filename, speed_str)
+
+        return True, speed_bps
+    except urllib.error.URLError as e:
+        # data corruption may lead to error status codes; logs a warning (cron) and returns normally
+        cron_logger.warning(
+            "Could not download file : %s; error : %s; ignoring.", filename, e
+        )
+        return False, None
+    except socket.timeout as e:
+        raise UserWarning(
+            f"Timeout communicating with dashcam at address : {base_url}; error : {e}"
+        ) from e
+
+
+def download_recording(base_url: str, recording: Recording, destination: str) -> None:
+    """downloads the set of recordings, including gps data, for the given filename from the dashcam to the destination
+    directory"""
+    # first checks that we have enough room left
+    disk_usage = shutil.disk_usage(destination)
+    disk_used_percent = disk_usage.used / disk_usage.total * 100.0
+
+    if max_disk_used_percent is not None and disk_used_percent > max_disk_used_percent:
+        raise RuntimeError(
+            f"Not enough disk space left. Max used disk space percentage allowed : {max_disk_used_percent}%"
+        )
+
+    # whether any file of a recording (video, thumbnail, gps, accel.) was downloaded
+    any_downloaded = False
+
+    # downloads the video recording
+    filename = recording.filename
+    downloaded, speed_bps = download_file(
+        base_url, filename, destination, recording.group_name
+    )
+    any_downloaded |= downloaded
+
+    # downloads the thumbnail file
+    thm_filename = (
+        f"{recording.base_filename}_{recording.type}{recording.direction}.thm"
+    )
+    downloaded, _ = download_file(
+        base_url, thm_filename, destination, recording.group_name
+    )
+    any_downloaded |= downloaded
+
+    # downloads the accelerometer data
+    tgf_filename = f"{recording.base_filename}_{recording.type}.3gf"
+    downloaded, _ = download_file(
+        base_url, tgf_filename, destination, recording.group_name
+    )
+    any_downloaded |= downloaded
+
+    # downloads the gps data
+    gps_filename = f"{recording.base_filename}_{recording.type}.gps"
+    downloaded, _ = download_file(
+        base_url, gps_filename, destination, recording.group_name
+    )
+    any_downloaded |= downloaded
+
+    # logs if any part of a recording was downloaded (or would have been)
+    if any_downloaded:
+        # recording logger, depends on type of recording
+        recording_logger = cron_logger if recording.type in ("N", "M") else logger
+
+        if not dry_run:
+            speed_str = format_natural_speed(speed_bps)
+            recording_logger.info(
+                "Downloaded recording : %s (%s%s)%s",
+                recording.base_filename,
+                recording.type,
+                recording.direction,
+                speed_str,
+            )
+        else:
+            recording_logger.info(
+                "DRY RUN Would download recording : %s (%s%s)",
+                recording.base_filename,
+                recording.type,
+                recording.direction,
+            )
+
+
+def sort_recordings(recordings: list[Recording], recording_priority: str) -> None:
+    """sorts recordings in place according to the given priority"""
+
+    # preferred orderings (by type and direction)
+    recording_types = "MEIBOATRXGNP"
+    recording_directions = "FRIO"
+
+    # tomorrow, for reverse datetime sorting
+    tomorrow = datetime.datetime.now() + datetime.timedelta(days=1)
+
+    def datetime_sort_key(recording: Recording) -> tuple[datetime.datetime, int]:
+        """sorts by datetime, then front/rear direction, then recording type"""
+        return recording.datetime, recording_directions.find(recording.direction)
+
+    def rev_datetime_sort_key(recording: Recording) -> tuple[datetime.timedelta, int]:
+        """sorts by newest to oldest datetime, then front/rear/interior direction"""
+        return tomorrow - recording.datetime, recording_directions.find(
+            recording.direction
+        )
+
+    def manual_event_sort_key(
+        recording: Recording,
+    ) -> tuple[int, datetime.datetime, int]:
+        """sorts by recording type (manual and events first), then datetime, then front/rear/interior direction"""
+        return (
+            recording_types.find(recording.type),
+            recording.datetime,
+            recording_directions.find(recording.direction),
+        )
+
+    sort_key: Callable[[Recording], tuple[object, ...]]
+    if recording_priority == "date":
+        # least recent first
+        sort_key = datetime_sort_key
+    elif recording_priority == "rdate":
+        # most recent first
+        sort_key = rev_datetime_sort_key
+    elif recording_priority == "type":
+        # manual, event, normal, parking
+        sort_key = manual_event_sort_key
+    else:
+        # this indicates a coding error
+        raise RuntimeError(f"unknown recording priority : {recording_priority}")
+
+    recordings.sort(key=sort_key)
+
+
+# group name globs, keyed by grouping
+group_name_globs = {
+    "none": None,
+    "daily": "[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]",
+    "weekly": "[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]",
+    "monthly": "[0-9][0-9][0-9][0-9]-[0-9][0-9]",
+    "yearly": "[0-9][0-9][0-9][0-9]",
+}
+
+
+# represents a recording downloaded to the destination; matches all files (video front/rear, gps, etc.)
+@dataclass(frozen=True)
+class DownloadedRecording:
+    base_filename: str
+    group_name: str | None
+    datetime: datetime.datetime
+
+
+# downloaded recording filename regular expression
+downloaded_filename_re = re.compile(
+    r"""^(?P<base_filename>(?P<year>\d\d\d\d)(?P<month>\d\d)(?P<day>\d\d)
+    _(?P<hour>\d\d)(?P<minute>\d\d)(?P<second>\d\d))_""",
+    re.VERBOSE,
+)
+
+
+def to_downloaded_recording(filename: str, grouping: str) -> DownloadedRecording | None:
+    """extracts destination recording information from a filename"""
+    if (filename_match := re.match(downloaded_filename_re, filename)) is None:
+        return None
+
+    year = int(filename_match.group("year"))
+    month = int(filename_match.group("month"))
+    day = int(filename_match.group("day"))
+    hour = int(filename_match.group("hour"))
+    minute = int(filename_match.group("minute"))
+    second = int(filename_match.group("second"))
+    recording_datetime = datetime.datetime(year, month, day, hour, minute, second)
+
+    recording_base_filename = filename_match.group("base_filename")
+    recording_group_name = get_group_name(recording_datetime, grouping)
+
+    return DownloadedRecording(
+        recording_base_filename, recording_group_name, recording_datetime
+    )
+
+
+# downloaded recording filename glob pattern
+downloaded_filename_glob = (
+    "[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]_[0-9][0-9][0-9][0-9][0-9][0-9]_*.*"
+)
+
+
+def get_downloaded_recordings(
+    destination: str, grouping: str
+) -> set[DownloadedRecording]:
+    """reads files from the destination directory and returns them as recording records"""
+    group_name_glob = group_name_globs[grouping]
+
+    downloaded_filepath_glob = get_filepath(
+        destination, group_name_glob, downloaded_filename_glob
+    )
+
+    downloaded_filepaths = glob.glob(downloaded_filepath_glob)
+
+    return {
+        r
+        for p in downloaded_filepaths
+        if (r := to_downloaded_recording(os.path.basename(p), grouping)) is not None
+    }
+
+
+def get_outdated_recordings(
+    destination: str, grouping: str
+) -> list[DownloadedRecording]:
+    """returns the recordings prior to the cutoff date"""
+    if cutoff_date is None:
+        return []
+
+    downloaded_recordings = get_downloaded_recordings(destination, grouping)
+
+    return [x for x in downloaded_recordings if x.datetime.date() < cutoff_date]
+
+
+def get_current_recordings(recordings: list[Recording]) -> list[Recording]:
+    """returns the recordings that are after or on the cutoff date"""
+    return (
+        recordings
+        if cutoff_date is None
+        else [x for x in recordings if x.datetime.date() >= cutoff_date]
+    )
+
+
+def get_filtered_recordings(
+    recordings: list[Recording], recording_filter: tuple[str, ...] | None
+) -> list[Recording]:
+    """returns recordings filtered by recording_filter"""
+    return (
+        recordings
+        if recording_filter is None
+        else [x for x in recordings if f"{x.type}{x.direction}" in recording_filter]
+    )
+
+
+def ensure_destination(destination: str) -> None:
+    """ensures the destination directory exists, creates if not, verifies it's writeable"""
+    # if no destination, creates it
+    if not os.path.exists(destination):
+        os.makedirs(destination)
+        return
+
+    # destination exists, tests if directory
+    if not os.path.isdir(destination):
+        raise RuntimeError(f"download destination is not a directory : {destination}")
+
+    # destination is a directory, tests if writable
+    if not os.access(destination, os.W_OK):
+        raise RuntimeError(
+            f"download destination directory not writable : {destination}"
+        )
+
+
+def prepare_destination(destination: str, grouping: str) -> None:
+    """prepares the destination, ensuring it's valid and removing excess recordings"""
+    # optionally removes outdated recordings
+    if cutoff_date:
+        outdated_recordings = get_outdated_recordings(destination, grouping)
+
+        for outdated_recording in outdated_recordings:
+            if dry_run:
+                logger.info(
+                    "DRY RUN Would remove outdated recording : %s",
+                    outdated_recording.base_filename,
+                )
+                continue
+
+            logger.info(
+                "Removing outdated recording : %s", outdated_recording.base_filename
+            )
+
+            outdated_recording_glob = (
+                f"{outdated_recording.base_filename}_[NEPMIOATBRXGDLYF]*.*"
+            )
+            outdated_filepath_glob = get_filepath(
+                destination, outdated_recording.group_name, outdated_recording_glob
+            )
+
+            outdated_filepaths = glob.glob(outdated_filepath_glob)
+
+            for outdated_filepath in outdated_filepaths:
+                os.remove(outdated_filepath)
+
+
+def sync(
+    address: str,
+    destination: str,
+    grouping: str,
+    download_priority: str,
+    recording_filter: tuple[str, ...] | None,
+) -> None:
+    """synchronizes the recordings at the dashcam address with the destination directory"""
+    prepare_destination(destination, grouping)
+
+    base_url = f"http://{address}"
+    dashcam_filenames = get_dashcam_filenames(base_url)
+    dashcam_recordings = [
+        r for x in dashcam_filenames if (r := to_recording(x, grouping)) is not None
+    ]
+
+    # figures out which recordings are current and should be downloaded
+    current_dashcam_recordings = get_current_recordings(dashcam_recordings)
+
+    # filters recordings according to recording_filter tuple
+    current_dashcam_recordings = get_filtered_recordings(
+        current_dashcam_recordings, recording_filter
+    )
+
+    # sorts the dashcam recordings so we download them according to some priority
+    sort_recordings(current_dashcam_recordings, download_priority)
+
+    for recording in current_dashcam_recordings:
+        download_recording(base_url, recording, destination)
+
+
+def is_empty_directory(dirpath: str) -> bool:
+    """tests if a directory is empty, ignoring anything that's not a video recording"""
+    return all(not x.endswith(".mp4") for x in os.listdir(dirpath))
+
+
+# temp filename regular expression
+temp_filename_glob = ".[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]_[0-9][0-9][0-9][0-9][0-9][0-9]_[NEPMIOATBRXGDLYF]*.*"
+
+
+def clean_destination(destination: str, grouping: str) -> None:
+    """removes temporary artifacts from the destination directory"""
+    # removes temporary files from interrupted downloads
+    temp_filepath_glob = os.path.join(destination, temp_filename_glob)
+    temp_filepaths = glob.glob(temp_filepath_glob)
+
+    for temp_filepath in temp_filepaths:
+        if not dry_run:
+            logger.debug("Removing temporary file : %s", temp_filepath)
+            os.remove(temp_filepath)
+        else:
+            logger.debug("DRY RUN Would remove temporary file : %s", temp_filepath)
+
+    # removes empty grouping directories; ignores dotfiles such as .DS_Store
+    group_name_glob = group_name_globs[grouping]
+    if group_name_glob:
+        group_filepath_glob = os.path.join(destination, group_name_glob)
+
+        group_filepaths = glob.glob(group_filepath_glob)
+
+        for group_filepath in group_filepaths:
+            if is_empty_directory(group_filepath):
+                if not dry_run:
+                    logger.debug("Removing grouping directory : %s", group_filepath)
+                    shutil.rmtree(group_filepath)
+                else:
+                    logger.debug(
+                        "DRY RUN Would remove grouping directory : %s", group_filepath
+                    )
+
+
+def lock(destination: str) -> int:
+    """creates a lock to ensure only one instance is running on a given destination; adapted from:
+    https://stackoverflow.com/questions/220525/ensure-a-single-instance-of-an-application-in-linux
+    """
+    # Establish lock file settings
+    lf_path = os.path.join(destination, ".blackvuesync.lock")
+    lf_flags = os.O_WRONLY | os.O_CREAT
+    lf_mode = stat.S_IWUSR | stat.S_IWGRP | stat.S_IWOTH  # This is 0o222, i.e. 146
+
+    # Create lock file
+    # Regarding umask, see https://stackoverflow.com/a/15015748/832230
+    umask_original = os.umask(0)
+
+    try:
+        lf_fd = os.open(lf_path, lf_flags, lf_mode)
+    finally:
+        os.umask(umask_original)
+
+    try:
+        fcntl.lockf(lf_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+        return lf_fd
+    except OSError as e:
+        raise UserWarning(
+            f"Another instance is already running for destination : {destination}"
+        ) from e
+
+
+def unlock(lf_fd: int) -> None:
+    """unlocks the lock file; does not remove because another process may lock it in the meantime"""
+    fcntl.lockf(lf_fd, fcntl.LOCK_UN)
+
+
+def parse_args() -> argparse.Namespace:
+    """parses the command-line arguments"""
+    arg_parser = argparse.ArgumentParser(
+        description="Synchronizes BlackVue dashcam recordings with a local directory.",
+        epilog="Bug reports: https://github.com/acolomba/BlackVueSync",
+    )
+    arg_parser.add_argument(
+        "address", metavar="ADDRESS", help="dashcam IP address or name"
+    )
+    arg_parser.add_argument(
+        "-d",
+        "--destination",
+        metavar="DEST",
+        help="sets the destination directory to DEST; defaults to the current directory",
+    )
+    arg_parser.add_argument(
+        "-g",
+        "--grouping",
+        metavar="GROUPING",
+        default="none",
+        choices=["none", "daily", "weekly", "monthly", "yearly"],
+        help="groups recording by day, week, month or year under a directory named after the date; so respectively 2019-06-15, 2019-06-09 (Mon), 2019-07 or 2019; defaults to none, indicating no grouping",
+    )
+    arg_parser.add_argument(
+        "-k",
+        "--keep",
+        metavar="KEEP_RANGE",
+        help="""keeps recordings in the given range, removing the rest; defaults to days, but can suffix with d, w for days or weeks respectively""",
+    )
+    arg_parser.add_argument(
+        "-p",
+        "--priority",
+        metavar="DOWNLOAD_PRIORITY",
+        default="date",
+        choices=["date", "rdate", "type"],
+        help="sets the recording download priority; date: downloads in chronological order from oldest to newest; rdate: downloads in chronological order from newest to oldest; type: prioritizes manual, event, normal and then parkingrecordings; defaults to date",
+    )
+    arg_parser.add_argument(
+        "-f",
+        "--filter",
+        default=None,
+        help="downloads recordings filtered by event type and camera direction; e.g.: --filter PF PR downloads only Parking Front and Parking Rear recordings",
+        nargs="+",
+    )
+    arg_parser.add_argument(
+        "-u",
+        "--max-used-disk",
+        metavar="DISK_USAGE_PERCENT",
+        default=90,
+        type=int,
+        choices=range(5, 99),
+        help="stops downloading recordings if disk is over DISK_USAGE_PERCENT used; defaults to 90",
+    )
+    arg_parser.add_argument(
+        "-t",
+        "--timeout",
+        metavar="TIMEOUT",
+        default=10.0,
+        type=float,
+        help="sets the connection timeout in seconds (float); defaults to 10.0 seconds",
+    )
+    arg_parser.add_argument(
+        "-v", "--verbose", action="count", default=0, help="increases verbosity"
+    )
+    arg_parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="quiets down output messages; overrides verbosity options",
+    )
+    arg_parser.add_argument(
+        "--cron",
+        action="store_true",
+        help="cron mode, only logs normal recordings at default verbosity",
+    )
+    arg_parser.add_argument(
+        "--dry-run", action="store_true", help="shows what the program would do"
+    )
+    arg_parser.add_argument(
+        "--session-key",
+        metavar="SESSION_KEY",
+        help="session key; reserved for test isolation",
+    )
+    arg_parser.add_argument(
+        "--version",
+        action="version",
+        default=__version__,
+        version=f"%(prog)s {__version__}",
+        help="shows the version and exits",
+    )
+
+    return arg_parser.parse_args()
+
+
+def main() -> int:
+    """run forrest run"""
+    # dry-run is a global setting
+    global dry_run
+    global max_disk_used_percent
+    global cutoff_date
+    global socket_timeout
+    global session_key
+
+    args = parse_args()
+
+    dry_run = args.dry_run
+    session_key = args.session_key
+    if dry_run:
+        logger.info("DRY RUN No action will be taken.")
+
+    max_disk_used_percent = args.max_used_disk
+
+    set_logging_levels(-1 if args.quiet else args.verbose, args.cron)
+
+    # sets socket timeout
+    socket_timeout = args.timeout
+    if socket_timeout <= 0:
+        raise argparse.ArgumentTypeError("TIMEOUT must be greater than zero.")
+    socket.setdefaulttimeout(socket_timeout)
+
+    # lock file file descriptor
+    lf_fd = None
+
+    try:
+        if args.keep:
+            cutoff_date = calc_cutoff_date(args.keep)
+            logger.info("Recording cutoff date : %s", cutoff_date)
+
+        # prepares the local file destination
+        destination = args.destination or os.getcwd()
+        ensure_destination(destination)
+
+        # grouping
+        grouping = args.grouping
+
+        lf_fd = lock(destination)
+
+        try:
+            sync(args.address, destination, grouping, args.priority, args.filter)
+        finally:
+            # removes temporary files (if we synced successfully, these are temp files from lost recordings)
+            clean_destination(destination, grouping)
+    except UserWarning as e:
+        logger.warning(e.args[0])
+        return 0 if args.cron else 1
+    except RuntimeError as e:
+        logger.error(e.args[0])
+        return 2
+    except Exception as e:
+        logger.exception(e)
+        return 3
+    finally:
+        if lf_fd:
+            unlock(lf_fd)
+
+        flush_logs()
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())