Skip to content

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

19.8 KB
Raw Blame
"""Engine selection: native installs auto-use whisper.cpp when openai-whisper
is absent, unless the user explicitly asked for the whisper-py engine."""

import importlib.util
import os
import sys
import tempfile
import unittest

ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
BACKEND_ROOT = os.path.join(ROOT, "backend")
if BACKEND_ROOT not in sys.path:
    sys.path.insert(0, BACKEND_ROOT)

import services.transcription as tr


class TranscriptionEngineTests(unittest.TestCase):
    def setUp(self):
        self._orig_wcpp = tr._transcribe_with_whispercpp
        self._orig_aai = tr._transcribe_with_assemblyai
        self._orig_omni = tr._transcribe_with_omnilingual
        self._orig_ready = tr._whispercpp_ready
        tr._transcribe_with_whispercpp = lambda *a, **k: {"engine": "whispercpp"}
        tr._transcribe_with_assemblyai = lambda *a, **k: {"engine": "assemblyai"}
        tr._transcribe_with_omnilingual = lambda *a, **k: {"engine": "omnilingual"}
        tr._whispercpp_ready = lambda size: True
        # Make `import whisper` fail to simulate a native (hermetic) install.
        self._had_whisper = sys.modules.get("whisper", "__absent__")
        sys.modules["whisper"] = None
        self._tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
        self._tmp.write(b"x")
        self._tmp.close()
        self._saved_engine = os.environ.pop("PODCLI_ENGINE", None)

    def tearDown(self):
        tr._transcribe_with_whispercpp = self._orig_wcpp
        tr._transcribe_with_assemblyai = self._orig_aai
        tr._transcribe_with_omnilingual = self._orig_omni
        tr._whispercpp_ready = self._orig_ready
        if self._had_whisper == "__absent__":
            sys.modules.pop("whisper", None)
        else:
            sys.modules["whisper"] = self._had_whisper
        os.unlink(self._tmp.name)
        if self._saved_engine is None:
            os.environ.pop("PODCLI_ENGINE", None)
        else:
            os.environ["PODCLI_ENGINE"] = self._saved_engine

    def test_auto_falls_back_to_whispercpp(self):
        os.environ.pop("PODCLI_ENGINE", None)
        result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)
        self.assertEqual(result["engine"], "whispercpp")

    def test_explicit_whispercpp_uses_it(self):
        os.environ["PODCLI_ENGINE"] = "whispercpp"
        result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)
        self.assertEqual(result["engine"], "whispercpp")

    def test_explicit_assemblyai_uses_it(self):
        os.environ["PODCLI_ENGINE"] = "assemblyai"
        result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)
        self.assertEqual(result["engine"], "assemblyai")

    def test_explicit_omnilingual_uses_it(self):
        os.environ["PODCLI_ENGINE"] = "omnilingual"
        result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)
        self.assertEqual(result["engine"], "omnilingual")

    def test_omnilingual_skips_diarization_like_whispercpp(self):
        os.environ["PODCLI_ENGINE"] = "omnilingual"
        result = tr.transcribe_file(self._tmp.name, model_size="base")
        self.assertEqual(result["engine"], "omnilingual")
        self.assertEqual(result.get("diarization_warning"), "Speaker detection disabled")

    def test_unset_engine_never_auto_falls_back_to_omnilingual(self):
        # Only whispercpp is an automatic fallback for an unset engine on a
        # native install; omnilingual is explicit-only.
        os.environ.pop("PODCLI_ENGINE", None)
        result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)
        self.assertEqual(result["engine"], "whispercpp")

    def test_whispercpp_skips_diarization_by_default(self):
        # Regression: the cpp path must not attempt torch-backed diarization even
        # with the default enable_diarization=True: importing a broken torch in a
        # native runtime hard-crashes the process. Face analysis still runs.
        os.environ["PODCLI_ENGINE"] = "whispercpp"
        result = tr.transcribe_file(self._tmp.name, model_size="base")
        self.assertEqual(result["engine"], "whispercpp")
        self.assertEqual(result.get("diarization_warning"), "Speaker detection disabled")

    def test_explicit_whisper_py_still_errors(self):
        os.environ["PODCLI_ENGINE"] = "whisper-py"
        with self.assertRaises(RuntimeError):
            tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)

    def test_no_fallback_when_whispercpp_unavailable(self):
        os.environ.pop("PODCLI_ENGINE", None)
        tr._whispercpp_ready = lambda size: False
        with self.assertRaises(RuntimeError):
            tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)

    def test_whispercpp_never_marks_diarization_attempted(self):
        # whisper.cpp can never diarize. A cache entry from this engine must
        # say so explicitly, or a reader asking for speaker labels would
        # re-transcribe it forever (every run looks like a retriable miss).
        os.environ["PODCLI_ENGINE"] = "whispercpp"
        result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=True)
        self.assertFalse(result["diarization_attempted"])

    def test_omnilingual_never_marks_diarization_attempted(self):
        os.environ["PODCLI_ENGINE"] = "omnilingual"
        result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=True)
        self.assertFalse(result["diarization_attempted"])

    def test_assemblyai_marks_diarization_attempted_from_its_own_request_flag(self):
        os.environ["PODCLI_ENGINE"] = "assemblyai"
        result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=True)
        self.assertTrue(result["diarization_attempted"])

    def test_assemblyai_without_diarization_is_not_marked_attempted(self):
        os.environ["PODCLI_ENGINE"] = "assemblyai"
        result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)
        self.assertFalse(result["diarization_attempted"])


class SampleModeTests(unittest.TestCase):
    """start_seconds/duration_seconds should transcribe a trimmed window
    instead of the full file, mark the result incomplete, and skip
    diarization/face analysis (the trimmed clip has no video track for face
    analysis to read, and a throwaway sample isn't worth either pass)."""

    def setUp(self):
        self._orig_wcpp = tr._transcribe_with_whispercpp
        self._orig_ready = tr._whispercpp_ready
        self._saved_engine = os.environ.pop("PODCLI_ENGINE", None)
        os.environ["PODCLI_ENGINE"] = "whispercpp"
        self._tmp = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False)
        self._tmp.write(b"not a real video")
        self._tmp.close()
        self.extract_calls = []

        def fake_extract(file_path, wav_path=None, timeout=1800, start_seconds=None, duration_seconds=None):
            self.extract_calls.append(
                {"file_path": file_path, "start_seconds": start_seconds, "duration_seconds": duration_seconds}
            )
            fd, path = tempfile.mkstemp(suffix=".wav")
            os.close(fd)
            return path

        self._fake_extract = fake_extract
        import services.audio_extract as audio_extract

        self._orig_extract = audio_extract.extract_wav_16k_mono
        audio_extract.extract_wav_16k_mono = fake_extract

        def fake_wcpp(*args, **kwargs):
            # The inner call must receive the sample wav as both file_path
            # and wav_path, and diarization must be forced off.
            self.inner_file_path = args[0] if args else kwargs.get("file_path")
            self.inner_wav_path = kwargs.get("wav_path")
            return {"engine": "whispercpp", "words": [], "segments": [], "duration": 40.0}

        tr._transcribe_with_whispercpp = fake_wcpp
        tr._whispercpp_ready = lambda size: True

    def tearDown(self):
        tr._transcribe_with_whispercpp = self._orig_wcpp
        tr._whispercpp_ready = self._orig_ready
        import services.audio_extract as audio_extract

        audio_extract.extract_wav_16k_mono = self._orig_extract
        os.unlink(self._tmp.name)
        if self._saved_engine is None:
            os.environ.pop("PODCLI_ENGINE", None)
        else:
            os.environ["PODCLI_ENGINE"] = self._saved_engine

    def test_sample_window_is_passed_to_extraction(self):
        tr.transcribe_file(
            self._tmp.name, model_size="base", start_seconds=120.0, duration_seconds=40.0,
            enable_diarization=False,
        )
        self.assertEqual(len(self.extract_calls), 1)
        self.assertEqual(self.extract_calls[0]["start_seconds"], 120.0)
        self.assertEqual(self.extract_calls[0]["duration_seconds"], 40.0)

    def test_result_marked_incomplete_with_offset(self):
        result = tr.transcribe_file(
            self._tmp.name, model_size="base", start_seconds=120.0, duration_seconds=40.0,
            enable_diarization=False,
        )
        self.assertFalse(result["complete"])
        self.assertEqual(result["sample_offset_seconds"], 120.0)

    def test_full_run_is_marked_neither_incomplete_nor_offset(self):
        result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)
        self.assertNotIn("complete", result)
        self.assertNotIn("sample_offset_seconds", result)

    def test_default_start_is_zero_when_only_duration_given(self):
        result = tr.transcribe_file(
            self._tmp.name, model_size="base", duration_seconds=40.0, enable_diarization=False,
        )
        self.assertEqual(self.extract_calls[0]["start_seconds"], 0.0)
        self.assertEqual(result["sample_offset_seconds"], 0.0)

    def test_duration_seconds_zero_is_a_full_run_not_a_sample(self):
        # Matches src/handlers/transcribe.handler.ts and web-server.ts: a
        # sample is a *positive* window, not merely a present key.
        result = tr.transcribe_file(
            self._tmp.name, model_size="base", duration_seconds=0.0, enable_diarization=False,
        )
        self.assertEqual(self.extract_calls, [])
        self.assertNotIn("complete", result)
        self.assertNotIn("sample_offset_seconds", result)

    def test_start_seconds_zero_alone_is_a_full_run_not_a_sample(self):
        result = tr.transcribe_file(
            self._tmp.name, model_size="base", start_seconds=0.0, enable_diarization=False,
        )
        self.assertEqual(self.extract_calls, [])
        self.assertNotIn("complete", result)


class ResolveEngineInfoTests(unittest.TestCase):
    """resolve_engine_info predicts transcribe_file's engine choice so a
    caller can build a matching cache key before deciding to transcribe."""

    def setUp(self):
        self._had_whisper = sys.modules.get("whisper", "__absent__")
        self._orig_ready = tr._whispercpp_ready
        self._saved_engine = os.environ.pop("PODCLI_ENGINE", None)
        # _whisper_py_available is memoized for the process lifetime (the
        # package's installed-ness can't change mid-run), but that means
        # a value cached by one test would leak into the next, which
        # sabotages sys.modules["whisper"] to simulate availability.
        tr._whisper_py_available.cache_clear()

    def tearDown(self):
        if self._had_whisper == "__absent__":
            sys.modules.pop("whisper", None)
        else:
            sys.modules["whisper"] = self._had_whisper
        tr._whispercpp_ready = self._orig_ready
        tr._whisper_py_available.cache_clear()
        if self._saved_engine is None:
            os.environ.pop("PODCLI_ENGINE", None)
        else:
            os.environ["PODCLI_ENGINE"] = self._saved_engine

    def test_explicit_whispercpp_resolves_as_is(self):
        self.assertEqual(tr.resolve_engine_info("whispercpp")["engine"], "whispercpp")

    def test_explicit_assemblyai_resolves_as_is(self):
        self.assertEqual(tr.resolve_engine_info("assemblyai")["engine"], "assemblyai")

    def test_unset_falls_back_to_whispercpp_on_native_install(self):
        sys.modules["whisper"] = None  # simulate "import whisper" failing
        tr._whispercpp_ready = lambda size: True
        self.assertEqual(tr.resolve_engine_info(None)["engine"], "whispercpp")

    def test_unset_stays_whisper_py_when_whisper_importable(self):
        sys.modules.pop("whisper", None)
        try:
            import whisper  # noqa: F401
        except Exception:
            self.skipTest("openai-whisper not installed in this environment")
        self.assertEqual(tr.resolve_engine_info(None)["engine"], "whisper-py")

    def test_explicit_whisper_py_request_never_falls_back(self):
        # Fallback only applies to an unset request; an explicit whisper-py
        # ask should resolve as whisper-py even on a native install, matching
        # transcribe_file which raises instead of silently substituting.
        sys.modules["whisper"] = None
        tr._whispercpp_ready = lambda size: True
        self.assertEqual(tr.resolve_engine_info("whisper-py")["engine"], "whisper-py")


class OmnilingualReceiptKeyTests(unittest.TestCase):
    """The resumable run directory has to change whenever a resumed
    window's receipt would no longer be valid: a different model file, or
    a change to the window/context constants its timestamps assume."""

    def setUp(self):
        self._model = tempfile.NamedTemporaryFile(suffix=".onnx", delete=False)
        self._model.write(b"fake model bytes")
        self._model.close()
        self._tokens = tempfile.NamedTemporaryFile(suffix=".txt", delete=False)
        self._tokens.write(b"fake tokens")
        self._tokens.close()
        self._media = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False)
        self._media.write(b"fake media")
        self._media.close()

        self._orig_model = tr._omnilingual_model
        self._orig_tokens = tr._omnilingual_tokens
        tr._omnilingual_model = lambda: self._model.name
        tr._omnilingual_tokens = lambda: self._tokens.name

        self.captured = []
        import services.transcription_omnilingual as omni

        self._orig_omni_transcribe = omni.transcribe_file

        def fake_transcribe(*a, run_dir=None, **k):
            self.captured.append(run_dir)
            return {"transcript": "", "segments": [], "words": [], "duration": 0.0, "language": "und"}

        omni.transcribe_file = fake_transcribe
        self._omni = omni

    def tearDown(self):
        tr._omnilingual_model = self._orig_model
        tr._omnilingual_tokens = self._orig_tokens
        self._omni.transcribe_file = self._orig_omni_transcribe
        for f in (self._model, self._tokens, self._media):
            os.unlink(f.name)

    def test_a_different_model_file_gets_its_own_run_dir(self):
        tr._transcribe_with_omnilingual(self._media.name, progress_callback=None)
        first = self.captured[0]

        # Swap in a "different" model: same path, new content/mtime.
        import time as _time
        _time.sleep(0.01)
        with open(self._model.name, "wb") as f:
            f.write(b"a completely different and larger fake model")

        tr._transcribe_with_omnilingual(self._media.name, progress_callback=None)
        second = self.captured[1]

        self.assertNotEqual(first, second)

    def test_the_window_and_context_constants_are_baked_into_the_key(self):
        tr._transcribe_with_omnilingual(self._media.name, progress_callback=None)
        run_dir = self.captured[0]
        self.assertIn(f"w{self._omni.WINDOW_SECONDS}", run_dir)
        self.assertIn(f"c{self._omni.CONTEXT_SECONDS}", run_dir)


class WhisperPyFallbackSharedPathTests(unittest.TestCase):
    """resolve_engine_info (a cheap cache-key prediction) and transcribe_file
    (about to actually transcribe) make the same fallback decision through
    one shared function, _resolve_whisper_py_fallback, differing only in
    whether they load the model weights to check it."""

    def setUp(self):
        self._orig_wcpp = tr._transcribe_with_whispercpp
        self._orig_ready = tr._whispercpp_ready
        tr._transcribe_with_whispercpp = lambda *a, **k: {"engine": "whispercpp"}
        tr._whispercpp_ready = lambda size: True
        self._saved_engine = os.environ.pop("PODCLI_ENGINE", None)
        self._tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
        self._tmp.write(b"x")
        self._tmp.close()

        # Simulate "import whisper" succeeding but whisper.load_model()
        # failing: the one gap resolve_engine_info's cheap check can't see.
        import importlib.machinery

        class _BrokenWhisperModule:
            # find_spec requires a real module to carry __spec__. A bare
            # object stand-in raises ValueError instead of just finding it.
            __spec__ = importlib.machinery.ModuleSpec("whisper", loader=None)

            @staticmethod
            def load_model(size):
                raise RuntimeError("corrupt model weights")

        self._had_whisper = sys.modules.get("whisper", "__absent__")
        sys.modules["whisper"] = _BrokenWhisperModule()
        tr._whisper_py_available.cache_clear()

    def tearDown(self):
        tr._transcribe_with_whispercpp = self._orig_wcpp
        tr._whispercpp_ready = self._orig_ready
        if self._had_whisper == "__absent__":
            sys.modules.pop("whisper", None)
        else:
            sys.modules["whisper"] = self._had_whisper
        tr._whisper_py_available.cache_clear()
        os.unlink(self._tmp.name)
        if self._saved_engine is None:
            os.environ.pop("PODCLI_ENGINE", None)
        else:
            os.environ["PODCLI_ENGINE"] = self._saved_engine

    def test_transcribe_file_falls_back_to_whispercpp_on_a_load_model_failure(self):
        result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)
        self.assertEqual(result["engine"], "whispercpp")

    def test_resolve_engine_info_cannot_see_this_failure_by_design(self):
        # Documents the known, acceptable gap: resolve_engine_info only
        # checks the import, so it still predicts whisper-py here even
        # though transcribe_file will fall back, a one-time cache miss,
        # not a wrong cache write (that's keyed by what actually ran).
        self.assertEqual(tr.resolve_engine_info(None, "base")["engine"], "whisper-py")


class WhisperPyAvailableMemoizationTests(unittest.TestCase):
    """resolve_engine_info runs on every transcribe request. The
    availability check behind it has to find_spec (not import, which would
    pull in torch) and compute that only once per process."""

    def setUp(self):
        tr._whisper_py_available.cache_clear()
        self._orig_find_spec = importlib.util.find_spec
        self.calls = 0

        def counting_find_spec(name, *a, **k):
            self.calls += 1
            return self._orig_find_spec(name, *a, **k)

        importlib.util.find_spec = counting_find_spec

    def tearDown(self):
        importlib.util.find_spec = self._orig_find_spec
        tr._whisper_py_available.cache_clear()

    def test_find_spec_runs_at_most_once_across_repeated_calls(self):
        for _ in range(5):
            tr._whisper_py_available()
        self.assertEqual(self.calls, 1)


class WhisperCppModelAliasTests(unittest.TestCase):
    """"large" alone doesn't name a real ggml file upstream (v1/v2/v3/v3-turbo
    are separate downloads); provisioning always fetches large-v3, so the
    model path lookup must resolve the same alias."""

    def setUp(self):
        self._saved = os.environ.pop("PODCLI_WHISPERCPP_MODEL", None)

    def tearDown(self):
        if self._saved is not None:
            os.environ["PODCLI_WHISPERCPP_MODEL"] = self._saved

    def test_large_resolves_to_large_v3(self):
        self.assertTrue(tr._whispercpp_model("large").endswith("ggml-large-v3.bin"))

    def test_medium_is_unaliased(self):
        self.assertTrue(tr._whispercpp_model("medium").endswith("ggml-medium.bin"))


if __name__ == "__main__":
    unittest.main()