hive-video 0.1.0__tar.gz

hive_video-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Local Python environments and caches
+.venv/
+__pycache__/
+*.py[cod]
+.ipynb_checkpoints/
+
+# Local configuration and stop files
+.env
+.env.*
+.safeword
+
+# OS/editor noise
+.DS_Store
+
+# Slurm opens these scheduler logs before a worker can verify its Git revision.
+slurm.*.out
+slurm.*.err
+
+# Large generated pipeline outputs.
+#
+# Ignore raw source data by default. Keep only the named small seed sample.
+data/raw/**
+!data/raw/
+!data/raw/.gitkeep
+
+# Always keep our pet sample video.
+!data/raw/start04_sample_5s.mp4
+
+data/qc/**
+!data/qc/
+!data/qc/.gitkeep
+!data/qc/README.md
+
+data/artifacts/**
+!data/artifacts/
+!data/artifacts/.gitkeep
+!data/artifacts/README.md
+
+data/experiments/*
+
+# Always keep our pet experiment
+!data/experiments/experiment_example_5s/
+
+# A no-sync folder
+data/no-sync/**
+
+# Local distribution staging output
+distribution-1/

hive_video-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Peter Dresslar
+Copyright (c) 2026 Collective Logic Lab, School of Complex Adaptive Systems, Arizona State University
+
+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.

hive_video-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: hive-video
+Version: 0.1.0
+Summary: Portable download, resequencing, and fragment tools for honey bee hive video.
+Project-URL: Documentation, https://github.com/Collective-Logic-Lab/honeybee-hive-video/blob/main/docs/agent-generated/package-interface.md
+Project-URL: Source, https://github.com/Collective-Logic-Lab/honeybee-hive-video
+Project-URL: Issues, https://github.com/Collective-Logic-Lab/honeybee-hive-video/issues
+Project-URL: Releases, https://github.com/Collective-Logic-Lab/honeybee-hive-video/releases
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: certifi>=2026.4.22
+Requires-Dist: filelock>=3.20
+Requires-Dist: portable-ffmpeg==0.3.0
+Provides-Extra: resequence
+Requires-Dist: numpy>=1.26; extra == 'resequence'
+Requires-Dist: opencv-python>=4.13.0.92; extra == 'resequence'
+Requires-Dist: pillow>=12.2.0; extra == 'resequence'
+Description-Content-Type: text/markdown
+
+# Hive Video Tools
+
+`hive-video` provides command-line tools and Python APIs for downloading, resequencing, and extracting fragments from honey bee hive videos. It is part of the [Collective Logic Lab's honeybee-hive-video project](https://github.com/Collective-Logic-Lab/honeybee-hive-video).
+
+- `download` selects a recording from the Edmond 2019 honey bee video archive, resumes partial transfers, and verifies the archive MD5 checksum.
+- `fragment` extracts a PNG frame or an MP4 clip from a local video and writes a JSON sidecar with provenance and an output checksum.
+- `resequence` provides individual reconstruction, inspection, quality-control, and rendering stages. Its dependencies are optional.
+
+Version 0.1.0 is the first public package release. These tools have been used in research; the packaged API is still evolving. During 0.x, incompatible interface changes receive a minor version increment and release notes. Retain a dependency lockfile for reproducible work.
+
+## Install
+
+Use Python 3.12 or newer. To install the command-line tools with `uv`:
+
+```bash
+uv tool install hive-video
+hive-video --help
+```
+
+To include resequencing support, install with the optional extra:
+
+```bash
+uv tool install 'hive-video[resequence]'
+```
+
+FFmpeg and ffprobe are resolved automatically. The tools use an explicitly configured pair or a complete pair on `PATH`; otherwise, the included provider downloads and caches platform-specific builds from the FFmpeg 8 family. Prepare them before offline work with:
+
+```bash
+hive-video setup-ffmpeg
+```
+
+This reports their executable paths, versions, and checksums. Help and archive downloading do not need FFmpeg.
+
+## Extract a fragment
+
+Given a local `source.mp4`, extract its first 25 frames:
+
+```bash
+hive-video fragment --video source.mp4 --start-frame 0 --duration-frames 25 --out clip.mp4
+```
+
+Omit the duration and use a `.png` output to extract one frame. Existing output files are refused. The bee progress display can be changed with `--progress plain` or disabled with `--progress off`.
+
+## Use from Python
+
+Add the library to the project that will import it:
+
+```bash
+uv add hive-video
+```
+
+Use `uv add 'hive-video[resequence]'` if you also need resequencing. Then download a recording and extract a clip:
+
+```python
+from pathlib import Path
+
+from hive_video.download import download_video
+from hive_video.fragment import create_fragment
+
+my_dir = Path("data/day22")
+source = download_video(day=22, side=0, panel="top", target=my_dir)
+clip = create_fragment(source, my_dir / "clip.mp4", start=0, duration=30, unit="seconds")
+print(clip)
+```
+
+`day=22` selects the archive's sequential `start22` capture identifier; the filename gives its calendar timestamp. Downloading retrieves the entire source recording, which can be tens of gigabytes. Seconds use the source's nominal frame clock. See the [package interface guide](https://github.com/Collective-Logic-Lab/honeybee-hive-video/blob/main/docs/agent-generated/package-interface.md) for selectors, transfer settings, progress callbacks, and fragment conventions.
+
+## Resequencing and scientific scope
+
+Resequencing is computationally expensive and includes human inspection and join quality control. Follow the [stage workflow](https://github.com/Collective-Logic-Lab/honeybee-hive-video/blob/main/docs/agent-generated/resequencing.md) and [methods record](https://github.com/Collective-Logic-Lab/honeybee-hive-video/blob/main/docs/agent-generated/METHODS.md). Reconstruction does not independently establish absolute recording chronology or validate a biological interpretation.
+
+This distribution contains the reusable video tools. Internal analyses, experimental recipes, Slurm launchers, and research data remain in the source project.
+
+The package source is MIT licensed. FFmpeg executables are supplied separately by the selected system installation or binary provider.

hive_video-0.1.0/docs/agent-generated/package-readme.md

@@ -0,0 +1,74 @@
+# Hive Video Tools
+
+`hive-video` provides command-line tools and Python APIs for downloading, resequencing, and extracting fragments from honey bee hive videos. It is part of the [Collective Logic Lab's honeybee-hive-video project](https://github.com/Collective-Logic-Lab/honeybee-hive-video).
+
+- `download` selects a recording from the Edmond 2019 honey bee video archive, resumes partial transfers, and verifies the archive MD5 checksum.
+- `fragment` extracts a PNG frame or an MP4 clip from a local video and writes a JSON sidecar with provenance and an output checksum.
+- `resequence` provides individual reconstruction, inspection, quality-control, and rendering stages. Its dependencies are optional.
+
+Version 0.1.0 is the first public package release. These tools have been used in research; the packaged API is still evolving. During 0.x, incompatible interface changes receive a minor version increment and release notes. Retain a dependency lockfile for reproducible work.
+
+## Install
+
+Use Python 3.12 or newer. To install the command-line tools with `uv`:
+
+```bash
+uv tool install hive-video
+hive-video --help
+```
+
+To include resequencing support, install with the optional extra:
+
+```bash
+uv tool install 'hive-video[resequence]'
+```
+
+FFmpeg and ffprobe are resolved automatically. The tools use an explicitly configured pair or a complete pair on `PATH`; otherwise, the included provider downloads and caches platform-specific builds from the FFmpeg 8 family. Prepare them before offline work with:
+
+```bash
+hive-video setup-ffmpeg
+```
+
+This reports their executable paths, versions, and checksums. Help and archive downloading do not need FFmpeg.
+
+## Extract a fragment
+
+Given a local `source.mp4`, extract its first 25 frames:
+
+```bash
+hive-video fragment --video source.mp4 --start-frame 0 --duration-frames 25 --out clip.mp4
+```
+
+Omit the duration and use a `.png` output to extract one frame. Existing output files are refused. The bee progress display can be changed with `--progress plain` or disabled with `--progress off`.
+
+## Use from Python
+
+Add the library to the project that will import it:
+
+```bash
+uv add hive-video
+```
+
+Use `uv add 'hive-video[resequence]'` if you also need resequencing. Then download a recording and extract a clip:
+
+```python
+from pathlib import Path
+
+from hive_video.download import download_video
+from hive_video.fragment import create_fragment
+
+my_dir = Path("data/day22")
+source = download_video(day=22, side=0, panel="top", target=my_dir)
+clip = create_fragment(source, my_dir / "clip.mp4", start=0, duration=30, unit="seconds")
+print(clip)
+```
+
+`day=22` selects the archive's sequential `start22` capture identifier; the filename gives its calendar timestamp. Downloading retrieves the entire source recording, which can be tens of gigabytes. Seconds use the source's nominal frame clock. See the [package interface guide](https://github.com/Collective-Logic-Lab/honeybee-hive-video/blob/main/docs/agent-generated/package-interface.md) for selectors, transfer settings, progress callbacks, and fragment conventions.
+
+## Resequencing and scientific scope
+
+Resequencing is computationally expensive and includes human inspection and join quality control. Follow the [stage workflow](https://github.com/Collective-Logic-Lab/honeybee-hive-video/blob/main/docs/agent-generated/resequencing.md) and [methods record](https://github.com/Collective-Logic-Lab/honeybee-hive-video/blob/main/docs/agent-generated/METHODS.md). Reconstruction does not independently establish absolute recording chronology or validate a biological interpretation.
+
+This distribution contains the reusable video tools. Internal analyses, experimental recipes, Slurm launchers, and research data remain in the source project.
+
+The package source is MIT licensed. FFmpeg executables are supplied separately by the selected system installation or binary provider.

hive_video-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "hive-video"
+version = "0.1.0"
+description = "Portable download, resequencing, and fragment tools for honey bee hive video."
+readme = "docs/agent-generated/package-readme.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["certifi>=2026.4.22", "filelock>=3.20", "portable-ffmpeg==0.3.0"]
+
+[project.urls]
+Documentation = "https://github.com/Collective-Logic-Lab/honeybee-hive-video/blob/main/docs/agent-generated/package-interface.md"
+Source = "https://github.com/Collective-Logic-Lab/honeybee-hive-video"
+Issues = "https://github.com/Collective-Logic-Lab/honeybee-hive-video/issues"
+Releases = "https://github.com/Collective-Logic-Lab/honeybee-hive-video/releases"
+
+[project.optional-dependencies]
+resequence = [
+    "numpy>=1.26",
+    "opencv-python>=4.13.0.92",
+    "pillow>=12.2.0",
+]
+
+[project.scripts]
+hive-video = "hive_video.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hive_video"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["pyproject.toml", "LICENSE", "docs/agent-generated/package-readme.md", "src/hive_video"]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.5",
+]
+research = [
+    "certifi>=2026.4.22",
+    "hf>=1.14.0",
+    "ipykernel>=6.29",
+    "jupyterlab>=4.2",
+    "matplotlib>=3.8",
+    "numpy>=1.26",
+    "opencv-python>=4.13.0.92",
+    "pandas>=2.2",
+    "pillow>=12.2.0",
+    "scikit-learn>=1.5",
+    "scipy>=1.13",
+    "seaborn>=0.13",
+]
+
+[tool.uv]
+default-groups = ["dev", "research"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # Pyflakes
+    "I",    # isort (import sorting)
+    "NPY",  # NumPy-specific rules
+]
+ignore = [
+    "E501", # Do not enforce line length (supports unwrapped prose in comments/docstrings)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"notebooks/**" = ["F401", "F841"]
+"experiments/**" = ["E402"]

hive_video-0.1.0/src/hive_video/__init__.py

@@ -0,0 +1,3 @@
+"""Portable tools for working with honey bee hive videos."""
+
+__version__ = "0.1.0"

hive_video-0.1.0/src/hive_video/__main__.py

@@ -0,0 +1,6 @@
+"""Run the hive-video command with ``python -m hive_video``."""
+
+from hive_video.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hive_video-0.1.0/src/hive_video/_binaries.py

@@ -0,0 +1,108 @@
+"""Resolve the FFmpeg pair without changing PATH; see method HV-P002."""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from functools import lru_cache
+from pathlib import Path
+
+_NAMES = ("ffmpeg", "ffprobe")
+_OVERRIDES = ("HIVE_VIDEO_FFMPEG", "HIVE_VIDEO_FFPROBE")
+
+
+def _executable(value: str | Path, name: str) -> str:
+    path = Path(value).expanduser()
+    if not path.is_absolute():
+        raise ValueError(f"{name} must name an absolute executable path, got {value!r}")
+    if not path.is_file():
+        raise FileNotFoundError(f"{name} executable is missing or not a file: {path}")
+    if not os.access(path, os.X_OK):
+        raise PermissionError(f"{name} is not executable: {path}")
+    return str(path.resolve())
+
+
+@lru_cache(maxsize=1)
+def _managed_binaries() -> tuple[str, str]:
+    # Only request a native build on explicitly supported platforms.
+    machine = platform.machine().lower()
+    supported = {
+        "darwin": {"arm64", "aarch64", "x86_64", "amd64"},
+        "linux": {"arm64", "aarch64", "x86_64", "amd64"},
+        "win32": {"x86_64", "amd64"},
+    }
+    if machine not in supported.get(sys.platform, set()):
+        raise RuntimeError(
+            f"Managed FFmpeg is unsupported on {sys.platform}/{machine}; "
+            "set HIVE_VIDEO_FFMPEG and HIVE_VIDEO_FFPROBE to a compatible executable pair."
+        )
+    # Lazy import keeps help and archive downloads independent of provisioning.
+    from filelock import FileLock
+    from portable_ffmpeg import FFmpegVersions, core, get_ffmpeg
+
+    # The provider reports download progress to stdout. Keep CLI stdout usable
+    # for the output path or JSON and surface provisioning on stderr instead.
+    # The provider has a thread lock; serialize preparation across processes too.
+    # A timeout fails rather than breaking another process's installation lock.
+    with FileLock(str(core.CACHE_DIR.parent / "hive-video.lock"), timeout=60):
+        with contextlib.redirect_stdout(sys.stderr):
+            paths = get_ffmpeg(version=FFmpegVersions.V8)
+    return tuple(_executable(path, name) for name, path in zip(_NAMES, paths, strict=True))
+
+
+def _resolve_pair() -> tuple[str, str]:
+    explicit = tuple(os.environ.get(name) for name in _OVERRIDES)
+    if any(value is not None for value in explicit):
+        if not all(explicit):
+            raise ValueError(
+                "Set both HIVE_VIDEO_FFMPEG and HIVE_VIDEO_FFPROBE to absolute executable paths."
+            )
+        return tuple(
+            _executable(value, name) for name, value in zip(_OVERRIDES, explicit, strict=True)
+        )
+
+    found = tuple(shutil.which(name) for name in _NAMES)
+    if all(found):
+        return tuple(
+            _executable(Path(path).absolute(), name)
+            for name, path in zip(_NAMES, found, strict=True)
+        )
+    if "SLURM_JOB_ID" in os.environ:
+        raise RuntimeError(
+            "FFmpeg and ffprobe are unavailable in this Slurm task. Prepare them before "
+            "submission and set HIVE_VIDEO_FFMPEG and HIVE_VIDEO_FFPROBE to their absolute paths."
+        )
+    return _managed_binaries()
+
+
+def resolve_binary(name: str) -> str:
+    """Return one executable from the selected pair, provisioning it if needed."""
+    if name not in _NAMES:
+        raise ValueError(f"Expected 'ffmpeg' or 'ffprobe', got {name!r}")
+    return _resolve_pair()[_NAMES.index(name)]
+
+
+def setup_ffmpeg() -> dict[str, dict[str, str]]:
+    """Prepare and inspect both executables before offline or parallel work."""
+    result = {}
+    for name, executable in zip(_NAMES, _resolve_pair(), strict=True):
+        completed = subprocess.run(
+            [executable, "-version"], capture_output=True, text=True, check=False
+        )
+        if completed.returncode:
+            raise RuntimeError(
+                f"{name} version check failed (exit {completed.returncode}) for {executable}: "
+                f"{completed.stderr.strip()[-4000:]}"
+            )
+        lines = completed.stdout.splitlines()
+        if not lines or not lines[0].startswith(f"{name} version "):
+            raise RuntimeError(f"Unexpected {name} version output from {executable}: {lines!r}")
+        with Path(executable).open("rb") as handle:
+            checksum = hashlib.file_digest(handle, "sha256").hexdigest()
+        result[name] = {"path": executable, "version": lines[0], "sha256": checksum}
+    return result

hive_video-0.1.0/src/hive_video/cli.py

@@ -0,0 +1,151 @@
+"""Command-line entry point for portable hive-video utilities."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from .fragment import create_fragment
+from .progress import BeeProgress
+from .sources import fragment_filename, resolve_source
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="hive-video",
+        description="Local, reproducible utilities for honey bee hive video.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    fragment = commands.add_parser(
+        "fragment",
+        help="Extract a frame as PNG or an interval as MP4.",
+        description=(
+            "Extract a frame or interval from a local video using FFmpeg and ffprobe. "
+            "Frame indices are zero-based. Seconds use the nominal frame clock n/fps "
+            "and select [ceil(start * fps), ceil((start + duration) * fps)); a still "
+            "selects ceil(start * fps). Omitted or zero duration writes one PNG. "
+            "Every output receives a JSON provenance sidecar; existing files are refused."
+        ),
+    )
+    sources = fragment.add_mutually_exclusive_group(required=True)
+    sources.add_argument("--video", type=Path, help="Explicit local source video path.")
+    sources.add_argument(
+        "--locator", help="Archive shorthand such as start4_side0_top; requires --data-dir."
+    )
+    fragment.add_argument(
+        "--data-dir",
+        type=Path,
+        help="Explicit local search root for --locator; multiple matching copies are an error.",
+    )
+    start = fragment.add_mutually_exclusive_group(required=True)
+    start.add_argument("--start-seconds", metavar="DECIMAL", help="Non-negative start in seconds.")
+    start.add_argument(
+        "--start-frame", type=int, metavar="INT", help="Zero-based start frame index."
+    )
+    duration = fragment.add_mutually_exclusive_group()
+    duration.add_argument("--duration-seconds", metavar="DECIMAL", help="Duration in seconds.")
+    duration.add_argument("--duration-frames", type=int, metavar="INT", help="Number of frames.")
+    destination = fragment.add_mutually_exclusive_group()
+    destination.add_argument("--out", type=Path, help="Explicit .png or .mp4 output path.")
+    destination.add_argument(
+        "--out-dir",
+        type=Path,
+        help="Directory for a generated filename (default: ./data/artifacts/fragments).",
+    )
+    fragment.add_argument(
+        "--threads", type=int, default=1, help="FFmpeg thread limit (default: 1)."
+    )
+    fragment.add_argument(
+        "--progress",
+        choices=("auto", "plain", "off"),
+        default="auto",
+        help="Progress on stderr: animated on terminals, plain in logs, or off (default: auto).",
+    )
+    commands.add_parser("download", add_help=False, help="Resolve and download archive videos.")
+    commands.add_parser(
+        "resequence", add_help=False, help="Run individual reconstruction and review stages."
+    )
+    commands.add_parser(
+        "setup-ffmpeg",
+        help="Prepare FFmpeg and ffprobe for media operations, including offline work.",
+        description=(
+            "Resolve or download FFmpeg and ffprobe, verify both executables, and print "
+            "their paths, versions, and SHA-256 checksums as JSON. Provider progress goes "
+            "to stderr. Help does not download binaries."
+        ),
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    # Each tool owns its argument contract. Dispatch before parsing so stage
+    # help and all existing downloader flags reach their own parsers intact.
+    try:
+        if arguments and arguments[0] == "setup-ffmpeg":
+            build_parser().parse_args(arguments)
+            from ._binaries import setup_ffmpeg
+
+            print(json.dumps(setup_ffmpeg(), indent=2))
+            return 0
+        if arguments and arguments[0] == "download":
+            from . import download
+
+            return download.main(arguments[1:])
+        if arguments and arguments[0] == "resequence":
+            from .resequence.cli import main as resequence_main
+
+            return resequence_main(arguments[1:])
+    except KeyboardInterrupt:
+        print("hive-video: cancelled", file=sys.stderr)
+        return 130
+    except (OSError, ValueError, RuntimeError) as error:
+        print(f"hive-video: error: {error}", file=sys.stderr)
+        return 1
+    parser = build_parser()
+    args = parser.parse_args(arguments)
+    if args.locator is not None and args.data_dir is None:
+        parser.error("--locator requires an explicit --data-dir")
+    if args.video is not None and args.data_dir is not None:
+        parser.error("--data-dir applies only to --locator; --video already selects a source")
+    unit = "seconds" if args.start_seconds is not None else "frames"
+    if (unit == "seconds" and args.duration_frames is not None) or (
+        unit == "frames" and args.duration_seconds is not None
+    ):
+        parser.error("start and duration must use the same units (seconds or frames)")
+    if args.threads < 1:
+        parser.error(f"--threads must be a positive integer; observed {args.threads}")
+    start = args.start_seconds if unit == "seconds" else args.start_frame
+    duration = args.duration_seconds if unit == "seconds" else args.duration_frames
+    try:
+        source = (
+            resolve_source(args.locator, args.data_dir)
+            if args.locator is not None
+            else args.video.expanduser().resolve(strict=True)
+        )
+        filename = fragment_filename(source, start=start, duration=duration, unit=unit)
+        output_dir = args.out_dir or Path.cwd() / "data" / "artifacts" / "fragments"
+        output = args.out if args.out is not None else output_dir / filename
+        if args.progress != "off":
+            print(f"Source: {source}", file=sys.stderr)
+        with BeeProgress(args.progress) as progress:
+            result = create_fragment(
+                source,
+                output,
+                start=start,
+                duration=duration,
+                unit=unit,
+                threads=args.threads,
+                on_progress=None if args.progress == "off" else progress.update,
+            )
+    except KeyboardInterrupt:
+        print(f"{parser.prog}: cancelled", file=sys.stderr)
+        return 130
+    except (OSError, ValueError, RuntimeError) as error:
+        print(f"{parser.prog}: error: {error}", file=sys.stderr)
+        return 1
+    print(result)
+    return 0