"""Video ingest: probe files in ``data/raw`` and extract audio (spec M1, lane A).

STUB — lane A fills the bodies; the public signatures below are frozen (``cli.py`` calls
``run_ingest``). For each file in ``config.RAW_DIR``: ffprobe it, insert/update the
``videos`` row via ``db`` helpers, and extract a mono 16 kHz WAV into ``config.AUDIO_DIR``.
"""

from __future__ import annotations

import logging
from pathlib import Path

log = logging.getLogger("festival4d.ingest")


def probe_video(path: Path) -> dict:
    """ffprobe a video; return ``{duration_s, fps, width, height}`` (lane A / M1)."""
    raise NotImplementedError("lane A (M1): implement probe_video")


def extract_audio(path: Path, out_wav: Path, sample_rate: int = 16_000) -> Path:
    """Extract a mono ``sample_rate`` WAV from ``path`` via ffmpeg (lane A / M1)."""
    raise NotImplementedError("lane A (M1): implement extract_audio")


def run_ingest() -> list[dict]:
    """Ingest every video in ``config.RAW_DIR``: probe, register in DB, extract audio.

    Entrypoint for ``python -m festival4d ingest``. Returns a per-video summary list.
    """
    raise NotImplementedError("lane A (M1): implement run_ingest")