语音¶

def say(
    self, script: str, *animations: Animation, voice: Voice | None = None
) -> Speech:
    """朗读一段脚本，在其被朗读时播放动画；场景等待二者完成。

    用方括号标记动画所属的词：给定的动画按顺序在括号标记的词期间播放，每个
    在其词开始时开始，持续其词的朗读时长，或其自身运行时间（取较长者；空的
    `[]` 在其所在处开始一个）。无括号时，动画在整个语音期间播放。括号不被
    朗读。

    Args:
        script: 要朗读的内容，每个动画对应一个括号区间（或无）。
        *animations: 动画，每个区间一个。
        voice: 朗读者；默认为场景的 [`voice`][manimgx.Scene.voice]。

    Returns:
        该语音，带有其各词及朗读时刻。

    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:
    """场景的语音为 `text` 所说的内容，但不播放。

    朗读一次后保存在场景文件旁的 `voice/` 中（以文本命名），因此场景再次
    渲染时不再朗读；用你自己相同内容的录音替换其中文件，即可改用该录音。
    播放该语音、添加它（[`add_sound`][manimgx.Scene.add_sound]：它在场景
    继续时朗读），或读取其 [`words`][manimgx.Speech.words]。

    Args:
        text: 要朗读的内容。
        voice: 朗读者；默认为场景的 [`voice`][manimgx.Scene.voice]。

    Returns:
        该语音。
    """
    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:
    """为影片添加字幕：`content` 从现在起加 `offset` 开始显示，持续
    `duration` 秒。

    影片的 [`captions`][manimgx.Film.captions] 持有它，连同其语音的字幕；
    `manimgx render` 将其作为字幕写入视频旁。

    Args:
        content: 字幕的文本。
        duration: 显示时长，以秒为单位。
        offset: 距现在多久后开始，以秒为单位。
    """
    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, ...]:
    """`text` 的词语，由 voice 对其定时片段按顺序计时（其字符
    或其标记）：每个词从其第一个字母所在片段的开始到
    其最后一个字母所在片段的结束。若片段未拼出文本的字母
    （voice 将 "2" 说成 "two"）则为空：其词语随后被估算。"""
    # 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 not letters or 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
        else:  # punctuation: beside the preceding word, or the first following word
            at = words[-1].end if words else owner[0][0]
            words.append(Word(m.group(), at, at))
    return tuple(words)

def estimate(text: str, samples: np.ndarray) -> tuple[Word, ...]:
    """`text` 中每个词在 `samples` 中被说出的时间，估算得出：音频的发声跨度
    按词语的字母数分配给各词，逗号或句号后的停顿会获得更多份额。"""
    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:
    """`voice` 为 `text` 说出的内容：说出一次，然后保存在 `folder` 中，作为其音频和
    一个包含其词语的 JSON，以文本以及 voice 和文本的摘要命名。

    音频可以被替换（相同词语的录音，引擎能读取的任何格式，
    同名文件下）：其词语随后从它重新计时。
    """
    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 []
        speech = Speech(audio, text=text, words=words)
        speech._edit = _Edit(**record.get("edit", {}))
        return speech
    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}",
                "edit": dataclasses.asdict(speech._edit),
                "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