SceneFileWriter

Qualified name: manim.scene.scene\_file\_writer.SceneFileWriter

class SceneFileWriter(settings)

Bases: object

Coordinate segment jobs and assemble one scene’s media artifacts.

The writer receives immutable resolved settings and concrete top-left-origin RGBA arrays. Ownership of each array passed to write_frame() transfers to the writer; callers must not mutate or reuse it afterward. For video output the writer coordinates queued VideoSegmentEncoder jobs, then assembles their silent cached segments with optional audio, sections, and subcaptions. It also writes still images and PNG sequences described by the output plan.

Parameters:

settings (_SceneFileWriterSettings) – Resolved output, encoding, pool, cache, and asset-search settings.

sections

Ordered section metadata for the scene.

partial_movie_files

Segment paths in animation order, including None for skipped plays.

Methods

abort_encode_jobs	Discard the current segment and drain completed encode jobs.
add_audio_segment	This method adds an audio segment from an AudioSegment type object and suitable parameters.
add_partial_movie_file	Append a planned segment path to the writer and current section.
add_sound	This method adds an audio segment from a sound file.
begin_animation	Start a segment job for one animation when video writing is enabled.
close_partial_movie_stream	Seal the current segment and enforce the in-flight job limit.
combine_files
combine_to_movie	Used internally by Manim to combine the separate partial movie files that make up a Scene into a single video file for that Scene.
combine_to_section_videos	Concatenate partial movie files for each section.
create_audio_segment	Creates an empty, silent, Audio Segment.
end_animation	Seal the current segment job when video writing is enabled.
finish	Drain segment jobs and assemble the configured time-based output.
finish_last_section	Delete current section if it is empty.
init_audio	Preps the writer for adding audio to the movie.
is_already_cached	Will check if a file named with hash_invocation exists.
join_all_encode_jobs	Join every in-flight encode job, re-raising the first failure.
next_section	Create segmentation cut here.
open_partial_movie_stream	Create a queued encoder job for one planned video segment.
output_image
print_file_ready_message	Record and report a completed primary artifact.
save_image	Save one RGBA frame to the planned still-image path.
write_frame	Take ownership of one top-left C-contiguous uint8 RGBA frame.
write_subcaption_file	Writes the subcaption file next to the primary video artifact.

Attributes

gif_file_path	Return the planned GIF artifact path.
image_file_path	Return the planned still or video-fallback image path.
image_sequence_directory	Return the planned PNG-sequence directory.
movie_file_path	Return the planned primary video artifact path.
output_name	Return the planned logical output stem as a compatibility view.
partial_movie_directory	Return the planned silent-segment cache directory.
sections_output_dir	Return the planned sections directory, or the legacy empty path.

static _concat_manifest_bytes(input_files)

Return a complete FFmpeg concat manifest for input_files.

Parameters:

input_files (list[str])

Return type:

bytes

_join_job(job)

Remove and join an in-flight partial movie encode job.

Parameters:

job (_PartialMovieEncodeJob)

Return type:

None

_join_job_and_drain_on_failure(job)

Join one job, draining all remaining jobs if it fails.

Parameters:

job (_PartialMovieEncodeJob)

Return type:

None

_write_concat_manifest(input_files)

Atomically persist the complete scene segment order for diagnostics.

Parameters:

input_files (list[str])

Return type:

None

abort_encode_jobs(reraise_encoder_failures=False)

Discard the current segment and drain completed encode jobs.

When reraise_encoder_failures is true, the first encoder failure is propagated. Otherwise failures are logged so an active render exception remains primary.

Parameters:

reraise_encoder_failures (bool)

Return type:

None

add_audio_segment(new_segment, time=None, gain_to_background=None)

This method adds an audio segment from an AudioSegment type object and suitable parameters.

Parameters:

• new_segment (AudioSegment) – The audio segment to add

• time (float | None) – the timestamp at which the sound should be added.

• gain_to_background (float | None) – The gain of the segment from the background.

Return type:

None

add_partial_movie_file(hash_animation)

Append a planned segment path to the writer and current section.

The list retains one entry per animation so explicit animation indices select the corresponding segment.

Parameters:

hash_animation (str | None) – Hash of the animation.

Return type:

None

add_sound(sound_file, time=None, gain=None, **kwargs)

This method adds an audio segment from a sound file.

Parameters:

• sound_file (StrPath) – The path to the sound file.

• time (float | None) – The timestamp at which the audio should be added.

• gain (float | None) – The gain of the given audio segment.

• **kwargs (Any) – This method uses add_audio_segment, so any keyword arguments used there can be referenced here.

Return type:

None

begin_animation(allow_write=False, *, animation_index, file_path=None)

Start a segment job for one animation when video writing is enabled.

Parameters:

• allow_write (bool) – Whether this animation needs a new segment.

• animation_index (int) – Scene-local animation index used to select and label the segment.

• file_path (TypeAliasForwardRef('~manim.typing.StrPath') | None) – Explicit segment target, or None to use the planned cache path.

Return type:

None

close_partial_movie_stream()

Seal the current segment and enforce the in-flight job limit.

Return type:

None

combine_to_movie()

Used internally by Manim to combine the separate partial movie files that make up a Scene into a single video file for that Scene.

Return type:

None

combine_to_section_videos()

Concatenate partial movie files for each section.

Return type:

None

create_audio_segment()

Creates an empty, silent, Audio Segment.

Return type:

None

end_animation(allow_write=False)

Seal the current segment job when video writing is enabled.

Parameters:

allow_write (bool) – Whether the current animation has an open segment job.

Return type:

None

finish()

Drain segment jobs and assemble the configured time-based output.

Return type:

None

finish_last_section()

Delete current section if it is empty.

Return type:

None

property gif_file_path: Path

Return the planned GIF artifact path.

property image_file_path: Path

Return the planned still or video-fallback image path.

property image_sequence_directory: Path

Return the planned PNG-sequence directory.

init_audio()

Preps the writer for adding audio to the movie.

Return type:

None

is_already_cached(hash_invocation)

Will check if a file named with hash_invocation exists.

Parameters:

hash_invocation (str) – The hash corresponding to an invocation to either scene.play or scene.wait.

Returns:

Whether the file exists.

Return type:

bool

join_all_encode_jobs()

Join every in-flight encode job, re-raising the first failure.

Return type:

None

property movie_file_path: Path

Return the planned primary video artifact path.

next_section(name, type_, skip_animations)

Create segmentation cut here.

Parameters:

• name (str)

• type_ (str)

• skip_animations (bool)

Return type:

None

open_partial_movie_stream(*, animation_index, file_path=None)

Create a queued encoder job for one planned video segment.

Parameters:

• animation_index (int)

• file_path (TypeAliasForwardRef('~manim.typing.StrPath') | None)

Return type:

None

property output_name: Path

Return the planned logical output stem as a compatibility view.

property partial_movie_directory: Path

Return the planned silent-segment cache directory.

print_file_ready_message(file_path)

Record and report a completed primary artifact.

Parameters:

file_path (StrPath)

Return type:

None

save_image(pixels)

Save one RGBA frame to the planned still-image path.

Parameters:

pixels (RGBAPixelArray)

Return type:

None

property sections_output_dir: Path

Return the planned sections directory, or the legacy empty path.

write_frame(pixels, *, repeat=1)

Take ownership of one top-left C-contiguous uint8 RGBA frame.

The caller must not mutate or reuse pixels after this method returns because video encoding can consume the array asynchronously.

Parameters:

• pixels (RGBAPixelArray)

• repeat (int)

Return type:

None

write_subcaption_file()

Writes the subcaption file next to the primary video artifact.

Return type:

None