cutan 0.0.2__py3-none-any.whl

cutan/__init__.py

@@ -0,0 +1,80 @@
+"""cutan: cut-out animation, as a genre package on the ``an`` core.
+
+``an`` is the core of structured animation (scene documents, the timing kernel,
+renderers, audio, storage, verification). A *genre* adds what one kind of
+animation needs and registers it with the core; ``cutan`` is the first genre to
+leave ``an``: rigged characters, faces and expressions, lip-sync visemes, swap
+sets and views, cut-out styles and impacts (ADR 0001 in ``an``'s
+``misc/docs/adr/``, tracked by an#225 under the epic an#231).
+
+Rigged characters (``cutan.characters``), faces (``cutan.expression``), impacts
+(``cutan.impacts``), the cut-out compile passes (``cutan.compile``), lip-sync
+providers (``cutan.audio``), the style lint (``cutan.verify``) and the genre object
+(``cutan.genre``) lived inside ``an`` until the P8 move (an#225); ``an`` keeps
+warning aliases at the old import paths. Install it with ``pip install "an[cutout]"``;
+``an`` finds it through the ``an.genres`` entry point.
+
+The identifiers below are the genre's **persisted** names (ADR 0001 decision 9):
+they are written into documents, stores and entry-point metadata, and none of
+them changes when code moves between distributions.
+
+>>> GENRE_NAME
+'cutout_animation'
+>>> ENTRY_POINT_GROUP, ENTRY_POINT_NAME
+('an.genres', 'cutout_animation')
+>>> RENDERER_NAME, LIBRARY_NAME
+('cutout', 'cutan')
+"""
+
+#: The genre's slug: the ``an.genres`` entry-point name and the ``nw`` genre id.
+GENRE_NAME: str = "cutout_animation"
+
+#: The entry-point group ``an.genres.load()`` reads.
+ENTRY_POINT_GROUP: str = "an.genres"
+
+#: The entry-point name this distribution declares (``pyproject.toml``): the name
+#: ``an`` used to declare for the in-distribution genre, so the handover was by name.
+ENTRY_POINT_NAME: str = GENRE_NAME
+
+#: Where the entry point points.
+ENTRY_POINT_VALUE: str = "cutan.genre:CUTOUT"
+
+#: The persisted renderer name of cut-out shots (``an.stage`` claims it).
+RENDERER_NAME: str = "cutout"
+
+#: The package whose data root holds the genre's asset library and projects
+#: (``~/.local/share/cutan`` by default; ``CUTAN_HOME`` overrides it).
+LIBRARY_NAME: str = "cutan"
+
+#: The lowest ``an.genres.API_LEVEL`` this ``cutan`` runs against ("the lowest ``an``
+#: it supports", ADR 0001 decision 8, said without a version pin: ``an``'s version is
+#: assigned by CI at merge). Level 2 is the move itself: ``Genre.services``,
+#: ``ActionKind.lowering``, ``EntityKind.swap_declaration`` and ``an.stage.rig``.
+REQUIRED_AN_API_LEVEL: int = 2
+
+
+def require_an() -> None:
+    """Refuse, with an upgrade hint, to load against an ``an`` older than this ``cutan`` needs.
+
+    >>> require_an()
+    """
+    import an.genres
+
+    level = getattr(an.genres, "API_LEVEL", 0)
+    if level < REQUIRED_AN_API_LEVEL:
+        raise ImportError(
+            f"cutan needs an.genres API level {REQUIRED_AN_API_LEVEL} or higher; this an "
+            f"provides {level}. Upgrade an: pip install -U an"
+        )
+
+
+__all__ = [
+    "ENTRY_POINT_GROUP",
+    "ENTRY_POINT_NAME",
+    "ENTRY_POINT_VALUE",
+    "GENRE_NAME",
+    "LIBRARY_NAME",
+    "REQUIRED_AN_API_LEVEL",
+    "RENDERER_NAME",
+    "require_an",
+]

cutan/audio/__init__.py

@@ -0,0 +1,50 @@
+"""The cut-out genre's lip-sync providers: letters, Rhubarb and word timings to mouth shapes.
+
+Moved from ``an.audio`` (an#225). ``an.audio`` keeps the protocols
+(:class:`~an.audio.lipsync.LipSyncProvider`, :class:`~an.audio.lipsync.VisemeTrack`),
+text-to-speech and the pipeline; a viseme only means something to a genre that
+draws mouths. The genre registers these by name as ``lipsync.<name>`` services
+(:mod:`cutan.genre`), which is how ``render(lipsync="offline")`` and
+``an render --lipsync rhubarb`` keep working.
+
+>>> offline_factory().name
+'offline'
+"""
+
+from __future__ import annotations
+
+from cutan.audio.injectable_lipsync import StaticWordTimings, WordTimingsLipSync
+from cutan.audio.offline_lipsync import OfflineLipSync
+from cutan.audio.rhubarb_lipsync import RhubarbLipSync
+from cutan.audio.whisper_lipsync import WhisperLipSync
+
+#: The language a provider aligns for when the caller says nothing (Rhubarb's
+#: recognizer follows it, an#96): the same default ``an.audio.providers`` has.
+DFLT_LANGUAGE: str = "en"
+
+
+def offline_factory(**_: object) -> OfflineLipSync:
+    """The deterministic char-to-viseme provider (the default)."""
+    return OfflineLipSync()
+
+
+def rhubarb_factory(*, language: str = DFLT_LANGUAGE, **_: object) -> RhubarbLipSync:
+    """Rhubarb Lip Sync (needs the ``rhubarb`` binary); ``language`` picks its recognizer."""
+    return RhubarbLipSync(language=language)
+
+
+def whisper_factory(**_: object) -> WhisperLipSync:
+    """Word timings from Whisper, distributed over the mouth shapes."""
+    return WhisperLipSync()
+
+
+__all__ = [
+    "OfflineLipSync",
+    "RhubarbLipSync",
+    "StaticWordTimings",
+    "WhisperLipSync",
+    "WordTimingsLipSync",
+    "offline_factory",
+    "rhubarb_factory",
+    "whisper_factory",
+]

cutan/audio/injectable_lipsync.py

@@ -0,0 +1,123 @@
+"""Lip-sync provider that consumes pre-computed word timings.
+
+Useful when an upstream system already has authoritative word-level
+timings and would otherwise force ``an`` to re-transcribe the same
+audio. The canonical case is ``muvid``, where the lyric → audio
+alignment store (``lacing``) is the SSOT and re-running
+``WhisperLipSync`` on the audio produces a redundant (and possibly
+divergent) word-timestamp set.
+
+Two pieces:
+
+- :class:`StaticWordTimings` — a :class:`WordTimingProvider` over a
+  fixed list of ``(word, start, end)`` tuples.
+- :class:`WordTimingsLipSync` — a :class:`LipSyncProvider` that reads
+  from any :class:`WordTimingProvider` and runs the same
+  word→viseme conversion as :class:`WhisperLipSync` (via
+  :func:`word_timings_to_visemes`), so output is shape-compatible with
+  the rest of the cutout pipeline.
+
+Drop-in usage::
+
+    from cutan.audio.injectable_lipsync import (
+        StaticWordTimings, WordTimingsLipSync,
+    )
+
+    timings = [("hello", 0.5, 1.0), ("world", 1.2, 1.8)]
+    lipsync = WordTimingsLipSync(StaticWordTimings(timings))
+    track = lipsync.align(audio_clip, "hello world")
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from an.audio.lipsync import (
+    LipSyncProvider,
+    VisemeTrack,
+    WordTiming,
+    WordTimingProvider,
+    word_timings_to_visemes,
+)
+from cutan.audio.offline_lipsync import _CHAR_TO_VISEME, _REST_VISEME
+from an.audio.tts import AudioClip
+
+
+class StaticWordTimings:
+    """A :class:`WordTimingProvider` over a fixed list of timings."""
+
+    name: str = "static"
+
+    def __init__(self, words: Sequence[WordTiming], *, label: str = "static") -> None:
+        self._words = tuple(words)
+        self.name = label
+
+    def words_for(
+        self, audio: AudioClip, *, transcript: str = ""
+    ) -> Sequence[WordTiming]:
+        return self._words
+
+
+class WordTimingsLipSync:
+    """:class:`LipSyncProvider` driven by a :class:`WordTimingProvider`.
+
+    Skips transcription entirely. Use this when the caller already has
+    authoritative word timings (e.g. from a separate lyric-alignment
+    pipeline).
+
+    Args:
+        provider: any :class:`WordTimingProvider`.
+        char_to_viseme: optional override of the character→viseme code
+            mapping; defaults to the one shared with
+            :class:`OfflineLipSync` / :class:`WhisperLipSync`.
+        convention: declared viseme convention string for the produced
+            track. Defaults to ``"rhubarb"`` for compatibility with the
+            existing cutout adapter.
+        rest_viseme: code emitted in silent gaps. Defaults to
+            :data:`_REST_VISEME`.
+        min_gap_for_rest: minimum inter-word silence (seconds) before
+            we insert a rest keyframe. Defaults to ``0.20``.
+    """
+
+    convention: str = "rhubarb"
+
+    def __init__(
+        self,
+        provider: WordTimingProvider,
+        *,
+        char_to_viseme: dict[str, str] | None = None,
+        convention: str = "rhubarb",
+        rest_viseme: str = _REST_VISEME,
+        min_gap_for_rest: float = 0.20,
+    ) -> None:
+        self.provider = provider
+        self.convention = convention
+        self._mapping = (
+            dict(char_to_viseme) if char_to_viseme else dict(_CHAR_TO_VISEME)
+        )
+        self._rest = rest_viseme
+        self._min_gap = min_gap_for_rest
+
+    @property
+    def name(self) -> str:
+        # Disambiguate cache keys per-provider so swapping providers
+        # invalidates the viseme cache.
+        return f"word-timings:{getattr(self.provider, 'name', 'unknown')}"
+
+    #: Built from words, so the track carries them (an#96).
+    emits_word_timings: bool = True
+
+    def align(self, audio: AudioClip, transcript: str) -> VisemeTrack:
+        words = list(self.provider.words_for(audio, transcript=transcript))
+        return VisemeTrack(
+            visemes=word_timings_to_visemes(
+                words,
+                total_duration=audio.duration,
+                char_to_viseme=self._mapping,
+                rest_viseme=self._rest,
+                min_gap_for_rest=self._min_gap,
+            ),
+            convention=self.convention,
+            duration=audio.duration,
+            words=words,
+        )

cutan/audio/offline_lipsync.py

@@ -0,0 +1,126 @@
+"""OfflineLipSync — deterministic transcript → viseme track. No network, no binary.
+
+The default lip-sync provider for `an`. Maps each meaningful character of the
+transcript to a Rhubarb-convention viseme letter (A–H + X), then distributes
+keyframes evenly across the audio's duration. Repeated visemes get collapsed
+into a single keyframe so the mouth doesn't "stutter" on long vowel runs.
+
+Crude but visible. Use ``RhubarbLipSync`` for real phoneme alignment once
+you've installed the Rhubarb binary.
+
+>>> from an.audio.tts import AudioClip
+>>> ls = OfflineLipSync()
+>>> track = ls.align(AudioClip(duration=1.0, transcript="hello"), "hello")
+>>> track.convention
+'rhubarb'
+>>> track.duration
+1.0
+>>> len(track.visemes) >= 2
+True
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from an.audio.lipsync import Viseme, VisemeTrack
+from an.audio.tts import AudioClip
+
+
+# Map a single ASCII character (lowercased) to a Rhubarb viseme letter.
+# A=closed (P/B/M, rest), B=tight open (D/S/T/Z/N/L), C=eh, D=ah/wide,
+# E=ohh, F=ooh, G=teeth-on-lip (F/V), H=th, X=idle.
+_CHAR_TO_VISEME: dict[str, str] = {
+    # closed lips
+    "p": "A",
+    "b": "A",
+    "m": "A",
+    # teeth-on-lip
+    "f": "G",
+    "v": "G",
+    # th-ish
+    "h": "C",
+    # vowel families
+    "a": "D",
+    "e": "C",
+    "i": "B",
+    "o": "E",
+    "u": "F",
+    "y": "B",
+    # alveolar consonants
+    "d": "B",
+    "t": "B",
+    "s": "B",
+    "z": "B",
+    "n": "B",
+    "l": "B",
+    "r": "B",
+    # remaining consonants — neutral semi-open
+    "c": "C",
+    "g": "C",
+    "j": "C",
+    "k": "C",
+    "q": "C",
+    "w": "F",
+    "x": "C",
+}
+_REST_VISEME: str = "X"
+
+
+class OfflineLipSync:
+    """Default lip-sync provider: deterministic char-to-viseme mapping.
+
+    Implements the ``LipSyncProvider`` protocol.
+    """
+
+    name: str = "offline"
+    convention: str = "rhubarb"
+
+    def __init__(self, *, char_to_viseme: dict[str, str] | None = None) -> None:
+        self._mapping = (
+            dict(char_to_viseme) if char_to_viseme else dict(_CHAR_TO_VISEME)
+        )
+
+    def align(self, audio: AudioClip, transcript: str) -> VisemeTrack:
+        codes = list(self._codes_for(transcript))
+        if not codes:
+            # Empty transcript → just rest at start, rest at end.
+            return VisemeTrack(
+                visemes=[
+                    Viseme(time=0.0, code=_REST_VISEME),
+                    Viseme(time=max(0.0, audio.duration), code=_REST_VISEME),
+                ],
+                convention=self.convention,
+                duration=audio.duration,
+            )
+        # Distribute one keyframe per code over [0, duration].
+        n = len(codes)
+        duration = max(audio.duration, 1e-3)
+        visemes: list[Viseme] = []
+        # Always lead with rest at t=0
+        visemes.append(Viseme(time=0.0, code=_REST_VISEME))
+        for i, code in enumerate(codes):
+            t = (i + 1) / (n + 1) * duration
+            visemes.append(Viseme(time=t, code=code))
+        # Trailing rest
+        visemes.append(Viseme(time=duration, code=_REST_VISEME))
+        return VisemeTrack(
+            visemes=visemes, convention=self.convention, duration=audio.duration
+        )
+
+    def _codes_for(self, transcript: str) -> Iterable[str]:
+        """Per-character viseme codes; collapses adjacent duplicates."""
+        previous: str | None = None
+        for raw in transcript:
+            ch = raw.lower()
+            if not ch.isalpha():
+                # Spaces, punctuation → mouth rest. Insert if not redundant.
+                if previous != _REST_VISEME:
+                    previous = _REST_VISEME
+                    yield _REST_VISEME
+                continue
+            code = self._mapping.get(ch, "C")
+            if code == previous:
+                continue
+            previous = code
+            yield code

cutan/audio/rhubarb_lipsync.py

@@ -0,0 +1,152 @@
+"""RhubarbLipSync — calls the rhubarb-lip-sync binary for phoneme-aligned visemes.
+
+Requires the ``rhubarb`` binary on PATH. macOS: ``brew install rhubarb-lipsync``.
+Linux/Windows: download from the project's GitHub releases.
+
+Falls back gracefully (raises a clear error) if the binary is missing — the
+default ``OfflineLipSync`` keeps the pipeline functional in the meantime.
+
+**The recognizer follows the language** (an#96, epic #9 defect 5a). Rhubarb has
+two: ``pocketSphinx`` — its default, "use for English recordings", the only one
+that reads ``--dialogFile`` (it builds a dialog language model and mixes it 90/10
+with the default) — and ``phonetic``, "use for non-English recordings", which
+``UNUSED(dialog)``s the transcript at source. This module used to pass
+``-r phonetic`` **and** ``--dialogFile`` unconditionally: English speech from an
+English transcript ran the language-independent recognizer and the transcript
+it wrote to disk was never read. Now ``recognizer=None`` (the default) resolves
+per ``language`` — ``"en"`` → ``pocketSphinx`` with the dialog file, anything
+else → ``phonetic`` and **no transcript is written** (a file nothing reads is a
+lie waiting for the next reader). An explicit ``recognizer`` still overrides.
+``name`` carries the recognizer so the viseme cache key changes with it and no
+stale ``phonetic`` track replays.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from an.audio.lipsync import Viseme, VisemeTrack
+from an.audio.tts import AudioClip
+
+
+_DEFAULT_TIMEOUT_S: float = 60.0
+#: Rhubarb's own default and its English recognizer — the one that reads the
+#: dialog file.
+_ENGLISH_RECOGNIZER: str = "pocketSphinx"
+#: Language-independent; ignores the dialog file at source.
+_PHONETIC_RECOGNIZER: str = "phonetic"
+#: The languages `pocketSphinx` (CMU Sphinx US English acoustic model) covers.
+ENGLISH_LANGUAGES: frozenset[str] = frozenset({"en"})
+RECOGNIZERS: frozenset[str] = frozenset({_ENGLISH_RECOGNIZER, _PHONETIC_RECOGNIZER})
+
+
+def recognizer_for(language: str) -> str:
+    """The Rhubarb recognizer for a BCP-47 language tag (primary subtag only).
+
+    Accepts the POSIX locale spelling too (``en_US``); an empty tag is refused
+    rather than read as "non-English" (an#96 review).
+
+    >>> recognizer_for("en"), recognizer_for("en-GB"), recognizer_for("en_US"), recognizer_for("fr")
+    ('pocketSphinx', 'pocketSphinx', 'pocketSphinx', 'phonetic')
+    """
+    primary = language.replace("_", "-").split("-", 1)[0].strip().lower()
+    if not primary:
+        raise ValueError("language must be a BCP-47 tag such as 'en' or 'fr'; got ''")
+    return _ENGLISH_RECOGNIZER if primary in ENGLISH_LANGUAGES else _PHONETIC_RECOGNIZER
+
+
+class RhubarbLipSync:
+    """Wrap the rhubarb CLI. Implements the ``LipSyncProvider`` protocol.
+
+    >>> RhubarbLipSync(binary_path="/bin/rhubarb").recognizer
+    'pocketSphinx'
+    >>> RhubarbLipSync(binary_path="/bin/rhubarb", language="de").recognizer
+    'phonetic'
+    >>> RhubarbLipSync(binary_path="/bin/rhubarb", language="de").name
+    'rhubarb:phonetic'
+    """
+
+    convention: str = "rhubarb"
+
+    def __init__(
+        self,
+        *,
+        binary_path: str | None = None,
+        language: str = "en",
+        recognizer: str | None = None,
+        timeout_s: float = _DEFAULT_TIMEOUT_S,
+    ) -> None:
+        self.binary_path = binary_path or shutil.which("rhubarb")
+        self.language = language
+        chosen = recognizer if recognizer is not None else recognizer_for(language)
+        if chosen not in RECOGNIZERS:
+            raise ValueError(
+                f"unknown rhubarb recognizer {chosen!r}; known: {sorted(RECOGNIZERS)}"
+            )
+        self.recognizer = chosen
+        self.timeout_s = timeout_s
+
+    @property
+    def name(self) -> str:
+        # The recognizer is part of the identity: it changes the track, so it
+        # must change the viseme cache key (the pipeline hashes `name`).
+        return f"rhubarb:{self.recognizer}"
+
+    @property
+    def uses_dialog_file(self) -> bool:
+        """Whether the chosen recognizer reads a transcript at all."""
+        return self.recognizer == _ENGLISH_RECOGNIZER
+
+    def align(self, audio: AudioClip, transcript: str) -> VisemeTrack:
+        if not self.binary_path:
+            raise RuntimeError(
+                "rhubarb binary not found on PATH. Install with: "
+                "brew install rhubarb-lipsync (macOS) or grab a release from "
+                "https://github.com/DanielSWolf/rhubarb-lip-sync/releases."
+            )
+        with tempfile.TemporaryDirectory() as d:
+            d = Path(d)
+            audio_path = audio.path
+            if audio_path is None:
+                if audio.bytes_ is None:
+                    raise ValueError("AudioClip needs either .path or .bytes_")
+                audio_path = d / "audio.wav"
+                audio_path.write_bytes(audio.bytes_)
+
+            out_json = d / "out.json"
+            cmd = [self.binary_path, "-f", "json", "-r", self.recognizer]
+            if self.uses_dialog_file:
+                dialog_path = d / "transcript.txt"
+                dialog_path.write_text(transcript, encoding="utf-8")
+                cmd += ["--dialogFile", str(dialog_path)]
+            cmd += ["-o", str(out_json), str(audio_path)]
+            try:
+                subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    timeout=self.timeout_s,
+                    check=True,
+                )
+            except subprocess.CalledProcessError as e:
+                raise RuntimeError(
+                    f"rhubarb failed (rc={e.returncode}): {e.stderr}"
+                ) from e
+            data = json.loads(out_json.read_text(encoding="utf-8"))
+
+        cues = data.get("mouthCues", [])
+        visemes = [Viseme(time=float(c["start"]), code=str(c["value"])) for c in cues]
+        if cues:
+            # Append a final rest at the last cue's "end" so the track matches duration.
+            last_end = float(cues[-1]["end"])
+            if not visemes or visemes[-1].code != "X":
+                visemes.append(Viseme(time=last_end, code="X"))
+        return VisemeTrack(
+            visemes=visemes,
+            convention=self.convention,
+            duration=audio.duration,
+        )

cutan/audio/whisper_lipsync.py

@@ -0,0 +1,143 @@
+"""WhisperLipSync — faster-whisper word timestamps → viseme keyframes.
+
+Phase 9. Bridges the gap between deterministic ``OfflineLipSync`` (twitchy,
+char-distributed) and the system-binary-dependent ``RhubarbLipSync``. Uses
+``faster-whisper`` to transcribe the rendered audio into word-level
+timestamps, then distributes visemes within each word's [start, end] span
+based on the word's letter→viseme mapping (collapsed-duplicates).
+
+This gives ~75% of Rhubarb-quality lip-sync without any system binaries,
+just a ~75 MB model download (cached after first use).
+
+Trade-offs vs. OfflineLipSync:
+
+- **Better**: timing is locked to actual word boundaries. Mouth holds shape
+  through silent gaps between words instead of cycling through visemes.
+- **Same**: viseme codes per phoneme are still our simple letter mapping;
+  no IPA/ARPAbet awareness yet (that's a future upgrade with cmudict).
+- **Cost**: ~3–5 seconds CPU inference for a 10s clip on first call;
+  subsequent calls in the same process re-use the cached model.
+"""
+
+from __future__ import annotations
+
+import io
+import tempfile
+from pathlib import Path
+from typing import Iterable
+
+from an.audio.lipsync import (
+    LipSyncProvider,
+    Viseme,
+    VisemeTrack,
+    WordTiming,
+    word_timings_to_visemes,
+)
+from an.audio.tts import AudioClip
+
+
+# Reuse the offline char→viseme mapping so the two providers stay consistent.
+from cutan.audio.offline_lipsync import _CHAR_TO_VISEME, _REST_VISEME
+
+
+_DEFAULT_MODEL_SIZE: str = "tiny"  # ~75 MB; "base" gives slightly better word-timing
+_DEFAULT_DEVICE: str = "cpu"
+_DEFAULT_COMPUTE_TYPE: str = "int8"
+_MIN_WORD_GAP_FOR_REST: float = (
+    0.20  # seconds; insert rest viseme in gaps wider than this
+)
+
+
+class WhisperLipSync:
+    """faster-whisper word timestamps → visemes.
+
+    Implements the ``LipSyncProvider`` protocol. The model is lazy-loaded on
+    the first call (subsequent calls in the same process reuse the instance
+    via the class-level ``_model`` cache).
+    """
+
+    #: Whisper aligns from words, so the track carries them (an#96).
+    emits_word_timings: bool = True
+
+    name: str = "whisper"
+    convention: str = "rhubarb"
+
+    _model = None  # class-level cache so repeated align() calls share the model
+
+    def __init__(
+        self,
+        *,
+        model_size: str = _DEFAULT_MODEL_SIZE,
+        device: str = _DEFAULT_DEVICE,
+        compute_type: str = _DEFAULT_COMPUTE_TYPE,
+        char_to_viseme: dict[str, str] | None = None,
+    ) -> None:
+        self.model_size = model_size
+        self.device = device
+        self.compute_type = compute_type
+        self._mapping = (
+            dict(char_to_viseme) if char_to_viseme else dict(_CHAR_TO_VISEME)
+        )
+
+    def _get_model(self):
+        if WhisperLipSync._model is not None:
+            return WhisperLipSync._model
+        try:
+            from faster_whisper import WhisperModel  # type: ignore
+        except ImportError as e:
+            raise RuntimeError(
+                "faster-whisper not installed. pip install faster-whisper "
+                "(adds ~100 MB) or use the offline lipsync provider."
+            ) from e
+        WhisperLipSync._model = WhisperModel(
+            self.model_size, device=self.device, compute_type=self.compute_type
+        )
+        return WhisperLipSync._model
+
+    def align(self, audio: AudioClip, transcript: str) -> VisemeTrack:
+        # faster-whisper takes a path or file-like. Materialize bytes to disk
+        # if the caller didn't pass a path.
+        if audio.path and Path(audio.path).exists():
+            audio_path: str | Path = audio.path
+            cleanup: Path | None = None
+        elif audio.bytes_:
+            tmp = tempfile.NamedTemporaryFile(delete=False, suffix=".bin")
+            tmp.write(audio.bytes_)
+            tmp.close()
+            audio_path = tmp.name
+            cleanup = Path(tmp.name)
+        else:
+            raise ValueError("AudioClip needs either .path or .bytes_")
+
+        try:
+            model = self._get_model()
+            segments, _info = model.transcribe(
+                str(audio_path),
+                word_timestamps=True,
+                # faster-whisper auto-detects language; pass the transcript as
+                # an "initial prompt" to bias decoding toward the known text.
+                initial_prompt=transcript or None,
+            )
+            words: list[WordTiming] = []
+            for seg in segments:
+                for w in seg.words or []:
+                    words.append((w.word, float(w.start), float(w.end)))
+        finally:
+            if cleanup is not None:
+                try:
+                    cleanup.unlink()
+                except OSError:
+                    pass
+
+        return VisemeTrack(
+            visemes=word_timings_to_visemes(
+                words,
+                total_duration=audio.duration,
+                char_to_viseme=self._mapping,
+                rest_viseme=_REST_VISEME,
+                min_gap_for_rest=_MIN_WORD_GAP_FOR_REST,
+            ),
+            convention=self.convention,
+            duration=audio.duration,
+            words=list(words),
+        )