vidstats 0.1.0__tar.gz

vidstats-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv
+*.csv
+*.parquet
+__pycache__
+.pytest_cache
+.DS_Store

vidstats-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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.

vidstats-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: vidstats
+Version: 0.1.0
+Summary: Extract per-frame colour and luminosity metrics from video via ffprobe signalstats.
+Project-URL: Repository, https://github.com/roaldarbol/vidstats
+Project-URL: Issues, https://github.com/roaldarbol/vidstats/issues
+Author-email: Mikkel Roald-Arbøl <vidstats.ez7zw@passmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: colour,ffprobe,luminosity,signalstats,video
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: polars>=0.20
+Requires-Dist: typer>=0.9
+Requires-Dist: typing-extensions>=4.0
+Description-Content-Type: text/markdown
+
+# vidstats
+
+Extract per-frame colour and luminosity metrics from video using
+[ffprobe's `signalstats` filter](https://ffmpeg.org/ffmpeg-filters.html#signalstats).
+Output goes to Parquet, CSV, IPC/Feather, or NDJSON.
+
+Designed for research pipelines that need a fast, dependency-light way to turn
+a video into a tabular time series — for example, non-contact cardiac monitoring
+in animals via colour/motion video analysis.
+
+## Installation
+
+**pixi** (recommended — pulls in ffmpeg automatically):
+
+```bash
+pixi global install vidstats
+```
+
+**uv** (global install):
+
+```bash
+uv tool install vidstats
+```
+
+**conda**:
+
+```bash
+conda install -c conda-forge vidstats
+```
+
+**pip** (requires ffmpeg on PATH separately):
+
+```bash
+pip install vidstats
+```
+
+## Usage
+
+```bash
+# Extract all metrics → Parquet
+vidstats spider_abdomen.mp4 output.parquet
+
+# Extract only luminance and saturation averages → CSV
+vidstats spider_abdomen.mp4 output.csv --metrics YAVG,SATAVG
+
+# Include both frame number and timestamp in seconds
+vidstats spider_abdomen.mp4 output.parquet --timestamps both
+
+# Override FPS when stream metadata is missing or wrong
+vidstats spider_abdomen.mp4 output.parquet --timestamps both --fps 30
+
+# Apply a crop region (X Y W H) before extraction
+vidstats spider_abdomen.mp4 output.parquet --crop "10 20 180 180"
+
+# Force format regardless of extension
+vidstats spider_abdomen.mp4 output.dat --format csv
+
+# Disable hardware acceleration
+vidstats spider_abdomen.mp4 output.parquet --no-hwaccel
+
+# List all available metric names and their output column names
+vidstats --list-metrics
+```
+
+## Supported output formats
+
+| Extension(s)                   | Format    |
+|--------------------------------|-----------|
+| `.parquet`                     | Parquet   |
+| `.csv`                         | CSV       |
+| `.tsv`                         | TSV       |
+| `.ipc`, `.arrow`, `.feather`   | Arrow IPC |
+| `.ndjson`, `.jsonl`            | NDJSON    |
+
+## Available metrics
+
+All 25 `signalstats` metrics are extracted by default. Run
+`vidstats --list-metrics` for the full table of ffprobe names, output column
+names, and descriptions. They cover:
+
+- **Luminance**: `YMIN`, `YLOW`, `YAVG`, `YHIGH`, `YMAX`
+- **Cb chrominance (U)**: same set of five
+- **Cr chrominance (V)**: same set of five
+- **Saturation**: `SATMIN`, `SATLOW`, `SATAVG`, `SATHIGH`, `SATMAX`
+- **Hue**: `HUEMED`, `HUEAVG`
+- **Quality flags**: `TOUT`, `VREP`, `BRNG`
+
+The `--metrics` flag accepts ffprobe names (e.g. `YAVG,SATAVG`).
+Output columns use descriptive snake_case names (e.g. `luminance_mean`,
+`saturation_mean`) — see `--list-metrics` for the full mapping.
+
+## Output schema
+
+| Column    | Type    | Condition                          |
+|-----------|---------|------------------------------------|
+| `frame`   | UInt32  | always                             |
+| `time_s`  | Float64 | `--timestamps seconds` or `both`   |
+| metrics…  | Float32 | selected metrics                   |
+
+`time_s` is computed as `frame / fps`. FPS is read from stream metadata
+automatically; use `--fps` to override it or supply it when metadata is absent.
+
+## Hardware acceleration
+
+vidstats auto-detects CUDA and passes `-hwaccel cuda` to ffprobe if available.
+This accelerates the **decode** stage only — `signalstats` itself always runs
+on CPU. For small (e.g. 200×200) videos the gain is negligible, but the
+detection is there for larger inputs. Suppress with `--no-hwaccel`.
+
+No special CUDA packages or drivers are required beyond what you already have.
+vidstats uses ffprobe's built-in NVDEC hardware decoding, which talks directly
+to the NVIDIA driver on your system — there is no `cudatoolkit`, no
+`pytorch-cuda`, and no GPU-specific installation step.
+
+## License
+
+MIT

vidstats-0.1.0/README.md

@@ -0,0 +1,117 @@
+# vidstats
+
+Extract per-frame colour and luminosity metrics from video using
+[ffprobe's `signalstats` filter](https://ffmpeg.org/ffmpeg-filters.html#signalstats).
+Output goes to Parquet, CSV, IPC/Feather, or NDJSON.
+
+Designed for research pipelines that need a fast, dependency-light way to turn
+a video into a tabular time series — for example, non-contact cardiac monitoring
+in animals via colour/motion video analysis.
+
+## Installation
+
+**pixi** (recommended — pulls in ffmpeg automatically):
+
+```bash
+pixi global install vidstats
+```
+
+**uv** (global install):
+
+```bash
+uv tool install vidstats
+```
+
+**conda**:
+
+```bash
+conda install -c conda-forge vidstats
+```
+
+**pip** (requires ffmpeg on PATH separately):
+
+```bash
+pip install vidstats
+```
+
+## Usage
+
+```bash
+# Extract all metrics → Parquet
+vidstats spider_abdomen.mp4 output.parquet
+
+# Extract only luminance and saturation averages → CSV
+vidstats spider_abdomen.mp4 output.csv --metrics YAVG,SATAVG
+
+# Include both frame number and timestamp in seconds
+vidstats spider_abdomen.mp4 output.parquet --timestamps both
+
+# Override FPS when stream metadata is missing or wrong
+vidstats spider_abdomen.mp4 output.parquet --timestamps both --fps 30
+
+# Apply a crop region (X Y W H) before extraction
+vidstats spider_abdomen.mp4 output.parquet --crop "10 20 180 180"
+
+# Force format regardless of extension
+vidstats spider_abdomen.mp4 output.dat --format csv
+
+# Disable hardware acceleration
+vidstats spider_abdomen.mp4 output.parquet --no-hwaccel
+
+# List all available metric names and their output column names
+vidstats --list-metrics
+```
+
+## Supported output formats
+
+| Extension(s)                   | Format    |
+|--------------------------------|-----------|
+| `.parquet`                     | Parquet   |
+| `.csv`                         | CSV       |
+| `.tsv`                         | TSV       |
+| `.ipc`, `.arrow`, `.feather`   | Arrow IPC |
+| `.ndjson`, `.jsonl`            | NDJSON    |
+
+## Available metrics
+
+All 25 `signalstats` metrics are extracted by default. Run
+`vidstats --list-metrics` for the full table of ffprobe names, output column
+names, and descriptions. They cover:
+
+- **Luminance**: `YMIN`, `YLOW`, `YAVG`, `YHIGH`, `YMAX`
+- **Cb chrominance (U)**: same set of five
+- **Cr chrominance (V)**: same set of five
+- **Saturation**: `SATMIN`, `SATLOW`, `SATAVG`, `SATHIGH`, `SATMAX`
+- **Hue**: `HUEMED`, `HUEAVG`
+- **Quality flags**: `TOUT`, `VREP`, `BRNG`
+
+The `--metrics` flag accepts ffprobe names (e.g. `YAVG,SATAVG`).
+Output columns use descriptive snake_case names (e.g. `luminance_mean`,
+`saturation_mean`) — see `--list-metrics` for the full mapping.
+
+## Output schema
+
+| Column    | Type    | Condition                          |
+|-----------|---------|------------------------------------|
+| `frame`   | UInt32  | always                             |
+| `time_s`  | Float64 | `--timestamps seconds` or `both`   |
+| metrics…  | Float32 | selected metrics                   |
+
+`time_s` is computed as `frame / fps`. FPS is read from stream metadata
+automatically; use `--fps` to override it or supply it when metadata is absent.
+
+## Hardware acceleration
+
+vidstats auto-detects CUDA and passes `-hwaccel cuda` to ffprobe if available.
+This accelerates the **decode** stage only — `signalstats` itself always runs
+on CPU. For small (e.g. 200×200) videos the gain is negligible, but the
+detection is there for larger inputs. Suppress with `--no-hwaccel`.
+
+No special CUDA packages or drivers are required beyond what you already have.
+vidstats uses ffprobe's built-in NVDEC hardware decoding, which talks directly
+to the NVIDIA driver on your system — there is no `cudatoolkit`, no
+`pytorch-cuda`, and no GPU-specific installation step.
+
+## License
+
+MIT

vidstats-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vidstats"
+version = "0.1.0"
+description = "Extract per-frame colour and luminosity metrics from video via ffprobe signalstats."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Mikkel Roald-Arbøl", email = "vidstats.ez7zw@passmail.com" }]
+keywords = ["video", "colour", "luminosity", "ffprobe", "signalstats"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Multimedia :: Video",
+]
+dependencies = [
+    "typer>=0.9",
+    "polars>=0.20",
+    "typing_extensions>=4.0",
+]
+
+[project.scripts]
+vidstats = "vidstats.cli:cli"
+
+[project.urls]
+Repository = "https://github.com/roaldarbol/vidstats"
+Issues = "https://github.com/roaldarbol/vidstats/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vidstats"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0",
+    "pytest-cov",
+    "ruff",
+    "mypy",
+]

vidstats-0.1.0/src/vidstats/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from .metrics import ALL_METRICS, COLUMN_NAMES, METRIC_DESCRIPTIONS
+from .parse import parse
+from .probe import build_command, run
+
+__version__ = "0.1.0"
+__all__ = [
+    "__version__",
+    "ALL_METRICS",
+    "COLUMN_NAMES",
+    "METRIC_DESCRIPTIONS",
+    "build_command",
+    "run",
+    "parse",
+]

vidstats-0.1.0/src/vidstats/cli.py

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from .hwaccel import detect_hwaccel
+from .metrics import ALL_METRICS, COLUMN_NAMES, METRIC_DESCRIPTIONS, validate_metrics
+from .output import SUPPORTED_FORMATS, infer_format, write
+from .parse import parse
+from .probe import FFprobeError, FFprobeNotFoundError, build_command, get_fps, run
+
+app = typer.Typer(
+    name="vidstats",
+    help=(
+        "Extract per-frame colour and luminosity metrics from a video "
+        "using ffprobe's signalstats filter."
+    ),
+    add_completion=True,
+)
+
+
+class TimestampMode(str, Enum):
+    frames = "frames"
+    seconds = "seconds"
+    both = "both"
+
+
+def _echo_err(msg: str) -> None:
+    typer.echo(msg, err=True)
+
+
+def _abort(msg: str) -> None:
+    _echo_err(f"Error: {msg}")
+    raise typer.Exit(code=1)
+
+
+def _list_metrics_callback(value: bool | None) -> None:
+    if not value:
+        return
+    ffprobe_w = max(len(m) for m in ALL_METRICS)
+    col_w = max(len(COLUMN_NAMES[m]) for m in ALL_METRICS)
+    header = f"  {'ffprobe name':<{ffprobe_w}}  {'output column':<{col_w}}  description"
+    typer.echo(header)
+    typer.echo("  " + "-" * (ffprobe_w + col_w + len("  description") + 4))
+    for m in ALL_METRICS:
+        typer.echo(
+            f"  {m:<{ffprobe_w}}  {COLUMN_NAMES[m]:<{col_w}}  {METRIC_DESCRIPTIONS[m]}"
+        )
+    raise typer.Exit()
+
+
+@app.command()
+def main(
+    input: Annotated[
+        Path,
+        typer.Argument(help="Input video file."),
+    ],
+    output: Annotated[
+        Path,
+        typer.Argument(
+            help=(
+                "Output file. Format is inferred from the extension "
+                f"({', '.join(sorted({'.parquet', '.csv', '.tsv', '.ipc', '.arrow', '.feather', '.ndjson', '.jsonl'}))})."
+            )
+        ),
+    ],
+    metrics: Annotated[
+        Optional[str],
+        typer.Option(
+            "--metrics", "-m",
+            help=(
+                "Comma-separated list of signalstats metrics to extract "
+                "(e.g. YAVG,UAVG,SATAVG). Defaults to all metrics. "
+                "Run --list-metrics to see available names."
+            ),
+        ),
+    ] = None,
+    crop: Annotated[
+        Optional[str],
+        typer.Option(
+            "--crop",
+            help=(
+                "Crop region applied before metric extraction, as 'X Y W H' "
+                "(top-left pixel coordinates and dimensions, space-separated)."
+            ),
+        ),
+    ] = None,
+    timestamps: Annotated[
+        TimestampMode,
+        typer.Option(
+            "--timestamps", "-t",
+            help=(
+                "Timestamp columns to include: "
+                "'frames' (zero-based integer, default), "
+                "'seconds' (float, requires FPS), or "
+                "'both'."
+            ),
+        ),
+    ] = TimestampMode.frames,
+    fps: Annotated[
+        Optional[float],
+        typer.Option(
+            "--fps",
+            help=(
+                "Override frame rate (frames per second) used to compute time_s. "
+                "If not provided, FPS is read from the video stream metadata. "
+                "Only relevant when --timestamps is 'seconds' or 'both'."
+            ),
+        ),
+    ] = None,
+    hwaccel: Annotated[
+        Optional[str],
+        typer.Option(
+            "--hwaccel",
+            help=(
+                "Hardware acceleration backend for decoding (e.g. 'cuda'). "
+                "Auto-detected by default. Only affects the decode stage."
+            ),
+        ),
+    ] = None,
+    no_hwaccel: Annotated[
+        bool,
+        typer.Option("--no-hwaccel", help="Disable hardware acceleration entirely."),
+    ] = False,
+    format: Annotated[
+        Optional[str],
+        typer.Option(
+            "--format", "-f",
+            help=(
+                f"Override output format ({', '.join(SUPPORTED_FORMATS)}). "
+                "Useful when the output extension does not match the desired format."
+            ),
+        ),
+    ] = None,
+    list_metrics: Annotated[
+        Optional[bool],
+        typer.Option(
+            "--list-metrics",
+            help="Print all available metric names and exit.",
+            is_eager=True,
+            callback=_list_metrics_callback,
+        ),
+    ] = None,
+) -> None:
+
+    # --- validate input file ---
+    if not input.exists():
+        _abort(f"Input file not found: '{input}'.")
+    if not input.is_file():
+        _abort(f"Input path is not a file: '{input}'.")
+
+    # --- validate fps if provided ---
+    if fps is not None and fps <= 0:
+        _abort("--fps must be a positive number.")
+
+    # --- resolve metrics ---
+    if metrics:
+        selected = [m.strip().upper() for m in metrics.split(",") if m.strip()]
+        invalid = validate_metrics(selected)
+        if invalid:
+            _abort(
+                f"Unknown metric(s): {', '.join(invalid)}. "
+                f"Run --list-metrics to see valid names."
+            )
+    else:
+        selected = ALL_METRICS
+
+    # --- resolve crop ---
+    crop_tuple: tuple[int, int, int, int] | None = None
+    if crop is not None:
+        try:
+            parts = [int(v) for v in crop.split()]
+            if len(parts) != 4:
+                raise ValueError
+            if any(v < 0 for v in parts):
+                raise ValueError
+            crop_tuple = (parts[0], parts[1], parts[2], parts[3])
+        except ValueError:
+            _abort("--crop must be four non-negative integers: 'X Y W H'.")
+
+    # --- resolve output format ---
+    try:
+        fmt = infer_format(output, format)
+    except ValueError as exc:
+        _abort(str(exc))
+        return  # unreachable, satisfies type checker
+
+    # --- resolve hardware acceleration ---
+    resolved_hwaccel: str | None
+    if no_hwaccel:
+        resolved_hwaccel = None
+    elif hwaccel:
+        resolved_hwaccel = hwaccel
+        _echo_err(f"Hardware acceleration: {resolved_hwaccel} (user-specified).")
+    else:
+        resolved_hwaccel = detect_hwaccel()
+        if resolved_hwaccel:
+            _echo_err(f"Hardware acceleration: {resolved_hwaccel} (auto-detected).")
+
+    # --- resolve fps for time_s column ---
+    resolved_fps: float | None = None
+    want_seconds = timestamps in (TimestampMode.seconds, TimestampMode.both)
+    if want_seconds:
+        if fps is not None:
+            resolved_fps = fps
+            _echo_err(f"FPS: {resolved_fps} (user-specified).")
+        else:
+            resolved_fps = get_fps(input)
+            if resolved_fps is not None:
+                _echo_err(f"FPS: {resolved_fps} (from stream metadata).")
+            else:
+                _echo_err(
+                    "Warning: could not determine FPS from stream metadata. "
+                    "time_s column will be omitted. Use --fps to provide it manually."
+                )
+
+    # --- build and run ffprobe ---
+    try:
+        cmd = build_command(
+            input_path=input,
+            metrics=selected,
+            crop=crop_tuple,
+            hwaccel=resolved_hwaccel,
+        )
+    except FFprobeNotFoundError as exc:
+        _abort(str(exc))
+        return
+
+    _echo_err(f"Processing '{input}'...")
+
+    try:
+        stdout = run(cmd)
+    except FFprobeError as exc:
+        _abort(str(exc))
+        return
+
+    # --- parse and write ---
+    df = parse(stdout, selected, resolved_fps)
+
+    if len(df) == 0:
+        _echo_err(
+            "Warning: no frames were extracted. "
+            "Check that the input is a valid video file."
+        )
+
+    _echo_err(f"Extracted {len(df)} frames, {len(df.columns)} columns.")
+
+    try:
+        write(df, output, fmt)
+    except Exception as exc:
+        _abort(f"Failed to write output: {exc}")
+
+    _echo_err(f"Written to '{output}'.")
+
+
+def cli() -> None:
+    app()

vidstats-0.1.0/src/vidstats/hwaccel.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+
+def detect_hwaccel() -> str | None:
+    """
+    Probe ffprobe for available hardware acceleration backends.
+
+    Returns the backend name (e.g. ``"cuda"``) if CUDA is available,
+    otherwise ``None``. Only accelerates the decode stage; signalstats
+    itself runs on CPU regardless. Most useful for large or high-fps videos.
+    """
+    if shutil.which("ffprobe") is None:
+        return None
+
+    try:
+        result = subprocess.run(
+            ["ffprobe", "-hwaccels"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        backends = result.stdout.lower().splitlines()
+        if any("cuda" in line for line in backends):
+            return "cuda"
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        pass
+
+    return None