Coverage for src/manimgx/rendering/film.py: 99%
271 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"""Film: a scene's frames, as the player draws them — a view and one record per object (`feed`) —
2and its plays, sounds, sections and captions. Shapes and brushes reach the player once, keyed by
3content; a frame equal to the previous one lengthens it, unless it begins a section (a keyframe).
4Frames go to a video, to a callback (which draws those it wants), or nowhere (their records are
5still made); each play, as it ends, to a callback. The sounds are mixed as the video is written.
6"""
8import contextlib
9import json
10import os
11import pathlib
12from collections.abc import Callable
13from dataclasses import asdict, dataclass
14from fractions import Fraction
15from typing import TYPE_CHECKING, Final, Literal, get_args
16from warnings import deprecated
18from manimgx import _engine
19from manimgx.animation import clock
20from manimgx.rendering import feed
21from manimgx.rendering.feed import CameraView, Feeder
22from manimgx.settings import config
24__all__ = ["Film"]
26if TYPE_CHECKING:
27 import numpy as np
29 from manimgx.animation.timeline import Animation
30 from manimgx.audio.sound import Clip
31 from manimgx.drawing.geometry import Path
32 from manimgx.mobject import Mobject
33 from manimgx.scene import Camera
36X264Preset = Literal[
37 "ultrafast",
38 "superfast",
39 "veryfast",
40 "faster",
41 "fast",
42 "medium",
43 "slow",
44 "slower",
45 "veryslow",
46 "placebo",
47]
48"""The x264 presets, from fastest to slowest."""
50DEFAULT_ENCODER_PRESET: Final[X264Preset] = _engine.DEFAULT_ENCODER_PRESET
51"""The native encoder's default preset, shared by Python and the command line."""
52DEFAULT_ENCODER_CRF: Final[float] = _engine.DEFAULT_ENCODER_CRF
53"""The native encoder's default constant rate factor."""
56class Frame:
57 """A frame of a film, as the film sends it: shown as frames `index` to
58 `index + repeat - 1` of the video.
60 A frame the world holds still for is sent once, shown `repeat` times. Its pixels are
61 drawn only when asked for, by [`pixels`][manimgx.rendering.film.Frame.pixels].
63 Args:
64 index: Where it is in the film: the number of the first frame it is shown as.
65 repeat: How many frames it is shown for.
66 draw: The function that draws its pixels.
67 key: Whether it begins a section of the film.
68 """
70 __slots__ = ("_draw", "index", "key", "repeat")
72 def __init__(
73 self, index: int, repeat: int, draw: Callable[[], bytes], key: bool = False
74 ) -> None:
75 self.index = index
76 """Where it is in the film: the number of the first frame it is shown as, from
77 0."""
78 self.repeat = repeat
79 """How many frames it is shown for: more than 1 for a hold."""
80 self.key = key
81 """Whether it begins a [section][manimgx.rendering.film.Section] of the film: the picture
82 the section before it ends on."""
83 self._draw = draw
85 def pixels(self) -> bytes:
86 """Draw the frame, now.
88 Drawing is what a frame costs: ask only for the frames you keep, and before the
89 film sends its next frame.
91 Returns:
92 Its pixels: RGBA, a byte a channel, row after row from the top.
93 """
94 return self._draw()
97type FrameSink = Callable[[Frame], object]
98"""A function handed each frame of a film as the film sends it, a
99[`Frame`][manimgx.rendering.film.Frame] (see [`Scene.render`][manimgx.Scene.render]); what it returns
100is ignored. It may raise [`Cut`][manimgx.rendering.film.Cut] to end the film there."""
103@dataclass(frozen=True, slots=True)
104class Play:
105 """One play, or wait, of a scene, as its film keeps it: its number, when it began
106 and ended, and where the scene's code played it."""
108 index: int
109 """Its number, from 0: plays and waits are counted together."""
110 start: Fraction
111 """When it began, in seconds of scene time, exactly."""
112 end: Fraction
113 """When it ended, in seconds of scene time, exactly."""
114 where: tuple[str, int] | None
115 """Where the scene's code played it: the file and line of the innermost call outside
116 manimgx; None if there is none."""
119type SectionType = Literal[
120 "default.normal",
121 "presentation.normal",
122 "presentation.skip",
123 "presentation.loop",
124 "presentation.complete_loop",
125]
126"""How a presentation plays a section (Manim's section types): `normal` stops at its end
127until the presenter goes on; `skip` goes on by itself; `loop` plays it again and again until
128the presenter goes on; `complete_loop` too, finishing the round it is in first."""
131@dataclass(frozen=True, slots=True)
132class Section:
133 """A section of a film, as [`next_section`][manimgx.Scene.next_section] begins one: it
134 lasts until the next section begins, or the film ends."""
136 name: str
137 """Its name."""
138 start: Fraction
139 """When it begins, in seconds of scene time: a frame's time, exactly."""
140 frame: int
141 """Its first frame's number: a keyframe of the video, where a player can start."""
142 type: SectionType
143 """How a presentation plays it."""
144 notes: str
145 """What the presenter reads during it."""
148@dataclass(frozen=True, slots=True)
149class Caption:
150 """A caption of a film: `text`, shown from `start` to `end`, in seconds of scene
151 time."""
153 start: float
154 end: float
155 text: str
158def _wav(sound: "np.ndarray") -> bytes:
159 """A soundtrack as a WAV file: 16-bit, which every browser plays."""
160 import io
161 import wave
163 import numpy as np
165 from manimgx.audio.sound import RATE
167 out = io.BytesIO()
168 with wave.open(out, "wb") as w:
169 w.setnchannels(sound.shape[1])
170 w.setsampwidth(2)
171 w.setframerate(RATE)
172 w.writeframes((np.clip(sound, -1, 1) * 32767).round().astype("<i2").tobytes())
173 return out.getvalue()
176type Take = Callable[[bytes], object]
177"""A function handed a film's take as it is recorded (see [`Film`][manimgx.rendering.film.Film]):
178bytes of the stream manimgx's player reads — uploads, frames and notes, then the film's
179sound and captions — in order, frame by frame; what it returns is ignored. It may raise
180[`Cut`][manimgx.rendering.film.Cut] to end the film there: it is then sent nothing more (a
181[`Window`][manimgx.Window] closed by its viewer does)."""
184type PlayHook = Callable[[Play, tuple[Animation, ...]], object]
185"""A function called as each play or wait of a film ends (see
186[`Scene.render`][manimgx.Scene.render]), with the [`Play`][manimgx.rendering.film.Play] and the
187animations it played, the world as the play left it; what it returns is ignored. It may
188raise [`Cut`][manimgx.rendering.film.Cut] to end the film there."""
191class Cut(Exception):
192 """An early end to a film: raised by a frame sink, a play hook or a take, it stops
193 the scene there.
195 The film closes as it is: its video, if any, is written up to the last frame sent.
196 """
199@dataclass(frozen=True, slots=True)
200class Export:
201 """How a film's video was made: what [`Film.export`][manimgx.Film.export] holds once
202 the video is written."""
204 seconds: float
205 """How long the video took, in seconds: from its start, as the scene began
206 rendering, to its file written."""
207 x264: float
208 """Of those, the seconds spent in x264, the H.264 encoder (on a thread of its
209 own)."""
210 converted: float
211 """The share of the video's 16 × 16 pixel blocks converted for the encoder, from 0
212 to 1: the others had not changed since the frame before, and were skipped."""
213 bytes: int
214 """The size of the file, in bytes."""
217class Film:
218 """A scene's film: its frames, as they are sent, its plays, and its sounds, sections
219 and captions.
221 [`Scene.render`][manimgx.Scene.render] makes one and returns it. Each frame is sent
222 once: encoded into the video, if there is one, and handed to `frames`, if given; a
223 frame equal to the one before is not sent again, but lengthens it. Each play, as it
224 ends, is kept, and handed to `plays`, if given. The sounds the scene placed are mixed
225 into the video's sound track as it is written.
227 A film can instead be recorded as a take: the engine's work written down — each shape
228 once, then each frame's view and records, and at the end its sound and captions — for
229 ManimGX's player to play, at any moment: in a [`Window`][manimgx.Window], live as the
230 scene runs (`manimgx preview`), or in the browser, where Python has no GPU (Pyodide).
232 Args:
233 video: The MP4 file the frames are encoded into as they come, if any; its folder
234 is made if it is missing.
235 frames: A function handed each frame, a [`Frame`][manimgx.rendering.film.Frame] (see
236 [`FrameSink`][manimgx.rendering.film.FrameSink]).
237 plays: A function called as each play ends (see
238 [`PlayHook`][manimgx.rendering.film.PlayHook]).
239 take: A function handed the take's bytes as they are recorded, frame by frame,
240 if the film is recorded as a take (see [`Take`][manimgx.rendering.film.Take]).
241 preset: The x264 preset the video is encoded with: faster presets make larger
242 files.
243 crf: The video's quality, as x264's constant rate factor, from 0 to 51:
244 lower is better, the default value is 23.
245 """
247 def __init__(
248 self,
249 video: str | os.PathLike[str] | None = None,
250 *,
251 frames: FrameSink | None = None,
252 plays: PlayHook | None = None,
253 take: Take | None = None,
254 preset: X264Preset = DEFAULT_ENCODER_PRESET,
255 crf: float = DEFAULT_ENCODER_CRF,
256 ) -> None:
257 if preset not in get_args(X264Preset):
258 raise ValueError(f"unknown x264 preset {preset!r}")
259 if not 0 <= crf <= 51:
260 raise ValueError(
261 f"x264 CRF must be a finite number from 0 to 51, not {crf}"
262 )
263 fps = config.frame_rate
264 if video is not None and fps != int(fps):
265 raise ValueError(
266 f"a video needs a whole number of frames per second, not {fps}"
267 )
268 width, height = config.pixel_width, config.pixel_height
269 if video is not None and (width % 2 or height % 2): # H.264's 4:2:0 halves both
270 raise ValueError(
271 f"a video needs an even width and height, not {width}x{height}"
272 )
273 self.fps = clock.rational(fps)
274 """How many frames a second the film has: the configuration's when it began."""
275 # the GPU draws the film; or its take is recorded, to be drawn by ManimGX's player: by
276 # choice, or where the engine has no GPU (in Pyodide)
277 self._player: _engine.Player | None = None
278 self._recorder: _engine.Recorder | None = None
279 drawn: _engine.Player | _engine.Recorder
280 if take is None and (gpu := feed.Player) is not None:
281 if video is not None or frames is not None:
282 _engine.start_gpu() # the film draws: the GPU comes up as it begins
283 self._player = drawn = gpu(width, height)
284 if video is not None:
285 pathlib.Path(video).parent.mkdir(parents=True, exist_ok=True)
286 drawn.begin_export(
287 os.fspath(video), fps=int(fps), preset=preset, crf=crf
288 )
289 elif video is None and frames is None:
290 self._recorder = drawn = _engine.Recorder(width, height, fps)
291 else:
292 raise ValueError(
293 "a film recorded as a take is drawn by ManimGX's player, not here: it"
294 " has no video or pixels"
295 + ("" if feed.Player else " (this Python has no GPU)")
296 )
297 self._take = take
298 self.feeder = Feeder(width, height, drawn)
299 self.video = None if video is None else os.fspath(video)
300 """The path of the video being written; None once it is written, and if there is
301 none."""
302 self.frames = frames
303 """The function each drawn frame is handed to, if any."""
304 self.frame_count = 0
305 """How many frames the film has so far, a hold counting every frame it lasts."""
306 self.plays: list[Play] = []
307 """The plays and waits the scene has run, in order: each a
308 [`Play`][manimgx.rendering.film.Play]."""
309 self.sections: list[Section] = [
310 Section("unnamed", Fraction(0), 0, "default.normal", "")
311 ]
312 """The film's sections, in order: each a [`Section`][manimgx.rendering.film.Section],
313 lasting until the next begins. The first begins with the film."""
314 self.subcaptions: list[Caption] = []
315 """The captions the scene added (see
316 [`add_subcaption`][manimgx.Scene.add_subcaption]); [`captions`]
317 [manimgx.Film.captions] adds those of its speech."""
318 self.clips: list[Clip] = []
319 """The sounds the scene placed, in the order it placed them: each a
320 [`Clip`][manimgx.audio.sound.Clip], from its start in scene time."""
321 self.export: Export | None = None
322 """How the video was made, once it is written: an
323 [`Export`][manimgx.rendering.film.Export]; None until then, and with no video."""
324 self._hook = plays
325 self._pending: tuple[bytes, bytes, list[CameraView], int] | None = (
326 None # sent once it ends
327 )
328 self._first = 0 # the index of the pending frame
329 self._key = False # the next frame begins a section: a keyframe of its own
330 self._pending_key = False # the pending frame is one
332 def soundtrack(self) -> "np.ndarray | None":
333 """The film's sound: its clips mixed over its length, at
334 [`RATE`][manimgx.audio.sound.RATE] samples a second, one column per channel; None if
335 the scene placed no sound."""
336 from manimgx.audio.sound import mix
338 return mix(self.clips, self.frame_count / self.fps)
340 @deprecated("ManimGX's machinery: the scene calls it", category=None)
341 def section(
342 self, name: str, start: Fraction, type: SectionType, notes: str
343 ) -> None:
344 """Begin a section at the next frame, which starts at `start`: the scene calls it
345 (see [`next_section`][manimgx.Scene.next_section]). A section with no frame yet
346 gives way to it.
348 Args:
349 name: Its name.
350 start: When it begins: the next frame's time.
351 type: How a presentation plays it.
352 notes: What the presenter reads during it.
353 """
354 if self.sections[-1].frame == self.frame_count:
355 self.sections.pop()
356 self.sections.append(Section(name, start, self.frame_count, type, notes))
357 self._key = True
358 self._note({"section": asdict(self.sections[-1])})
360 def cut(self) -> list[tuple["Clip", float]]:
361 """The sounds the film's end cuts short: each clip, with the seconds it loses."""
362 end = self.frame_count / self.fps
363 out = []
364 for clip in self.clips:
365 if clip.end is None and clip.sound.duration != float("inf"):
366 lost = float(clip.start) + clip.sound.duration - float(end)
367 if lost > 1e-3:
368 out.append((clip, lost))
369 return out
371 def subtitles(self) -> str:
372 """The film's [`captions`][manimgx.Film.captions] as subtitles, in SubRip (`.srt`)
373 form: what players, editors and video sites read beside a video."""
375 def stamp(t: float) -> str:
376 ms = round(t * 1000)
377 return f"{ms // 3_600_000:02d}:{ms // 60_000 % 60:02d}:{ms // 1000 % 60:02d},{ms % 1000:03d}"
379 return "".join(
380 f"{i}\n{stamp(c.start)} --> {stamp(c.end)}\n{c.text}\n\n"
381 for i, c in enumerate(self.captions(), 1)
382 )
384 def captions(self) -> list[Caption]:
385 """The film's captions, in order of their start: those the scene added, and its
386 speech's, a line of a few words at a time as they are said."""
387 from manimgx.audio.sound import Speech, lines
389 spoken = [
390 Caption(float(clip.start) + a, float(clip.start) + b, text)
391 for clip in self.clips
392 if isinstance(clip.sound, Speech)
393 for a, b, text in lines(clip.sound)
394 ]
395 return sorted(self.subcaptions + spoken, key=lambda c: c.start)
397 @deprecated("ManimGX's machinery: the scene calls it", category=None)
398 def played(self, play: Play, animations: "tuple[Animation, ...]") -> None:
399 """Keep a play that has ended, and hand it to the play hook with the animations
400 it played: the scene calls it as each play ends, the world as the play left it.
402 Args:
403 animations: What it played.
404 """
405 # the film keeps the play, not the animations: they hold their objects' copies
406 self.plays.append(play)
407 if self._recorder is not None:
408 self._note({"play": asdict(play)})
409 if self._hook is not None:
410 self._hook(play, animations)
412 @deprecated("ManimGX's machinery: the scene calls it", category=None)
413 def picture(self, camera: "Camera", mobjects: "list[Mobject]") -> bytes:
414 """Draw the world as `camera` sees it now: a picture, not a frame of the film.
416 Args:
417 camera: The camera it is seen through.
418 mobjects: The mobjects drawn, in the order they are drawn.
420 Returns:
421 Its pixels: RGBA, a byte a channel, row after row from the top.
422 """
423 view, records, cameras = self.feeder.picture(camera, mobjects)
424 if self._player is None:
425 raise RuntimeError("a film recorded as a take is drawn by ManimGX's player")
426 if self._player.pressured():
427 self.feeder.sweep([records, *[c[4] for c in cameras]], pressed=True)
428 return self._player.render(view, records, cameras)
430 @deprecated("ManimGX's machinery: the scene calls it", category=None)
431 def record(
432 self, camera: "Camera", mobjects: "list[Mobject]", repeat: int = 1
433 ) -> None:
434 """Record a frame: the mobjects as `camera` sees them, shown for `repeat`
435 frames.
437 The scene calls it for each frame it computes.
439 Args:
440 camera: The camera the frame is seen through.
441 mobjects: The mobjects drawn, in the order they are drawn (see
442 [`display_list`][manimgx.Scene.display_list]).
443 repeat: How many frames it is shown for.
444 """
445 view, records, cameras = self.feeder.frame(camera, mobjects)
446 self._add(view, records, cameras, repeat)
448 @deprecated("ManimGX's machinery: the scene calls it", category=None)
449 def tween(
450 self,
451 camera: "Camera",
452 mobjects: "list[Mobject]",
453 leaves: "list[tuple[Mobject, list[Mobject], Path, np.ndarray, np.ndarray]]",
454 ) -> None:
455 """Record, at once, the frames of a play that only carries its leaves between
456 keyframes: the scene calls it for such a play.
458 Args:
459 camera: The camera the frames are seen through.
460 mobjects: The mobjects drawn, in the order they are drawn.
461 leaves: For each moving leaf: the leaf, its keyframes, its path, and per
462 frame the interval it is in and the time along it (-1 marking the frames
463 the entry does not claim).
464 """
465 for view, records in self.feeder.tween(camera, mobjects, leaves):
466 self._add(view, records, [], 1)
468 def _add(
469 self, view: bytes, records: bytes, cameras: list[CameraView], repeat: int
470 ) -> None:
471 pending = self._pending
472 if (
473 pending is not None
474 and not self._key
475 and pending[:3] == (view, records, cameras)
476 ):
477 self._pending = (view, records, cameras, pending[3] + repeat)
478 else:
479 self._send()
480 self._pending = (view, records, cameras, repeat)
481 self._first = self.frame_count
482 self._pending_key, self._key = self._key, False
483 self.frame_count += repeat
485 def _send(self) -> None:
486 pending, self._pending = self._pending, None
487 if pending is None:
488 return
489 view, records, cameras, repeat = pending
490 if self._recorder is not None:
491 self._recorder.frame(view, records, repeat, cameras)
492 self._flush()
493 if (player := self._player) is None:
494 return
495 if (self.video is not None or self.frames is not None) and player.pressured():
496 self.feeder.sweep([records, *[c[4] for c in cameras]], pressed=True)
497 key = self._pending_key
498 if self.frames is None:
499 if self.video is not None:
500 player.push(view, records, repeat, cameras, key)
501 return
502 sent = self.video is None
504 def push() -> None:
505 nonlocal sent
506 if not sent:
507 player.push(view, records, repeat, cameras, key)
508 sent = True
510 def draw() -> bytes:
511 nonlocal sent
512 if sent:
513 return player.render(view, records, cameras)
514 # A pixel consumer and the encoder share one completed GPU draw. Defer export
515 # until the callback asks: metadata-only callbacks keep the asynchronous path.
516 pixels = player.push(view, records, repeat, cameras, key, capture=True)
517 sent = True
518 assert pixels is not None
519 return pixels
521 try:
522 self.frames(Frame(self._first, repeat, draw, key))
523 except Cut:
524 push() # the frame that cuts a film still belongs to its video
525 raise
526 push()
528 @deprecated("ManimGX's machinery: the scene calls it", category=None)
529 def close(self) -> None:
530 """Close the film: send its last frame, and write its video, if any.
532 [`Scene.render`][manimgx.Scene.render] calls it as the scene ends. A
533 [`Cut`][manimgx.rendering.film.Cut] raised for the last frame ends the film all the same;
534 any other error abandons the video.
535 """
536 try:
537 with contextlib.suppress(Cut):
538 self._send()
539 with contextlib.suppress(Cut): # its take cut it: it hears no more
540 self._end()
541 except BaseException:
542 self.abort()
543 raise
545 def _end(self) -> None:
546 """Write the closed film's video, if any, and tell its take how it ends."""
547 if self.video is not None and self._player is not None:
548 sound = self.soundtrack()
549 if sound is None:
550 self.export = Export(*self._player.end_export())
551 else:
552 from manimgx.audio.sound import BITRATE, RATE
554 channels = sound.shape[1]
555 self.export = Export(
556 *self._player.end_export(
557 sound.tobytes(), channels, RATE, BITRATE * channels
558 )
559 )
560 self.video = None
561 if self._recorder is not None:
562 # what the player plays and shows beside the frames; then the take's end
563 if (sound := self.soundtrack()) is not None:
564 self._recorder.sound(_wav(sound))
565 if captions := self.captions():
566 self._note({"captions": [asdict(c) for c in captions]})
567 self._recorder.end()
568 self._flush()
570 @deprecated("ManimGX's machinery: the scene calls it", category=None)
571 def abort(self) -> None:
572 """Stop the film without writing its video; its take, if it is recorded as one, ends
573 saying that its scene failed.
575 [`Scene.render`][manimgx.Scene.render] calls it when the scene fails.
576 """
577 if self.video is not None and self._player is not None:
578 self.video = None
579 self._player.abort_export()
580 if self._recorder is not None:
581 # its take keeps what was made until the scene failed, and ends saying so: a player
582 # drops it, unless it shows it already
583 pending, self._pending = self._pending, None
584 if pending is not None:
585 view, records, cameras, repeat = pending
586 self._recorder.frame(view, records, repeat, cameras)
587 self._recorder.end(failed=True)
588 with contextlib.suppress(Cut): # cut already: it hears nothing more
589 self._flush()
591 def _note(self, note: dict[str, object]) -> None:
592 """Tell whoever shows the take the film's own records, as JSON (an exact time as a
593 float): a play that ended, a section, the captions."""
594 if self._recorder is not None:
595 self._recorder.note(json.dumps(note, default=float))
596 self._flush()
598 def _flush(self) -> None:
599 """Hand the take what was recorded since (with nobody to hand it to, drop it); once
600 it cuts the film, it is handed nothing more."""
601 if self._recorder is not None:
602 data = self._recorder.drain()
603 if self._take is not None and data:
604 try:
605 self._take(data)
606 except Cut:
607 self._take = None
608 raise