unrender 0.2.1__py3-none-any.whl

unrender/cli/commands/audio.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from unrender.cli.commands.context import (
+    _audio_arg,
+    _audio_output_prefix,
+    _audioshake_client,
+    _bandit_settings,
+    _default_voice_clip_spec,
+    _dx_stem_arg,
+    _path_arg,
+    _run_paths,
+    _shot_speakers_arg,
+    _speaker_db_path,
+    _stem_sources_arg,
+    _string_arg,
+)
+from unrender.cli.helpers import positive_float, threshold
+from unrender.dialogue.clusters import resolve_voice_clips_clustered
+from unrender.dialogue.lines import (
+    build_voice_clips,
+    import_dub_script_lines,
+    map_dialogue_to_shots,
+    materialize_dialogue_line_stems,
+    resolve_voice_clips,
+    transcribe_dialogue_lines,
+)
+from unrender.manifests import load_dialogue_lines, load_shot_manifest, load_voice_inputs, read_json
+from unrender.separation import separate_full_audio_source, separate_global_dx_stem
+from unrender.shots.dx import build_shot_dx, resolve_dx_stem
+
+
+def _audio_separate(args: argparse.Namespace) -> int:
+    run = _run_paths(args, explicit=args.out)
+    audio_prefix = _audio_output_prefix(args, run)
+    if args.full_audio and args.dx_stem:
+        raise ValueError("--full-audio and --dx-stem are mutually exclusive for audio separate")
+    full_audio = args.full_audio or (
+        None
+        if args.dx_stem
+        else _string_arg(
+            args,
+            "full_audio",
+            None,
+            required=False,
+            aliases=("full_audio_stem", "full_stem", "full_mix", "mix_stem"),
+        )
+    )
+    if full_audio:
+        source_backend = str(_audio_arg(args, "source_backend", args.source_backend, "audioshake"))
+        if source_backend == "bandit":
+            from unrender.separation.bandit import separate_full_audio_source_bandit
+
+            source_result = separate_full_audio_source_bandit(
+                run=run,
+                full_audio=full_audio,
+                settings=_bandit_settings(args),
+                fmt=_audio_arg(args, "source_format", args.format, "wav"),
+                prefix=audio_prefix,
+                force=args.force,
+                dry_run=args.dry_run,
+            )
+        elif source_backend == "audioshake":
+            source_result = separate_full_audio_source(
+                run=run,
+                full_audio=full_audio,
+                fmt=_audio_arg(args, "audioshake_format", args.format, "wav"),
+                prefix=audio_prefix,
+                timeout=int(
+                    positive_float(
+                        _audio_arg(args, "audioshake_timeout", args.timeout, 1800), "timeout"
+                    )
+                ),
+                poll_interval=int(
+                    positive_float(
+                        _audio_arg(args, "audioshake_poll_interval", args.poll_interval, 5),
+                        "poll-interval",
+                    )
+                ),
+                force=args.force,
+                dry_run=args.dry_run,
+                client=None if args.api_key is None else _audioshake_client(args.api_key),
+            )
+        else:
+            raise ValueError(f"unsupported source backend: {source_backend}")
+        if args.dry_run:
+            print("DRY RUN: would speaker-separate the generated dialogue stem", flush=True)
+            return 0
+        if source_result.dialogue_stem is None:
+            raise RuntimeError("source separation did not produce a dialogue stem")
+        dx_stem: str | Path = source_result.dialogue_stem
+    else:
+        dx_stem = _dx_stem_arg(args, run, explicit=args.dx_stem, required=True)
+    separate_global_dx_stem(
+        run=run,
+        dx_stem=dx_stem,
+        variant=_audio_arg(args, "audioshake_variant", args.variant, "n_speaker"),
+        fmt=_audio_arg(args, "audioshake_format", args.format, "wav"),
+        prefix=audio_prefix,
+        timeout=int(
+            positive_float(_audio_arg(args, "audioshake_timeout", args.timeout, 1800), "timeout")
+        ),
+        poll_interval=int(
+            positive_float(
+                _audio_arg(args, "audioshake_poll_interval", args.poll_interval, 5),
+                "poll-interval",
+            )
+        ),
+        force=args.force,
+        dry_run=args.dry_run,
+        client=None if args.api_key is None else _audioshake_client(args.api_key),
+    )
+    return 0
+
+
+def _audio_transcribe_lines(args: argparse.Namespace) -> int:
+    run = _run_paths(args, explicit=args.out)
+    run.ensure()
+    if args.dub_script is not None and args.dx_stem:
+        raise ValueError("--dub-script and --dx-stem are mutually exclusive for transcribe-lines")
+    dub_script = _path_arg(args, "dub_script", args.dub_script, required=False)
+    if dub_script is not None:
+        import_dub_script_lines(
+            dub_script_path=dub_script,
+            output_json=run.dialogue_lines_json,
+            output_csv=run.dialogue_lines_csv,
+            fps=float(_audio_arg(args, "dub_script_fps", args.dub_script_fps, 24.0)),
+            default_duration_sec=float(
+                _audio_arg(args, "default_duration_sec", args.default_duration_sec, 3.0)
+            ),
+            min_duration_sec=float(
+                _audio_arg(args, "min_duration_sec", args.min_duration_sec, 0.3)
+            ),
+            handle_sec=float(_audio_arg(args, "handle_sec", args.handle_sec, 0.18)),
+            force=args.force,
+        )
+        return 0
+    shots_path = _path_arg(args, "shots", args.shots, required=False)
+    shots = load_shot_manifest(shots_path) if shots_path else []
+    transcribe_dialogue_lines(
+        audio_path=Path(_dx_stem_arg(args, run, explicit=args.dx_stem, required=True)),
+        output_json=run.dialogue_lines_json,
+        output_csv=run.dialogue_lines_csv,
+        shots=shots,
+        whisper_model=str(_audio_arg(args, "whisper_model", args.whisper_model, "small")),
+        device=str(_audio_arg(args, "device", args.device, "cpu")),
+        compute_type=str(_audio_arg(args, "compute_type", args.compute_type, "float32")),
+        language=_audio_arg(args, "language", args.language, None),
+        max_gap_sec=float(_audio_arg(args, "max_gap_sec", args.max_gap_sec, 0.5)),
+        handle_sec=float(_audio_arg(args, "handle_sec", args.handle_sec, 0.18)),
+        force=args.force,
+    )
+    return 0
+
+
+def _audio_build_clips(args: argparse.Namespace) -> int:
+    run = _run_paths(args, explicit=args.out)
+    run.ensure()
+    lines = load_dialogue_lines(
+        _path_arg(args, "dialogue_lines", args.dialogue_lines, required=False)
+        or run.dialogue_lines_json
+    )
+    build_voice_clips(
+        lines=lines,
+        stems=_stem_sources_arg(args, run),
+        output_dir=run.voice_clips_dir,
+        output_json=run.voice_clips_json,
+        output_csv=run.voice_clips_csv,
+        clip_type="dialogue_line",
+        silence_threshold_db=float(
+            _audio_arg(args, "silence_threshold_db", args.silence_threshold_db, -100.0)
+        ),
+        force=args.force,
+        ffmpeg=str(_audio_arg(args, "ffmpeg", args.ffmpeg, "ffmpeg")),
+    )
+    return 0
+
+
+def _audio_shot_dx(args: argparse.Namespace) -> int:
+    run = _run_paths(args, explicit=args.out)
+    run.ensure()
+    shots = load_shot_manifest(_path_arg(args, "shots", args.shots, required=True))
+    explicit = _dx_stem_arg(args, run, explicit=args.dx_stem, required=False)
+    merge_sources = None
+    if not explicit:
+        # No DX anywhere: fall back to merging the separated speaker stems.
+        merge_sources = _stem_sources_arg(args, run)
+    dx_stem = resolve_dx_stem(
+        run,
+        explicit=Path(explicit) if explicit else None,
+        merge_sources=merge_sources,
+        force=args.force,
+    )
+    build_shot_dx(
+        run=run,
+        shots=shots,
+        dx_stem=dx_stem,
+        force=args.force,
+        ffmpeg=str(_audio_arg(args, "ffmpeg", args.ffmpeg, "ffmpeg")),
+    )
+    return 0
+
+
+def _audio_resolve_clips(args: argparse.Namespace) -> int:
+    run = _run_paths(args, explicit=args.out)
+    run.ensure()
+    clips = load_voice_inputs(args.clips or _default_voice_clip_spec(run))
+    resolver = str(_audio_arg(args, "clip_resolver", args.resolver, "cluster"))
+    backend = str(_audio_arg(args, "voice_backend", args.backend, "pyannote"))
+    if resolver == "cluster":
+        clusters = _audio_arg(args, "clusters", args.clusters, None)
+        resolve_voice_clips_clustered(
+            clips=clips,
+            speaker_db_path=_speaker_db_path(args, args.speaker_db, run),
+            output_json=run.clip_stem_plan_json,
+            output_csv=run.clip_stem_plan_csv,
+            backend=backend,
+            n_clusters=None if clusters in (None, "") else int(clusters),
+            override_min_sec=positive_float(
+                _audio_arg(args, "override_sec", args.override_sec, 1.5), "override-sec"
+            ),
+            override_margin=float(_audio_arg(args, "override_margin", args.override_margin, 0.15)),
+        )
+    elif resolver == "clip":
+        resolve_voice_clips(
+            clips=clips,
+            speaker_db_path=_speaker_db_path(args, args.speaker_db, run),
+            voice_matches_json=run.voice_matches_json,
+            output_json=run.clip_stem_plan_json,
+            output_csv=run.clip_stem_plan_csv,
+            backend=backend,
+            sim_threshold=threshold(
+                _audio_arg(args, "sim_threshold", args.sim_threshold, 0.65), "sim-threshold"
+            ),
+            min_margin=float(_audio_arg(args, "min_margin", args.min_margin, 0.05)),
+        )
+    else:
+        raise ValueError(f"unsupported clip resolver: {resolver}")
+    return 0
+
+
+def _audio_map_dialogue(args: argparse.Namespace) -> int:
+    run = _run_paths(args, explicit=args.out)
+    run.ensure()
+    lines = load_dialogue_lines(
+        _path_arg(args, "dialogue_lines", args.dialogue_lines, required=False)
+        or run.dialogue_lines_json
+    )
+    shots = load_shot_manifest(_path_arg(args, "shots", args.shots, required=True))
+    clip_plan_path = _path_arg(args, "clip_plan", args.clip_plan, required=False) or (
+        run.dialogue_stem_plan_json
+        if run.dialogue_stem_plan_json.exists()
+        else run.clip_stem_plan_json
+    )
+    clip_plan = read_json(clip_plan_path).get("clips") or []
+    shot_speakers = _shot_speakers_arg(args, run)
+    dialogue_plan = materialize_dialogue_line_stems(
+        clip_plan=clip_plan,
+        output_dir=run.dialogue_mapped_dir,
+        output_json=run.dialogue_stem_plan_json,
+        output_csv=run.dialogue_stem_plan_csv,
+        force=args.force,
+    )
+    cut_shot_stems = bool(_audio_arg(args, "cut_shot_stems", args.cut_shot_stems or None, False))
+    map_dialogue_to_shots(
+        lines=lines,
+        shots=shots,
+        clip_plan=dialogue_plan,
+        output_json=run.shot_dialogue_map_json,
+        output_csv=run.shot_dialogue_map_csv,
+        shot_plan_json=run.shot_stem_plan_json,
+        shot_plan_csv=run.shot_stem_plan_csv,
+        mapped_dir=run.shot_mapped_dir if cut_shot_stems else None,
+        shot_speakers_by_id=shot_speakers,
+        min_overlap_ratio=float(
+            _audio_arg(args, "min_overlap_ratio", args.min_overlap_ratio, 0.01)
+        ),
+        force=args.force,
+        ffmpeg=str(_audio_arg(args, "ffmpeg", args.ffmpeg, "ffmpeg")),
+    )
+    return 0

unrender/cli/commands/context.py

@@ -0,0 +1,342 @@
+from __future__ import annotations
+
+import argparse
+import glob as glob_module
+from pathlib import Path
+from typing import Any, Literal, overload
+
+from unrender.manifests import read_json
+from unrender.media.names import safe_name
+from unrender.project import RunPaths
+from unrender.project.config import ProjectConfig, load_speaker_config, resolve_project_configs
+from unrender.shots.stems import StemSource, load_stem_map, load_stem_sources
+from unrender.speakers import configured_speakers
+
+
+def _project_path_issue(
+    project: ProjectConfig,
+    key: str,
+    *,
+    allow_glob: bool = False,
+) -> str | None:
+    value = project.string_value(key)
+    if not value:
+        return None
+    if value.startswith(("http://", "https://")):
+        return None
+    if allow_glob and any(char in value for char in "*?[]"):
+        if glob_module.glob(value):
+            return None
+        return f"paths.{key} matched no files: {value}"
+    path = project.path_value(key)
+    if path is not None and not path.exists():
+        return f"paths.{key} does not exist: {path}"
+    return None
+
+
+def _projects_from_args(args: argparse.Namespace) -> list[ProjectConfig]:
+    specs = getattr(args, "projects", None) or []
+    return resolve_project_configs([str(spec) for spec in specs]) if specs else []
+
+
+def _project(args: argparse.Namespace) -> ProjectConfig | None:
+    return getattr(args, "project_config", None)
+
+
+def _run_paths(args: argparse.Namespace, *, explicit: Path | None) -> RunPaths:
+    if explicit is not None:
+        return RunPaths.from_path(explicit)
+    project = _project(args)
+    if project is not None:
+        value = project.path_value("run_dir")
+        if value is not None:
+            return RunPaths.from_path(value)
+    raise ValueError("missing --run-dir/--out/--run (or paths.run_dir in project config)")
+
+
+@overload
+def _path_arg(
+    args: argparse.Namespace,
+    key: str,
+    explicit: Path | None,
+    *,
+    required: Literal[True],
+) -> Path: ...
+
+
+@overload
+def _path_arg(
+    args: argparse.Namespace,
+    key: str,
+    explicit: Path | None,
+    *,
+    required: Literal[False],
+) -> Path | None: ...
+
+
+def _path_arg(
+    args: argparse.Namespace,
+    key: str,
+    explicit: Path | None,
+    *,
+    required: bool,
+) -> Path | None:
+    if explicit is not None:
+        return explicit.expanduser()
+    project = _project(args)
+    if project is not None:
+        value = project.path_value(key)
+        if value is not None:
+            return value
+    if required:
+        raise ValueError(f"missing --{key.replace('_', '-')} (or paths.{key} in project config)")
+    return None
+
+
+def _dx_stem_arg(
+    args: argparse.Namespace,
+    run: RunPaths,
+    *,
+    explicit: str | None,
+    required: bool,
+) -> str:
+    configured = _string_arg(
+        args,
+        "dx_stem",
+        explicit,
+        required=False,
+        aliases=("dialogue_stem", "dx_path", "dialogue_path"),
+    )
+    if configured:
+        return configured
+    derived = _derived_dialogue_stem(args, run)
+    if derived is not None:
+        return str(derived)
+    if required:
+        raise ValueError(
+            "missing --dx-stem (or paths.dx_stem/dialogue_stem in project config). "
+            "If you configured paths.full_audio, run `unrender audio separate -p <project>` first "
+            "so audio/source_separation.json can provide the generated DX stem."
+        )
+    return ""
+
+
+def _derived_dialogue_stem(args: argparse.Namespace, run: RunPaths) -> Path | None:
+    if run.source_separation_json.exists():
+        data = read_json(run.source_separation_json)
+        raw = str(data.get("dialogue_stem") or "").strip()
+        if raw:
+            path = Path(raw).expanduser()
+            if path.exists():
+                return path
+    prefix = _audio_output_prefix(args, run)
+    candidates = sorted(run.source_stems_dir.glob(f"{prefix}_DX_stem.*"))
+    return candidates[0] if candidates else None
+
+
+def _shot_speakers_arg(args: argparse.Namespace, run: RunPaths) -> dict[str, list[str]]:
+    explicit = getattr(args, "shot_matches", None)
+    path = explicit.expanduser() if explicit else run.shot_matches_json
+    if not path.exists():
+        return {}
+    data = read_json(path)
+    out: dict[str, list[str]] = {}
+    for row in data.get("shots") or []:
+        shot_id = str(row.get("shot_id") or "").strip()
+        if not shot_id:
+            continue
+        speakers = _speaker_values(row.get("accepted") or row.get("proposed_value") or "")
+        if speakers:
+            out[shot_id] = speakers
+    return out
+
+
+def _speaker_values(value: Any) -> list[str]:
+    if isinstance(value, list):
+        raw = value
+    else:
+        raw = str(value or "").replace(";", ",").split(",")
+    speakers: list[str] = []
+    for item in raw:
+        speaker = str(item or "").strip().upper()
+        if speaker and speaker not in speakers:
+            speakers.append(speaker)
+    return speakers
+
+
+def _string_arg(
+    args: argparse.Namespace,
+    key: str,
+    explicit: str | None,
+    *,
+    required: bool,
+    aliases: tuple[str, ...] = (),
+) -> str | None:
+    if explicit:
+        return explicit
+    project = _project(args)
+    if project is not None:
+        for candidate in (key, *aliases):
+            value = project.string_value(candidate)
+            if value:
+                return value
+    if required:
+        raise ValueError(f"missing --{key.replace('_', '-')} (or paths.{key} in project config)")
+    return None
+
+
+def _speaker_db_path(args: argparse.Namespace, explicit: Path | None, run: RunPaths) -> Path:
+    return _path_arg(args, "speaker_db", explicit, required=False) or run.speaker_db
+
+
+def _speaker_config_arg(args: argparse.Namespace) -> dict[str, Any]:
+    if getattr(args, "config", None) is not None:
+        return load_speaker_config(args.config.expanduser())
+    project = _project(args)
+    if project is not None:
+        return project.data
+    raise ValueError("missing --config (or -p/--project with speakers)")
+
+
+def _config_speaker_names(args: argparse.Namespace) -> list[str]:
+    project = _project(args)
+    if project is None:
+        return []
+    return [meta["name"] for meta in configured_speakers(project.data).values()]
+
+
+def _stem_sources_arg(
+    args: argparse.Namespace,
+    run: RunPaths,
+) -> list[StemSource]:
+    if args.stems:
+        return load_stem_sources(args.stems)
+    project = _project(args)
+    if project is not None:
+        stem_map = project.data.get("stem_map")
+        if stem_map:
+            if not isinstance(stem_map, dict):
+                raise ValueError(f"project config stem_map must be an object: {project.path}")
+            return load_stem_map(stem_map, speaker_names=_config_speaker_names(args))
+        separated = project.string_value("separated_stems")
+        if separated:
+            return load_stem_sources(separated)
+    return load_stem_sources(run.unmapped_speaker_glob)
+
+
+def _voice_clips_spec_arg(args: argparse.Namespace, run: RunPaths) -> str:
+    return (
+        args.clips
+        or _string_arg(args, "voice_clips", None, required=False, aliases=("clips",))
+        or _default_voice_clip_spec(run)
+    )
+
+
+def _default_voice_clip_spec(run: RunPaths) -> str:
+    return str(run.voice_clips_json) if run.voice_clips_json.exists() else run.voice_clips_glob
+
+
+def _default_voice_clone_plan(run: RunPaths) -> Path:
+    if run.dialogue_stem_plan_json.exists():
+        return run.dialogue_stem_plan_json
+    return run.clip_stem_plan_json
+
+
+def _section_arg(
+    args: argparse.Namespace,
+    section: str,
+    key: str,
+    explicit: Any,
+    default: Any,
+) -> Any:
+    if explicit is not None:
+        return explicit
+    project = _project(args)
+    if project is not None:
+        section_data = project.data.get(section) or {}
+        if not isinstance(section_data, dict):
+            raise ValueError(f"project config {section} must be an object: {project.path}")
+        value = section_data.get(key)
+        if value is not None:
+            return value
+    return default
+
+
+def _audio_arg(args: argparse.Namespace, key: str, explicit: Any, default: Any) -> Any:
+    return _section_arg(args, "audio", key, explicit, default)
+
+
+def _audio_output_prefix(args: argparse.Namespace, run: RunPaths) -> str:
+    configured = _audio_arg(args, "audioshake_prefix", getattr(args, "prefix", None), None)
+    if configured:
+        return safe_name(configured, fallback="audio")
+    project = _project(args)
+    if project is not None:
+        return safe_name(project.name, fallback="audio")
+    return safe_name(run.root.name, fallback="audio")
+
+
+def _face_arg(args: argparse.Namespace, key: str, explicit: Any, default: Any) -> Any:
+    return _section_arg(args, "face", key, explicit, default)
+
+
+def _voice_arg(args: argparse.Namespace, key: str, explicit: Any, default: Any) -> Any:
+    return _section_arg(args, "voice", key, explicit, default)
+
+
+def _shots_arg(args: argparse.Namespace, key: str, explicit: Any, default: Any) -> Any:
+    return _section_arg(args, "shots", key, explicit, default)
+
+
+def _voice_clone_arg(args: argparse.Namespace, key: str, explicit: Any, default: Any) -> Any:
+    return _section_arg(args, "voice_clone", key, explicit, default)
+
+
+def _timeline_arg(args: argparse.Namespace, key: str, explicit: Any, default: Any) -> Any:
+    return _section_arg(args, "timeline", key, explicit, default)
+
+
+def _voice_clone_speakers_arg(args: argparse.Namespace) -> list[str] | None:
+    if args.speakers:
+        return args.speakers
+    value = _voice_clone_arg(args, "speakers", None, None)
+    if isinstance(value, list):
+        return [str(item) for item in value if str(item).strip()]
+    if isinstance(value, str) and value.strip():
+        return [item.strip() for item in value.split(",") if item.strip()]
+    return None
+
+
+def _timeline_fps(args: argparse.Namespace, default: float) -> float:
+    explicit = getattr(args, "fps", None)
+    if explicit is not None:
+        return float(explicit)
+    project = _project(args)
+    if project is not None:
+        audio = project.data.get("audio")
+        if isinstance(audio, dict):
+            value = audio.get("fps") or audio.get("dub_script_fps")
+            if value is not None and value != "":
+                return float(value)
+        value = project.data.get("fps")
+        if value is not None and value != "":
+            return float(value)
+    return default
+
+
+def _audioshake_client(api_key: str):
+    from unrender.separation.audioshake import AudioShakeClient
+
+    return AudioShakeClient(api_key=api_key)
+
+
+def _bandit_settings(args: argparse.Namespace):
+    from unrender.separation.bandit import settings_from_values
+
+    bigshifts = _audio_arg(args, "bandit_bigshifts", args.bandit_bigshifts, None)
+    return settings_from_values(
+        config=_audio_arg(args, "bandit_config", args.bandit_config, None),
+        checkpoint=_audio_arg(args, "bandit_checkpoint", args.bandit_checkpoint, None),
+        device=_audio_arg(args, "bandit_device", args.bandit_device, None),
+        bigshifts=None if bigshifts in (None, "") else int(bigshifts),
+    )

unrender/cli/commands/export.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import argparse
+
+from unrender.cli.commands.context import _run_paths
+from unrender.exports.artifacts import export_artifacts
+
+
+def _export_artifacts(args: argparse.Namespace) -> int:
+    export_artifacts(
+        _run_paths(args, explicit=args.run), args.out.expanduser() if args.out else None
+    )
+    return 0

unrender/cli/commands/face.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import argparse
+
+from unrender.cli.commands.context import (
+    _face_arg,
+    _path_arg,
+    _run_paths,
+    _shots_arg,
+    _speaker_db_path,
+)
+from unrender.cli.helpers import threshold
+from unrender.identity.face import build_face_db, match_shots
+from unrender.manifests import load_shot_manifest
+
+
+def _face_build(args: argparse.Namespace) -> int:
+    run = _run_paths(args, explicit=args.out)
+    run.ensure()
+    build_face_db(
+        video_path=_path_arg(args, "proxy_master", args.video, required=True),
+        face_db_path=run.face_db,
+        review_dir=run.face_review_dir,
+        interval_sec=float(_face_arg(args, "interval", args.interval, 2.0)),
+        max_frames=args.max_frames or None,
+        threshold=float(_face_arg(args, "threshold", args.threshold, 0.5)),
+        min_cluster_size=int(_face_arg(args, "min_cluster_size", args.min_cluster_size, 5)),
+        min_confidence=float(_face_arg(args, "min_confidence", args.min_confidence, 0.5)),
+        min_face_px=int(_face_arg(args, "min_face_px", args.min_face_px, 36)),
+        force=args.force,
+    )
+    return 0
+
+
+def _shots_match(args: argparse.Namespace) -> int:
+    run = _run_paths(args, explicit=args.out)
+    run.ensure()
+    shots = load_shot_manifest(_path_arg(args, "shots", args.shots, required=True))
+    match_shots(
+        shots=shots,
+        speaker_db_path=_speaker_db_path(args, args.speaker_db, run),
+        output_json=run.shot_matches_json,
+        output_csv=run.shot_matches_csv,
+        samples_per_shot=int(_shots_arg(args, "samples_per_shot", args.samples_per_shot, 8)),
+        sim_threshold=threshold(
+            _shots_arg(args, "sim_threshold", args.sim_threshold, 0.45), "sim-threshold"
+        ),
+        min_confidence=threshold(
+            _shots_arg(args, "min_confidence", args.min_confidence, 0.5), "min-confidence"
+        ),
+        min_votes=int(_shots_arg(args, "min_votes", args.min_votes, 2)),
+        min_margin=float(_shots_arg(args, "min_margin", args.min_margin, 0.05)),
+    )
+    return 0