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

1"""Sounds and timed speech: sources, edits, placement and soundtrack mixing.""" 

2 

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 

16 

17import numpy as np 

18 

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 

24 

25if TYPE_CHECKING: 

26 from manimgx.scene import Scene 

27import json 

28import re 

29from collections.abc import Sequence 

30 

31__all__ = ["Sound", "Speech", "Voice", "Word", "cached", "estimate", "timed"] 

32 

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.""" 

41 

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).""" 

46 

47_DECODED: Memo[int, np.ndarray] = Memo(64) 

48 

49 

50@dataclass(frozen=True, slots=True) 

51class _Edit: 

52 """How a sound is made from its source: in the order applied.""" 

53 

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 

63 

64 

65class Sound(Animation[Mobject]): 

66 """A sound a film plays. 

67 

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]. 

75 

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 """ 

81 

82 defaults: ClassVar[AnimationOptions] = {"rate_func": linear} 

83 speaks: ClassVar[bool] = False # speech ducks what is set to duck 

84 

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()) 

98 

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 

106 

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) 

110 

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) 

114 

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) 

118 

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) 

122 

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) 

127 

128 def speed(self, factor: float) -> Self: 

129 """This sound played `factor` times as fast, as a tape is: higher and shorter. 

130 

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) 

137 

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) 

141 

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) 

148 

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). 

155 

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) 

161 

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 

170 

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 

177 

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 ) 

185 

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 

197 

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' 

201 

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: ... 

208 

209 

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.""" 

214 

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 

221 

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 

226 

227 

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 

240 

241 key = digest(raw) 

242 return _DECODED.recall(key, lambda: _decode(raw)) 

243 

244 

245def _decode(raw: bytes) -> np.ndarray: 

246 from manimgx._engine import decode_audio 

247 

248 samples, channels = decode_audio(raw, RATE) 

249 return np.frombuffer(samples, np.float32).reshape(-1, channels) 

250 

251 

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 

255 

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) 

259 

260 

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 

282 

283 

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] 

294 

295 

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. 

299 

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 

328 

329 

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 ) 

350 

351 

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.""" 

358 

359 text: str 

360 start: float 

361 end: float 

362 

363 

364class Speech(Sound): 

365 """Speech: a sound that knows what it says and when it says each word. 

366 

367 A voice returns one. It plays as any sound does; [`Scene.say`][manimgx.Scene.say] 

368 also times animations by its words. 

369 

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 """ 

377 

378 speaks: ClassVar[bool] = True 

379 

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 

393 

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 ) 

410 

411 

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)`.""" 

415 

416 

417# ── timing ─────────────────────────────────────────────────────────────────────────────── 

418 

419 

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 

427 

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 

440 

441 

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 ) 

477 

478 

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 

493 

494 

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 ) 

501 

502 

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 

523 

524 

525# ── the script: [spans] in the text ───────────────────────────────────────────────────── 

526 

527_MARK = re.compile(r"\[([^\[\]]*)\]|([\[\]])") # a span, or a bracket that is no span's 

528 

529 

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 

550 

551 

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 

565 

566 

567# ── the cache: what a voice said, kept ────────────────────────────────────────────────── 

568 

569 

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. 

573 

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 

578 

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 

612 

613 

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 

630 

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}" 

643 

644 

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 ) 

655 

656 

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) 

661 

662 

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 

671 

672 

673_OTHER = object() # not a plain value: left out of a voice's name 

674 

675 

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() 

684 

685 

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" 

696 

697 

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 

720 

721 

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)