Coverage for src/manimgx/audio/sound.py: 97%
400 statements
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
1"""Sounds and timed speech: sources, edits, placement and soundtrack mixing."""
3import dataclasses
4import marshal
5import math
6import os
7import unicodedata
8from collections.abc import Callable
9from dataclasses import dataclass
10from fractions import Fraction
11from itertools import pairwise
12from pathlib import Path
13from types import CodeType
14from typing import TYPE_CHECKING, ClassVar, Self
15from warnings import deprecated
17import numpy as np
19from manimgx.animation import clock
20from manimgx.animation.easing import linear
21from manimgx.animation.timeline import Animation, AnimationOptions
22from manimgx.caches import Memo
23from manimgx.mobject import Mobject
25if TYPE_CHECKING:
26 from manimgx.scene import Scene
27import json
28import re
29from collections.abc import Sequence
31__all__ = ["Sound", "Speech", "Voice", "Word", "cached", "estimate", "timed"]
33RATE = 48_000
34"""The soundtrack's sample rate: 48,000 samples a second, as video's sound has."""
35CUT = 0.005
36"""How long a sound cut short fades out, at least, in seconds: a cut mid-wave clicks."""
37DUCK_ATTACK, DUCK_RELEASE = 0.15, 0.5
38"""How long a ducking sound takes to dip before speech, and to come back after it (s)."""
39BITRATE = 224_000
40"""The soundtrack's bitrate per channel: AAC-LC at 224 kbps."""
42type Source = str | os.PathLike[str] | bytes | np.ndarray
43"""What a sound is made from: a file's path, a file's bytes (any common audio file: WAV, AIFF,
44MP3, AAC/M4A, Opus, Vorbis, FLAC, ALAC; a video's sound too), or samples (float, -1 to 1: one
45column per channel)."""
47_DECODED: Memo[int, np.ndarray] = Memo(64)
50@dataclass(frozen=True, slots=True)
51class _Edit:
52 """How a sound is made from its source: in the order applied."""
54 start: float = 0.0 # the source trimmed to [start, end) seconds
55 end: float | None = None
56 speed: float = 1.0 # played faster (and higher) or slower (and lower)
57 loop: float | None = None # repeated to last this long (inf: until stopped)
58 gain: float = 0.0 # in decibels
59 fade_in: float = 0.0
60 fade_out: float = 0.0
61 pan: float = 0.0 # -1 left, 0 center, 1 right
62 duck: float = 0.0 # decibels it dips by while anything speaks
65class Sound(Animation[Mobject]):
66 """A sound a film plays.
68 Make one from a file, the bytes of one, or samples; edit it (each edit makes a new
69 sound); place it in a scene: [`add_sound`][manimgx.Scene.add_sound] starts it now and
70 takes no time, while [`play`][manimgx.Scene.play] plays it as a part of the play, which
71 then lasts at least as long as the sound. In a composition it starts when its window
72 opens: `LaggedStart(*(AnimationGroup(FadeIn(d), click) for d in dots))` clicks as each
73 dot appears. It changes nothing on screen, and a play's `run_time` does not change it:
74 a sound lasts its [`duration`][manimgx.audio.sound.Sound.duration].
76 Args:
77 source: A file's path, a file's bytes, or samples: floats from -1 to 1, one
78 column per channel (a 1-D array is mono), copied as they are given.
79 rate: The samples' rate, in samples a second; only for samples.
80 """
82 defaults: ClassVar[AnimationOptions] = {"rate_func": linear}
83 speaks: ClassVar[bool] = False # speech ducks what is set to duck
85 def __init__(self, source: Source, *, rate: int | None = None) -> None:
86 if isinstance(source, np.ndarray) != (rate is not None):
87 raise ValueError("give a rate with samples, and only with samples")
88 if rate is not None and (not math.isfinite(rate) or rate <= 0):
89 raise ValueError("the sample rate must be finite and positive")
90 if isinstance(source, str | os.PathLike) and not Path(source).is_file():
91 raise FileNotFoundError(f"no sound file at {os.fspath(source)!r}")
92 if isinstance(source, np.ndarray): # its own: the samples as they were given
93 source = np.array(source, copy=True, subok=True)
94 self.source = source
95 self.rate = rate
96 self._edit = _Edit()
97 super().__init__(Mobject())
99 # ── edits: each makes a new sound ─────────────────────────────────────────
100 def _but(self, **changes: float | None) -> Self:
101 other = object.__new__(type(self))
102 other.__dict__.update(self.__dict__)
103 other._edit = dataclasses.replace(self._edit, **changes)
104 other.__dict__.pop("_made", None)
105 return other
107 def gain(self, decibels: float) -> Self:
108 """This sound louder by `decibels` (quieter if negative: -6 halves it)."""
109 return self._but(gain=self._edit.gain + decibels)
111 def fade_in(self, seconds: float) -> Self:
112 """This sound fading in from silence over its first `seconds`."""
113 return self._but(fade_in=seconds)
115 def fade_out(self, seconds: float) -> Self:
116 """This sound fading out to silence over its last `seconds`."""
117 return self._but(fade_out=seconds)
119 def trim(self, start: float = 0.0, end: float | None = None) -> Self:
120 """The part of this sound from `start` to `end` seconds (None: its end)."""
121 return self._but(start=start, end=end)
123 def loop(self, duration: float | None = None) -> Self:
124 """This sound repeated to last `duration` seconds; None: until the film ends, or
125 until its clip is [stopped][manimgx.audio.sound.Clip.stop]."""
126 return self._but(loop=math.inf if duration is None else duration)
128 def speed(self, factor: float) -> Self:
129 """This sound played `factor` times as fast, as a tape is: higher and shorter.
131 The resulting speed must be finite and positive.
132 """
133 speed = self._edit.speed * factor
134 if not math.isfinite(speed) or speed <= 0:
135 raise ValueError("the resulting speed must be finite and positive")
136 return self._but(speed=speed)
138 def pan(self, position: float) -> Self:
139 """This sound placed from -1 (left) through 0 (center) to 1 (right)."""
140 return self._but(pan=position)
142 def duck(self, decibels: float = 12) -> Self:
143 """This sound dipping by `decibels` while anything speaks (while a
144 [`Speech`][manimgx.Speech] plays): music under a narration. It eases down
145 `DUCK_ATTACK` seconds before the speech and back up over `DUCK_RELEASE` after.
146 """
147 return self._but(duck=decibels)
149 @classmethod
150 def of(
151 cls, function: Callable[[np.ndarray], np.ndarray], duration: float
152 ) -> "Sound":
153 """A sound made by a function of time: `function(t)`, given the times of its
154 samples (seconds, an array), returns their values (-1 to 1).
156 Examples:
157 `Sound.of(lambda t: 0.3 * np.sin(2 * np.pi * 440 * t), 1)`: a second of A.
158 """
159 t = np.arange(round(duration * RATE)) / RATE
160 return cls(np.asarray(function(t), np.float32), rate=RATE)
162 # ── what it is ──────────────────────────────────────────────────────────────
163 @property
164 def samples(self) -> np.ndarray:
165 """Its samples at `RATE`: floats, one column per channel (1 or 2)."""
166 made = self.__dict__.get("_made")
167 if made is None:
168 made = self.__dict__["_made"] = _make(self)
169 return made
171 @property
172 def duration(self) -> float:
173 """How long it lasts, in seconds (inf for a sound looped until stopped)."""
174 if self._edit.loop is not None:
175 return self._edit.loop
176 return len(self.samples) / RATE
178 @property
179 def _duration(self) -> Fraction:
180 return (
181 Fraction(len(self.samples), RATE)
182 if self._edit.loop is None
183 else super()._duration
184 )
186 @property
187 def run_time(self) -> float:
188 """Its duration: a sound plays for as long as it lasts. An endless one (`loop()`)
189 cannot be played: add it ([`add_sound`][manimgx.Scene.add_sound]), and stop it.
190 """
191 if self._edit.loop == math.inf:
192 raise ValueError(
193 "an endless sound (loop()) never ends: add it with add_sound, and stop"
194 " its clip, instead of playing it"
195 )
196 return self.duration
198 @run_time.setter
199 def run_time(self, value: float) -> None:
200 pass # a play's run_time sets its animations', not its sounds'
202 # ── as an animation: it changes nothing on screen ─────────────────────────
203 def begin(self) -> None: ...
204 def finish(self) -> None: ...
205 def clean_up_from_scene(self, scene: "Scene") -> None: ...
206 def advance(self, t: Fraction) -> None: ...
207 def interpolate(self, alpha: float) -> None: ...
210@dataclass(eq=False)
211class Clip:
212 """A sound as a film plays it: from `start`, in seconds of scene time, until it ends
213 or is stopped. [`add_sound`][manimgx.Scene.add_sound] returns it."""
215 sound: Sound
216 start: Fraction
217 end: Fraction | None = (
218 None # stopped: silent from here, having faded out over `fade`
219 )
220 fade: float = 0.0
222 def stop(self, fade: float = 0.05) -> None:
223 """Stop the sound: it fades out from now (the instant the scene is computing) over
224 `fade` seconds, and is silent after."""
225 self.end, self.fade = clock.now + clock.rational(fade), fade
228def _source_samples(sound: Sound) -> np.ndarray:
229 """Source samples at RATE (2-D), possibly borrowed; consumers must not mutate them."""
230 source = sound.source
231 if isinstance(source, np.ndarray):
232 data = source.astype(np.float32, copy=False).reshape(
233 len(source), math.prod(source.shape[1:])
234 )
235 rate = sound.rate
236 assert rate is not None
237 return data if rate == RATE else _resample(data, rate, RATE)
238 raw = source if isinstance(source, bytes) else Path(source).read_bytes()
239 from manimgx._engine import digest
241 key = digest(raw)
242 return _DECODED.recall(key, lambda: _decode(raw))
245def _decode(raw: bytes) -> np.ndarray:
246 from manimgx._engine import decode_audio
248 samples, channels = decode_audio(raw, RATE)
249 return np.frombuffer(samples, np.float32).reshape(-1, channels)
252def _resample(data: np.ndarray, rate: float, to: float) -> np.ndarray:
253 """Samples at `rate` resampled to `to`: band-limited (the engine's windowed sinc)."""
254 from manimgx._engine import resample_audio
256 channels = data.shape[1]
257 out = resample_audio(np.ascontiguousarray(data).tobytes(), channels, rate, to)
258 return np.frombuffer(out, np.float32).reshape(-1, channels)
261def _make(sound: Sound) -> np.ndarray:
262 """The sound's samples: its source trimmed, sped, looped, its gain, fades and pan. An
263 endless loop is one round of it, without fades: the mix repeats it for as long as its
264 clip plays, and fades it where the clip starts and ends."""
265 e = sound._edit
266 data = _source_samples(sound)
267 data = data[round(e.start * RATE) : None if e.end is None else round(e.end * RATE)]
268 if e.speed != 1:
269 data = _resample(data, RATE * e.speed, RATE)
270 if e.loop is not None and math.isfinite(e.loop) and len(data):
271 n = round(e.loop * RATE)
272 data = np.tile(data, (-(-n // len(data)), 1))[:n]
273 data = data * np.float32(10 ** (e.gain / 20))
274 if e.loop != math.inf:
275 _ramp(data, e.fade_in, e.fade_out)
276 if e.pan:
277 if data.shape[1] == 1:
278 data = np.repeat(data, 2, axis=1)
279 data[:, 0] *= min(1.0, 1 - e.pan)
280 data[:, 1] *= min(1.0, 1 + e.pan)
281 return data
284def _ramp(data: np.ndarray, fade_in: float, fade_out: float) -> None:
285 """Fade the ends of `data` in place: linear ramps of those lengths."""
286 for seconds, head in ((fade_in, True), (fade_out, False)):
287 n = min(len(data), round(seconds * RATE))
288 if n:
289 ramp = np.linspace(0, 1, n, endpoint=False, dtype=np.float32)[:, None]
290 if head:
291 data[:n] *= ramp
292 else:
293 data[len(data) - n :] *= ramp[::-1]
296def mix(clips: list[Clip], duration: Fraction) -> np.ndarray | None:
297 """The soundtrack of a film `duration` seconds long: its clips mixed, at RATE (one
298 column per channel: mono when every clip is mono and centered); None if it has none.
300 A clip plays from its start until its sound ends, it is stopped, or the film ends; a
301 sound cut short fades out over its stop's fade, or `CUT` at least (a cut mid-wave
302 clicks). An endless loop fades in where its clip starts and out where it ends.
303 """
304 if not clips:
305 return None
306 total = round(duration * RATE)
307 channels = max(c.sound.samples.shape[1] for c in clips)
308 out = np.zeros((total, channels), np.float32)
309 for clip in clips:
310 at = round(clip.start * RATE)
311 if at >= total:
312 continue
313 e, data = clip.sound._edit, clip.sound.samples
314 span = (total if clip.end is None else min(total, round(clip.end * RATE))) - at
315 if span <= 0:
316 continue
317 stop = 0.0 if clip.end is None else clip.fade
318 if e.loop == math.inf and len(data):
319 data = np.tile(data, (-(-span // len(data)), 1))[:span]
320 _ramp(data, e.fade_in, max(e.fade_out, stop, CUT))
321 elif len(data) > span:
322 data = data[:span].copy()
323 _ramp(data, 0, max(stop, CUT))
324 if e.duck:
325 data = data * _ducked(clips, e.duck, at, len(data))[:, None]
326 out[at : at + len(data)] += data # mono into each channel of stereo
327 return out
330def _ducked(clips: list[Clip], decibels: float, at: int, length: int) -> np.ndarray:
331 """The gain of a ducking sound placed at sample `at` for `length` samples: 1, dipping
332 by `decibels` while any speech among `clips` plays (eased on a 10 ms grid)."""
333 low, hop = 10 ** (-decibels / 20), RATE // 100
334 grid = np.arange(at, at + length + hop, hop, dtype=np.float64) / RATE
335 gain = np.ones(len(grid))
336 for clip in clips:
337 if clip.sound.speaks:
338 a = float(clip.start)
339 b = a + clip.sound.duration
340 if clip.end is not None:
341 b = min(b, float(clip.end))
342 if b <= a:
343 continue
344 ease_in = np.clip((grid - (a - DUCK_ATTACK)) / DUCK_ATTACK, 0, 1)
345 ease_out = np.clip(((b + DUCK_RELEASE) - grid) / DUCK_RELEASE, 0, 1)
346 gain = np.minimum(gain, 1 - (1 - low) * np.minimum(ease_in, ease_out))
347 return np.interp(np.arange(length) / hop, np.arange(len(grid)), gain).astype(
348 np.float32
349 )
352@dataclass(frozen=True, slots=True)
353class Word:
354 """A word of a speech, and when it is said: from `start` to `end`, in seconds from the
355 speech's start. The words of a speech are pieces of its text, in order: those Unicode lets
356 a line break between (a word, a Chinese or Japanese character, a Thai word, each with the
357 marks that go with it), unless its voice gives its own."""
359 text: str
360 start: float
361 end: float
364class Speech(Sound):
365 """Speech: a sound that knows what it says and when it says each word.
367 A voice returns one. It plays as any sound does; [`Scene.say`][manimgx.Scene.say]
368 also times animations by its words.
370 Args:
371 source: The audio: a file's path, a file's bytes, or samples.
372 text: What it says.
373 words: Each word and when it is said, if the voice knows ([`timed`][manimgx.timed]
374 makes them from a voice's own timing); otherwise they are estimated from the audio.
375 rate: The samples' rate; only for samples.
376 """
378 speaks: ClassVar[bool] = True
380 def __init__(
381 self,
382 source: Source,
383 *,
384 text: str,
385 words: Sequence[Word] = (),
386 rate: int | None = None,
387 ) -> None:
388 super().__init__(source, rate=rate)
389 self.text = text
390 self._words = tuple(words) # the source's: before trims and speed
391 if self._words:
392 _located(self) # refuses words that are not pieces of the text
394 @property
395 def words(self) -> tuple[Word, ...]:
396 """Its words, in order, with when each is said (in seconds from its start): the
397 voice's, or estimated from the audio; a trim or a change of speed moves them with
398 the audio."""
399 if not self._words:
400 self._words = estimate(self.text, _source_samples(self))
401 e = self._edit
402 if e.start == 0 and e.speed == 1 and e.end is None:
403 return self._words
404 end = math.inf if e.end is None else e.end
405 return tuple(
406 Word(w.text, (w.start - e.start) / e.speed, (w.end - e.start) / e.speed)
407 for w in self._words
408 if e.start <= w.start < end
409 )
412type Voice = Callable[[str], Speech]
413"""Anything that speaks: a function from text to [`Speech`][manimgx.Speech]. Bring any
414text-to-speech: wrap its call in a function that returns `Speech(audio, text=text)`."""
417# ── timing ───────────────────────────────────────────────────────────────────────────────
420def _pieces(text: str) -> list[tuple[int, int, bool]]:
421 """The pieces a text is timed and shown in: what lies between two places Unicode lets a
422 line break, without its spaces (a word, a Chinese or Japanese character, a Thai word, each
423 with the marks that go with it), as the characters (begin, end) it spells, and whether a
424 sentence ends with it. An opening bracket or quote that the end of a sentence takes with it
425 (`。「`) begins the next sentence, as it begins the next line."""
426 from manimgx._engine import segments
428 breaks, sentences = segments(text)
429 ends = set()
430 for end in sentences:
431 while end and unicodedata.category(text[end - 1]) in ("Ps", "Pi"):
432 end -= 1
433 ends.add(end)
434 pieces = []
435 for a, b in pairwise(breaks):
436 if piece := text[a:b].strip():
437 begin = text.index(piece, a)
438 pieces.append((begin, begin + len(piece), b in ends))
439 return pieces
442def estimate(text: str, samples: np.ndarray) -> tuple[Word, ...]:
443 """When each word of `text` is said in `samples`, estimated: the audio's voiced span
444 shared among the words by their letters, with a share more for the pause after a comma or
445 a full stop."""
446 words = [text[a:b] for a, b, _ in _pieces(text)]
447 if not words:
448 return ()
449 level = np.abs(samples).max(axis=1) if samples.ndim > 1 else np.abs(samples)
450 hop = RATE // 100 # 10 ms
451 frames = len(level) // hop
452 loud = level[: frames * hop].reshape(frames, hop).max(axis=1) > 0.02
453 voiced = np.flatnonzero(loud)
454 if not len(voiced):
455 total = len(samples) / RATE
456 return tuple(
457 Word(w, total * i / len(words), total * (i + 1) / len(words))
458 for i, w in enumerate(words)
459 )
460 first, last = voiced[0], voiced[-1] + 1
461 # weight: letters, plus a pause after a comma or a full stop
462 weights = []
463 for w in words:
464 weights.append(len(w) + (6 if w[-1] in ".!?:;" else 3 if w[-1] == "," else 1))
465 total_weight = sum(weights)
466 edges = np.concatenate([[0], np.cumsum(weights)]) / total_weight
467 span = (last - first) / 100
468 times = first / 100 + edges * span
469 return tuple(
470 Word(
471 w,
472 float(times[i]),
473 float(times[i + 1] - (weights[i] - len(w)) / total_weight * span),
474 )
475 for i, w in enumerate(words)
476 )
479def _located(speech: Speech) -> list[tuple[int, int]]:
480 """Where each word of a speech is in its text, as the characters (begin, end) it spells.
481 The words are pieces of the text, in order: each is found after the one before."""
482 text, at, found = speech.text, 0, []
483 for word in speech.words:
484 begin = text.find(word.text, at)
485 if begin < 0:
486 raise ValueError(
487 f"the word {word.text!r} is not in {text!r} after character {at}: a"
488 " speech's words are pieces of its text, in order"
489 )
490 at = begin + len(word.text)
491 found.append((begin, at))
492 return found
495def _columns(text: str) -> int:
496 """How wide a text is shown, in columns: its spaces as one, and a wide character (Chinese,
497 Japanese, Korean) as two."""
498 return sum(
499 1 + (unicodedata.east_asian_width(c) in "WF") for c in " ".join(text.split())
500 )
503@deprecated("ManimGX's machinery: the captions call it", category=None)
504def lines(speech: Speech, width: int = 42) -> list[tuple[float, float, str]]:
505 """A speech as captions: its text in lines at most `width` columns wide (a Chinese or
506 Japanese character takes two), broken where Unicode lets a line break, a line ending where
507 a sentence does. A line is shown from when it begins to be said until the next one does,
508 or, ending a sentence, until it has been said; in seconds from the speech's start."""
509 text = speech.text
510 # each line's characters, and whether a sentence ends it
511 cut: list[tuple[int, int, bool]] = []
512 for a, b, ends in _pieces(text):
513 if cut and not cut[-1][2] and _columns(text[cut[-1][0] : b]) <= width:
514 cut[-1] = (cut[-1][0], b, ends)
515 else:
516 cut.append((a, b, ends))
517 said = [times(speech, (a, b)) for a, b, _ in cut]
518 shown = []
519 for k, ((a, b, ends), (start, end)) in enumerate(zip(cut, said, strict=True)):
520 until = end if ends or k + 1 == len(cut) else said[k + 1][0]
521 shown.append((start, until, " ".join(text[a:b].split())))
522 return shown
525# ── the script: [spans] in the text ─────────────────────────────────────────────────────
527_MARK = re.compile(r"\[([^\[\]]*)\]|([\[\]])") # a span, or a bracket that is no span's
530@deprecated("ManimGX's machinery: say calls it", category=None)
531def spans(script: str) -> tuple[str, list[tuple[int, int]]]:
532 """The text of a script, its brackets taken out, and each bracketed span's characters
533 in that text: `"Here is [a circle]."` is `("Here is a circle.", [(8, 16)])`. A span is
534 one `[` and the `]` after it, with no bracket between: any other bracket is an error."""
535 text, found, at = [], [], 0
536 shift = 0
537 for m in _MARK.finditer(script):
538 if m[2]:
539 raise ValueError(
540 f"the {m[2]!r} at character {m.start()} of {script!r} is not part of a"
541 " span: a span is one [ and the ] after it, with no bracket between"
542 )
543 text.append(script[at : m.start()])
544 begin = m.start() - shift
545 found.append((begin, begin + len(m[1])))
546 text.append(m[1])
547 at, shift = m.end(), shift + 2
548 text.append(script[at:])
549 return "".join(text), found
552@deprecated("ManimGX's machinery: say calls it", category=None)
553def times(speech: Speech, span: tuple[int, int]) -> tuple[float, float]:
554 """When the characters `span` of a speech's text are said: from the start of its first
555 word to the end of its last; an empty span, the start of the word it comes before (the
556 end of the last, if it comes after them all)."""
557 begin, end = span
558 words, places = speech.words, _located(speech)
559 inside = [w for w, (a, b) in zip(words, places) if a < end and b > begin]
560 if begin < end and inside:
561 return inside[0].start, inside[-1].end
562 ahead = (w.start for w, (_, b) in zip(words, places) if b > begin)
563 start = next(ahead, words[-1].end)
564 return start, start
567# ── the cache: what a voice said, kept ──────────────────────────────────────────────────
570def cached(voice: Voice, text: str, folder: Path) -> Speech:
571 """What `voice` says for `text`: spoken once, then kept in `folder` as its audio and a
572 JSON of its words, named by the text and a digest of the voice and the text.
574 The audio may be replaced (a recording of the same words, in any format the engine
575 reads, under the same name): its words are then timed again, from it.
576 """
577 from manimgx._engine import digest
579 identity = _identity(voice)
580 key = f"{digest(identity.encode(), b'\0', text.encode()):016x}"
581 slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")[:40]
582 stem = folder / f"{slug}-{key[:10]}"
583 meta = stem.with_suffix(".json")
584 if meta.exists():
585 record = json.loads(meta.read_text(encoding="utf-8"))
586 audio = stem.with_suffix(record["suffix"]).read_bytes()
587 same = record.get("audio") == f"{digest(audio):016x}"
588 words = [Word(*w) for w in record["words"]] if same else []
589 speech = Speech(audio, text=text, words=words)
590 speech._edit = _Edit(**record.get("edit", {}))
591 return speech
592 speech = voice(text)
593 folder.mkdir(parents=True, exist_ok=True)
594 suffix, data = _stored(speech)
595 stem.with_suffix(suffix).write_bytes(data)
596 meta.write_text(
597 json.dumps(
598 {
599 "text": text,
600 "voice": identity,
601 "suffix": suffix,
602 "audio": f"{digest(data):016x}",
603 "edit": dataclasses.asdict(speech._edit),
604 "words": [[w.text, w.start, w.end] for w in speech._words],
605 },
606 indent=1,
607 )
608 + "\n", # a text file, to commit
609 encoding="utf-8",
610 )
611 return speech
614def _identity(voice: Voice) -> str:
615 """What names a voice in the cache: what decides what it says. A dataclass's repr (its
616 settings; a key is left out of it); a function's name, its code and the plain values it
617 holds (in its closure, its defaults, and the fields of the object a method is bound
618 to); another callable's type and plain fields. A plain value is immutable: a string, a
619 number, a boolean, None, or a tuple of them — a voice's settings, not its state (a
620 client, a list it appends to)."""
621 if hasattr(voice, "__dataclass_fields__"):
622 return repr(voice)
623 fn = getattr(
624 voice, "__func__", voice
625 ) # a bound method: its function, and its object
626 code = getattr(fn, "__code__", None)
627 if code is None: # an object with __call__
628 return f"{type(voice).__module__}.{type(voice).__qualname__}{_fields(voice)!r}"
629 from manimgx._engine import digest
631 body = digest(marshal.dumps(_code(code)))
632 cells = tuple(c.cell_contents for c in getattr(fn, "__closure__", None) or ())
633 defaults = getattr(fn, "__defaults__", None) or ()
634 keywords = getattr(fn, "__kwdefaults__", None) or {}
635 held = (
636 _plain(cells),
637 _plain(defaults),
638 _plain(tuple(sorted(keywords.items()))),
639 _fields(getattr(voice, "__self__", None)),
640 )
641 name = f"{getattr(fn, '__module__', '')}.{getattr(fn, '__qualname__', '')}"
642 return f"{name}#{body:016x}{held!r}"
645def _code(code: CodeType) -> CodeType:
646 """A voice's code without source locations, including its nested functions."""
647 return code.replace(
648 co_filename="",
649 co_firstlineno=0,
650 co_linetable=b"",
651 co_consts=tuple(
652 _code(c) if isinstance(c, CodeType) else c for c in code.co_consts
653 ),
654 )
657def _fields(owner: object) -> tuple[tuple[str, object], ...]:
658 """An object's plain fields, in order of their names."""
659 plain = ((k, _plain(v)) for k, v in sorted(getattr(owner, "__dict__", {}).items()))
660 return tuple((k, v) for k, v in plain if v is not _OTHER)
663def _plain(value: object) -> object:
664 """`value` if it is plain (immutable: a string, number, boolean, None, or a tuple of
665 them, whose other items are left out); else `_OTHER`."""
666 if value is None or isinstance(value, str | int | float | bool | bytes):
667 return value
668 if isinstance(value, tuple):
669 return tuple(v for v in map(_plain, value) if v is not _OTHER)
670 return _OTHER
673_OTHER = object() # not a plain value: left out of a voice's name
676def _stored(speech: Speech) -> tuple[str, bytes]:
677 source = speech.source
678 if isinstance(source, bytes):
679 return _sniff(source), source
680 if isinstance(source, np.ndarray):
681 return ".wav", _wav(_source_samples(speech))
682 path = Path(source)
683 return path.suffix or ".bin", path.read_bytes()
686def _sniff(data: bytes) -> str:
687 if data[:4] == b"RIFF":
688 return ".wav"
689 if data[:4] == b"fLaC":
690 return ".flac"
691 if data[:4] == b"OggS":
692 return ".ogg"
693 if data[4:8] == b"ftyp":
694 return ".m4a"
695 return ".mp3"
698def _wav(samples: np.ndarray) -> bytes:
699 """Float samples at RATE as a 32-bit float WAV file."""
700 data = np.ascontiguousarray(samples, np.float32)
701 channels = data.shape[1] if data.ndim > 1 else 1
702 body = data.tobytes()
703 header = b"".join(
704 [
705 b"RIFF",
706 (36 + len(body)).to_bytes(4, "little"),
707 b"WAVEfmt ",
708 (16).to_bytes(4, "little"),
709 (3).to_bytes(2, "little"), # IEEE float
710 channels.to_bytes(2, "little"),
711 RATE.to_bytes(4, "little"),
712 (RATE * 4 * channels).to_bytes(4, "little"),
713 (4 * channels).to_bytes(2, "little"),
714 (32).to_bytes(2, "little"),
715 b"data",
716 len(body).to_bytes(4, "little"),
717 ]
718 )
719 return header + body
722def timed(text: str, pieces: Sequence[tuple[str, float, float]]) -> tuple[Word, ...]:
723 """The words of `text`, timed by a voice's timed pieces of it, in order (its characters,
724 or its tokens): each word from the start of the piece its first letter is in to the end
725 of the piece its last letter is in. Empty if the pieces don't spell the text's letters
726 (a voice that said "two" for "2"): its words are then estimated."""
727 # each letter of the pieces: its piece's times
728 owner: list[tuple[float, float]] = []
729 for piece, a, b in pieces:
730 owner += [(a, b)] * sum(c.isalnum() for c in piece)
731 letters = [c.lower() for c in text if c.isalnum()]
732 spelled = [c.lower() for piece, _, _ in pieces for c in piece if c.isalnum()]
733 if not letters or letters != spelled:
734 return ()
735 words, k = [], 0
736 for a, b, _ in _pieces(text):
737 n = sum(c.isalnum() for c in text[a:b])
738 if n:
739 words.append(Word(text[a:b], owner[k][0], owner[k + n - 1][1]))
740 k += n
741 else: # punctuation: beside the preceding word, or the first following word
742 at = words[-1].end if words else owner[0][0]
743 words.append(Word(text[a:b], at, at))
744 return tuple(words)