Skip to content

Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.

35.9 KB
Raw Blame
"""
Transcription service using OpenAI Whisper + speaker diarization.

Produces word-level timestamps with speaker labels by:
1. Running Whisper for speech-to-text with word timing
2. Running pyannote speaker diarization (if available)
3. Merging speaker labels onto each word and segment
"""

import json
import functools
import hashlib
import http.client
import importlib.util
import os
import shutil
import sys
import tempfile
import time
import urllib.error
import urllib.parse
import urllib.request
from typing import Optional, Callable

from services.engines import is_assemblyai_engine, is_omnilingual_engine, normalize_engine


def _managed_home() -> str:
    h = os.environ.get("PODCLI_HOME")
    if h:
        return h
    home = os.path.expanduser("~")
    if sys.platform == "darwin":
        return os.path.join(home, "Library", "Application Support", "podcli")
    if sys.platform == "win32":
        return os.environ.get("LOCALAPPDATA") or os.path.join(home, "AppData", "Local", "podcli")
    return os.environ.get("XDG_DATA_HOME") or os.path.join(home, ".local", "share", "podcli")


def _whispercpp_cli() -> Optional[str]:
    """Resolve the whisper.cpp binary: explicit env, PATH, then the hermetic
    runtime location the native installer provisions."""
    cli = os.environ.get("PODCLI_WHISPER_CLI")
    if cli and (os.path.exists(cli) or shutil.which(cli)):
        return cli
    found = shutil.which("whisper-cli") or shutil.which("whisper-cpp")
    if found:
        return found
    exe = "whisper-cli.exe" if sys.platform == "win32" else "whisper-cli"
    hermetic = os.path.join(_managed_home(), "runtime", "whisper", exe)
    return hermetic if os.path.exists(hermetic) else None



# "large" alone doesn't name a real ggml file (upstream ships v1/v2/v3/v3-turbo
# builds); provisioning always fetches large-v3, so resolve the same way here.
_WHISPERCPP_MODEL_ALIASES = {"large": "large-v3"}


def _whispercpp_model(model_size: str) -> str:
    resolved = _WHISPERCPP_MODEL_ALIASES.get(model_size, model_size)
    return os.environ.get("PODCLI_WHISPERCPP_MODEL") or os.path.join(
        _managed_home(), "models", f"ggml-{resolved}.bin"
    )


def _whispercpp_ready(model_size: str) -> bool:
    return _whispercpp_cli() is not None and os.path.exists(_whispercpp_model(model_size))


def _omnilingual_model() -> str:
    return os.environ.get("PODCLI_OMNILINGUAL_MODEL") or os.path.join(
        _managed_home(), "models", "omnilingual", "model.int8.onnx"
    )


def _omnilingual_tokens() -> str:
    return os.environ.get("PODCLI_OMNILINGUAL_TOKENS") or os.path.join(
        _managed_home(), "models", "omnilingual", "tokens.txt"
    )


def _omnilingual_ready() -> bool:
    return os.path.exists(_omnilingual_model()) and os.path.exists(_omnilingual_tokens())


def _omnilingual_model_fingerprint(model_path: str) -> str:
    """Cheap stand-in for hashing the whole model file: size+mtime changes
    whenever the file is replaced (re-provisioned, a different quantization
    swapped in), without reading potentially hundreds of MB on every run."""
    try:
        st = os.stat(model_path)
        return f"{st.st_size}-{int(st.st_mtime)}"
    except OSError:
        return "unknown"


def _whisper_threads() -> int:
    raw = os.environ.get("PODCLI_WHISPER_THREADS", "").strip()
    try:
        n = int(raw)
    except ValueError:
        n = 0
    return n if n > 0 else 4


def _transcribe_with_whispercpp(file_path, model_size, language, progress_callback, wav_path=None):
    from services import transcription_whispercpp as wcpp

    if progress_callback:
        progress_callback(10, "Transcribing with whisper.cpp...")

    cli = _whispercpp_cli() or "whisper-cli"
    model = _whispercpp_model(model_size)
    if not os.path.exists(model):
        raise FileNotFoundError(
            f"whisper.cpp model not found: {model}. "
            "Set PODCLI_WHISPERCPP_MODEL or run provisioning."
        )
    vad = os.environ.get("PODCLI_WHISPERCPP_VAD", "").strip().lower() in ("1", "true", "yes", "on")
    result = wcpp.transcribe_file(
        file_path,
        model_path=model,
        whisper_cli=cli,
        ffmpeg=os.environ.get("PODCLI_FFMPEG", "ffmpeg"),
        language=language,
        vad=vad,
        vad_model=os.environ.get("PODCLI_WHISPERCPP_VAD_MODEL") or None,
        wav_path=wav_path,
        threads=_whisper_threads(),
    )
    if progress_callback:
        progress_callback(50, "Transcription complete")
    return result


def _transcribe_with_omnilingual(file_path, progress_callback, wav_path=None):
    from config.paths import paths
    from services import transcribe_runs
    from services import transcription_omnilingual as omni

    if progress_callback:
        progress_callback(10, "Transcribing with omnilingual...")

    model = _omnilingual_model()
    tokens = _omnilingual_tokens()
    # Fetch only into podcli's own model folder; a custom model path is the
    # caller's to provide, and must never trigger a 1 GB download beside it.
    managed_dir = os.path.join(_managed_home(), "models", "omnilingual")
    if os.path.dirname(model) == managed_dir and os.path.dirname(tokens) == managed_dir:
        omni.ensure_model(managed_dir, progress_callback)
    if not os.path.exists(model) or not os.path.exists(tokens):
        raise FileNotFoundError(
            f"omnilingual model not found: {model}. "
            "Set PODCLI_OMNILINGUAL_MODEL/PODCLI_OMNILINGUAL_TOKENS or run provisioning."
        )

    # Resumable: a crash partway through a long file loses at most the
    # window that was decoding, not the whole run. A rerun with the same
    # file/model/language skips every window that already has a receipt.
    #
    # The key has to change whenever a resumed window's receipt would no
    # longer match what a fresh decode produces: a different model file (so
    # fold in its size+mtime, cheap to stat vs. hashing the whole model), or
    # a change to the window/context constants a receipt's timestamps are
    # only valid under (resuming under new constants would silently splice
    # old-geometry windows into a new-geometry transcript).
    model_fp = _omnilingual_model_fingerprint(model)
    run_dir = transcribe_runs.run_dir(
        paths["cache"], file_path, "omnilingual",
        model_size=f"int8-{model_fp}-w{omni.WINDOW_SECONDS}-c{omni.CONTEXT_SECONDS}",
        language="und",
    )

    def window_progress(pct, msg):
        if progress_callback:
            progress_callback(10 + int(pct * 0.4), msg)

    result = omni.transcribe_file(
        file_path,
        model_path=model,
        tokens_path=tokens,
        wav_path=wav_path,
        threads=_whisper_threads(),
        run_dir=run_dir,
        progress_callback=window_progress,
    )
    if progress_callback:
        progress_callback(50, "Transcription complete")
    return result


def _assemblyai_base_url() -> str:
    region = os.environ.get("ASSEMBLYAI_REGION", "").strip().lower()
    if region == "eu":
        return "https://api.eu.assemblyai.com/v2"
    return "https://api.assemblyai.com/v2"


class AssemblyAIHTTPError(RuntimeError):
    """Carries the HTTP status so callers can tell a bad/expired resource
    (4xx, e.g. the transcript a resumed receipt points at no longer exists)
    from a transient server error, without re-parsing the message string."""

    def __init__(self, message: str, status: int):
        super().__init__(message)
        self.status = status


def _assemblyai_json_request(method: str, url: str, api_key: str, payload: Optional[dict], timeout: int) -> dict:
    body = None if payload is None else json.dumps(payload).encode("utf-8")
    headers = {"Authorization": api_key}
    if body is not None:
        headers["Content-Type"] = "application/json"
    last_error = None
    for attempt in range(1, 4):
        try:
            req = urllib.request.Request(url, data=body, headers=headers, method=method)
            with urllib.request.urlopen(req, timeout=timeout) as res:
                return json.loads(res.read().decode("utf-8"))
        except urllib.error.HTTPError as e:
            detail = e.read().decode("utf-8", errors="replace")
            last_error = AssemblyAIHTTPError(
                f"AssemblyAI request failed: method={method} url={url} status={e.code} body={detail}",
                status=e.code,
            )
            if e.code not in (408, 409, 425, 429) and e.code < 500:
                raise last_error from e
            print(
                f"Warning: AssemblyAI request retry {attempt}/3 failed: method={method} url={url} status={e.code} body={detail}",
                file=sys.stderr,
            )
            if attempt < 3:
                time.sleep(attempt)
        except (urllib.error.URLError, TimeoutError) as e:
            last_error = e
            print(
                f"Warning: AssemblyAI request retry {attempt}/3 failed: method={method} url={url} error={e}",
                file=sys.stderr,
            )
            if attempt < 3:
                time.sleep(attempt)
    raise RuntimeError(
        f"AssemblyAI request failed after retries: method={method} url={url} error={last_error}"
    ) from last_error


def _assemblyai_upload(file_path: str, api_key: str, base_url: str) -> str:
    url = f"{base_url}/upload"
    parsed = urllib.parse.urlparse(url)
    if parsed.scheme != "https" or not parsed.netloc:
        raise RuntimeError(f"AssemblyAI upload URL is invalid: url={url}")

    last_error = None
    for attempt in range(1, 4):
        conn = None
        try:
            size = os.path.getsize(file_path)
            conn = http.client.HTTPSConnection(parsed.netloc, timeout=3600)
            conn.putrequest("POST", parsed.path)
            conn.putheader("Authorization", api_key)
            conn.putheader("Content-Type", "application/octet-stream")
            conn.putheader("Content-Length", str(size))
            conn.endheaders()
            with open(file_path, "rb") as f:
                while True:
                    chunk = f.read(1024 * 1024)
                    if not chunk:
                        break
                    conn.send(chunk)

            res = conn.getresponse()
            detail = res.read().decode("utf-8", errors="replace")
            if res.status < 200 or res.status >= 300:
                last_error = RuntimeError(
                    f"AssemblyAI upload failed: url={url} file_path={file_path} status={res.status} body={detail}"
                )
                if res.status not in (408, 409, 425, 429) and res.status < 500:
                    raise last_error
                print(
                    f"Warning: AssemblyAI upload retry {attempt}/3 failed: file_path={file_path} status={res.status} body={detail}",
                    file=sys.stderr,
                )
                if attempt < 3:
                    time.sleep(attempt)
                continue

            data = json.loads(detail)
            upload_url = data.get("upload_url")
            if not upload_url:
                raise RuntimeError(f"AssemblyAI upload response missing upload_url: body={data}")
            return upload_url
        except (OSError, TimeoutError, http.client.HTTPException) as e:
            last_error = e
            print(
                f"Warning: AssemblyAI upload retry {attempt}/3 failed: file_path={file_path} error={e}",
                file=sys.stderr,
            )
            if attempt < 3:
                time.sleep(attempt)
        finally:
            if conn:
                conn.close()
    raise RuntimeError(
        f"AssemblyAI upload failed after retries: url={url} file_path={file_path} error={last_error}"
    ) from last_error


def _assemblyai_speaker(raw_speaker: Optional[str]) -> Optional[str]:
    if raw_speaker is None:
        return None
    label = str(raw_speaker).strip()
    if not label:
        return None
    if len(label) == 1 and label.isalpha():
        return f"SPEAKER_{ord(label.upper()) - ord('A'):02d}"
    return label


def _assemblyai_words(data: dict) -> list[dict]:
    return [
        {
            "word": str(w.get("text", "")).strip(),
            "start": round(float(w.get("start", 0)) / 1000.0, 3),
            "end": round(float(w.get("end", 0)) / 1000.0, 3),
            "confidence": round(float(w.get("confidence", 0)), 3),
            "speaker": _assemblyai_speaker(w.get("speaker")),
        }
        for w in data.get("words", [])
        if str(w.get("text", "")).strip()
    ]


def _assemblyai_result(data: dict) -> dict:
    words = _assemblyai_words(data)
    utterances = data.get("utterances") or []
    if utterances:
        segments = [
            {
                "id": i,
                "start": round(float(u.get("start", 0)) / 1000.0, 3),
                "end": round(float(u.get("end", 0)) / 1000.0, 3),
                "text": str(u.get("text", "")).strip(),
                "speaker": _assemblyai_speaker(u.get("speaker")),
            }
            for i, u in enumerate(utterances)
            if str(u.get("text", "")).strip()
        ]
    else:
        segments = [{
            "id": 0,
            "start": words[0]["start"] if words else 0.0,
            "end": words[-1]["end"] if words else 0.0,
            "text": str(data.get("text") or "").strip(),
            "speaker": None,
        }]

    speaker_segments = [
        {
            "speaker": segment["speaker"],
            "start": segment["start"],
            "end": segment["end"],
        }
        for segment in segments
        if segment["speaker"]
    ]
    speakers = sorted({s["speaker"] for s in speaker_segments})
    speaker_map = {
        speaker: {
            "label": speaker,
            "total_time": round(
                sum(s["end"] - s["start"] for s in speaker_segments if s["speaker"] == speaker),
                2,
            ),
            "segments": sum(1 for s in speaker_segments if s["speaker"] == speaker),
        }
        for speaker in speakers
    }
    return {
        "transcript": str(data.get("text") or "").strip(),
        "segments": segments,
        "words": words,
        "duration": round(float(data.get("audio_duration") or (words[-1]["end"] if words else 0.0)), 3),
        "language": str(data.get("language_code") or "en"),
        "speakers": {
            "num_speakers": len(speakers),
            "speakers": speaker_map,
        },
        "speaker_segments": speaker_segments,
        "engine": "assemblyai",
    }


def _transcribe_with_assemblyai(file_path, language, enable_diarization, num_speakers, progress_callback):
    from config.paths import paths
    from services import transcribe_runs

    api_key = os.environ.get("ASSEMBLYAI_API_KEY", "").strip()
    if not api_key:
        raise RuntimeError("ASSEMBLYAI_API_KEY is required when PODCLI_ENGINE=assemblyai")

    base_url = _assemblyai_base_url()
    region = os.environ.get("ASSEMBLYAI_REGION", "").strip().lower() or "us"
    key_hash = hashlib.sha256(api_key.encode("utf-8")).hexdigest()[:8]
    # A restarted job (crash, kill, machine reboot) must resume by polling
    # the transcript it already started, not re-upload the file and pay for
    # a second AssemblyAI job. The receipt is keyed by exactly what affects
    # the AssemblyAI request (language, diarization, speaker count, region,
    # which account) so a different request for the same file never adopts
    # someone else's job: a region or key mismatch would otherwise poll a
    # transcript ID that belongs to a different account/API surface.
    directory = transcribe_runs.run_dir(
        paths["cache"], file_path, "assemblyai",
        model_size=f"diar{int(bool(enable_diarization))}-spk{num_speakers or 0}-{region}-{key_hash}",
        language=language,
    )

    # A resumed transcript_id that 4xxs on the resume GET (e.g. AssemblyAI
    # deleted it after its retention window, or it belonged to a key that's
    # since been rotated) is permanently bad: retrying it forever would
    # never succeed. Clear the receipt and fall through to a fresh upload,
    # once.
    for resume_attempt in (True, False):
        receipt = transcribe_runs.read_receipt(directory, "assemblyai.json") if resume_attempt else None
        transcript_id = receipt.get("transcript_id") if receipt else None
        resumed = transcript_id is not None

        if not transcript_id:
            if progress_callback:
                progress_callback(10, "Uploading media to AssemblyAI...")
            upload_url = _assemblyai_upload(file_path, api_key, base_url)

            payload = {
                "audio_url": upload_url,
                "punctuate": True,
                "format_text": True,
                "speaker_labels": bool(enable_diarization),
            }
            if language:
                payload["language_code"] = language
            else:
                payload["language_detection"] = True
            if num_speakers:
                payload["speakers_expected"] = num_speakers

            if progress_callback:
                progress_callback(20, "Starting AssemblyAI transcript...")
            started = _assemblyai_json_request("POST", f"{base_url}/transcript", api_key, payload, 60)
            transcript_id = started.get("id")
            if not transcript_id:
                raise RuntimeError(f"AssemblyAI transcript response missing id: body={started}")
            # Written before the poll loop starts: if the process dies mid-poll,
            # the next run finds this and resumes instead of re-uploading.
            transcribe_runs.write_receipt(directory, "assemblyai.json", {"transcript_id": transcript_id})
        elif progress_callback:
            progress_callback(20, f"Resuming AssemblyAI transcript {transcript_id}...")

        url = f"{base_url}/transcript/{transcript_id}"
        try:
            for _ in range(720):
                data = _assemblyai_json_request("GET", url, api_key, None, 60)
                status = data.get("status")
                if status == "completed":
                    if progress_callback:
                        progress_callback(50, "AssemblyAI transcription complete")
                    transcribe_runs.clear_run(directory)
                    return _assemblyai_result(data)
                if status == "error":
                    transcribe_runs.clear_run(directory)
                    raise RuntimeError(
                        f"AssemblyAI transcript failed: transcript_id={transcript_id} error={data.get('error')}"
                    )
                if status not in ("queued", "processing"):
                    raise RuntimeError(
                        f"AssemblyAI transcript returned unknown status: transcript_id={transcript_id} status={status} body={data}"
                    )
                if progress_callback:
                    progress_callback(30, f"AssemblyAI transcript {status}...")
                time.sleep(5)
            raise TimeoutError(f"AssemblyAI transcript timed out: transcript_id={transcript_id}")
        except AssemblyAIHTTPError as e:
            if resumed and 400 <= e.status < 500:
                transcribe_runs.clear_run(directory)
                if progress_callback:
                    progress_callback(
                        10, f"Saved AssemblyAI transcript {transcript_id} is gone (status {e.status}); re-uploading..."
                    )
                continue
            raise
    raise RuntimeError("AssemblyAI resume retry exhausted")  # unreachable: loop always returns or raises


def _attach_speakers_and_faces(
    file_path,
    base,
    enable_diarization,
    num_speakers,
    progress_callback,
    wav_path=None,
):
    """Merge speaker diarization + face analysis into a transcribed result.
    Shared by both engines; face analysis (OpenCV) runs even when diarization
    is unavailable."""
    segments = base.get("segments") or []
    words = base.get("words") or []
    duration = base.get("duration") or (segments[-1]["end"] if segments else 0.0)

    speaker_segments = base.get("speaker_segments") or []
    speaker_summary = base.get("speakers") or {"num_speakers": 0, "speakers": {}}
    diarization_warning = None

    if enable_diarization:
        try:
            from services.speaker_detection import (
                extract_audio_wav,
                run_diarization,
                assign_speakers_to_segments,
                assign_speakers_to_words,
                create_speaker_summary,
            )

            if progress_callback:
                progress_callback(55, "Extracting audio for speaker detection...")

            shared_wav = wav_path if wav_path and os.path.exists(wav_path) else None
            if shared_wav:
                diar_wav = shared_wav
            else:
                with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
                    diar_wav = tmp.name

            try:
                if not shared_wav:
                    extract_audio_wav(file_path, diar_wav)

                if progress_callback:
                    progress_callback(60, "Running speaker diarization...")

                speaker_segments = run_diarization(
                    diar_wav,
                    num_speakers=num_speakers,
                    progress_callback=lambda pct, msg: (
                        progress_callback(60 + int(pct * 0.3), msg) if progress_callback else None
                    ),
                )

                if speaker_segments:
                    if progress_callback:
                        progress_callback(92, "Assigning speakers to transcript...")

                    segments = assign_speakers_to_segments(segments, speaker_segments)
                    words = assign_speakers_to_words(words, speaker_segments)
                    speaker_summary = create_speaker_summary(speaker_segments)

                    if progress_callback:
                        progress_callback(
                            95,
                            f"Found {speaker_summary['num_speakers']} speakers",
                        )

            finally:
                if not shared_wav and os.path.exists(diar_wav):
                    os.unlink(diar_wav)

        except ImportError as e:
            diarization_warning = f"Speaker detection unavailable: {e}"
            if progress_callback:
                progress_callback(90, diarization_warning)
        except PermissionError as e:
            diarization_warning = str(e)
            if progress_callback:
                progress_callback(90, diarization_warning)
        except Exception as e:
            diarization_warning = f"Speaker detection failed: {e}"
            if progress_callback:
                progress_callback(90, diarization_warning)
    else:
        if not speaker_segments:
            diarization_warning = "Speaker detection disabled"

    face_map = None
    try:
        if progress_callback:
            progress_callback(95, "Analyzing face positions...")
        from services.face_analysis import analyze_faces

        face_map = analyze_faces(
            video_path=file_path,
            speaker_segments=speaker_segments,
            duration=duration,
        )
    except Exception as e:
        print(f"Warning: face analysis failed: {e}", file=sys.stderr)

    if progress_callback:
        progress_callback(100, "Complete")

    base["segments"] = segments
    base["words"] = words
    base["duration"] = round(duration, 3)
    base["speakers"] = speaker_summary
    base["speaker_segments"] = speaker_segments
    if face_map:
        base["face_map"] = face_map
    if diarization_warning:
        base["diarization_warning"] = diarization_warning
    return base


@functools.lru_cache(maxsize=1)
def _whisper_py_available() -> bool:
    """Cheap availability check for the openai-whisper package.

    `import whisper` doesn't just find the module, it executes it, which
    transitively imports torch and costs hundreds of ms to seconds.
    resolve_engine_info runs this on every single transcribe request (it's
    a cache-key prediction, not an actual transcription), so it uses
    find_spec, which only locates the module and never runs its code, and
    memoizes the result, since whether the package is installed can't
    change within a process's lifetime.
    """
    try:
        return importlib.util.find_spec("whisper") is not None
    except (ImportError, ValueError):
        # find_spec itself can raise if "whisper" is already in sys.modules
        # under a module object missing __spec__ (a malformed stand-in, not
        # a real install state). Fall back to treating that as available
        # rather than crashing a cache-key prediction over it.
        return True


def _resolve_whisper_py_fallback(requested: Optional[str], model_size: str, probe_model: bool):
    """Single source of truth for "should an unset whisper-py request fall
    back to whispercpp instead": the one decision resolve_engine_info and
    transcribe_file both have to make the same way, or a cache key built
    from one's answer misses the transcript the other actually wrote.

    probe_model=False (resolve_engine_info, a cache-key prediction made on
    every request, so it can't afford to load model weights, or even
    import whisper for real, see _whisper_py_available) only checks
    whether the package is installed. probe_model=True (transcribe_file,
    about to actually transcribe) does the real import and loads the
    model, catching the one case the cheap check can't: the package is
    present but load_model fails. That gap means a cache lookup built from
    resolve_engine_info's prediction can still miss once in that rarer
    case, before the result is written under the engine transcribe_file
    actually ran with.

    Returns (fall_back_to_whispercpp, loaded_model_or_None, error_or_None).
    """
    if not probe_model:
        if _whisper_py_available():
            return False, None, None
        if not requested and _whispercpp_ready(model_size):
            return True, None, None
        return False, None, None

    try:
        import whisper

        model = whisper.load_model(model_size)
        return False, model, None
    except Exception as e:
        if not requested and _whispercpp_ready(model_size):
            return True, None, None
        return False, None, e


def resolve_engine_info(requested: Optional[str], model_size: str = "base") -> dict:
    """Predict which engine transcribe_file will actually use, without doing
    any transcription work. Callers cache transcripts by engine; the cache
    key has to match what transcribe_file resolves to, not the raw request,
    or an unset engine writes under one key and reads under another.
    """
    requested = requested if requested is not None else os.environ.get("PODCLI_ENGINE", "")
    engine = normalize_engine(requested)
    if engine != "whisper-py":
        return {"engine": engine, "model_size": model_size}
    fall_back, _model, _error = _resolve_whisper_py_fallback(requested, model_size, probe_model=False)
    return {"engine": "whispercpp" if fall_back else "whisper-py", "model_size": model_size}


def transcribe_file(
    file_path: str,
    model_size: str = "base",
    engine: Optional[str] = None,
    language: Optional[str] = None,
    enable_diarization: bool = True,
    num_speakers: Optional[int] = None,
    progress_callback: Optional[Callable[[int, str], None]] = None,
    wav_path: Optional[str] = None,
    start_seconds: Optional[float] = None,
    duration_seconds: Optional[float] = None,
) -> dict:
    """
    Transcribe a video/audio file with word-level timestamps and speaker detection.

    wav_path: optional pre-extracted 16 kHz mono WAV shared across analysis
    stages: used by whisper.cpp and diarization instead of re-decoding.

    start_seconds/duration_seconds: sample mode, transcribe only a window of
    the source (e.g. to test a language on 40s before committing to a full
    run) instead of the whole file. The result is marked complete: False and
    its timestamps are relative to the sample window, not the source;
    sample_offset_seconds carries where in the source the window started.
    Diarization and face analysis are skipped: a throwaway sample isn't
    worth the extra passes, and both would need frame/audio access to the
    original file that the trimmed clip doesn't carry.

    Returns:
        {
            "transcript": str,
            "segments": [{id, start, end, text, speaker}, ...],
            "words": [{word, start, end, confidence, speaker}, ...],
            "duration": float,
            "language": str,
            "speakers": {num_speakers, speakers: {SPEAKER_00: {total_time, segments, label}, ...}},
            "speaker_segments": [{speaker, start, end}, ...]
        }
    """
    if not os.path.exists(file_path):
        raise FileNotFoundError(f"File not found: {file_path}")

    # Matches backend/main.py's handle_transcribe and both TS transcribe
    # entry points exactly: a sample is a positive window, not merely a
    # present key, so start_seconds=0/duration_seconds=0 or an explicit
    # null both mean "no sample" rather than "sample from t=0".
    is_sample = (duration_seconds or 0) > 0 or (start_seconds or 0) > 0
    if is_sample:
        from services.audio_extract import extract_wav_16k_mono

        sample_wav = extract_wav_16k_mono(
            file_path,
            start_seconds=start_seconds or 0.0,
            duration_seconds=duration_seconds,
        )
        try:
            result = _transcribe_file_inner(
                sample_wav,
                model_size=model_size,
                engine=engine,
                language=language,
                enable_diarization=False,
                num_speakers=num_speakers,
                progress_callback=progress_callback,
                wav_path=sample_wav,
            )
        finally:
            try:
                os.unlink(sample_wav)
            except OSError:
                pass
        result["complete"] = False
        result["sample_offset_seconds"] = start_seconds or 0.0
        return result

    return _transcribe_file_inner(
        file_path,
        model_size=model_size,
        engine=engine,
        language=language,
        enable_diarization=enable_diarization,
        num_speakers=num_speakers,
        progress_callback=progress_callback,
        wav_path=wav_path,
    )


def _transcribe_file_inner(
    file_path: str,
    model_size: str = "base",
    engine: Optional[str] = None,
    language: Optional[str] = None,
    enable_diarization: bool = True,
    num_speakers: Optional[int] = None,
    progress_callback: Optional[Callable[[int, str], None]] = None,
    wav_path: Optional[str] = None,
) -> dict:

    requested = engine if engine is not None else os.environ.get("PODCLI_ENGINE", "")
    engine = normalize_engine(requested)
    use_cpp = engine == "whispercpp"
    use_assemblyai = is_assemblyai_engine(engine)
    use_omnilingual = is_omnilingual_engine(engine)

    if use_assemblyai:
        base = _transcribe_with_assemblyai(
            file_path, language, enable_diarization, num_speakers, progress_callback
        )
        # AssemblyAI does its own diarization (speaker_labels in the request),
        # not the pyannote path _attach_speakers_and_faces runs below. Record
        # against the flag that actually drove that request, not the False
        # passed to attach (which only controls the pyannote attempt here).
        base["diarization_attempted"] = bool(enable_diarization)
        return _attach_speakers_and_faces(file_path, base, False, num_speakers, progress_callback)

    if use_omnilingual:
        base = _transcribe_with_omnilingual(file_path, progress_callback, wav_path=wav_path)
        base["engine"] = "omnilingual"
        # Same no-torch constraint as whisper.cpp: skip diarization, keep face analysis.
        # Diarization is never possible on this engine, so it's never
        # "attempted" regardless of what the caller asked for: a cache
        # entry from this engine must never look like a retriable miss.
        base["diarization_attempted"] = False
        return _attach_speakers_and_faces(
            file_path, base, False, num_speakers, progress_callback, wav_path=wav_path
        )

    # Native installs ship whisper.cpp, not openai-whisper. Fall back to it
    # automatically: whether whisper is missing OR a broken install fails to
    # load/run: unless the user explicitly asked for the whisper-py engine.
    if not use_cpp:
        if progress_callback:
            progress_callback(5, "Loading Whisper model...")
        fall_back, model, error = _resolve_whisper_py_fallback(requested, model_size, probe_model=True)
        if fall_back:
            use_cpp = True
        elif error is not None:
            raise RuntimeError(
                "The whisper-py engine needs the full source install (openai-whisper + torch). "
                "This native install ships whisper.cpp. Rerun with --engine whispercpp."
            ) from error

    if use_cpp:
        base = _transcribe_with_whispercpp(
            file_path, model_size, language, progress_callback, wav_path=wav_path
        )
        base["engine"] = "whispercpp"
        # whisper.cpp is the no-torch path: importing torch for diarization can
        # hard-crash native runtimes. Skip diarization, keep face analysis (OpenCV).
        # Never possible on this engine, see the omnilingual branch above.
        base["diarization_attempted"] = False
        return _attach_speakers_and_faces(
            file_path, base, False, num_speakers, progress_callback
        )

    # ================================================================
    # Step 1: Whisper transcription
    # ================================================================
    if progress_callback:
        progress_callback(10, f"Transcribing with Whisper ({model_size})...")

    result = model.transcribe(
        file_path,
        language=language,
        word_timestamps=True,
        verbose=False,
    )

    if progress_callback:
        progress_callback(50, "Processing timestamps...")

    segments = []
    words = []

    for seg in result.get("segments", []):
        segments.append(
            {
                "id": seg["id"],
                "start": round(seg["start"], 3),
                "end": round(seg["end"], 3),
                "text": seg["text"].strip(),
                "speaker": None,  # Will be filled by diarization
            }
        )

        seg_words = seg.get("words", [])
        if seg_words:
            for w in seg_words:
                words.append(
                    {
                        "word": w.get("word", "").strip(),
                        "start": round(w.get("start", 0), 3),
                        "end": round(w.get("end", 0), 3),
                        "confidence": round(w.get("probability", 0), 3),
                        "speaker": None,
                    }
                )
        else:
            text = seg["text"].strip()
            if not text:
                continue
            seg_words_list = text.split()
            seg_start = seg["start"]
            seg_end = seg["end"]
            seg_duration = seg_end - seg_start

            if len(seg_words_list) == 0:
                continue

            word_duration = seg_duration / len(seg_words_list)

            for i, word_text in enumerate(seg_words_list):
                w_start = seg_start + i * word_duration
                w_end = w_start + word_duration
                words.append(
                    {
                        "word": word_text,
                        "start": round(w_start, 3),
                        "end": round(w_end, 3),
                        "confidence": 0.5,
                        "speaker": None,
                    }
                )

    duration = result.get("duration", 0)
    if not duration and segments:
        duration = segments[-1]["end"]

    detected_lang = result.get("language", language or "en")

    base = {
        "transcript": result.get("text", "").strip(),
        "segments": segments,
        "words": words,
        "duration": duration,
        "language": detected_lang,
        "engine": "whisper-py",
        "diarization_attempted": bool(enable_diarization),
    }
    return _attach_speakers_and_faces(
        file_path, base, enable_diarization, num_speakers, progress_callback,
        wav_path=wav_path,
    )