A community-maintained Python framework for creating mathematical animations.
Add support for encoding partial movie files in parallel (#4899)
pjfoba50f81485f3
diff --git a/docs/source/guides/configuration.rst b/docs/source/guides/configuration.rstindex 17cdfecc9..3ea27b89d 100644--- a/docs/source/guides/configuration.rst+++ b/docs/source/guides/configuration.rst@@ -351,11 +351,12 @@ A list of all config options['aspect_ratio', 'assets_dir', 'background_color', 'background_opacity','bottom', 'custom_folders', 'disable_caching', 'dry_run',- 'ffmpeg_loglevel', 'flush_cache', 'frame_height', 'frame_rate',+ 'encoder_queue_size', 'ffmpeg_loglevel', 'flush_cache', 'frame_height', 'frame_rate','frame_size', 'frame_width', 'frame_x_radius', 'frame_y_radius','from_animation_number', `fullscreen`, 'images_dir', 'input_file', 'left_side',- 'log_dir', 'log_to_file', 'max_files_cached', 'media_dir', 'media_width',- 'movie_file_extension', 'notify_outdated_version', 'output_file', 'partial_movie_dir',+ 'log_dir', 'log_to_file', 'max_files_cached', 'max_inflight_encoders',+ 'media_dir', 'media_width', 'movie_file_extension', 'notify_outdated_version',+ 'output_file', 'partial_movie_dir','pixel_height', 'pixel_width', 'plugins', 'preview','progress_bar', 'quality', 'right_side', 'save_as_gif', 'save_last_frame','save_pngs', 'scene_names', 'show_in_file_browser', 'sound', 'tex_dir',diff --git a/docs/source/guides/deep_dive.rst b/docs/source/guides/deep_dive.rstindex a5dc298d1..df3724882 100644--- a/docs/source/guides/deep_dive.rst+++ b/docs/source/guides/deep_dive.rst@@ -102,10 +102,12 @@ discussing the contents of the following chapters on a very high level.a part in which the passed animations and keyword arguments are processedand prepared, followed by the actual "render loop" in which the librarysteps through a time line and renders frame by frame. The final part- does some post-processing to save a short video segment ("partial movie file")- and cleanup for the next call to :meth:`.Scene.play`. In the end, after all of- :meth:`.Scene.construct` has been run, the library combines the partial movie- files to one video.+ does some post-processing and seals the encoding job for a short video segment+ ("partial movie file") before cleaning up for the next call to+ :meth:`.Scene.play`. Depending on the encoding configuration, the partial movie+ file can continue encoding while the next animation is rendered. In the end,+ after all of :meth:`.Scene.construct` has been run, the library waits for any+ remaining encoding jobs and combines the partial movie files into one video.And with that, let us get *in medias res*.@@ -310,10 +312,11 @@ the order they are called, these customizable methods are:After these three methods are run, the animations have been fully rendered,and Manim calls :meth:`.CairoRenderer.scene_finished` to gracefullycomplete the rendering process. This checks whether any animations have been-played -- and if so, it tells the :class:`.SceneFileWriter` to close the output-file. If not, Manim assumes that a static image should be output-which it then renders using the same strategy by calling the render loop-(see below) once.+played -- and if so, it tells the :class:`.SceneFileWriter` to finish the output.+For video output, this first waits for any partial movie files that are still+being encoded and then combines them into the final movie. If no animations have+been played, Manim assumes that a static image should be output, which it renders+using the same strategy by calling the render loop (see below) once.**Back in our toy example,** the call to :meth:`.Scene.render` firsttriggers :meth:`.Scene.setup` (which only consists of ``pass``), followed by@@ -762,12 +765,18 @@ to learn more, the :func:`.get_hash_from_play_call` function in themechanism.In the event that the animation has to be rendered, the renderer asks-its :class:`.SceneFileWriter` to open an output container. The process-is started by a call to ``libav`` and opens a container to which rendered-raw frames can be written. As long as the output is open, the container-can be accessed via the ``output_container`` attribute of the file writer.-With the writing process in place, the renderer then asks the scene-to "begin" the animations.+its :class:`.SceneFileWriter` to open a partial movie stream. The file writer+uses ``libav`` to create a container and video stream, then wraps them in a+``_PartialMovieEncodeJob``. Each encoding job owns its container, stream, frame+queue, and worker thread. During the render loop, rendered raw frames are added+to this queue and encoded by the worker. With the writing process in place, the+renderer then asks the scene to "begin" the animations.++By default, Manim finishes encoding each partial movie file before rendering the+next animation. If ``max_inflight_encoders`` is set to a value greater than 1,+encoding can instead overlap with rendering. The setting bounds the number of+partial movie encoders active at the same time, while ``encoder_queue_size``+bounds the number of pending frame buffers held by each parallel encoder.First, it literally *begins* all of the animations by calling theirsetup methods (:meth:`.Animation._setup_scene`, :meth:`.Animation.begin`).@@ -1001,26 +1010,33 @@ and :meth:`.Animation.clean_up_from_scene` methods are called.In the end, the time progression is closed (which completes the displayed progress bar)in the terminal. With the closing of the time progression, the:meth:`.Scene.play_internal` call is completed, and we return to the renderer,-which now orders the :class:`.SceneFileWriter` to close the output container that has-been opened for this animation: a partial movie file is written.+which now orders the :class:`.SceneFileWriter` to close the partial movie stream.+This seals the corresponding encoding job so that it accepts no more frames. With+the default ``max_inflight_encoders = 1``, the file writer immediately waits for+the job and the partial movie file has been written when the call returns. With a+higher value, the job can remain in flight while the next animation is rendered;+the oldest jobs are joined as the configured limit is reached.This pretty much concludes the walkthrough of a :class:`.Scene.play` call,and actually there is not too much more to say for our toy example either: at-this point, a partial movie file that represents playing the-:class:`.ReplacementTransform` has been written. The initialization of-the :class:`.Dot` happens analogous to the initialization of ``blue_circle``,-which has been discussed above. The :meth:`.Mobject.add_updater` call literally-just attaches a function to the ``updaters`` attribute of the ``small_dot``. And-the remaining :meth:`.Scene.play` and :meth:`.Scene.wait` calls follow the-exact same procedure as discussed in the render loop section above; each such call-produces a corresponding partial movie file.--Once the :meth:`.Scene.construct` method has been fully processed (and thus all-of the corresponding partial movie files have been written), the-scene calls its cleanup method :meth:`.Scene.tear_down`, and then-asks its renderer to finish the scene. The renderer, in turn, asks-its scene file writer to wrap things up by calling :meth:`.SceneFileWriter.finish`,-which triggers the combination of the partial movie files into the final product.+this point, the encoding job for a partial movie file representing the+:class:`.ReplacementTransform` has been sealed (and, with the default encoding+configuration, the file has been written). The initialization of the+:class:`.Dot` happens analogous to the initialization of ``blue_circle``, which+has been discussed above. The :meth:`.Mobject.add_updater` call literally just+attaches a function to the ``updaters`` attribute of the ``small_dot``. And the+remaining :meth:`.Scene.play` and :meth:`.Scene.wait` calls follow the exact same+procedure as discussed in the render loop section above; each such call produces+a corresponding partial movie file.++Once the :meth:`.Scene.construct` method has been fully processed, the scene calls+its cleanup method :meth:`.Scene.tear_down`, and then asks its renderer to finish+the scene. The renderer, in turn, asks its scene file writer to wrap things up by+calling :meth:`.SceneFileWriter.finish`. The file writer first waits for all+remaining encoding jobs, then combines the completed partial movie files into the+final product. If rendering aborts during a play instead, the current job is+sealed and drained, and its incomplete partial movie file is removed so that it+cannot be mistaken for a valid cached result on a later render.And there you go! This is a more or less detailed description of how Manim worksunder the hood. While we did not discuss every single line of code in detaildiff --git a/manim/_config/default.cfg b/manim/_config/default.cfgindex 9155d28db..a77e83227 100644--- a/manim/_config/default.cfg+++ b/manim/_config/default.cfg@@ -129,6 +129,17 @@ use_projection_stroke_shaders = Falsemovie_file_extension = .mp4+# Maximum number of partial movie files being encoded concurrently while the+# scene continues rendering. 1 encodes each animation's file before the next+# animation starts; values > 1 overlap encoding with rendering (bounds pipeline+# depth, not CPU use; each encoder already slice-threads internally).+# 4 is a good value on typical hardware.+max_inflight_encoders = 1++# Maximum number of pending frame buffers held by each encoder when parallel+# encoding is enabled. Ignored when max_inflight_encoders is 1.+encoder_queue_size = 8+# These now override the --quality option.frame_rate = 60pixel_height = 1080diff --git a/manim/_config/utils.py b/manim/_config/utils.pyindex 3e4584653..53db049b6 100644--- a/manim/_config/utils.py+++ b/manim/_config/utils.py@@ -266,6 +266,7 @@ class ManimConfig(MutableMapping):"disable_caching","disable_caching_warning","dry_run",+ "encoder_queue_size","enable_wireframe","ffmpeg_loglevel","format",@@ -283,6 +284,7 @@ class ManimConfig(MutableMapping):"log_dir","log_to_file","max_files_cached",+ "max_inflight_encoders","media_dir","movie_file_extension","notify_outdated_version",@@ -605,6 +607,8 @@ class ManimConfig(MutableMapping):"from_animation_number","upto_animation_number","max_files_cached",+ "max_inflight_encoders",+ "encoder_queue_size",# the next two must be set BEFORE digesting frame_width and frame_height"pixel_height","pixel_width",@@ -778,6 +782,8 @@ class ManimConfig(MutableMapping):"no_latex_cleanup","preview_command","seed",+ "max_inflight_encoders",+ "encoder_queue_size",]:if hasattr(args, key):attr = getattr(args, key)@@ -1227,6 +1233,37 @@ class ManimConfig(MutableMapping):def max_files_cached(self, value: int) -> None:self._set_pos_number("max_files_cached", value, True)+ @property+ def max_inflight_encoders(self) -> int:+ """Maximum number of partial movie files encoded concurrently while the+ scene continues rendering. 1 encodes each animation's file before the+ next animation starts; values > 1 overlap encoding with rendering+ (4 is a good value on typical hardware) (--max-inflight-encoders).+ """+ return self._d["max_inflight_encoders"]++ @max_inflight_encoders.setter+ def max_inflight_encoders(self, value: int) -> None:+ if isinstance(value, int) and value >= 1:+ self._d.__setitem__("max_inflight_encoders", value)+ else:+ raise ValueError("max_inflight_encoders must be a positive integer")++ @property+ def encoder_queue_size(self) -> int:+ """Maximum number of pending frame buffers held by each encoder when+ parallel encoding is enabled. Ignored when ``max_inflight_encoders`` is+ 1 (--encoder-queue-size).+ """+ return self._d["encoder_queue_size"]++ @encoder_queue_size.setter+ def encoder_queue_size(self, value: int) -> None:+ if isinstance(value, int) and value >= 1:+ self._d.__setitem__("encoder_queue_size", value)+ else:+ raise ValueError("encoder_queue_size must be a positive integer")+@propertydef window_monitor(self) -> int:"""The monitor on which the scene will be rendered."""diff --git a/manim/cli/render/render_options.py b/manim/cli/render/render_options.pyindex 9a31d36ed..4e42c134b 100644--- a/manim/cli/render/render_options.py+++ b/manim/cli/render/render_options.py@@ -5,7 +5,7 @@ import reimport sysfrom typing import TYPE_CHECKING-from cloup import Choice, option, option_group+from cloup import Choice, IntRange, option, option_groupfrom manim.constants import QUALITIES, RendererType@@ -165,6 +165,23 @@ render_options = option_group(default=None,help="Render at this frame rate.",),+ option(+ "--max-inflight-encoders",+ type=IntRange(min=1),+ default=None,+ help="Maximum number of partial movie files being encoded concurrently "+ "while the scene continues rendering. 1 (the default) encodes each "+ "animation's file before the next animation starts; values > 1 overlap "+ "encoding with rendering (4 is a good value on typical hardware).",+ ),+ option(+ "--encoder-queue-size",+ type=IntRange(min=1),+ default=None,+ help="Maximum number of pending frame buffers held by each encoder when "+ "parallel encoding is enabled. Ignored when --max-inflight-encoders is "+ "1 (the default). Defaults to 8.",+ ),option("--renderer",type=Choice(diff --git a/manim/scene/scene.py b/manim/scene/scene.pyindex 845fafd0b..81dc7ee64 100644--- a/manim/scene/scene.py+++ b/manim/scene/scene.py@@ -264,7 +264,19 @@ class Scene:# TODO: The CairoRenderer does not have the method clear_screen()self.renderer.clear_screen() # type: ignore[union-attr]self.renderer.num_plays = 0+ # The rerun replaces the file writer; tear down its encode jobs so+ # no worker is still writing a partial file the new writer may+ # reuse. Encoder failures propagate: a rerun must not silently+ # continue past corrupt output.+ self.renderer.file_writer.abort_encode_jobs(+ reraise_encoder_failures=True,+ )return True+ except BaseException:+ # A mid-play exception leaves an unsealed encode job whose+ # non-daemon worker would hang the process at exit.+ self.renderer.file_writer.abort_encode_jobs()+ raiseself.tear_down()# We have to reset these settings in case of multiple renders.self.renderer.scene_finished(self)diff --git a/manim/scene/scene_file_writer.py b/manim/scene/scene_file_writer.pyindex 21425af75..f540b210c 100644--- a/manim/scene/scene_file_writer.py+++ b/manim/scene/scene_file_writer.py@@ -7,6 +7,7 @@ __all__ = ["SceneFileWriter"]import jsonimport shutilimport warnings+from contextlib import suppressfrom fractions import Fractionfrom pathlib import Pathfrom queue import Queue@@ -90,6 +91,110 @@ def convert_audio(output_audio.mux(packet)+class _PartialMovieEncodeJob:+ """Encode and write the frames for one partial movie file."""++ def __init__(+ self,+ path: StrPath,+ animation_index: int,+ container: OutputContainer,+ stream: Stream,+ frame_queue_size: int,+ ) -> None:+ self.path = path+ self.animation_index = animation_index+ self.container = container+ self.stream = stream+ # A size of 0 preserves the unbounded queue used by serial encoding.+ # Parallel encoding uses a bounded queue; at the default capacity, eight+ # 1080p RGBA frames occupy about 66 MB per job. The worker drains through+ # the sentinel after an exception, so a bounded queue cannot deadlock.+ self.queue: Queue[tuple[int, PixelArray | None]] = Queue(+ maxsize=frame_queue_size,+ )+ self._exception: BaseException | None = None+ self.thread = Thread(+ target=self._listen_and_write,+ name=f"partial-movie-encoder-{animation_index}",+ )+ self.thread.start()++ def _capture_exception(self, exception: BaseException) -> None:+ if self._exception is None:+ self._exception = exception++ @property+ def failed(self) -> bool:+ """Whether the worker has captured an exception."""+ return self._exception is not None++ def _listen_and_write(self) -> None:+ while True:+ num_frames, frame_data = self.queue.get()+ if frame_data is None:+ break+ if self._exception is not None:+ continue++ try:+ self._encode_and_write_frame(frame_data, num_frames)+ except BaseException as exception:+ self._capture_exception(exception)++ try:+ for packet in self.stream.encode():+ self.container.mux(packet)+ except BaseException as exception:+ self._capture_exception(exception)+ finally:+ try:+ self.container.close()+ except BaseException as exception:+ self._capture_exception(exception)++ def _encode_and_write_frame(self, frame: PixelArray, num_frames: int) -> None:+ for _ in range(num_frames):+ # Notes: precomputing reusing packets does not work!+ # I.e., you cannot do `packets = encode(...)`+ # and reuse it, as it seems that `mux(...)`+ # consumes the packet.+ # The same issue applies for `av_frame`,+ # reusing it renders weird-looking frames.+ av_frame = av.VideoFrame.from_ndarray(frame, format="rgba")+ for packet in self.stream.encode(av_frame):+ self.container.mux(packet)++ def put(self, num_frames: int, frame: PixelArray) -> None:+ """Add a frame to the encoding queue."""+ self.queue.put((num_frames, frame))++ def seal(self) -> None:+ """Signal that no more frames will be added."""+ self.queue.put((-1, None))++ def join(self) -> None:+ """Wait for encoding to finish and propagate worker failures."""+ self.thread.join()+ if self._exception is not None:+ # A failed encode may leave a structurally valid but truncated+ # file behind; remove it so a later run cannot cache-hit it.+ try:+ Path(self.path).unlink(missing_ok=True)+ except OSError as cleanup_error:+ logger.warning(+ "Failed to remove incomplete partial movie file %(path)s: "+ "%(error)s",+ {"path": f"'{self.path}'", "error": cleanup_error},+ )+ raise self._exception++ logger.info(+ f"Animation {self.animation_index} : Partial movie file written in %(path)s",+ {"path": f"'{self.path}'"},+ )++class SceneFileWriter:"""SceneFileWriter is the object that actually writes the animationsplayed, into video files, using FFMPEG.@@ -127,6 +232,9 @@ class SceneFileWriter:**kwargs: Any,) -> None:self.renderer = renderer+ self._inflight_encode_jobs: list[_PartialMovieEncodeJob] = []+ self._inflight_by_path: dict[str, _PartialMovieEncodeJob] = {}+ self._current_encode_job: _PartialMovieEncodeJob | None = Noneself.init_output_directories(scene_name)self.init_audio()self.frame_count = 0@@ -426,30 +534,6 @@ class SceneFileWriter:if write_to_movie() and allow_write:self.close_partial_movie_stream()- def listen_and_write(self) -> None:- """For internal use only: blocks until new frame is available on the queue."""- while True:- num_frames, frame_data = self.queue.get()- if frame_data is None:- break-- self.encode_and_write_frame(frame_data, num_frames)-- def encode_and_write_frame(self, frame: PixelArray, num_frames: int) -> None:- """For internal use only: takes a given frame in ``np.ndarray`` format and- writes it to the stream- """- for _ in range(num_frames):- # Notes: precomputing reusing packets does not work!- # I.e., you cannot do `packets = encode(...)`- # and reuse it, as it seems that `mux(...)`- # consumes the packet.- # The same issue applies for `av_frame`,- # reusing it renders weird-looking frames.- av_frame = av.VideoFrame.from_ndarray(frame, format="rgba")- for packet in self.video_stream.encode(av_frame):- self.video_container.mux(packet)-def write_frame(self, frame_or_renderer: PixelArray | OpenGLRenderer, num_frames: int = 1) -> None:@@ -472,8 +556,18 @@ class SceneFileWriter:else frame_or_renderer)- msg = (num_frames, frame)- self.queue.put(msg)+ job = self._current_encode_job+ if job is None:+ # Interactive OpenGL rendering emits frames outside an open+ # partial movie stream; drop them silently.+ return+ if job.failed:+ # Surface the failure at the first write after it was captured;+ # join() unlinks the partial and re-raises.+ job.seal()+ self._current_encode_job = None+ job.join()+ job.put(num_frames, frame)if is_png_format() and not config["dry_run"]:if isinstance(frame_or_renderer, np.ndarray):@@ -524,9 +618,11 @@ class SceneFileWriter:If save_last_frame is True, saves the last frame in the default image directory."""if write_to_movie():+ self.join_all_encode_jobs()self.combine_to_movie()if config.save_sections:self.combine_to_section_videos()+ # Cache cleanup runs after the in-flight encode jobs have been drained.if config["flush_cache"]:self.flush_cache_directory()else:@@ -545,6 +641,14 @@ class SceneFileWriter:"""if file_path is None:file_path = self.partial_movie_files[self.renderer.num_plays]+ if file_path is None:+ raise RuntimeError(+ "open_partial_movie_stream() called for a play that has no "+ "partial movie file path.",+ )+ path_key = str(file_path)+ if path_key in self._inflight_by_path:+ self._join_job_and_drain_on_failure(self._inflight_by_path[path_key])self.partial_movie_file_path = file_pathfps = to_av_frame_rate(config.frame_rate)@@ -576,12 +680,103 @@ class SceneFileWriter:stream.width = config.pixel_widthstream.height = config.pixel_height- self.video_container: OutputContainer = video_container- self.video_stream: Stream = stream+ frame_queue_size = (+ 0 if config.max_inflight_encoders == 1 else config.encoder_queue_size+ )+ self._current_encode_job = _PartialMovieEncodeJob(+ path=file_path,+ animation_index=self.renderer.num_plays,+ container=video_container,+ stream=stream,+ frame_queue_size=frame_queue_size,+ )- self.queue: Queue[tuple[int, PixelArray | None]] = Queue()- self.writer_thread = Thread(target=self.listen_and_write, args=())- self.writer_thread.start()+ def _join_job(self, job: _PartialMovieEncodeJob) -> None:+ """Remove and join an in-flight partial movie encode job."""+ if job in self._inflight_encode_jobs:+ self._inflight_encode_jobs.remove(job)+ self._inflight_by_path.pop(str(job.path), None)+ job.join()++ def _join_job_and_drain_on_failure(+ self,+ job: _PartialMovieEncodeJob,+ ) -> None:+ """Join one job, draining all remaining jobs if it fails."""+ try:+ self._join_job(job)+ except BaseException:+ # Preserve the failure which triggered the drain.+ with suppress(BaseException):+ self.join_all_encode_jobs()+ raise++ def join_all_encode_jobs(self) -> None:+ """Join every in-flight encode job, re-raising the first failure."""+ first_exception: BaseException | None = None+ for job in list(self._inflight_encode_jobs):+ try:+ self._join_job(job)+ except BaseException as exception:+ if first_exception is None:+ first_exception = exception++ self._inflight_encode_jobs.clear()+ self._inflight_by_path.clear()+ if first_exception is not None:+ raise first_exception++ def abort_encode_jobs(self, reraise_encoder_failures: bool = False) -> None:+ """Tear down encode jobs after an aborted or rerun render.++ Seals the current job so its worker can exit (a non-daemon thread+ blocked on the queue would hang the process at exit), then deletes its+ partial file unconditionally: an aborted partial is structurally valid+ but truncated, so leaving it behind produces an erroneous cache hit on+ a later run. Sealed in-flight jobs are then drained. With+ ``reraise_encoder_failures=False`` (a render exception is already+ propagating) drain failures are logged, not raised; with ``True``+ (rerun path -- no primary exception exists) the first drain failure+ propagates so corrupt completed partials cannot be silently ignored.+ """+ current_exception: BaseException | None = None+ job = self._current_encode_job+ if job is not None:+ # Seal before clearing: an interrupt landing between the two+ # statements must not orphan the worker.+ job.seal()+ self._current_encode_job = None+ job.thread.join()+ current_exception = job._exception+ if current_exception is not None:+ logger.error(+ "Encoder for aborted animation %d had also failed",+ job.animation_index,+ exc_info=current_exception,+ )+ try:+ Path(job.path).unlink(missing_ok=True)+ logger.info(+ "Discarded partial movie file of aborted animation %(index)d",+ {"index": job.animation_index},+ )+ except OSError as cleanup_error:+ logger.warning(+ "Failed to remove incomplete partial movie file %(path)s: "+ "%(error)s",+ {"path": f"'{job.path}'", "error": cleanup_error},+ )+ if reraise_encoder_failures:+ self.join_all_encode_jobs()+ if current_exception is not None:+ # The rerun path has no primary exception: a failed current+ # job must not be silently absorbed.+ raise current_exception+ else:+ try:+ self.join_all_encode_jobs()+ except BaseException:+ logger.exception("Encoder failure while aborting render")def close_partial_movie_stream(self) -> None:"""Close the currently opened video container.@@ -590,18 +785,19 @@ class SceneFileWriter:in the video stream holding a partial file, and then closethe corresponding container."""- self.queue.put((-1, None))- self.writer_thread.join()-- for packet in self.video_stream.encode():- self.video_container.mux(packet)-- self.video_container.close()+ job = self._current_encode_job+ if job is None:+ raise RuntimeError(+ "close_partial_movie_stream() called without an open partial "+ "movie stream.",+ )+ job.seal()+ self._inflight_encode_jobs.append(job)+ self._inflight_by_path[str(job.path)] = job+ self._current_encode_job = None- logger.info(- f"Animation {self.renderer.num_plays} : Partial movie file written in %(path)s",- {"path": f"'{self.partial_movie_file_path}'"},- )+ while len(self._inflight_encode_jobs) >= config.max_inflight_encoders:+ self._join_job_and_drain_on_failure(self._inflight_encode_jobs[0])def is_already_cached(self, hash_invocation: str) -> bool:"""Will check if a file named with `hash_invocation` exists.@@ -622,6 +818,9 @@ class SceneFileWriter:self.partial_movie_directory/ f"{hash_invocation}{config['movie_file_extension']}")+ path_key = str(path)+ if path_key in self._inflight_by_path:+ self._join_job_and_drain_on_failure(self._inflight_by_path[path_key])return path.exists()def combine_files(diff --git a/tests/test_scene_rendering/test_parallel_encoding.py b/tests/test_scene_rendering/test_parallel_encoding.pynew file mode 100644index 000000000..474a6fb89--- /dev/null+++ b/tests/test_scene_rendering/test_parallel_encoding.py@@ -0,0 +1,1152 @@+from __future__ import annotations++import subprocess+import sys+import textwrap+import threading+import time+from pathlib import Path+from unittest.mock import ANY, Mock, call++import av+import numpy as np+import pytest+from click.testing import CliRunner++from manim import FadeIn, Scene, Square, capture, tempconfig+from manim._config import config+from manim.cli.render.commands import render+from manim.utils.exceptions import RerunSceneException++_ENCODER_THREAD_PREFIX = "partial-movie-encoder-"+_UNIQUE_PLAYS = 6+_TOTAL_PLAYS = _UNIQUE_PLAYS + 2++_SCENE_NAME = "ParallelEncodingCacheScene"+_SCENE_SOURCE = textwrap.dedent(+ f"""\+ from manim import FadeIn, Scene, Square+++ class {_SCENE_NAME}(Scene):+ def construct(self):+ for index in range({_UNIQUE_PLAYS}):+ square = Square(side_length=0.2 + index / 100)+ self.play(FadeIn(square), run_time=0.1)+ self.clear()++ self.play(FadeIn(Square(side_length=0.75)), run_time=0.1)+ self.clear()+ self.play(FadeIn(Square(side_length=0.75)), run_time=0.1)+ """+)+++def _alive_encoder_threads():+ return [+ thread+ for thread in threading.enumerate()+ if thread.name.startswith(_ENCODER_THREAD_PREFIX) and thread.is_alive()+ ]+++def _render_scene(media_dir, scene_file):+ command = [+ sys.executable,+ "-m",+ "manim",+ "-ql",+ "--max-inflight-encoders",+ "3",+ "--media_dir",+ str(media_dir),+ str(scene_file),+ _SCENE_NAME,+ ]+ _, err, exit_code = capture(command)+ assert exit_code == 0, err+ quality_directory = media_dir / "videos" / scene_file.stem / "480p15"+ return quality_directory, quality_directory / "partial_movie_files" / _SCENE_NAME+++def test_parallel_encoding_cache_behavior(tmp_path):+ scene_file = tmp_path / "parallel_encoding_scenes.py"+ scene_file.write_text(_SCENE_SOURCE)++ # The duplicate tail play must cache-hit within the run (one file fewer+ # than the number of plays); that hit exercises the writer's in-flight+ # lookup while the first tail file may still be encoding.+ media_dir = tmp_path / "media"+ quality_directory, partial_directory = _render_scene(media_dir, scene_file)+ partial_movies = sorted(partial_directory.glob("*.mp4"))+ assert len(partial_movies) == _TOTAL_PLAYS - 1+ assert (quality_directory / f"{_SCENE_NAME}.mp4").exists()+ for partial_movie in partial_movies:+ with av.open(partial_movie) as container:+ next(container.decode(video=0))++ partial_snapshot = {+ partial_movie.name: partial_movie.stat().st_mtime_ns+ for partial_movie in partial_movies+ }++ _render_scene(media_dir, scene_file)++ second_snapshot = {+ partial_movie.name: partial_movie.stat().st_mtime_ns+ for partial_movie in sorted(partial_directory.glob("*.mp4"))+ }+ assert second_snapshot == partial_snapshot+++def test_no_encoder_threads_survive_render(config, tmp_path):+ class ThreadSweepScene(Scene):+ def construct(self):+ for index in range(3):+ square = Square(side_length=0.3 + index / 10)+ self.play(FadeIn(square), run_time=0.1)+ self.clear()++ with tempconfig(+ {+ "media_dir": tmp_path,+ "quality": "low_quality",+ "max_inflight_encoders": 3,+ "encoder_queue_size": 2,+ },+ ):+ scene = ThreadSweepScene()+ scene.render()++ assert not _alive_encoder_threads()+++def _frame():+ return np.zeros((4, 4, 4), dtype=np.uint8)+++def _new_encode_job(+ tmp_path,+ monkeypatch,+ name,+ stream,+ container,+ frame_queue_size=8,+):+ from manim.scene.scene_file_writer import _PartialMovieEncodeJob++ job = _PartialMovieEncodeJob(+ path=tmp_path / f"{name}.mp4",+ animation_index=0,+ stream=Mock(),+ container=Mock(),+ frame_queue_size=frame_queue_size,+ )+ monkeypatch.setattr(job, "stream", stream)+ monkeypatch.setattr(job, "container", container)+ return job+++def _assert_failed_join(job, expected_exception):+ job.thread.join(timeout=5)+ assert not job.thread.is_alive(), "Partial movie encoder did not finish"++ with pytest.raises(type(expected_exception)) as exc_info:+ job.join()++ assert exc_info.value is expected_exception+ assert not _alive_encoder_threads()+++def test_encode_failure_propagates_and_drains_bounded_queue(+ tmp_path,+ monkeypatch,+ manim_caplog,+):+ expected_exception = RuntimeError("encode failed")+ encode_failed = threading.Event()+ stream = Mock()+ container = Mock()++ def encode(*args):+ if args:+ encode_failed.set()+ raise expected_exception+ return []++ stream.encode.side_effect = encode+ job = _new_encode_job(tmp_path, monkeypatch, "encode_failure", stream, container)+ job.put(1, _frame())+ assert encode_failed.wait(timeout=2), "Encode failure was not triggered"++ def fill_queue_and_seal():+ for _ in range(job.queue.maxsize + 1):+ job.put(1, _frame())+ job.seal()++ producer = threading.Thread(target=fill_queue_and_seal, daemon=True)+ producer.start()+ producer.join(timeout=5)+ assert not producer.is_alive(), "Producer deadlocked on the bounded queue"++ _assert_failed_join(job, expected_exception)+ container.close.assert_called_once_with()+ assert "Partial movie file written" not in manim_caplog.text+++def test_flush_failure_propagates_and_closes_container(+ tmp_path,+ monkeypatch,+ manim_caplog,+):+ expected_exception = RuntimeError("flush failed")+ stream = Mock()+ container = Mock()++ def encode(*args):+ if args:+ return []+ raise expected_exception++ stream.encode.side_effect = encode+ job = _new_encode_job(tmp_path, monkeypatch, "flush_failure", stream, container)+ job.put(1, _frame())+ job.seal()++ _assert_failed_join(job, expected_exception)+ container.close.assert_called_once_with()+ assert "Partial movie file written" not in manim_caplog.text+++def test_close_failure_propagates_after_close_attempt(+ tmp_path,+ monkeypatch,+ manim_caplog,+):+ expected_exception = RuntimeError("close failed")+ stream = Mock()+ stream.encode.return_value = []+ container = Mock()+ container.close.side_effect = expected_exception+ job = _new_encode_job(tmp_path, monkeypatch, "close_failure", stream, container)+ job.put(1, _frame())+ job.seal()++ _assert_failed_join(job, expected_exception)+ container.close.assert_called_once_with()+ assert "Partial movie file written" not in manim_caplog.text+++def test_encode_failure_precedes_close_failure_and_removes_partial(+ tmp_path,+ monkeypatch,+ manim_caplog,+):+ expected_exception = RuntimeError("encode failed")+ close_exception = RuntimeError("close failed")+ stream = Mock()+ container = Mock()++ def encode(*args):+ if args:+ raise expected_exception+ return []++ stream.encode.side_effect = encode+ container.close.side_effect = close_exception+ job = _new_encode_job(+ tmp_path,+ monkeypatch,+ "encode_and_close_failure",+ stream,+ container,+ )+ job.path.write_bytes(b"stale")+ job.put(1, _frame())+ job.seal()++ _assert_failed_join(job, expected_exception)+ container.close.assert_called_once_with()+ assert not job.path.exists()+ assert "Partial movie file written" not in manim_caplog.text+++def test_partial_cleanup_failure_does_not_mask_encode_failure(+ tmp_path,+ monkeypatch,+ manim_caplog,+):+ expected_exception = RuntimeError("encode failed")+ cleanup_exception = PermissionError("cannot remove partial")+ stream = Mock()+ container = Mock()++ def encode(*args):+ if args:+ raise expected_exception+ return []++ stream.encode.side_effect = encode+ job = _new_encode_job(tmp_path, monkeypatch, "cleanup_failure", stream, container)+ job.path.write_bytes(b"stale")+ job.put(1, _frame())+ job.seal()+ unlink = Mock(side_effect=cleanup_exception)+ monkeypatch.setattr(Path, "unlink", unlink)++ _assert_failed_join(job, expected_exception)++ unlink.assert_called_once_with(missing_ok=True)+ assert "Failed to remove incomplete partial movie file" in manim_caplog.text+ assert "cannot remove partial" in manim_caplog.text+ assert "Partial movie file written" not in manim_caplog.text+++def test_successful_encode_job_logs_partial_movie_written(+ tmp_path,+ monkeypatch,+ manim_caplog,+):+ stream = Mock()+ stream.encode.return_value = []+ container = Mock()+ job = _new_encode_job(tmp_path, monkeypatch, "encode_success", stream, container)+ job.put(1, _frame())+ job.seal()++ job.join()++ container.close.assert_called_once_with()+ assert "Partial movie file written" in manim_caplog.text+ assert not _alive_encoder_threads()+++def test_write_frame_fails_fast_after_encoder_failure(+ config,+ tmp_path,+ monkeypatch,+):+ from manim.scene.scene_file_writer import SceneFileWriter++ expected_exception = RuntimeError("encode failed")+ stream = Mock()+ container = Mock()++ def encode(*args):+ if args:+ raise expected_exception+ return []++ stream.encode.side_effect = encode+ config.media_dir = str(tmp_path)+ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "FailFastScene")+ job = _new_encode_job(tmp_path, monkeypatch, "fail_fast", stream, container)+ job.path.write_bytes(b"stale")+ writer._current_encode_job = job++ try:+ writer.write_frame(_frame())+ for _ in range(500):+ if job.failed:+ break+ time.sleep(0.01)+ assert job.failed, "Encoder failure was not captured in time"++ with pytest.raises(RuntimeError) as exc_info:+ writer.write_frame(_frame())++ assert exc_info.value is expected_exception+ assert writer._current_encode_job is None+ assert not job.path.exists()+ assert not _alive_encoder_threads()+ finally:+ # An assertion failure above must not leave an unsealed non-daemon+ # worker behind: it would hang pytest at exit.+ if writer._current_encode_job is not None:+ job.seal()+ writer._current_encode_job = None+ job.thread.join(timeout=5)+++ ("max_inflight_encoders", "encoder_queue_size", "expected_queue_size"),+ [(1, 8, 0), (1, 3, 0), (2, 8, 8), (2, 3, 3)],+)+def test_frame_queue_configuration(+ config,+ tmp_path,+ max_inflight_encoders,+ encoder_queue_size,+ expected_queue_size,+):+ from manim.scene.scene_file_writer import SceneFileWriter++ config.max_inflight_encoders = max_inflight_encoders+ config.encoder_queue_size = encoder_queue_size+ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "FrameQueueSizeScene")++ writer.open_partial_movie_stream(tmp_path / "partial.mp4")+ job = writer._current_encode_job+ assert job is not None+ assert job.queue.maxsize == expected_queue_size++ writer.close_partial_movie_stream()+ writer.join_all_encode_jobs()+ assert not _alive_encoder_threads()++[email protected]("max_inflight_encoders", [1, 2, 3])+def test_close_partial_movie_stream_respects_cap_and_joins_fifo(+ config,+ tmp_path,+ max_inflight_encoders,+):+ from manim.scene.scene_file_writer import SceneFileWriter++ config.max_inflight_encoders = max_inflight_encoders+ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "EncoderCapScene")+ jobs = [Mock(path=tmp_path / f"partial_{index}.mp4") for index in range(3)]++ for index, job in enumerate(jobs):+ writer._current_encode_job = job+ writer.close_partial_movie_stream()++ closed_jobs = jobs[: index + 1]+ expected_joined = max(+ 0,+ len(closed_jobs) - max_inflight_encoders + 1,+ )+ expected_inflight = closed_jobs[expected_joined:]+ assert writer._inflight_encode_jobs == expected_inflight+ assert writer._inflight_by_path == {+ str(inflight_job.path): inflight_job for inflight_job in expected_inflight+ }+ assert len(writer._inflight_encode_jobs) < max_inflight_encoders++ for joined_job in closed_jobs[:expected_joined]:+ joined_job.join.assert_called_once_with()+ assert str(joined_job.path) not in writer._inflight_by_path+ for inflight_job in expected_inflight:+ inflight_job.join.assert_not_called()+ assert writer._inflight_by_path[str(inflight_job.path)] is inflight_job++ for job in jobs:+ job.seal.assert_called_once_with()+++def test_cap_join_failure_drains_all_inflight_jobs(config, tmp_path):+ from manim.scene.scene_file_writer import SceneFileWriter++ primary_exception = RuntimeError("first join failed")+ secondary_exception = RuntimeError("second join failed")+ config.max_inflight_encoders = 3+ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "EncoderCapFailureScene")+ jobs = [Mock(path=tmp_path / f"partial_{index}.mp4") for index in range(3)]+ jobs[0].join.side_effect = primary_exception+ jobs[1].join.side_effect = secondary_exception++ for job in jobs[:2]:+ writer._current_encode_job = job+ writer.close_partial_movie_stream()++ writer._current_encode_job = jobs[2]+ with pytest.raises(RuntimeError) as exc_info:+ writer.close_partial_movie_stream()++ assert exc_info.value is primary_exception+ for job in jobs:+ job.seal.assert_called_once_with()+ job.join.assert_called_once_with()+ assert writer._current_encode_job is None+ assert writer._inflight_encode_jobs == []+ assert writer._inflight_by_path == {}+++def test_is_already_cached_joins_same_path_inflight_job(config, tmp_path):+ from manim.scene.scene_file_writer import SceneFileWriter++ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "CachedInflightScene")+ hash_invocation = "same_path_hash"+ path = (+ writer.partial_movie_directory+ / f"{hash_invocation}{config['movie_file_extension']}"+ )+ job = Mock(path=path)+ writer._inflight_encode_jobs.append(job)+ writer._inflight_by_path[str(path)] = job++ writer.is_already_cached(hash_invocation)++ job.join.assert_called_once_with()+ assert writer._inflight_encode_jobs == []+ assert writer._inflight_by_path == {}+++def test_same_path_join_failure_drains_unrelated_jobs(config, tmp_path):+ from manim.scene.scene_file_writer import SceneFileWriter++ expected_exception = RuntimeError("same-path join failed")+ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "CachedInflightFailureScene")+ hash_invocation = "failing_same_path_hash"+ path = (+ writer.partial_movie_directory+ / f"{hash_invocation}{config['movie_file_extension']}"+ )+ unrelated_job = Mock(path=tmp_path / "unrelated.mp4")+ same_path_job = Mock(path=path)+ same_path_job.join.side_effect = expected_exception+ writer._inflight_encode_jobs.extend([unrelated_job, same_path_job])+ writer._inflight_by_path[str(unrelated_job.path)] = unrelated_job+ writer._inflight_by_path[str(path)] = same_path_job++ with pytest.raises(RuntimeError) as exc_info:+ writer.is_already_cached(hash_invocation)++ assert exc_info.value is expected_exception+ same_path_job.join.assert_called_once_with()+ unrelated_job.join.assert_called_once_with()+ assert writer._inflight_encode_jobs == []+ assert writer._inflight_by_path == {}+++def test_open_partial_movie_stream_joins_same_path_inflight_job(config, tmp_path):+ from manim.scene.scene_file_writer import SceneFileWriter++ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "OpenInflightScene")+ path = tmp_path / "same_path.mp4"+ inflight_job = Mock(path=path)+ writer._inflight_encode_jobs.append(inflight_job)+ writer._inflight_by_path[str(path)] = inflight_job++ writer.open_partial_movie_stream(file_path=path)+ current_job = writer._current_encode_job+ assert current_job is not None+ try:+ inflight_job.join.assert_called_once_with()+ assert writer._inflight_encode_jobs == []+ assert writer._inflight_by_path == {}+ finally:+ current_job.seal()+ current_job.join()+ writer._current_encode_job = None++ assert not _alive_encoder_threads()+++def test_finish_propagates_join_failure_and_clears_inflight_state(+ config,+ tmp_path,+ monkeypatch,+):+ from manim.scene.scene_file_writer import SceneFileWriter++ expected_exception = RuntimeError("join failed")+ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "JoinFailureScene")+ failing_job = Mock(path=tmp_path / "failing.mp4")+ failing_job.join.side_effect = expected_exception+ succeeding_job = Mock(path=tmp_path / "succeeding.mp4")+ writer._inflight_encode_jobs.extend([failing_job, succeeding_job])+ writer._inflight_by_path[str(failing_job.path)] = failing_job+ writer._inflight_by_path[str(succeeding_job.path)] = succeeding_job+ combine_to_movie = Mock()+ monkeypatch.setattr(writer, "combine_to_movie", combine_to_movie)++ with pytest.raises(RuntimeError) as exc_info:+ writer.finish()++ assert exc_info.value is expected_exception+ failing_job.join.assert_called_once_with()+ succeeding_job.join.assert_called_once_with()+ assert writer._inflight_encode_jobs == []+ assert writer._inflight_by_path == {}+ combine_to_movie.assert_not_called()+++def _new_writer(config, tmp_path, scene_name):+ from manim.scene.scene_file_writer import SceneFileWriter++ config.media_dir = str(tmp_path)+ renderer = Mock()+ renderer.num_plays = 0+ return SceneFileWriter(renderer, scene_name)+++def _healthy_current_job(tmp_path, monkeypatch, name):+ stream = Mock()+ stream.encode.return_value = []+ job = _new_encode_job(tmp_path, monkeypatch, name, stream, Mock())+ job.path.write_bytes(b"stale")+ return job+++def _add_inflight_job(writer, job):+ writer._inflight_encode_jobs.append(job)+ writer._inflight_by_path[str(job.path)] = job+++def test_abort_encode_jobs_unlinks_current_and_drains_inflight(+ config,+ tmp_path,+ monkeypatch,+ manim_caplog,+):+ writer = _new_writer(config, tmp_path, "AbortScene")+ job = _healthy_current_job(tmp_path, monkeypatch, "abort_current")+ writer._current_encode_job = job+ failing_inflight = Mock(path=tmp_path / "inflight.mp4")+ failing_inflight.join.side_effect = RuntimeError("in-flight join failed")+ _add_inflight_job(writer, failing_inflight)++ writer.abort_encode_jobs()++ assert writer._current_encode_job is None+ assert not job.path.exists()+ assert writer._inflight_encode_jobs == []+ assert writer._inflight_by_path == {}+ assert not _alive_encoder_threads()+ assert "Discarded partial movie file" in manim_caplog.text+ assert "Encoder failure while aborting render" in manim_caplog.text++ # A second call must be a no-op.+ writer.abort_encode_jobs()+ assert writer._current_encode_job is None+++def test_abort_encode_jobs_reraise_propagates_inflight_failure(+ config,+ tmp_path,+):+ expected_exception = RuntimeError("in-flight join failed")+ writer = _new_writer(config, tmp_path, "AbortReraiseScene")+ failing_inflight = Mock(path=tmp_path / "inflight.mp4")+ failing_inflight.join.side_effect = expected_exception+ _add_inflight_job(writer, failing_inflight)++ with pytest.raises(RuntimeError) as exc_info:+ writer.abort_encode_jobs(reraise_encoder_failures=True)++ assert exc_info.value is expected_exception+ assert writer._inflight_encode_jobs == []+ assert writer._inflight_by_path == {}+++def test_abort_encode_jobs_cleanup_failure_logs_warning(+ config,+ tmp_path,+ monkeypatch,+ manim_caplog,+):+ writer = _new_writer(config, tmp_path, "AbortCleanupFailureScene")+ job = _healthy_current_job(tmp_path, monkeypatch, "abort_cleanup_failure")+ writer._current_encode_job = job+ unlink = Mock(side_effect=PermissionError("cannot remove partial"))+ monkeypatch.setattr(Path, "unlink", unlink)++ writer.abort_encode_jobs()++ assert writer._current_encode_job is None+ unlink.assert_called_once_with(missing_ok=True)+ assert "Failed to remove incomplete partial movie file" in manim_caplog.text+ assert "cannot remove partial" in manim_caplog.text+ assert "Discarded partial movie file" not in manim_caplog.text+ assert not _alive_encoder_threads()+++def test_abort_encode_jobs_noop_on_dry_run_writer(config):+ from manim.scene.scene_file_writer import SceneFileWriter++ with tempconfig({"dry_run": True}):+ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "DryRunAbortScene")++ writer.abort_encode_jobs()+ writer.abort_encode_jobs(reraise_encoder_failures=True)++ assert not _alive_encoder_threads()+++def test_keyboard_interrupt_aborts_encode_jobs_and_reraises(config):+ scene = Scene(renderer=Mock())++ def construct():+ raise KeyboardInterrupt++ scene.construct = construct++ with pytest.raises(KeyboardInterrupt):+ scene.render()++ scene.renderer.file_writer.abort_encode_jobs.assert_called_once_with()+++def test_rerun_propagates_encoder_failure(config, tmp_path):+ expected_exception = RuntimeError("in-flight encoder failed")+ writer = _new_writer(config, tmp_path, "RerunFailureScene")+ failing_inflight = Mock(path=tmp_path / "inflight.mp4")+ failing_inflight.join.side_effect = expected_exception+ _add_inflight_job(writer, failing_inflight)+ scene = Scene(renderer=Mock())+ scene.renderer.file_writer = writer++ def construct():+ raise RerunSceneException++ scene.construct = construct++ with pytest.raises(RuntimeError) as exc_info:+ scene.render()++ assert exc_info.value is expected_exception+ assert writer._inflight_encode_jobs == []+ assert writer._inflight_by_path == {}+++def test_rerun_propagates_failed_current_job(config, tmp_path, monkeypatch):+ expected_exception = RuntimeError("encode failed")+ stream = Mock()++ def encode(*args):+ if args:+ raise expected_exception+ return []++ stream.encode.side_effect = encode+ writer = _new_writer(config, tmp_path, "RerunCurrentFailureScene")+ job = _new_encode_job(tmp_path, monkeypatch, "rerun_current", stream, Mock())+ job.path.write_bytes(b"stale")+ writer._current_encode_job = job+ job.put(1, _frame())+ for _ in range(500):+ if job.failed:+ break+ time.sleep(0.01)++ scene = Scene(renderer=Mock())+ scene.renderer.file_writer = writer++ def construct():+ raise RerunSceneException++ scene.construct = construct++ try:+ assert job.failed, "Encoder failure was not captured in time"++ with pytest.raises(RuntimeError) as exc_info:+ scene.render()++ assert exc_info.value is expected_exception+ assert writer._current_encode_job is None+ assert not job.path.exists()+ assert not _alive_encoder_threads()+ finally:+ # An assertion failure above must not leave an unsealed non-daemon+ # worker behind: it would hang pytest at exit.+ if writer._current_encode_job is not None:+ job.seal()+ writer._current_encode_job = None+ job.thread.join(timeout=5)+++def test_end_scene_early_keeps_completed_partials(config, tmp_path):+ class EarlyEndScene(Scene):+ def construct(self):+ for index in range(3):+ square = Square(side_length=0.3 + index / 10)+ self.play(FadeIn(square), run_time=0.1)+ self.clear()++ with tempconfig(+ {+ "media_dir": tmp_path,+ "quality": "low_quality",+ "max_inflight_encoders": 3,+ "disable_caching": True,+ "upto_animation_number": 1,+ },+ ):+ scene = EarlyEndScene()+ scene.render()+ partial_directory = Path(scene.renderer.file_writer.partial_movie_directory)++ partial_movies = sorted(path.name for path in partial_directory.glob("*.mp4"))+ assert partial_movies == ["uncached_00000.mp4", "uncached_00001.mp4"]+ assert not _alive_encoder_threads()+++_MID_PLAY_FAILURE_SCENE_NAME = "MidPlayFailureScene"+_MID_PLAY_FAILURE_SCENE_SOURCE = textwrap.dedent(+ f"""\+ from manim import FadeIn, Scene, Square+++ class {_MID_PLAY_FAILURE_SCENE_NAME}(Scene):+ def construct(self):+ self.play(FadeIn(Square(side_length=0.5)), run_time=0.1)++ square = Square()++ def fail(mobject, dt):+ # compile_animation_data pre-runs updaters with dt=0 before+ # the partial movie stream opens; only raise during playback.+ if dt > 0:+ raise RuntimeError("updater failure mid-play")++ square.add_updater(fail)+ self.add(square)+ self.wait(0.1)+ """+)+++def test_mid_play_exception_does_not_hang_process(tmp_path):+ scene_file = tmp_path / "mid_play_failure_scene.py"+ scene_file.write_text(_MID_PLAY_FAILURE_SCENE_SOURCE)+ media_dir = tmp_path / "media"+ command = [+ sys.executable,+ "-m",+ "manim",+ "-ql",+ "--disable_caching",+ "--max-inflight-encoders",+ "3",+ "--media_dir",+ str(media_dir),+ str(scene_file),+ _MID_PLAY_FAILURE_SCENE_NAME,+ ]++ # Without the abort path in Scene.render, the mid-play exception leaves+ # an unsealed encode job whose non-daemon worker hangs the interpreter+ # at exit; this run then dies with subprocess.TimeoutExpired.+ #+ # The decoding is pinned: with the locale default (cp1252 on Windows),+ # the UTF-8 box-drawing bytes in the traceback kill the pipe reader+ # thread with a UnicodeDecodeError, which communicate() swallows,+ # returning None instead of the captured stderr.+ completed = subprocess.run(+ command,+ capture_output=True,+ encoding="utf-8",+ errors="replace",+ timeout=90,+ )++ assert completed.returncode != 0+ output = (completed.stdout or "") + (completed.stderr or "")+ assert "updater failure mid-play" in output+ partial_directory = (+ media_dir+ / "videos"+ / scene_file.stem+ / "480p15"+ / "partial_movie_files"+ / _MID_PLAY_FAILURE_SCENE_NAME+ )+ assert (partial_directory / "uncached_00000.mp4").exists()+ assert not (partial_directory / "uncached_00001.mp4").exists()+++_BURST_SCENE_NAME = "ParallelEncodingBurstScene"+_BURST_PLAYS = 6+# Distinct side lengths so every play gets its own cache key and partial file.+_BURST_SCENE_SOURCE = textwrap.dedent(+ f"""\+ from manim import FadeIn, Scene, Square+++ class {_BURST_SCENE_NAME}(Scene):+ def construct(self):+ for index in range({_BURST_PLAYS}):+ square = Square(side_length=0.2 + index / 50)+ self.play(FadeIn(square), run_time=0.1)+ self.clear()+ """+)+++def _render_scene_with_args(media_dir, scene_file, scene_name, extra_args=()):+ command = [+ sys.executable,+ "-m",+ "manim",+ "-ql",+ "--media_dir",+ str(media_dir),+ *extra_args,+ str(scene_file),+ scene_name,+ ]+ _, err, exit_code = capture(command)+ assert exit_code == 0, err+ quality_directory = media_dir / "videos" / scene_file.stem / "480p15"+ return quality_directory, quality_directory / "partial_movie_files" / scene_name+++def _decode_frame_count(path):+ with av.open(path) as container:+ return sum(1 for _ in container.decode(video=0))+++def test_render_with_multiple_inflight_encoders(tmp_path):+ """Render with the cap raised so several encoders are genuinely in flight.++ This is the only end-to-end exercise of a raised cap with real encoders;+ it also covers the CLI flag reaching a real render (elsewhere only+ ``digest_args`` is tested).+ """+ scene_file = tmp_path / "parallel_burst_scenes.py"+ scene_file.write_text(_BURST_SCENE_SOURCE)++ quality_directory, partial_directory = _render_scene_with_args(+ tmp_path / "media",+ scene_file,+ _BURST_SCENE_NAME,+ extra_args=["--max-inflight-encoders", "4"],+ )++ partial_movies = sorted(partial_directory.glob("*.mp4"))+ assert len(partial_movies) == _BURST_PLAYS+ assert (quality_directory / f"{_BURST_SCENE_NAME}.mp4").exists()+ # Every partial must decode completely, not just produce a first frame.+ for partial_movie in partial_movies:+ assert _decode_frame_count(partial_movie) > 0+++def test_parallel_encoding_output_matches_serial(tmp_path):+ """The cap must not change what gets encoded: byte-identical partials.++ Per-job encoding is single-streamed and deterministic, so cap=1 and cap=4+ runs of the same scene must produce identical files. Partial file names+ come from animation hashes, which can rarely flip between processes, so+ mismatched *name sets* get one retry in fresh directories; mismatched+ *bytes* for a shared name is an immediate failure — that would mean+ parallelism changed the output.+ """+ scene_file = tmp_path / "parallel_identity_scenes.py"+ scene_file.write_text(_BURST_SCENE_SOURCE)++ for attempt in range(2):+ serial_dir = tmp_path / f"serial{attempt}"+ parallel_dir = tmp_path / f"parallel{attempt}"+ _, serial_partials = _render_scene_with_args(+ serial_dir,+ scene_file,+ _BURST_SCENE_NAME,+ extra_args=["--max-inflight-encoders", "1"],+ )+ _, parallel_partials = _render_scene_with_args(+ parallel_dir,+ scene_file,+ _BURST_SCENE_NAME,+ extra_args=["--max-inflight-encoders", "4"],+ )+ serial_files = {p.name: p for p in serial_partials.glob("*.mp4")}+ parallel_files = {p.name: p for p in parallel_partials.glob("*.mp4")}+ if serial_files.keys() == parallel_files.keys():+ break+ assert serial_files.keys() == parallel_files.keys()++ for name, serial_file in serial_files.items():+ assert serial_file.read_bytes() == parallel_files[name].read_bytes(), (+ f"partial movie {name} differs between cap=1 and cap=4 runs"+ )+++def test_encode_job_repeats_frame_num_frames_times(tmp_path):+ """``put(n, frame)`` must encode the frame n times and mux every packet.++ Every other test in this module uses ``num_frames=1``, leaving the+ repetition loop in ``_encode_and_write_frame`` uncovered.+ """+ from manim.scene.scene_file_writer import _PartialMovieEncodeJob++ packet = object()+ stream = Mock()+ stream.encode.side_effect = lambda *args: [packet] if args else []+ container = Mock()++ job = _PartialMovieEncodeJob(+ path=tmp_path / "freeze_frame.mp4",+ animation_index=0,+ container=container,+ stream=stream,+ frame_queue_size=8,+ )+ job.put(3, _frame())+ job.seal()+ job.join()++ # Three encode calls with a frame, then the argless flush.+ assert stream.encode.call_args_list == [call(ANY)] * 3 + [call()]+ assert container.mux.call_args_list == [call(packet)] * 3+++def test_is_already_cached_false_after_joining_failed_path(config, tmp_path):+ """After joining the in-flight job, a missing file means "not cached".++ The existing same-path test asserts the join happens but never checks the+ return value.+ """+ from manim.scene.scene_file_writer import SceneFileWriter++ with tempconfig({"media_dir": str(tmp_path)}):+ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "CachedReturnScene")+ hash_invocation = "missing_partial_hash"+ path = (+ writer.partial_movie_directory+ / f"{hash_invocation}{config['movie_file_extension']}"+ )+ job = Mock(path=path)+ writer._inflight_encode_jobs.append(job)+ writer._inflight_by_path[str(path)] = job++ assert writer.is_already_cached(hash_invocation) is False+ job.join.assert_called_once_with()+++def test_is_already_cached_true_when_partial_exists(config, tmp_path):+ from manim.scene.scene_file_writer import SceneFileWriter++ with tempconfig({"media_dir": str(tmp_path)}):+ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "CachedReturnScene")+ hash_invocation = "present_partial_hash"+ path = (+ writer.partial_movie_directory+ / f"{hash_invocation}{config['movie_file_extension']}"+ )+ path.write_bytes(b"cached partial")++ assert writer.is_already_cached(hash_invocation) is True+++def test_close_partial_movie_stream_without_open_stream_raises(config, tmp_path):+ from manim.scene.scene_file_writer import SceneFileWriter++ with tempconfig({"media_dir": str(tmp_path)}):+ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "GuardScene")++ with pytest.raises(RuntimeError, match="without an open partial"):+ writer.close_partial_movie_stream()+++def test_open_partial_movie_stream_without_path_raises(config, tmp_path):+ from manim.scene.scene_file_writer import SceneFileWriter++ with tempconfig({"media_dir": str(tmp_path)}):+ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "GuardScene")+ writer.partial_movie_files = [None]++ with pytest.raises(RuntimeError, match="partial movie file path"):+ writer.open_partial_movie_stream()+++def test_write_frame_without_open_stream_drops_frame(config, tmp_path):+ """Interactive OpenGL emits frames with no open stream; they are dropped.++ ``write_to_movie()`` is true under the default test config, so the call+ reaches the drop branch in ``write_frame``.+ """+ from manim.scene.scene_file_writer import SceneFileWriter++ with tempconfig({"media_dir": str(tmp_path)}):+ renderer = Mock()+ renderer.num_plays = 0+ writer = SceneFileWriter(renderer, "DropFrameScene")+ assert writer._current_encode_job is None++ # Must not raise and must not create a job.+ writer.write_frame(_frame())+ assert writer._current_encode_job is None+++def test_parallel_encoder_flags_digest_into_config(tmp_path):+ scene_file = tmp_path / "trivial_scene.py"+ scene_file.write_text("# never executed: --jupyter returns before rendering\n")+ cfg_file = tmp_path / "custom.cfg"+ cfg_file.write_text(+ "[CLI]\nmax_inflight_encoders = 2\nencoder_queue_size = 5\n",+ )+ runner = CliRunner()++ common_args = [str(scene_file), "--jupyter", "--config_file", str(cfg_file)]+ result = runner.invoke(+ render,+ [+ *common_args,+ "--max-inflight-encoders",+ "4",+ "--encoder-queue-size",+ "7",+ ],+ standalone_mode=False,+ )+ assert result.exit_code == 0+ with tempconfig({}):+ config.digest_args(result.return_value)+ assert config.max_inflight_encoders == 4+ assert config.encoder_queue_size == 7++ result = runner.invoke(render, common_args, standalone_mode=False)+ assert result.exit_code == 0+ with tempconfig({}):+ config.digest_args(result.return_value)+ assert config.max_inflight_encoders == 2+ assert config.encoder_queue_size == 5++ with tempconfig({}):+ assert config.max_inflight_encoders == 1+ assert config.encoder_queue_size == 8+++ "flag",+ ["--max-inflight-encoders", "--encoder-queue-size"],+)+def test_parallel_encoder_flags_reject_non_positive(tmp_path, flag):+ scene_file = tmp_path / "trivial_scene.py"+ scene_file.write_text("# never executed: parsing fails before any render\n")+ runner = CliRunner()++ for bad_value in ["0", "-1"]:+ result = runner.invoke(render, [str(scene_file), flag, bad_value])+ assert result.exit_code == 2+ assert "Invalid value" in result.output+++def test_encoder_queue_size_rejects_non_positive_programmatic_values():+ for bad_value in [0, -1]:+ with pytest.raises(ValueError, match="positive integer"):+ config.encoder_queue_size = bad_value