Skip to content

armgit / manim

Public Imported from GitHub
0

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.rst
index 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.rst
index 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 processed
and prepared, followed by the actual "render loop" in which the library
steps 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 gracefully
complete 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` first
triggers :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 the
mechanism.
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 their
setup 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 works
under the hood. While we did not discuss every single line of code in detail
diff --git a/manim/_config/default.cfg b/manim/_config/default.cfg
index 9155d28db..a77e83227 100644
--- a/manim/_config/default.cfg
+++ b/manim/_config/default.cfg
@@ -129,6 +129,17 @@ use_projection_stroke_shaders = False
movie_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 = 60
pixel_height = 1080
diff --git a/manim/_config/utils.py b/manim/_config/utils.py
index 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")
+
@property
def 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.py
index 9a31d36ed..4e42c134b 100644
--- a/manim/cli/render/render_options.py
+++ b/manim/cli/render/render_options.py
@@ -5,7 +5,7 @@ import re
import sys
from typing import TYPE_CHECKING
-from cloup import Choice, option, option_group
+from cloup import Choice, IntRange, option, option_group
from 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.py
index 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()
+ raise
self.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.py
index 21425af75..f540b210c 100644
--- a/manim/scene/scene_file_writer.py
+++ b/manim/scene/scene_file_writer.py
@@ -7,6 +7,7 @@ __all__ = ["SceneFileWriter"]
import json
import shutil
import warnings
+from contextlib import suppress
from fractions import Fraction
from pathlib import Path
from 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 animations
played, 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 = None
self.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_path
fps = to_av_frame_rate(config.frame_rate)
@@ -576,12 +680,103 @@ class SceneFileWriter:
stream.width = config.pixel_width
stream.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 close
the 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.py
new file mode 100644
index 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