hugpy-video 0.2.3__py3-none-any.whl

hugpy_video/__init__.py

@@ -0,0 +1,33 @@
+"""hugpy-video: execution and artifacts for Hugpy video work.
+
+Owns the media library jail, the sqlite media job bus and its lifecycle
+bridge, the frozen job specs and presets, the GPU reservation engine, the
+ffmpeg/diffusers/studio/identity runners and the studio spine
+(``intel``), the chat-side video analyzer (``chat_video``), the engine
+task runner for text-/image-to-video (``video_gen``) and the studio assist
+log. Decisions and plans belong to ``hugpy_oracle``, which plugs in through
+``hugpy_video.hooks`` (prompt coordination) and ``hugpy_video.jobs``
+(``register_job``) — this package never imports the oracle, the fleet or
+the server.
+
+Import-light: nothing here pulls torch/ffmpeg/studio stacks. Sub-modules are
+imported explicitly by callers (``hugpy_video.jobs``, ``hugpy_video.hooks``,
+``hugpy_video.plugin``, ``hugpy_video.state``, ``hugpy_video.config``).
+
+Version is single-sourced from pyproject.toml via importlib.metadata.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("hugpy-video")
+except PackageNotFoundError:  # running from a checkout without install
+    __version__ = "0.0.0+unknown"
+
+from hugpy_video.config import Config, load_config  # stdlib-only, cheap
+
+__all__ = [
+    "__version__",
+    "Config",
+    "load_config",
+]

hugpy_video/chat_video/__init__.py

@@ -0,0 +1 @@
+"""Chat-side video helpers (old ``managers/video``). Import-light; see ``video_analyzer``."""

hugpy_video/chat_video/video_analyzer.py

@@ -0,0 +1,174 @@
+"""Frame-by-frame video analysis over a vision runner (chat-side helper).
+
+Import-light: the vision runner/schemas come from ``hugpy_media`` (allowed),
+the no-think helpers from ``hugpy_engine`` (lazy, inside the loop).
+"""
+from __future__ import annotations
+
+import copy
+import os.path as osp
+import time
+import uuid
+from typing import Any, Union
+
+from abstract_essentials import safe_dump_to_file, safe_load_from_json
+from hugpy_media.vision.schemas import VisionRequest
+from hugpy_media.vision.vision_runner import VisionRunner
+from hugpy_platform.utils import get_base_64_image, require_file
+
+from hugpy_video.schemas.video_schemas import (
+    FrameAnalysis,
+    VideoAnalysisConfig,
+    VideoAnalysisSummary,
+)
+
+def _resolve_manifest_path(source: Union[str, Any]) -> str:
+    if isinstance(source, str):
+        return source
+    p = getattr(source, "manifest_path", None)
+    if isinstance(p, str):
+        return p
+    raise TypeError(
+        f"expected manifest path str or object with .manifest_path, "
+        f"got {type(source).__name__}"
+    )
+
+def _build_prompt(user_prompt: str, frame_context: dict) -> str:
+    return (
+        "-----------prompt---------\n"
+        f"{user_prompt}\n"
+        "-----------frame context---------\n"
+        f"{frame_context}\n"
+    )
+
+
+async def analyze_video(
+    source: Union[str, Any],
+    runner: VisionRunner,
+    config: VideoAnalysisConfig,
+) -> VideoAnalysisSummary:
+    manifest_path = require_file(_resolve_manifest_path(source), "manifest_path")
+    manifest_data = safe_load_from_json(manifest_path)
+    if not isinstance(manifest_data, dict):
+        raise ValueError(f"manifest is not a dict: {manifest_path}")
+
+    workspace_dir = manifest_data.get("workspace_dir")
+    if not workspace_dir or not osp.isdir(workspace_dir):
+        raise FileNotFoundError(f"workspace_dir invalid: {workspace_dir!r}")
+
+    files = manifest_data.get("files") or {}
+    frame_context_path = require_file(files.get("frame_context"), "files.frame_context")
+
+    frame_contexts = safe_load_from_json(frame_context_path)
+    if not isinstance(frame_contexts, list) or not frame_contexts:
+        raise ValueError(
+            f"frame_context must be a non-empty list, "
+            f"got {type(frame_contexts).__name__}"
+        )
+
+    total_frames = len(frame_contexts)
+    last = frame_contexts[-1]
+    total_video_length = last.get("timestamp") if isinstance(last, dict) else None
+
+    analysis_json_path = osp.join(workspace_dir, "analysis.json")
+    manifest_data.setdefault("files", {})["analysis_json"] = analysis_json_path
+    safe_dump_to_file(data=manifest_data, file_path=manifest_path)
+
+    # Resume keyed by frame_path so reruns are idempotent.
+    done_by_frame: dict[str, dict] = {}
+    if config.resume and osp.isfile(analysis_json_path):
+        prior = safe_load_from_json(analysis_json_path) or []
+        for entry in prior:
+            fp = entry.get("frame_path")
+            if fp and entry.get("error") is None:
+                done_by_frame[fp] = entry
+
+    records: list[dict] = list(done_by_frame.values())
+    model_key = runner.cfg.model_key  # runner is the source of truth
+
+    for i, raw_ctx in enumerate(frame_contexts):
+        if not isinstance(raw_ctx, dict):
+            records.append({
+                "frame_index": i,
+                "error": f"frame_context[{i}] is not a dict",
+            })
+            continue
+
+        ctx = copy.deepcopy(raw_ctx)  # never mutate caller's data
+        frame_path = ctx.get("frame_path")
+
+        if not frame_path or not osp.isfile(frame_path):
+            err = f"frame_path missing or not found: {frame_path!r}"
+            if config.raise_on_frame_error:
+                raise FileNotFoundError(err)
+            ctx.update({"frame_index": i, "error": err})
+            records.append(ctx)
+            continue
+
+        if frame_path in done_by_frame:
+            continue
+
+        ctx["frame_index"] = i
+        ctx["total_frames"] = total_frames
+        ctx["total_video_length"] = total_video_length
+        # NO-THINK (utils/no_think.py). Every frame's `analysis` is VALIDATED and
+        # PERSISTED to analysis.json — a monologue here poisons the whole dataset,
+        # and nothing downstream re-reads the frame to notice. The reasoning is
+        # kept alongside (FrameAnalysis is extra="allow") rather than discarded.
+        from hugpy_engine.utils.no_think import with_no_think, strip_think
+        rendered_prompt = with_no_think(_build_prompt(config.prompt, ctx))
+        image_b64 = get_base_64_image(frame_path)
+        req = VisionRequest(
+            request_id=f"frame-{i}-{uuid.uuid4().hex[:8]}",
+            model_key=model_key,
+            prompt=rendered_prompt,
+            max_new_tokens=config.max_new_tokens,
+            max_tokens=config.max_tokens,
+            image_b64=image_b64,
+        )
+
+        t0 = time.time()
+        try:
+            vresult = await runner.run(req)
+            text, err = vresult.text, vresult.error
+        except Exception as e:
+            if config.raise_on_frame_error:
+                raise
+            text, err = None, f"{type(e).__name__}: {e}"
+        duration = time.time() - t0
+
+        reasoning = ""
+        if text:
+            text, reasoning = strip_think(text)
+            if not text:
+                # Nothing but thinking — record it as an error rather than
+                # persisting an empty analysis that reads like a clean run.
+                err = err or ("model returned only reasoning and no analysis "
+                              "(ignored the no-think directive)")
+
+        ctx.update({
+            "analysis_prompt": rendered_prompt,
+            "analysis": text,
+            "analysis_reasoning": reasoning,
+            "model_key": model_key,
+            "analysis_duration": duration,
+            "error": err,
+        })
+
+        # Validate-on-write: schema drift fails fast, not three days from now
+        FrameAnalysis.model_validate(ctx)
+        records.append(ctx)
+
+        if (i + 1) % config.save_every == 0 or (i + 1) == total_frames:
+            safe_dump_to_file(data=records, file_path=analysis_json_path)
+
+    succeeded = sum(1 for r in records if r.get("error") is None)
+    failed = sum(1 for r in records if r.get("error") is not None)
+
+    return VideoAnalysisSummary(
+        manifest_path=manifest_path,
+        analysis_json_path=analysis_json_path,
+        frames_total=total_frames,
+        frames_succeeded=succeeded,
+        frames_failed=failed,
+    )

hugpy_video/cli.py

@@ -0,0 +1,130 @@
+"""``hugpy-video`` command line (minimal; the console script in pyproject).
+
+    hugpy-video --help
+    hugpy-video jobs list [--all] [--limit N] [--json]
+    hugpy-video jobs registry
+    hugpy-video selftest            # in-process checks, no GPU/service
+    hugpy-video models audit --json # declared model roster and readiness gates
+
+Everything heavy is imported inside the sub-command that needs it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import List, Optional
+
+
+def _cmd_jobs_list(args) -> int:
+    from hugpy_video import jobs
+
+    rows = jobs.list_jobs(include_terminal=args.all, limit=args.limit)
+    if args.json:
+        print(json.dumps(rows, indent=2, default=str))
+        return 0
+    if not rows:
+        print("no jobs")
+        return 0
+    for r in rows:
+        print(f"{r.get('job_id','?'):34} {r.get('name','?'):26} {r.get('status','?')}")
+    return 0
+
+
+def _cmd_jobs_registry(args) -> int:
+    from hugpy_video import jobs
+
+    for name, spec in sorted(jobs.registered_jobs().items()):
+        print(f"{name:26} {spec.runner_key[0]}/{spec.runner_key[1]:18} "
+              f"queue={spec.queue} timeout={spec.timeout_s}s")
+    return 0
+
+
+def _cmd_selftest(args) -> int:
+    from hugpy_video.selftest import run_selftest
+
+    failures = run_selftest(verbose=True)
+    return 1 if failures else 0
+
+
+def _cmd_state(args) -> int:
+    from dataclasses import asdict
+
+    from hugpy_video.state import get_state_roots
+
+    print(json.dumps(asdict(get_state_roots()), indent=2))
+    return 0
+
+
+def _cmd_models_audit(args) -> int:
+    """Inventory every declared model without loading weights or allocating a GPU."""
+    from hugpy_video.intel.studio.registry import MODEL_REGISTRY, model_gate_reasons
+
+    rows = []
+    for model_id, cfg in sorted(MODEL_REGISTRY.items()):
+        precision_gb = {precision.value: gb for precision, gb in cfg.vram.per_precision}
+        rows.append({
+            "model_id": model_id,
+            "family": cfg.family.value,
+            "capabilities": sorted(cap.value for cap in cfg.capabilities),
+            "tasks": sorted(task.value for task in cfg.tasks),
+            "minimum_vram_gb": min(precision_gb.values()) if precision_gb else None,
+            "vram_by_precision_gb": precision_gb,
+            "weights_pinned": cfg.weight_hash is not None,
+            "runner_gaps": model_gate_reasons(model_id),
+        })
+    if args.json:
+        print(json.dumps({"models": rows}, indent=2, sort_keys=True))
+    else:
+        for row in rows:
+            status = ", ".join(row["runner_gaps"].values()) or "runner present"
+            pin = "pinned" if row["weights_pinned"] else "unpinned"
+            print(f"{row['model_id']:32} {row['minimum_vram_gb']!s:>6} GB  {pin:8}  {status}")
+        print(f"{len(rows)} declared models; audit does not prove installed weights or GPU readiness")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    from hugpy_video import __version__
+
+    p = argparse.ArgumentParser(prog="hugpy-video",
+                                description="Hugpy video: media job bus, runners, studio.")
+    p.add_argument("--version", action="version", version=f"hugpy-video {__version__}")
+    sub = p.add_subparsers(dest="cmd")
+
+    jobs = sub.add_parser("jobs", help="media job bus")
+    jsub = jobs.add_subparsers(dest="jobs_cmd")
+    ls = jsub.add_parser("list", help="list jobs")
+    ls.add_argument("--all", action="store_true", help="include terminal jobs")
+    ls.add_argument("--limit", type=int, default=50)
+    ls.add_argument("--json", action="store_true")
+    ls.set_defaults(func=_cmd_jobs_list)
+    reg = jsub.add_parser("registry", help="registered job names and runner keys")
+    reg.set_defaults(func=_cmd_jobs_registry)
+
+    st = sub.add_parser("selftest", help="in-process self checks (no GPU, no service)")
+    st.set_defaults(func=_cmd_selftest)
+
+    state = sub.add_parser("state", help="print the resolved state roots")
+    state.set_defaults(func=_cmd_state)
+    models = sub.add_parser("models", help="studio model inventory")
+    msub = models.add_subparsers(dest="models_cmd")
+    audit = msub.add_parser("audit", help="report runner, pin and VRAM requirements")
+    audit.add_argument("--json", action="store_true")
+    audit.set_defaults(func=_cmd_models_audit)
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    func = getattr(args, "func", None)
+    if func is None:
+        parser.print_help()
+        return 0
+    return int(func(args) or 0)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

hugpy_video/config.py

@@ -0,0 +1,79 @@
+"""Canonical hugpy credential/config loader — the single-source-of-truth seam.
+
+Precedence (same contract as hugpy_agent.config, later layer wins):
+    agent.toml  ->  .env (workspace/CWD)  ->  process env  ->  explicit overrides
+
+Canonical variable names (frozen per ARMS-ASSESSMENT-2026-08-20):
+    HUGPY_API_KEY   the hp_ public API key
+    HUGPY_BASE      central base URL (default https://dev.hugpy.ai/api)
+
+Legacy aliases are accepted, lowest priority within their layer, and recorded in
+Config.deprecations so callers can warn. New code must never read the aliases.
+Fleet-scope store: /srv/vm_mgr/secrets/hugpy.env (0600) — pass as env_file.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_BASE = "https://dev.hugpy.ai/api"
+
+# alias -> canonical; order matters only for reporting
+_KEY_ALIASES = ("CONSOLE_API", "HUGPY_API_TOKEN", "HUGPY_AGENT_API", "HUGPY_API_KEY_NEWVM")
+_BASE_ALIASES = ("HUGPY_BASE_URL", "HUGPY_URL", "HUGPY_CENTRAL")
+
+
+@dataclass
+class Config:
+    base: str = DEFAULT_BASE
+    api_key: str = ""
+    sources: dict = field(default_factory=dict)       # attr -> winning layer
+    deprecations: list = field(default_factory=list)  # (alias, layer) hits
+
+
+def _parse_env_file(path: Path) -> dict:
+    out = {}
+    try:
+        for line in path.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, _, v = line.partition("=")
+            out[k.strip()] = v.strip().strip("'\"")
+    except OSError:
+        pass
+    return out
+
+
+def _apply(cfg: Config, mapping: dict, layer: str) -> None:
+    # aliases first so a canonical name in the same layer wins
+    for alias in _KEY_ALIASES:
+        if mapping.get(alias):
+            cfg.api_key = mapping[alias]
+            cfg.sources["api_key"] = layer
+            cfg.deprecations.append((alias, layer))
+    for alias in _BASE_ALIASES:
+        if mapping.get(alias):
+            cfg.base = mapping[alias]
+            cfg.sources["base"] = layer
+            cfg.deprecations.append((alias, layer))
+    if mapping.get("HUGPY_API_KEY"):
+        cfg.api_key = mapping["HUGPY_API_KEY"]
+        cfg.sources["api_key"] = layer
+    if mapping.get("HUGPY_BASE"):
+        cfg.base = mapping["HUGPY_BASE"]
+        cfg.sources["base"] = layer
+
+
+def load_config(env_file: str | os.PathLike | None = None, **overrides) -> Config:
+    cfg = Config()
+    if env_file:
+        _apply(cfg, _parse_env_file(Path(env_file)), f".env:{env_file}")
+    _apply(cfg, dict(os.environ), "env")
+    for attr, value in overrides.items():
+        if value:
+            setattr(cfg, attr, value)
+            cfg.sources[attr] = "override"
+    return cfg

hugpy_video/hooks.py

@@ -0,0 +1,152 @@
+"""Upper-layer callbacks video needs but must not import (EXTRACTION_GUIDE §3.3).
+
+``hugpy_video`` executes immutable specs; ``hugpy_oracle`` decides. Two places
+in video used to reach *up* into the oracle's ``prompt_coordination`` module:
+
+* ``intel.prompt_spread.coordinate_spread`` — after a spread reply is parsed,
+  review the rows' words against their knobs and apply the mechanical
+  decisions (joint mode, parent pointer, seed, frame count, identity refs).
+* ``intel.studio.movie_plan.preflight_coordination`` /
+  ``coordination_report`` — the submit-time words-vs-knobs review of a
+  ``StudioMovieSpec``.
+
+Both now call the :class:`PromptCoordinator` installed here. The default is a
+no-op coordinator whose report says *nothing was reviewed* (``reviewed: False``)
+— never a silent "reviewed and fine". The oracle installs its implementation at
+composition time (``hugpy_server`` wiring, or an oracle CLI)::
+
+    from hugpy_video.hooks import set_prompt_coordinator
+    from hugpy_oracle.relay import prompt_coordination as PC
+
+    class OracleCoordinator:
+        block_confidence = PC.BLOCK_CONFIDENCE
+        def review(self, rows, *, notes="", context=None, llm=None):
+            return PC.review(rows, notes=notes, context=context, llm=llm)
+        def review_goals(self, spec, *, context=None):
+            return PC.review_goals(spec, context=context)
+        def apply_decisions(self, rows, report):
+            return PC.apply_decisions(rows, report)
+        def blocking_mismatches(self, report, threshold=None):
+            return PC.blocking_mismatches(
+                report, PC.BLOCK_CONFIDENCE if threshold is None else threshold)
+
+    set_prompt_coordinator(OracleCoordinator())
+
+Report objects are opaque to video: it only calls ``as_dict()`` on them and
+reads ``segment_id`` / ``knob`` off the applied decisions. Invariant 9 (no
+generated prompt text crosses rows) is the coordinator's to keep; the null
+coordinator trivially keeps it by writing nothing.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional, Protocol, Sequence, Tuple, runtime_checkable
+
+__all__ = [
+    "CoordinationReportLike",
+    "KnobDecisionLike",
+    "PromptCoordinator",
+    "NullPromptCoordinator",
+    "NullCoordinationReport",
+    "get_prompt_coordinator",
+    "set_prompt_coordinator",
+    "reset_hooks",
+]
+
+
+@runtime_checkable
+class CoordinationReportLike(Protocol):
+    """What video reads off a review report: its wire shape."""
+
+    def as_dict(self) -> Dict[str, Any]: ...
+
+
+@runtime_checkable
+class KnobDecisionLike(Protocol):
+    """One applied decision: which row, which knob (the value is read off the row)."""
+
+    segment_id: str
+    knob: str
+
+
+@runtime_checkable
+class PromptCoordinator(Protocol):
+    """Words-vs-knobs review for a prompt set. Implemented by ``hugpy_oracle``."""
+
+    #: Confidence at or above which a ``mismatch`` blocks a submit.
+    block_confidence: float
+
+    def review(self, rows: Sequence[Mapping[str, Any]], *, notes: str = "",
+               context: Optional[Mapping[str, Any]] = None,
+               llm: Any = None) -> CoordinationReportLike:
+        """Review generated/enhanced prompt rows (``segment_id``, ``prompt``,
+        ``locked`` + current knobs). Every row must appear in the report."""
+        ...
+
+    def review_goals(self, spec: Any, *,
+                     context: Optional[Mapping[str, Any]] = None) -> CoordinationReportLike:
+        """:meth:`review` for a built ``StudioMovieSpec`` (submit preflight)."""
+        ...
+
+    def apply_decisions(self, rows: Sequence[Mapping[str, Any]],
+                        report: CoordinationReportLike,
+                        ) -> Tuple[List[Dict[str, Any]], List[KnobDecisionLike]]:
+        """Apply the report's ``set`` decisions to copies of ``rows``; return
+        ``(rows, applied)``. May write mechanics only, never ``prompt``."""
+        ...
+
+    def blocking_mismatches(self, report: CoordinationReportLike,
+                            threshold: Optional[float] = None) -> List[Dict[str, Any]]:
+        """Submit-blocking rows in ``movie_plan.preflight_movie``'s vocabulary
+        (``index`` / ``segment_id`` / ``reason`` / ``detail``)."""
+        ...
+
+
+class NullCoordinationReport:
+    """The honest empty report: nothing reviewed, nothing decided."""
+
+    decisions: Tuple[Any, ...] = ()
+    segments: Tuple[Any, ...] = ()
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {"reviewed": False, "coordinator": "none",
+                "segments": [], "decisions": [], "expectations": []}
+
+
+class NullPromptCoordinator:
+    """Default: no review, no decisions, nothing blocks (single-box / tests)."""
+
+    block_confidence = 0.8
+
+    def review(self, rows, *, notes: str = "", context=None, llm=None):
+        return NullCoordinationReport()
+
+    def review_goals(self, spec, *, context=None):
+        return NullCoordinationReport()
+
+    def apply_decisions(self, rows, report):
+        return [dict(r) for r in rows], []
+
+    def blocking_mismatches(self, report, threshold=None):
+        return []
+
+
+_providers: Dict[str, Any] = {}
+_defaults: Dict[str, Any] = {"prompt_coordinator": NullPromptCoordinator()}
+
+
+def get_prompt_coordinator() -> PromptCoordinator:
+    return _providers.get("prompt_coordinator", _defaults["prompt_coordinator"])
+
+
+def set_prompt_coordinator(impl: PromptCoordinator | None) -> None:
+    """Install (or, with ``None``, uninstall) the coordinator implementation."""
+    if impl is None:
+        _providers.pop("prompt_coordinator", None)
+    else:
+        _providers["prompt_coordinator"] = impl
+
+
+def reset_hooks() -> None:
+    """Drop every installed hook (tests)."""
+    _providers.clear()

hugpy_video/intel/__init__.py

@@ -0,0 +1,10 @@
+"""hugpy Video Intelligence — headless backbone (Phases 1 & 2).
+
+Additive package. Nothing here restarts a service or touches the serve/worker
+control plane. It provides the frozen schemas (MediaRef / CropSpec / JobSpec /
+JobResult), the ingest metadata resolver, the pure ffmpeg crop runner, and a
+durable sqlite-backed job bus.
+
+Build order matches hugpy_video_intelligence_map.md §11:
+    MediaRef + ingest  ->  CropSpec + (ffmpeg, crop) runner + crop JobSpec  ->  bus.
+"""

hugpy_video/intel/audio_schema.py

@@ -0,0 +1,44 @@
+"""Audio-extraction schema — map §4.4.
+
+Frozen spec + validating factory, mirroring frame_schema.py exactly. An audio
+extraction pulls a video's audio track out to a standalone audio file of one
+`fmt`. Per-field validity (`source` is a video, `fmt` is a known container) is
+enforced in the factory with LOCAL raises (construction-time, never across a
+boundary). Temporal trimming of the resulting audio is NOT this job's concern —
+that already works through the existing `crop` job's temporal branch.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from hugpy_video.intel.media_schema import MediaRef
+
+AudioFmt = Literal["wav", "mp3", "m4a"]
+
+# Construction-time guard set for `fmt` (registry-over-globals discipline).
+AUDIO_FMTS = frozenset({"wav", "mp3", "m4a"})
+
+
+@dataclass(frozen=True)
+class AudioExtractSpec:
+    """Extract `source`'s (a video) audio track into a standalone audio file.
+
+        fmt   output container/codec family: wav|mp3|m4a (default wav)
+    """
+    source: MediaRef
+    fmt: str = "wav"
+
+
+def make_audio_extract(source: MediaRef, fmt: str = "wav") -> AudioExtractSpec:
+    """Validate + build an AudioExtractSpec. A raise here is fine: local to
+    construction, never crosses a boundary (map §4 / §6).
+
+    Also the reconstruction path used by the bus when it deserializes the spec
+    from JSON — kwargs line up 1:1 with the fields so it round-trips.
+    """
+    if source.kind != "video":
+        raise ValueError(f"audio_extract source must be a video; got kind={source.kind!r}")
+    if fmt not in AUDIO_FMTS:
+        raise ValueError(f"fmt must be one of {sorted(AUDIO_FMTS)}; got {fmt!r}")
+    return AudioExtractSpec(source=source, fmt=fmt)