Voice¶

def say(
    self, script: str, *animations: Animation, voice: Voice | None = None
) -> Speech:
    """Speak a script, playing animations as it is said; the scene waits for both.

    Mark in brackets the words an animation belongs to: the animations given play,
    in order, during the bracketed words, each starting as its words start and
    lasting as long as they take to say, or its own run time if that is longer (an
    empty `[]` starts one where it stands). Without brackets, the animations play
    during the whole speech. The brackets are not spoken.

    Args:
        script: What to say, with a bracketed span for each animation (or none).
        *animations: The animations, one per span.
        voice: Who says it; by default the scene's [`voice`][manimgx.Scene.voice].

    Returns:
        The speech, with its words and when each is said.

    Examples:
        ```python
        import manimgx as m


        class SayExample(m.Scene):
            def construct(self) -> None:
                x2 = m.MathTex("x^2").shift(2 * m.LEFT)
                dx = m.MathTex("2x").shift(2 * m.RIGHT)
                self.add(x2)
                self.say(
                    "The derivative of [x squared] is [two x].",
                    m.Indicate(x2),
                    m.Write(dx),
                )
        ```
    """
    from manimgx.animation.timeline import AnimationGroup, Succession, Wait
    from manimgx.audio import spans, times

    text, found = spans(script)
    if found and len(found) != len(animations):
        raise ValueError(
            f"{len(found)} bracketed spans for {len(animations)} animations: give"
            " one animation per span"
        )
    speech = self.speech(text, voice)
    parts: list[Animation] = [speech]
    for anim, span in zip(
        animations, found or [None] * len(animations), strict=True
    ):
        start, end = (0.0, speech.duration) if span is None else times(speech, span)
        anim.run_time = max(anim.run_time, end - start)
        parts.append(Succession(Wait(start), anim) if start > 0 else anim)
    self.play(AnimationGroup(*parts))
    return speech

def speech(self, text: str, voice: Voice | None = None) -> Speech:
    """What the scene's voice says for `text`, without playing it.

    Spoken once, then kept in `voice/` beside the scene's file (named by the text), so
    the scene renders again without speaking again; replace a file there with your
    own recording of the same words, and it is used instead. Play the speech, add it
    ([`add_sound`][manimgx.Scene.add_sound]: it speaks while the scene goes on), or
    read its [`words`][manimgx.Speech.words].

    Args:
        text: What to say.
        voice: Who says it; by default the scene's [`voice`][manimgx.Scene.voice].

    Returns:
        The speech.
    """
    from manimgx.audio import Fal, cached

    # the scene's voice, as given: a function set on the class is not a method of it
    own = self.__dict__.get("voice", inspect.getattr_static(type(self), "voice"))
    if isinstance(own, staticmethod):
        own = own.__func__
    return cached(voice or own or Fal(), text, _voice_folder(self))

def add_subcaption(
    self, content: str, duration: float = 1, offset: float = 0
) -> None:
    """Caption the film: `content` shown from now plus `offset`, for `duration` seconds.

    The film's [`captions`][manimgx.Film.captions] hold it, with those of its
    speech; `manimgx render` writes them beside the video, as subtitles.

    Args:
        content: The caption's text.
        duration: How long it shows, in seconds.
        offset: How long after now it begins, in seconds.
    """
    start = float(clock.now) + offset
    self.film.subcaptions.append(Caption(start, start + duration, content))

def timed(text: str, pieces: Sequence[tuple[str, float, float]]) -> tuple[Word, ...]:
    """The words of `text`, timed by a voice's timed pieces of it, in order (its characters,
    or its tokens): each word from the start of the piece its first letter is in to the end
    of the piece its last letter is in. Empty if the pieces don't spell the text's letters
    (a voice that said "two" for "2"): its words are then estimated."""
    # each letter of the pieces: its piece's times
    owner: list[tuple[float, float]] = []
    for piece, a, b in pieces:
        owner += [(a, b)] * sum(c.isalnum() for c in piece)
    letters = [c.lower() for c in text if c.isalnum()]
    spelled = [c.lower() for piece, _, _ in pieces for c in piece if c.isalnum()]
    if letters != spelled:
        return ()
    words, k = [], 0
    for m in _WORD.finditer(text):
        n = sum(c.isalnum() for c in m.group())
        if n:
            words.append(Word(m.group(), owner[k][0], owner[k + n - 1][1]))
            k += n
        elif words:  # a word of no letters ("—"): at the end of the one before
            words.append(Word(m.group(), words[-1].end, words[-1].end))
    return tuple(words)

def estimate(text: str, samples: np.ndarray) -> tuple[Word, ...]:
    """When each word of `text` is said in `samples`, estimated: the audio's voiced span
    shared among the words by their letters, with a share more for the pause after a comma or
    a full stop. Against voices' own times, it is off by about 0.1 s on average."""
    words = _WORD.findall(text)
    if not words:
        return ()
    level = np.abs(samples).max(axis=1) if samples.ndim > 1 else np.abs(samples)
    hop = RATE // 100  # 10 ms
    frames = len(level) // hop
    loud = level[: frames * hop].reshape(frames, hop).max(axis=1) > 0.02
    voiced = np.flatnonzero(loud)
    if not len(voiced):
        total = len(samples) / RATE
        return tuple(
            Word(w, total * i / len(words), total * (i + 1) / len(words))
            for i, w in enumerate(words)
        )
    first, last = voiced[0], voiced[-1] + 1
    # weight: letters, plus a pause after a comma or a full stop
    weights = []
    for w in words:
        weights.append(len(w) + (6 if w[-1] in ".!?:;" else 3 if w[-1] == "," else 1))
    total_weight = sum(weights)
    edges = np.concatenate([[0], np.cumsum(weights)]) / total_weight
    span = (last - first) / 100
    times = first / 100 + edges * span
    return tuple(
        Word(
            w,
            float(times[i]),
            float(times[i + 1] - (weights[i] - len(w)) / total_weight * span),
        )
        for i, w in enumerate(words)
    )

def cached(voice: Voice, text: str, folder: Path) -> Speech:
    """What `voice` says for `text`: spoken once, then kept in `folder` as its audio and a
    JSON of its words, named by the text and a digest of the voice and the text.

    The audio may be replaced (a recording of the same words, in any format the engine
    reads, under the same name): its words are then timed again, from it.
    """
    from manimgx._engine import digest

    identity = _identity(voice)
    key = f"{digest(identity.encode(), b'\0', text.encode()):016x}"
    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")[:40]
    stem = folder / f"{slug}-{key[:10]}"
    meta = stem.with_suffix(".json")
    if meta.exists():
        record = json.loads(meta.read_text(encoding="utf-8"))
        audio = stem.with_suffix(record["suffix"]).read_bytes()
        same = record.get("audio") == f"{digest(audio):016x}"
        words = [Word(*w) for w in record["words"]] if same else []
        return Speech(audio, text=text, words=words)
    speech = voice(text)
    folder.mkdir(parents=True, exist_ok=True)
    suffix, data = _stored(speech)
    stem.with_suffix(suffix).write_bytes(data)
    meta.write_text(
        json.dumps(
            {
                "text": text,
                "voice": identity,
                "suffix": suffix,
                "audio": f"{digest(data):016x}",
                "words": [[w.text, w.start, w.end] for w in speech._words],
            },
            indent=1,
        )
        + "\n",  # a text file, to commit
        encoding="utf-8",
    )
    return speech