openmd-cli 0.1.0__py3-none-any.whl

openmd/adapters/local_audio/adapter.py

@@ -0,0 +1,169 @@
+"""Adapter for user-local audio files.
+
+This lane is deliberately local and read-only: it resolves audio files into
+``ContentItem`` records and leaves transcription to an explicit backend
+provider.  Raw audio is referenced as a local source and is not copied into the
+package writer's ``assets/`` directory.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+import hashlib
+
+from openmd.adapters.base import PlatformAdapter
+from openmd.core.detector import MEDIA_EXTENSIONS
+from openmd.core.models import ContentItem, TranscriptResult
+
+from .asr import MissingASRBackend, MockASRBackend
+
+FASTER_WHISPER_BACKEND = "asr.faster_whisper"
+QWEN3_BACKEND = "asr.qwen3"
+AUTO_BACKEND = "asr.auto"
+
+AUDIO_EXTENSIONS: tuple[str, ...] = (
+    ".mp3",
+    ".mp4",
+    ".m4a",
+    ".wav",
+    ".ogg",
+    ".flac",
+    ".opus",
+    ".aac",
+)
+
+
+class LocalAudioAdapter(PlatformAdapter):
+    """Resolve local audio files or folders into media items."""
+
+    def __init__(self, platform_id: str = "generic_media", default_backend: str = "asr.fallback") -> None:
+        self.id = platform_id
+        self.default_backend = default_backend
+
+    def can_handle(self, input_value: str) -> bool:
+        path = local_path_from_input(input_value)
+        return path is not None and _is_audio_path(path)
+
+    def resolve_items(
+        self,
+        input_value: str,
+        *,
+        limit: int | None = None,
+        all: bool = False,
+    ) -> list[ContentItem]:
+        path = local_path_from_input(input_value)
+        if path is None:
+            return [
+                _content_item_for_unresolved_input(
+                    input_value,
+                    platform=self.id,
+                    error_code="local_audio_path_unresolved",
+                )
+            ]
+
+        if path.is_dir():
+            files = sorted(candidate for candidate in path.rglob("*") if _is_audio_path(candidate))
+            if limit is not None and not all:
+                files = files[: max(0, limit)]
+            return [_content_item_for_path(candidate, platform=self.id) for candidate in files]
+
+        return [_content_item_for_path(path, platform=self.id)]
+
+    def extract_text(
+        self,
+        item: ContentItem,
+        *,
+        backend: str | None = None,
+        backend_chain: tuple[str, ...] | None = None,
+        allow_fallback: bool = True,
+    ) -> TranscriptResult:
+        selected = (backend_chain or (backend or self.default_backend,))[0]
+        path = _item_path(item)
+        if selected == "local_audio.mock":
+            return MockASRBackend().transcribe(path)
+        if selected in {FASTER_WHISPER_BACKEND, AUTO_BACKEND, QWEN3_BACKEND}:
+            from openmd.runtime.asr import get_asr_backend
+
+            return get_asr_backend(selected).transcribe(path)
+        return MissingASRBackend(selected).transcribe(path)
+
+
+def local_path_from_input(input_value: str) -> Path | None:
+    value = input_value.strip()
+    if not value:
+        return None
+
+    parsed = urlparse(value)
+    if parsed.scheme == "file":
+        # urlparse("file:///C:/tmp/a.wav").path -> "/C:/tmp/a.wav".
+        raw_path = unquote(parsed.path)
+        if parsed.netloc and not raw_path:
+            raw_path = parsed.netloc
+        if raw_path.startswith("/") and len(raw_path) >= 4 and raw_path[2] == ":":
+            raw_path = raw_path[1:]
+        return Path(raw_path)
+
+    if parsed.scheme in {"http", "https"}:
+        return None
+
+    return Path(value)
+
+
+def _content_item_for_path(path: Path, *, platform: str) -> ContentItem:
+    source_ref = path.resolve().as_uri() if path.exists() else str(path)
+    return ContentItem(
+        platform=platform,
+        input_type="single",
+        url=source_ref,
+        id=_audio_content_id(path),
+        title=path.stem,
+        source_type="audio",
+        raw_meta={
+            "profile": "media",
+            "permission_scope": "local_file",
+            "local_path": str(path),
+            "content_id": _audio_content_id(path),
+        },
+    )
+
+
+def _content_item_for_unresolved_input(
+    input_value: str,
+    *,
+    platform: str,
+    error_code: str,
+) -> ContentItem:
+    return ContentItem(
+        platform=platform,
+        input_type="single",
+        url=input_value,
+        source_type="audio",
+        raw_meta={
+            "profile": "media",
+            "permission_scope": "local_file",
+            "error_code": error_code,
+        },
+    )
+
+
+def _is_audio_path(path: Path) -> bool:
+    return path.suffix.lower() in AUDIO_EXTENSIONS or path.suffix.lower() in MEDIA_EXTENSIONS
+
+
+def _audio_content_id(path: Path) -> str:
+    if path.is_file():
+        digest = hashlib.sha256()
+        with path.open("rb") as handle:
+            for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                digest.update(chunk)
+        return digest.hexdigest()[:12]
+    return hashlib.sha256(str(path).encode("utf-8")).hexdigest()[:12]
+
+
+def _item_path(item: ContentItem) -> Path:
+    local_path = item.raw_meta.get("local_path") if isinstance(item.raw_meta, dict) else None
+    if isinstance(local_path, str) and local_path.strip():
+        return Path(local_path)
+    path = local_path_from_input(item.url)
+    return path or Path(item.url)

openmd/adapters/local_audio/asr.py

@@ -0,0 +1,58 @@
+"""Local audio ASR backend abstractions."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from openmd.core.models import TranscriptResult
+from openmd.core.secrets import sanitize_error_summary
+
+
+class ASRBackend(ABC):
+    name: str
+
+    @abstractmethod
+    def transcribe(self, path: Path) -> TranscriptResult:
+        raise NotImplementedError
+
+
+class MockASRBackend(ASRBackend):
+    name = "local_audio.mock"
+
+    def transcribe(self, path: Path) -> TranscriptResult:
+        return TranscriptResult(
+            text="[00:00:00] Mock local audio transcript for Openmd package smoke.\n",
+            status="verified",
+            source_level="asr",
+            backend=self.name,
+            source_notes=[
+                "local audio mock backend only",
+                "raw audio file was referenced, not copied into the package",
+            ],
+            title=path.stem or "local audio",
+            metadata={"profile": "media", "asr_backend": self.name},
+        )
+
+
+class MissingASRBackend(ASRBackend):
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def transcribe(self, path: Path) -> TranscriptResult:
+        return TranscriptResult(
+            text="",
+            status="failed",
+            source_level="partial_extraction",
+            backend=self.name,
+            source_notes=[
+                "local audio ASR backend is not installed or not enabled",
+                "no external ASR command was attempted",
+            ],
+            error_code="asr_backend_missing",
+            error_summary=sanitize_error_summary(
+                f"ASR backend {self.name!r} is not installed or enabled for {path.name}."
+            ),
+            title=path.stem or "local audio",
+            metadata={"profile": "media", "asr_backend": self.name},
+        )

openmd/adapters/local_audio/backends/__init__.py

@@ -0,0 +1 @@
+"""Optional real local-audio backend adapters."""

openmd/adapters/local_audio/backends/auto.py

@@ -0,0 +1,177 @@
+"""Pick the local ASR model from the spoken language.
+
+Routing follows the 2026-11-07 benchmark (quality 80%, speed 20%), recorded in
+``docs/benchmarks/asr/``:
+
+- Mandarin: Qwen3-ASR (lowest CER, fewest dropped characters) when its GPU stack is
+  installed; otherwise Whisper large-v3.
+- English: Whisper large-v3-turbo (best weighted score, 3.5x faster than large-v3).
+- Anything else: Whisper large-v3.
+
+The language is detected once with the English model, which is also the fastest one.
+Every choice can be overridden by environment variables listed in ``execution_config``.
+"""
+
+from __future__ import annotations
+
+import gc
+import importlib.util
+import os
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+from openmd.adapters.local_audio.asr import ASRBackend, MissingASRBackend
+from openmd.adapters.local_audio.backends.faster_whisper import (
+    FasterWhisperASRBackend,
+    _prepare_windows_dll_paths,
+)
+from openmd.adapters.local_audio.backends.qwen3_asr import Qwen3ASRBackend
+from openmd.core.models import TranscriptResult
+from openmd.runtime.models import ModelNotFoundError, model_label, offline_model_loading, require_model, resolve_model
+
+DEFAULT_ENGLISH_MODEL = "large-v3-turbo"
+DEFAULT_GENERAL_MODEL = "large-v3"
+
+
+class AutoASRBackend(ASRBackend):
+    name = "asr.auto"
+
+    def __init__(self, *, qwen3: Qwen3ASRBackend | None = None) -> None:
+        self.english_model = os.getenv("OPENMD_ASR_AUTO_EN_MODEL") or DEFAULT_ENGLISH_MODEL
+        self.general_model = os.getenv("OPENMD_FASTER_WHISPER_MODEL") or DEFAULT_GENERAL_MODEL
+        self.chinese_engine = os.getenv("OPENMD_ASR_AUTO_ZH_ENGINE") or "qwen3"
+        self._qwen3 = qwen3
+
+    def execution_config(self) -> dict[str, Any]:
+        return {
+            "english_model": model_label(self.english_model),
+            "english_model_origin": resolve_model(self.english_model, family="whisper").origin,
+            "general_model": model_label(self.general_model),
+            "general_model_origin": resolve_model(self.general_model, family="whisper").origin,
+            "chinese_engine": self.chinese_engine,
+            "qwen3": (self._qwen3 or Qwen3ASRBackend()).execution_config(),
+            "device": os.getenv("OPENMD_FASTER_WHISPER_DEVICE") or "cuda_if_available",
+            "local_files_only": True,
+        }
+
+    def is_available(self) -> bool:
+        return importlib.util.find_spec("faster_whisper") is not None
+
+    def transcribe(self, path: Path) -> TranscriptResult:
+        source_path = path.expanduser()
+        if not source_path.is_file() or not self.is_available():
+            return MissingASRBackend(self.name).transcribe(source_path)
+        try:
+            language, probability = self.detect_language(source_path)
+        except ModelNotFoundError as exc:
+            from openmd.runtime.asr import failed_result
+
+            return failed_result(self.name, "asr_model_missing", exc)
+        except Exception as exc:  # pragma: no cover - dependency/model safety net
+            result = FasterWhisperASRBackend(model_size=self.general_model, **self._whisper_device()).transcribe(source_path)
+            return self._annotate(result, None, None, f"language detection failed ({type(exc).__name__}); used Whisper {model_label(self.general_model)}")
+
+        backend, reason = self.choose(language)
+        result = backend.transcribe(source_path)
+        if result.status != "verified" and isinstance(backend, Qwen3ASRBackend):
+            fallback = FasterWhisperASRBackend(model_size=self.general_model, language="zh", **self._whisper_device())
+            result = fallback.transcribe(source_path)
+            reason += f"; Qwen3-ASR failed, fell back to Whisper {model_label(self.general_model)}"
+        return self._annotate(result, language, probability, reason)
+
+    def choose(self, language: str | None) -> tuple[ASRBackend, str]:
+        device = self._whisper_device()
+        if language == "zh":
+            qwen3 = self._qwen3 or Qwen3ASRBackend()
+            if self.chinese_engine == "qwen3" and qwen3.is_available() and self._device()[0] == "cuda":
+                return qwen3, "Mandarin: Qwen3-ASR scored the lowest CER"
+            reason = "Mandarin: Qwen3-ASR needs its GPU stack, which is unavailable" if self.chinese_engine == "qwen3" else "Mandarin: Whisper requested"
+            return FasterWhisperASRBackend(model_size=self.general_model, language="zh", **device), reason
+        if language == "en":
+            return (
+                FasterWhisperASRBackend(model_size=self.english_model, language="en", **device),
+                f"English: Whisper {model_label(self.english_model)} had the best quality/speed score",
+            )
+        return (
+            FasterWhisperASRBackend(model_size=self.general_model, language=language, **device),
+            f"Language {language or 'unknown'}: Whisper {model_label(self.general_model)} is the general model",
+        )
+
+    def detect_language(self, path: Path) -> tuple[str | None, float | None]:
+        model_path = require_model(self.english_model, family="whisper")
+        _load_torch_first()
+        _prepare_windows_dll_paths()
+        from faster_whisper import WhisperModel
+
+        device, compute_type = self._device()
+        with offline_model_loading():
+            model = WhisperModel(str(model_path), device=device, compute_type=compute_type, local_files_only=True)
+        try:
+            _, info = model.transcribe(str(path), vad_filter=True, beam_size=1)
+            return getattr(info, "language", None), getattr(info, "language_probability", None)
+        finally:
+            del model
+            gc.collect()
+            _free_torch_cache()
+
+    def _device(self) -> tuple[str, str]:
+        device = os.getenv("OPENMD_FASTER_WHISPER_DEVICE")
+        compute_type = os.getenv("OPENMD_FASTER_WHISPER_COMPUTE_TYPE")
+        if device is None:
+            device = "cuda" if _cuda_available() else "cpu"
+        if compute_type is None:
+            compute_type = "int8_float16" if device == "cuda" else "int8"
+        return device, compute_type
+
+    def _whisper_device(self) -> dict[str, str]:
+        device, compute_type = self._device()
+        return {"device": device, "compute_type": compute_type}
+
+    def _annotate(self, result: TranscriptResult, language: str | None, probability: float | None, reason: str) -> TranscriptResult:
+        route = {
+            "detected_language": language,
+            "language_probability": round(probability, 3) if probability is not None else None,
+            "selected_backend": result.backend,
+            "reason": reason,
+        }
+        return replace(
+            result,
+            source_notes=[*result.source_notes, f"asr.auto routed this audio: {reason}."],
+            metadata={**result.metadata, "asr_route": route},
+        )
+
+
+def _load_torch_first() -> None:
+    """Load torch's cuDNN before CTranslate2 when both share a process.
+
+    If CTranslate2 loads cuDNN first, Qwen3 on torch later crashes the process with
+    "Could not load symbol cudnnGetLibConfig".
+    """
+    if importlib.util.find_spec("torch") is not None:
+        import torch  # noqa: F401
+
+
+def _cuda_available() -> bool:
+    try:
+        _load_torch_first()
+        _prepare_windows_dll_paths()
+        import ctranslate2
+        import torch
+
+        return torch.cuda.is_available() and ctranslate2.get_cuda_device_count() > 0
+    except Exception:
+        return False
+
+
+def _free_torch_cache() -> None:
+    if importlib.util.find_spec("torch") is None:
+        return
+    import torch
+
+    if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+
+
+def create_backend() -> AutoASRBackend:
+    return AutoASRBackend()

openmd/adapters/local_audio/backends/faster_whisper.py

@@ -0,0 +1,285 @@
+"""Optional faster-whisper backend for local audio files.
+
+The dependency is imported lazily so normal Openmd imports, mock lanes, and
+safe skeleton discovery never download models or run ASR.  This backend only
+transcribes user-local files; URL media download/extraction remains a separate
+explicit media lane.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from openmd.adapters.local_audio.asr import ASRBackend, MissingASRBackend
+from openmd.core.models import TranscriptResult
+from openmd.core.secrets import sanitize_error_summary
+from openmd.runtime.models import ModelNotFoundError, model_label, offline_model_loading, require_model, resolve_model
+
+
+DEFAULT_MODEL_SIZE = "large-v3"
+DEFAULT_DEVICE = "cpu"
+DEFAULT_COMPUTE_TYPE = "int8"
+DEFAULT_LANGUAGE = None
+DEFAULT_BEAM_SIZE = 5
+DEFAULT_VAD_MIN_SILENCE_MS = 700
+DEFAULT_INITIAL_PROMPT = (
+    "这是中文播客或访谈，请保留中文专有名词、英文缩写、数字和人名。"
+    "常见词包括：搞钱女孩、大漂亮爱吃肉、梨涡小雨、Leiya、刘六六、Shelly、"
+    "小红书、LinkedIn、ETF、SOP、AI、自媒体、创业、投资理财。"
+)
+DEFAULT_HOTWORDS = (
+    "搞钱女孩 大漂亮爱吃肉 梨涡小雨 Leiya 刘六六 Shelly "
+    "小红书 LinkedIn ETF SOP AI 自媒体 创业 投资理财"
+)
+# Decode settings shared by the transcribe call and the execution fingerprint.
+FIXED_DECODE_OPTIONS: dict[str, Any] = {"best_of": 5, "temperature": 0.0, "vad_filter": True}
+# Keep handles alive: closing or collecting them removes Windows DLL directories.
+_DLL_DIRECTORY_HANDLES: dict[str, Any] = {}
+
+
+def _prepare_windows_dll_paths() -> None:
+    """Expose optional pip-installed NVIDIA runtimes before loading CTranslate2."""
+    if sys.platform != "win32":
+        return
+    spec = importlib.util.find_spec("faster_whisper")
+    if spec is None or spec.origin is None:
+        return
+    nvidia_root = Path(spec.origin).resolve().parent.parent / "nvidia"
+    directories = sorted(path.resolve() for path in nvidia_root.glob("*/bin") if path.is_dir())
+    # A CUDA torch install ships cuBLAS/cuDNN in torch/lib; reuse them without importing torch.
+    torch_lib = nvidia_root.parent / "torch" / "lib"
+    if torch_lib.is_dir():
+        directories.append(torch_lib.resolve())
+    existing = {
+        os.path.normcase(os.path.abspath(path))
+        for path in os.environ.get("PATH", "").split(os.pathsep)
+        if path
+    }
+    additions: list[str] = []
+    for directory in directories:
+        value = str(directory)
+        key = os.path.normcase(value)
+        if key not in _DLL_DIRECTORY_HANDLES:
+            _DLL_DIRECTORY_HANDLES[key] = os.add_dll_directory(value)
+        if key not in existing:
+            additions.append(value)
+            existing.add(key)
+    if additions:
+        os.environ["PATH"] = os.pathsep.join([*additions, os.environ.get("PATH", "")])
+
+
+class FasterWhisperASRBackend(ASRBackend):
+    name = "asr.faster_whisper"
+
+    def __init__(
+        self,
+        *,
+        model_size: str | None = None,
+        device: str | None = None,
+        compute_type: str | None = None,
+        language: str | None = None,
+        beam_size: int = DEFAULT_BEAM_SIZE,
+        vad_min_silence_ms: int = DEFAULT_VAD_MIN_SILENCE_MS,
+        initial_prompt: str | None = None,
+        hotwords: str | None = None,
+        condition_on_previous_text: bool = False,
+        profile: str | None = None,
+    ) -> None:
+        self.profile = profile or os.getenv("OPENMD_FASTER_WHISPER_PROFILE") or "general_v1"
+        if self.profile not in {"general_v1", "zh_podcast_v2"}:
+            raise ValueError("Unknown faster-whisper profile; use general_v1 or zh_podcast_v2")
+        podcast = self.profile == "zh_podcast_v2"
+        self.model_size = model_size or os.getenv("OPENMD_FASTER_WHISPER_MODEL") or DEFAULT_MODEL_SIZE
+        self.device = device or os.getenv("OPENMD_FASTER_WHISPER_DEVICE") or DEFAULT_DEVICE
+        self.compute_type = (
+            compute_type
+            or os.getenv("OPENMD_FASTER_WHISPER_COMPUTE_TYPE")
+            or DEFAULT_COMPUTE_TYPE
+        )
+        selected_language = language if language is not None else os.getenv(
+            "OPENMD_FASTER_WHISPER_LANGUAGE", "zh" if podcast else ""
+        )
+        self.language = selected_language or DEFAULT_LANGUAGE
+        self.beam_size = beam_size
+        self.vad_min_silence_ms = vad_min_silence_ms
+        self.initial_prompt = initial_prompt if initial_prompt is not None else os.getenv(
+            "OPENMD_FASTER_WHISPER_INITIAL_PROMPT", DEFAULT_INITIAL_PROMPT if podcast else ""
+        )
+        self.hotwords = hotwords if hotwords is not None else os.getenv(
+            "OPENMD_FASTER_WHISPER_HOTWORDS", DEFAULT_HOTWORDS if podcast else ""
+        )
+        self.condition_on_previous_text = condition_on_previous_text
+        self.chinese_script = os.getenv("OPENMD_ASR_CHINESE_SCRIPT", "simplified")
+
+    def execution_config(self) -> dict[str, Any]:
+        """Effective result settings; construction never imports or downloads a model."""
+        return {
+            "profile": self.profile,
+            "model": model_label(self.model_size),
+            "model_origin": resolve_model(self.model_size, family="whisper").origin,
+            "local_files_only": True,
+            "language": self.language,
+            "device": self.device,
+            "compute_type": self.compute_type,
+            "beam_size": self.beam_size,
+            **FIXED_DECODE_OPTIONS,
+            "vad_min_silence_ms": self.vad_min_silence_ms,
+            "initial_prompt": self.initial_prompt,
+            "hotwords": self.hotwords,
+            "condition_on_previous_text": self.condition_on_previous_text,
+            "chinese_script": self.chinese_script,
+        }
+
+    def is_available(self) -> bool:
+        return importlib.util.find_spec("faster_whisper") is not None
+
+    def transcribe(self, path: Path) -> TranscriptResult:
+        source_path = path.expanduser()
+        if not source_path.is_file():
+            return _failed_result(
+                self.name,
+                source_path,
+                "asr_local_file_required",
+                "faster-whisper ASR requires a local audio file path.",
+            )
+
+        if not self.is_available():
+            return MissingASRBackend(self.name).transcribe(source_path)
+
+        try:
+            model_path = require_model(self.model_size, family="whisper")
+            _prepare_windows_dll_paths()
+            from faster_whisper import WhisperModel
+
+            with offline_model_loading():
+                model = WhisperModel(
+                    str(model_path),
+                    device=self.device,
+                    compute_type=self.compute_type,
+                    local_files_only=True,
+                )
+            kwargs: dict[str, Any] = {
+                "beam_size": self.beam_size,
+                **FIXED_DECODE_OPTIONS,
+                "vad_parameters": {"min_silence_duration_ms": self.vad_min_silence_ms},
+                "condition_on_previous_text": self.condition_on_previous_text,
+                "initial_prompt": self.initial_prompt or None,
+                "hotwords": self.hotwords or None,
+            }
+            if self.language:
+                kwargs["language"] = self.language
+            segments, info = model.transcribe(str(source_path), **kwargs)
+            lines = _format_segments(segments)
+        except ModelNotFoundError as exc:
+            return _failed_result(self.name, source_path, "asr_model_missing", exc)
+        except Exception as exc:  # pragma: no cover - dependency/model safety net
+            return _failed_result(self.name, source_path, "asr_extraction_failed", exc)
+
+        text = "\n".join(lines).strip()
+        if not text:
+            return _failed_result(
+                self.name,
+                source_path,
+                "asr_empty_text",
+                "faster-whisper returned no recognized text.",
+            )
+
+        detected_language = getattr(info, "language", None) or self.language
+        text, script_note, applied_script = _normalize_chinese_script(text, detected_language, self.chinese_script)
+
+        return TranscriptResult(
+            text=f"{text}\n",
+            status="verified",
+            source_level="asr",
+            backend=self.name,
+            source_notes=[
+                "faster-whisper transcribed a local audio file.",
+                "Raw audio file was referenced, not copied into the package.",
+                *([script_note] if script_note else []),
+            ],
+            title=source_path.stem or "local audio",
+            metadata={
+                "profile": "media",
+                "asr_backend": self.name,
+                "chinese_script": applied_script,
+                "model_size": model_label(self.model_size),
+                "device": self.device,
+                "compute_type": self.compute_type,
+                "language": getattr(info, "language", None) or self.language,
+                "duration": getattr(info, "duration", None),
+                "segment_count": len(lines),
+                "beam_size": self.beam_size,
+                "vad_min_silence_ms": self.vad_min_silence_ms,
+                "condition_on_previous_text": self.condition_on_previous_text,
+                "quality_profile": self.profile,
+            },
+        )
+
+
+def create_backend() -> FasterWhisperASRBackend:
+    return FasterWhisperASRBackend()
+
+
+def _normalize_chinese_script(text: str, language: str | None, script: str) -> tuple[str, str | None, str | None]:
+    """Whisper mixes Traditional into Mandarin output even with a Simplified prompt.
+
+    Only the character form changes; wording is untouched. Cantonese keeps its own form.
+    """
+    if language != "zh" or script != "simplified":
+        return text, None, None
+    try:
+        from opencc import OpenCC
+    except ImportError:
+        return text, "OpenCC is not installed, so Traditional characters were left unconverted.", "original"
+    return OpenCC("t2s").convert(text), "Traditional characters were converted to Simplified with OpenCC; wording is unchanged.", "simplified"
+
+
+def _format_segments(segments: Any) -> list[str]:
+    lines: list[str] = []
+    for segment in segments:
+        text = str(getattr(segment, "text", "")).strip()
+        if not text:
+            continue
+        start = getattr(segment, "start", None)
+        end = getattr(segment, "end", None)
+        if isinstance(start, (int, float)) and isinstance(end, (int, float)):
+            prefix = f"[{_timestamp(float(start))}-{_timestamp(float(end))}]"
+        elif isinstance(start, (int, float)):
+            prefix = f"[{_timestamp(float(start))}]"
+        else:
+            prefix = "[00:00:00]"
+        lines.append(f"{prefix} {text}")
+    return lines
+
+
+def _timestamp(seconds: float) -> str:
+    value = max(0, int(seconds))
+    hours, remainder = divmod(value, 3600)
+    minutes, secs = divmod(remainder, 60)
+    return f"{hours:02d}:{minutes:02d}:{secs:02d}"
+
+
+def _failed_result(
+    backend: str,
+    path: Path,
+    code: str,
+    error: object,
+) -> TranscriptResult:
+    return TranscriptResult(
+        text="",
+        status="failed",
+        source_level="partial_extraction",
+        backend=backend,
+        source_notes=[
+            "local audio ASR backend did not produce usable text.",
+            "Raw audio file was referenced, not copied into the package.",
+        ],
+        error_code=code,
+        error_summary=sanitize_error_summary(error),
+        title=path.stem or "local audio",
+        metadata={"profile": "media", "asr_backend": backend, "source_ref": path.name},
+    )