"""Small FFprobe helpers for audio/video review artifacts."""

from __future__ import annotations

from collections.abc import Callable
import subprocess

Runner = Callable[..., subprocess.CompletedProcess[str]]


def probe_media_duration_seconds(path: str, *, runner: Runner = subprocess.run) -> float:
    """Return media duration in seconds via ffprobe."""

    command = [
        "ffprobe",
        "-v",
        "error",
        "-show_entries",
        "format=duration",
        "-of",
        "default=noprint_wrappers=1:nokey=1",
        path,
    ]
    completed = runner(command, capture_output=True, text=True, check=False)
    if completed.returncode != 0:
        raise RuntimeError(completed.stderr or "ffprobe failed")
    try:
        duration = float(completed.stdout.strip())
    except ValueError as exc:
        raise RuntimeError("could not parse media duration") from exc
    if duration <= 0:
        raise RuntimeError("media duration must be positive")
    return duration