Skip to content

The animation engine for agents: blazingly fast math and 3D videos with Manim's Python API, on a Rust GPU core.

Python

Add film frame capture

apoogdka3f957e4aa95
diff --git a/rust/bridge/crates/manimgx-core/src/encoder.rs b/rust/bridge/crates/manimgx-core/src/encoder.rs
new file mode 100644
index 00000000..5561e713
--- /dev/null
+++ b/rust/bridge/crates/manimgx-core/src/encoder.rs
@@ -0,0 +1,150 @@
+use std::io::Write;
+use std::process::{Child, Command, Stdio};
+
+#[derive(Debug, Clone, Copy)]
+pub enum FfmpegCodec {
+ H264VideoToolbox,
+ H264Vaapi,
+}
+
+pub struct FfmpegEncoder {
+ child: Child,
+ expected_frame_size: usize,
+}
+
+impl FfmpegEncoder {
+ pub fn with_pixel_format(
+ output_path: &str,
+ width: u32,
+ height: u32,
+ fps: u32,
+ codec: FfmpegCodec,
+ crf: u32,
+ pixel_format: &str,
+ ) -> Self {
+ let expected_frame_size = match pixel_format {
+ "nv12" => (width * height * 3 / 2) as usize,
+ _ => (width * height * 4) as usize,
+ };
+
+ let mut args = vec![
+ "-y".to_string(),
+ "-f".to_string(),
+ "rawvideo".to_string(),
+ "-pixel_format".to_string(),
+ pixel_format.to_string(),
+ "-video_size".to_string(),
+ format!("{}x{}", width, height),
+ "-framerate".to_string(),
+ fps.to_string(),
+ ];
+
+ // NV12: signal BT.709 color space to ffmpeg input
+ if pixel_format == "nv12" {
+ args.extend([
+ "-color_primaries".to_string(),
+ "bt709".to_string(),
+ "-color_trc".to_string(),
+ "bt709".to_string(),
+ "-colorspace".to_string(),
+ "bt709".to_string(),
+ ]);
+ }
+
+ // VAAPI needs -vaapi_device before -i
+ if matches!(codec, FfmpegCodec::H264Vaapi) {
+ args.extend([
+ "-vaapi_device".to_string(), "/dev/dri/renderD128".to_string(),
+ ]);
+ }
+
+ args.extend(["-i".to_string(), "-".to_string()]);
+
+ match codec {
+ FfmpegCodec::H264VideoToolbox => {
+ args.extend([
+ "-c:v".to_string(),
+ "h264_videotoolbox".to_string(),
+ ]);
+ // NV12 is already YUV420 semi-planar — no swscale needed
+ if pixel_format != "nv12" {
+ args.extend(["-pix_fmt".to_string(), "yuv420p".to_string()]);
+ }
+ args.extend([
+ "-q:v".to_string(),
+ "65".to_string(),
+ "-allow_sw".to_string(),
+ "0".to_string(),
+ ]);
+ }
+ FfmpegCodec::H264Vaapi => {
+ args.extend([
+ "-c:v".to_string(), "h264_vaapi".to_string(),
+ ]);
+ if pixel_format != "nv12" {
+ args.extend(["-vf".to_string(), "format=nv12,hwupload".to_string()]);
+ } else {
+ args.extend(["-vf".to_string(), "hwupload".to_string()]);
+ }
+ args.extend([
+ "-qp".to_string(), crf.to_string(),
+ ]);
+ }
+ }
+
+ args.push(output_path.to_string());
+
+ let child = Command::new("ffmpeg")
+ .args(&args)
+ .stdin(Stdio::piped())
+ .stdout(Stdio::null())
+ .stderr(Stdio::null())
+ .spawn()
+ .expect(
+ "Failed to start ffmpeg. Please ensure ffmpeg is installed and available in PATH.\n\
+ Install with: brew install ffmpeg (macOS) or apt install ffmpeg (Linux)",
+ );
+
+ log::info!(
+ "ffmpeg encoder started ({:?}): {}x{} @ {} fps -> {}",
+ codec,
+ width,
+ height,
+ fps,
+ output_path
+ );
+
+ Self {
+ child,
+ expected_frame_size,
+ }
+ }
+
+ pub fn write_frame(&mut self, pixels: &[u8]) {
+ assert_eq!(
+ pixels.len(),
+ self.expected_frame_size,
+ "Frame size mismatch: expected {} bytes, got {}",
+ self.expected_frame_size,
+ pixels.len()
+ );
+
+ if let Some(stdin) = self.child.stdin.as_mut() {
+ stdin
+ .write_all(pixels)
+ .expect("Failed to write frame to ffmpeg");
+ }
+ }
+
+ pub fn finish(mut self) {
+ // Close stdin to signal EOF to ffmpeg
+ drop(self.child.stdin.take());
+ let status = self.child.wait().expect("Failed to wait for ffmpeg");
+ if !status.success() {
+ log::error!("ffmpeg exited with status: {}", status);
+ } else {
+ log::info!("ffmpeg encoding completed successfully");
+ }
+ }
+}
+
diff --git a/rust/bridge/crates/manimgx-core/src/mp4_muxer.rs b/rust/bridge/crates/manimgx-core/src/mp4_muxer.rs
new file mode 100644
index 00000000..c70d0785
--- /dev/null
+++ b/rust/bridge/crates/manimgx-core/src/mp4_muxer.rs
@@ -0,0 +1,1007 @@
+//! MP4 muxer for single-track H.264 video.
+//!
+//! Pure Rust, zero external dependencies. Accepts Annex B H.264 NAL units,
+//! converts to AVCC format, writes ISO 14496-12 compliant MP4.
+//!
+//! Three muxing strategies:
+//! - **Ram** — buffer all mdat in memory, write faststart MP4 at finish
+//! - **Disk** — stream mdat to temp file, assemble faststart MP4 at finish
+//! - **Fmp4** — fragmented MP4, stream directly to output file
+
+use std::fs::File;
+use std::io::{self, BufWriter, Write};
+
+// ── Public types ──────────────────────────────────────────────────
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum MuxerStrategy {
+ Ram,
+ Disk,
+ Fmp4,
+}
+
+// ── Internal storage ──────────────────────────────────────────────
+
+enum MdatStorage {
+ Ram(Vec<u8>),
+ Disk {
+ writer: BufWriter<File>,
+ temp_path: String,
+ data_size: u64,
+ },
+ Fmp4 {
+ writer: BufWriter<File>,
+ sequence_number: u32,
+ fragment_samples: Vec<SampleInfo>,
+ fragment_mdat: Vec<u8>,
+ base_decode_time: i64,
+ flushed_init: bool,
+ },
+}
+
+// ── Mp4Muxer ─────────────────────────────────────────────────────
+
+pub struct Mp4Muxer {
+ path: String,
+ width: u32,
+ height: u32,
+ timescale: u32,
+
+ sps: Vec<u8>,
+ pps: Vec<u8>,
+
+ samples: Vec<SampleInfo>, // Ram/Disk only
+ has_b_frames: bool,
+
+ avcc_buf: Vec<u8>,
+ storage: MdatStorage,
+}
+
+struct SampleInfo {
+ size: u32,
+ is_keyframe: bool,
+ dts: i64,
+ cts_offset: i32,
+}
+
+impl Mp4Muxer {
+ pub fn new(
+ path: &str,
+ width: u32,
+ height: u32,
+ fps: f64,
+ strategy: MuxerStrategy,
+ ) -> io::Result<Self> {
+ let storage = match strategy {
+ MuxerStrategy::Ram => MdatStorage::Ram(Vec::with_capacity(4 * 1024 * 1024)),
+ MuxerStrategy::Disk => {
+ let temp_path = format!("{}.tmp", path);
+ let file = File::create(&temp_path)?;
+ MdatStorage::Disk {
+ writer: BufWriter::with_capacity(256 * 1024, file),
+ temp_path,
+ data_size: 0,
+ }
+ }
+ MuxerStrategy::Fmp4 => {
+ let file = File::create(path)?;
+ MdatStorage::Fmp4 {
+ writer: BufWriter::with_capacity(256 * 1024, file),
+ sequence_number: 1,
+ fragment_samples: Vec::new(),
+ fragment_mdat: Vec::with_capacity(1024 * 1024),
+ base_decode_time: 0,
+ flushed_init: false,
+ }
+ }
+ };
+
+ Ok(Self {
+ path: path.to_string(),
+ width,
+ height,
+ timescale: fps.round() as u32,
+ sps: Vec::new(),
+ pps: Vec::new(),
+ samples: Vec::new(),
+ has_b_frames: false,
+ avcc_buf: Vec::with_capacity(128 * 1024),
+ storage,
+ })
+ }
+
+ /// Write a video frame from pre-split NAL units (no start codes).
+ pub fn write_video_nals(
+ &mut self,
+ pts_secs: f64,
+ dts_secs: f64,
+ nals: &[&[u8]],
+ is_keyframe: bool,
+ ) -> io::Result<()> {
+ let ts = self.timescale as f64;
+ let pts_ticks = (pts_secs * ts).round() as i64;
+ let dts_ticks = (dts_secs * ts).round() as i64;
+ let cts_offset = (pts_ticks - dts_ticks) as i32;
+
+ if cts_offset != 0 {
+ self.has_b_frames = true;
+ }
+
+ // Build AVCC data into avcc_buf, filtering SPS/PPS/SEI/AUD/filler
+ self.avcc_buf.clear();
+ for nal in nals {
+ if nal.is_empty() {
+ continue;
+ }
+ let nal_type = nal[0] & 0x1F;
+ match nal_type {
+ 7 => {
+ if self.sps.is_empty() {
+ self.sps = nal.to_vec();
+ }
+ continue;
+ }
+ 8 => {
+ if self.pps.is_empty() {
+ self.pps = nal.to_vec();
+ }
+ continue;
+ }
+ 6 | 9 | 12 => continue,
+ _ => {}
+ }
+ self.avcc_buf
+ .extend_from_slice(&(nal.len() as u32).to_be_bytes());
+ self.avcc_buf.extend_from_slice(nal);
+ }
+
+ if self.avcc_buf.is_empty() {
+ return Ok(());
+ }
+
+ let sample = SampleInfo {
+ size: self.avcc_buf.len() as u32,
+ is_keyframe,
+ dts: dts_ticks,
+ cts_offset,
+ };
+
+ let mut avcc_data = std::mem::take(&mut self.avcc_buf);
+ self.append_sample_data(&avcc_data, sample)?;
+ avcc_data.clear();
+ self.avcc_buf = avcc_data;
+
+ Ok(())
+ }
+
+ /// Dispatch sample data to the active storage backend.
+ fn append_sample_data(&mut self, data: &[u8], sample: SampleInfo) -> io::Result<()> {
+ match &mut self.storage {
+ MdatStorage::Ram(vec) => {
+ vec.extend_from_slice(data);
+ self.samples.push(sample);
+ }
+ MdatStorage::Disk {
+ writer, data_size, ..
+ } => {
+ writer.write_all(data)?;
+ *data_size += data.len() as u64;
+ self.samples.push(sample);
+ }
+ MdatStorage::Fmp4 {
+ writer,
+ sequence_number,
+ fragment_samples,
+ fragment_mdat,
+ base_decode_time,
+ flushed_init,
+ } => {
+ // Write init segment on first sample with SPS/PPS available
+ if !*flushed_init && !self.sps.is_empty() && !self.pps.is_empty() {
+ let ftyp = build_fmp4_ftyp();
+ let init_moov = build_fmp4_init_moov(
+ self.width,
+ self.height,
+ self.timescale,
+ &self.sps,
+ &self.pps,
+ );
+ writer.write_all(&ftyp)?;
+ writer.write_all(&init_moov)?;
+ *flushed_init = true;
+ }
+
+ // Flush previous fragment on keyframe boundary
+ if sample.is_keyframe && !fragment_samples.is_empty() {
+ flush_fragment(
+ writer,
+ sequence_number,
+ fragment_samples,
+ fragment_mdat,
+ *base_decode_time,
+ )?;
+ // Advance base_decode_time to the DTS of this new keyframe
+ *base_decode_time = sample.dts;
+ }
+
+ // Set initial base_decode_time from first sample
+ if fragment_samples.is_empty() && *base_decode_time == 0 {
+ *base_decode_time = sample.dts;
+ }
+
+ fragment_mdat.extend_from_slice(data);
+ fragment_samples.push(sample);
+ }
+ }
+ Ok(())
+ }
+
+ /// Finalize the MP4 file.
+ pub fn finish(mut self) -> io::Result<()> {
+ assert!(!self.sps.is_empty(), "No SPS found in H.264 stream");
+ assert!(!self.pps.is_empty(), "No PPS found in H.264 stream");
+
+ // Move storage out to avoid borrow conflicts with self.build_moov()
+ let storage = std::mem::replace(
+ &mut self.storage,
+ MdatStorage::Ram(Vec::new()),
+ );
+
+ match storage {
+ MdatStorage::Ram(mdat_body) => {
+ let ftyp = build_ftyp();
+ let ftyp_size = ftyp.len() as u64;
+ let data_size = mdat_body.len() as u64;
+ let mdat_hdr_size = mdat_header_size(data_size);
+ let n_samples = self.samples.len();
+
+ // Two-pass moov build with co64 auto-detection
+ let moov_pass1 = self.build_moov(0, false);
+ let stco_moov_size = moov_pass1.len() as u64;
+ let base_stco = ftyp_size + stco_moov_size + mdat_hdr_size;
+
+ let total_data: u64 = self.samples.iter().map(|s| s.size as u64).sum();
+ let moov = if base_stco + total_data > u32::MAX as u64 {
+ let co64_moov_size = stco_moov_size + (4 * n_samples) as u64;
+ let base = ftyp_size + co64_moov_size + mdat_hdr_size;
+ let m = self.build_moov(base, true);
+ debug_assert_eq!(m.len() as u64, co64_moov_size);
+ m
+ } else {
+ let m = self.build_moov(base_stco, false);
+ debug_assert_eq!(m.len() as u64, stco_moov_size);
+ m
+ };
+
+ let mdat_header = build_mdat_header(data_size);
+
+ let file = File::create(&self.path)?;
+ let mut writer = BufWriter::new(file);
+ writer.write_all(&ftyp)?;
+ writer.write_all(&moov)?;
+ writer.write_all(&mdat_header)?;
+ writer.write_all(&mdat_body)?;
+ writer.flush()?;
+ }
+ MdatStorage::Disk {
+ writer: mut disk_writer,
+ temp_path,
+ data_size,
+ } => {
+ disk_writer.flush()?;
+ drop(disk_writer);
+
+ let ftyp = build_ftyp();
+ let ftyp_size = ftyp.len() as u64;
+ let mdat_hdr_size = mdat_header_size(data_size);
+ let n_samples = self.samples.len();
+
+ // Two-pass moov build with co64 auto-detection
+ let moov_pass1 = self.build_moov(0, false);
+ let stco_moov_size = moov_pass1.len() as u64;
+ let base_stco = ftyp_size + stco_moov_size + mdat_hdr_size;
+
+ let total_data: u64 = self.samples.iter().map(|s| s.size as u64).sum();
+ let moov = if base_stco + total_data > u32::MAX as u64 {
+ let co64_moov_size = stco_moov_size + (4 * n_samples) as u64;
+ let base = ftyp_size + co64_moov_size + mdat_hdr_size;
+ let m = self.build_moov(base, true);
+ debug_assert_eq!(m.len() as u64, co64_moov_size);
+ m
+ } else {
+ let m = self.build_moov(base_stco, false);
+ debug_assert_eq!(m.len() as u64, stco_moov_size);
+ m
+ };
+
+ let mdat_header = build_mdat_header(data_size);
+
+ // Write final file: ftyp + moov + mdat_header + copy temp data
+ let file = File::create(&self.path)?;
+ let mut out = BufWriter::with_capacity(256 * 1024, file);
+ out.write_all(&ftyp)?;
+ out.write_all(&moov)?;
+ out.write_all(&mdat_header)?;
+
+ let mut src = io::BufReader::with_capacity(256 * 1024, File::open(&temp_path)?);
+ io::copy(&mut src, &mut out)?;
+ out.flush()?;
+ drop(src);
+
+ let _ = std::fs::remove_file(&temp_path);
+ }
+ MdatStorage::Fmp4 {
+ mut writer,
+ mut sequence_number,
+ mut fragment_samples,
+ mut fragment_mdat,
+ base_decode_time,
+ ..
+ } => {
+ // Flush remaining fragment (last GOP)
+ if !fragment_samples.is_empty() {
+ flush_fragment(
+ &mut writer,
+ &mut sequence_number,
+ &mut fragment_samples,
+ &mut fragment_mdat,
+ base_decode_time,
+ )?;
+ }
+ writer.flush()?;
+ }
+ }
+
+ Ok(())
+ }
+
+ // ── moov construction ──────────────────────────────────────────────
+
+ fn build_moov(&self, base_offset: u64, use_co64: bool) -> Vec<u8> {
+ let duration = self.samples.len() as u32;
+ let mvhd = self.build_mvhd(duration);
+ let trak = self.build_trak(duration, base_offset, use_co64);
+ mp4_box(b"moov", &[&mvhd, &trak])
+ }
+
+ fn build_mvhd(&self, duration: u32) -> Vec<u8> {
+ let mut c = Vec::with_capacity(96);
+ c.extend_from_slice(&0u32.to_be_bytes()); // creation_time
+ c.extend_from_slice(&0u32.to_be_bytes()); // modification_time
+ c.extend_from_slice(&self.timescale.to_be_bytes());
+ c.extend_from_slice(&duration.to_be_bytes());
+ c.extend_from_slice(&0x0001_0000u32.to_be_bytes()); // rate 1.0
+ c.extend_from_slice(&0x0100u16.to_be_bytes()); // volume 1.0
+ c.extend_from_slice(&[0u8; 10]); // reserved
+ c.extend_from_slice(&IDENTITY_MATRIX);
+ c.extend_from_slice(&[0u8; 24]); // pre_defined
+ c.extend_from_slice(&2u32.to_be_bytes()); // next_track_ID
+ full_box(b"mvhd", 0, 0, &c)
+ }
+
+ fn build_trak(&self, duration: u32, base_offset: u64, use_co64: bool) -> Vec<u8> {
+ let tkhd = self.build_tkhd(duration);
+ let mdia = self.build_mdia(duration, base_offset, use_co64);
+ mp4_box(b"trak", &[&tkhd, &mdia])
+ }
+
+ fn build_tkhd(&self, duration: u32) -> Vec<u8> {
+ let mut c = Vec::with_capacity(80);
+ c.extend_from_slice(&0u32.to_be_bytes()); // creation_time
+ c.extend_from_slice(&0u32.to_be_bytes()); // modification_time
+ c.extend_from_slice(&1u32.to_be_bytes()); // track_ID
+ c.extend_from_slice(&0u32.to_be_bytes()); // reserved
+ c.extend_from_slice(&duration.to_be_bytes());
+ c.extend_from_slice(&[0u8; 8]); // reserved
+ c.extend_from_slice(&0u16.to_be_bytes()); // layer
+ c.extend_from_slice(&0u16.to_be_bytes()); // alternate_group
+ c.extend_from_slice(&0u16.to_be_bytes()); // volume (0 for video)
+ c.extend_from_slice(&0u16.to_be_bytes()); // reserved
+ c.extend_from_slice(&IDENTITY_MATRIX);
+ c.extend_from_slice(&(self.width << 16).to_be_bytes()); // width 16.16
+ c.extend_from_slice(&(self.height << 16).to_be_bytes()); // height 16.16
+ full_box(b"tkhd", 0, 3, &c) // flags = track_enabled | track_in_movie
+ }
+
+ fn build_mdia(&self, duration: u32, base_offset: u64, use_co64: bool) -> Vec<u8> {
+ let mdhd = self.build_mdhd(duration);
+ let hdlr = build_hdlr();
+ let minf = self.build_minf(base_offset, use_co64);
+ mp4_box(b"mdia", &[&mdhd, &hdlr, &minf])
+ }
+
+ fn build_mdhd(&self, duration: u32) -> Vec<u8> {
+ let mut c = Vec::with_capacity(20);
+ c.extend_from_slice(&0u32.to_be_bytes()); // creation_time
+ c.extend_from_slice(&0u32.to_be_bytes()); // modification_time
+ c.extend_from_slice(&self.timescale.to_be_bytes());
+ c.extend_from_slice(&duration.to_be_bytes());
+ c.extend_from_slice(&0x55C4u16.to_be_bytes()); // language "und"
+ c.extend_from_slice(&0u16.to_be_bytes()); // pre_defined
+ full_box(b"mdhd", 0, 0, &c)
+ }
+
+ fn build_minf(&self, base_offset: u64, use_co64: bool) -> Vec<u8> {
+ let vmhd = build_vmhd();
+ let dinf = build_dinf();
+ let stbl = self.build_stbl(base_offset, use_co64);
+ mp4_box(b"minf", &[&vmhd, &dinf, &stbl])
+ }
+
+ fn build_stbl(&self, base_offset: u64, use_co64: bool) -> Vec<u8> {
+ let stsd = self.build_stsd();
+ let stts = self.build_stts();
+ let stss = self.build_stss();
+ let stsz = self.build_stsz();
+ let stsc = build_stsc();
+ let chunk_offsets = self.build_chunk_offsets(base_offset, use_co64);
+
+ let mut children: Vec<&[u8]> = vec![&stsd, &stts, &stss, &stsz, &stsc, &chunk_offsets];
+
+ let ctts;
+ if self.has_b_frames {
+ ctts = self.build_ctts();
+ children.push(&ctts);
+ }
+
+ mp4_box(b"stbl", &children)
+ }
+
+ fn build_stsd(&self) -> Vec<u8> {
+ let avcc_box = self.build_avcc();
+ let avc1 = self.build_avc1(&avcc_box);
+ let mut c = Vec::with_capacity(4 + avc1.len());
+ c.extend_from_slice(&1u32.to_be_bytes()); // entry_count
+ c.extend_from_slice(&avc1);
+ full_box(b"stsd", 0, 0, &c)
+ }
+
+ fn build_avc1(&self, avcc_box: &[u8]) -> Vec<u8> {
+ let mut c = Vec::with_capacity(78 + avcc_box.len());
+ c.extend_from_slice(&[0u8; 6]); // reserved
+ c.extend_from_slice(&1u16.to_be_bytes()); // data_reference_index
+ c.extend_from_slice(&[0u8; 2]); // pre_defined
+ c.extend_from_slice(&[0u8; 2]); // reserved
+ c.extend_from_slice(&[0u8; 12]); // pre_defined
+ c.extend_from_slice(&(self.width as u16).to_be_bytes());
+ c.extend_from_slice(&(self.height as u16).to_be_bytes());
+ c.extend_from_slice(&0x0048_0000u32.to_be_bytes()); // horiz 72 dpi
+ c.extend_from_slice(&0x0048_0000u32.to_be_bytes()); // vert 72 dpi
+ c.extend_from_slice(&0u32.to_be_bytes()); // reserved
+ c.extend_from_slice(&1u16.to_be_bytes()); // frame_count
+ c.extend_from_slice(&[0u8; 32]); // compressorname
+ c.extend_from_slice(&0x0018u16.to_be_bytes()); // depth
+ c.extend_from_slice(&0xFFFFu16.to_be_bytes()); // pre_defined = -1
+ c.extend_from_slice(avcc_box);
+ mp4_box(b"avc1", &[&c])
+ }
+
+ fn build_avcc(&self) -> Vec<u8> {
+ let sps = &self.sps;
+ let pps = &self.pps;
+ let mut c = Vec::with_capacity(11 + sps.len() + pps.len());
+ c.push(1); // configurationVersion
+ c.push(sps[1]); // AVCProfileIndication
+ c.push(sps[2]); // profile_compatibility
+ c.push(sps[3]); // AVCLevelIndication
+ c.push(0xFF); // lengthSizeMinusOne = 3
+ c.push(0xE1); // numOfSPS = 1
+ c.extend_from_slice(&(sps.len() as u16).to_be_bytes());
+ c.extend_from_slice(sps);
+ c.push(1); // numOfPPS
+ c.extend_from_slice(&(pps.len() as u16).to_be_bytes());
+ c.extend_from_slice(pps);
+ mp4_box(b"avcC", &[&c])
+ }
+
+ fn build_stts(&self) -> Vec<u8> {
+ let mut entries: Vec<(u32, u32)> = Vec::new();
+ for i in 0..self.samples.len() {
+ let delta = if i + 1 < self.samples.len() {
+ (self.samples[i + 1].dts - self.samples[i].dts) as u32
+ } else if let Some(last) = entries.last() {
+ last.1
+ } else {
+ 1
+ };
+ if let Some(last) = entries.last_mut() {
+ if last.1 == delta {
+ last.0 += 1;
+ continue;
+ }
+ }
+ entries.push((1, delta));
+ }
+ let mut c = Vec::with_capacity(4 + entries.len() * 8);
+ c.extend_from_slice(&(entries.len() as u32).to_be_bytes());
+ for &(count, delta) in &entries {
+ c.extend_from_slice(&count.to_be_bytes());
+ c.extend_from_slice(&delta.to_be_bytes());
+ }
+ full_box(b"stts", 0, 0, &c)
+ }
+
+ fn build_stss(&self) -> Vec<u8> {
+ let keyframes: Vec<u32> = self
+ .samples
+ .iter()
+ .enumerate()
+ .filter(|(_, s)| s.is_keyframe)
+ .map(|(i, _)| (i + 1) as u32) // 1-based
+ .collect();
+ let mut c = Vec::with_capacity(4 + keyframes.len() * 4);
+ c.extend_from_slice(&(keyframes.len() as u32).to_be_bytes());
+ for &k in &keyframes {
+ c.extend_from_slice(&k.to_be_bytes());
+ }
+ full_box(b"stss", 0, 0, &c)
+ }
+
+ fn build_stsz(&self) -> Vec<u8> {
+ let n = self.samples.len() as u32;
+ let mut c = Vec::with_capacity(8 + self.samples.len() * 4);
+ c.extend_from_slice(&0u32.to_be_bytes()); // sample_size = 0 (variable)
+ c.extend_from_slice(&n.to_be_bytes());
+ for s in &self.samples {
+ c.extend_from_slice(&s.size.to_be_bytes());
+ }
+ full_box(b"stsz", 0, 0, &c)
+ }
+
+ fn build_chunk_offsets(&self, base_offset: u64, use_co64: bool) -> Vec<u8> {
+ if use_co64 {
+ self.build_co64(base_offset)
+ } else {
+ self.build_stco(base_offset)
+ }
+ }
+
+ fn build_stco(&self, base_offset: u64) -> Vec<u8> {
+ let n = self.samples.len() as u32;
+ let mut c = Vec::with_capacity(4 + self.samples.len() * 4);
+ c.extend_from_slice(&n.to_be_bytes());
+ let mut offset = base_offset;
+ for s in &self.samples {
+ debug_assert!(
+ offset <= u32::MAX as u64,
+ "Chunk offset {} exceeds u32 — should have used co64",
+ offset,
+ );
+ c.extend_from_slice(&(offset as u32).to_be_bytes());
+ offset += s.size as u64;
+ }
+ full_box(b"stco", 0, 0, &c)
+ }
+
+ fn build_co64(&self, base_offset: u64) -> Vec<u8> {
+ let n = self.samples.len() as u32;
+ let mut c = Vec::with_capacity(4 + self.samples.len() * 8);
+ c.extend_from_slice(&n.to_be_bytes());
+ let mut offset = base_offset;
+ for s in &self.samples {
+ c.extend_from_slice(&offset.to_be_bytes());
+ offset += s.size as u64;
+ }
+ full_box(b"co64", 0, 0, &c)
+ }
+
+ fn build_ctts(&self) -> Vec<u8> {
+ let mut entries: Vec<(u32, i32)> = Vec::new();
+ for s in &self.samples {
+ if let Some(last) = entries.last_mut() {
+ if last.1 == s.cts_offset {
+ last.0 += 1;
+ continue;
+ }
+ }
+ entries.push((1, s.cts_offset));
+ }
+ let mut c = Vec::with_capacity(4 + entries.len() * 8);
+ c.extend_from_slice(&(entries.len() as u32).to_be_bytes());
+ for &(count, offset) in &entries {
+ c.extend_from_slice(&count.to_be_bytes());
+ c.extend_from_slice(&offset.to_be_bytes());
+ }
+ full_box(b"ctts", 1, 0, &c) // version 1 for signed offsets
+ }
+}
+
+// ── Standalone box builders (regular MP4) ─────────────────────────
+
+fn build_ftyp() -> Vec<u8> {
+ let mut c = Vec::with_capacity(24);
+ c.extend_from_slice(b"isom"); // major_brand
+ c.extend_from_slice(&512u32.to_be_bytes()); // minor_version
+ c.extend_from_slice(b"isom");
+ c.extend_from_slice(b"iso2");
+ c.extend_from_slice(b"avc1");
+ c.extend_from_slice(b"mp41");
+ mp4_box(b"ftyp", &[&c])
+}
+
+fn build_hdlr() -> Vec<u8> {
+ let mut c = Vec::with_capacity(33);
+ c.extend_from_slice(&0u32.to_be_bytes()); // pre_defined
+ c.extend_from_slice(b"vide"); // handler_type
+ c.extend_from_slice(&[0u8; 12]); // reserved
+ c.extend_from_slice(b"VideoHandler\0"); // name (null-terminated)
+ full_box(b"hdlr", 0, 0, &c)
+}
+
+fn build_vmhd() -> Vec<u8> {
+ let mut c = Vec::with_capacity(8);
+ c.extend_from_slice(&0u16.to_be_bytes()); // graphicsmode
+ c.extend_from_slice(&[0u8; 6]); // opcolor
+ full_box(b"vmhd", 0, 1, &c) // flags = 1 per spec
+}
+
+fn build_dinf() -> Vec<u8> {
+ let url = full_box(b"url ", 0, 1, &[]); // self-contained
+ let mut dref_c = Vec::with_capacity(4 + url.len());
+ dref_c.extend_from_slice(&1u32.to_be_bytes()); // entry_count
+ dref_c.extend_from_slice(&url);
+ let dref = full_box(b"dref", 0, 0, &dref_c);
+ mp4_box(b"dinf", &[&dref])
+}
+
+fn build_stsc() -> Vec<u8> {
+ let mut c = Vec::with_capacity(16);
+ c.extend_from_slice(&1u32.to_be_bytes()); // entry_count
+ c.extend_from_slice(&1u32.to_be_bytes()); // first_chunk
+ c.extend_from_slice(&1u32.to_be_bytes()); // samples_per_chunk
+ c.extend_from_slice(&1u32.to_be_bytes()); // sample_description_index
+ full_box(b"stsc", 0, 0, &c)
+}
+
+fn build_mdat_header(data_size: u64) -> Vec<u8> {
+ let total = 8 + data_size;
+ if total <= u32::MAX as u64 {
+ let mut h = Vec::with_capacity(8);
+ h.extend_from_slice(&(total as u32).to_be_bytes());
+ h.extend_from_slice(b"mdat");
+ h
+ } else {
+ let mut h = Vec::with_capacity(16);
+ h.extend_from_slice(&1u32.to_be_bytes()); // extended size marker
+ h.extend_from_slice(b"mdat");
+ h.extend_from_slice(&(16 + data_size).to_be_bytes());
+ h
+ }
+}
+
+fn mdat_header_size(data_size: u64) -> u64 {
+ if 8 + data_size > u32::MAX as u64 {
+ 16
+ } else {
+ 8
+ }
+}
+
+// ── Fragmented MP4 box builders ───────────────────────────────────
+
+fn build_fmp4_ftyp() -> Vec<u8> {
+ let mut c = Vec::with_capacity(24);
+ c.extend_from_slice(b"isom"); // major_brand
+ c.extend_from_slice(&512u32.to_be_bytes()); // minor_version
+ c.extend_from_slice(b"isom");
+ c.extend_from_slice(b"iso6");
+ c.extend_from_slice(b"msdh");
+ c.extend_from_slice(b"msix");
+ mp4_box(b"ftyp", &[&c])
+}
+
+fn build_fmp4_init_moov(
+ width: u32,
+ height: u32,
+ timescale: u32,
+ sps: &[u8],
+ pps: &[u8],
+) -> Vec<u8> {
+ let mvhd = {
+ let mut c = Vec::with_capacity(96);
+ c.extend_from_slice(&0u32.to_be_bytes()); // creation_time
+ c.extend_from_slice(&0u32.to_be_bytes()); // modification_time
+ c.extend_from_slice(&timescale.to_be_bytes());
+ c.extend_from_slice(&0u32.to_be_bytes()); // duration = 0 (fragmented)
+ c.extend_from_slice(&0x0001_0000u32.to_be_bytes()); // rate 1.0
+ c.extend_from_slice(&0x0100u16.to_be_bytes()); // volume 1.0
+ c.extend_from_slice(&[0u8; 10]); // reserved
+ c.extend_from_slice(&IDENTITY_MATRIX);
+ c.extend_from_slice(&[0u8; 24]); // pre_defined
+ c.extend_from_slice(&2u32.to_be_bytes()); // next_track_ID
+ full_box(b"mvhd", 0, 0, &c)
+ };
+
+ let tkhd = {
+ let mut c = Vec::with_capacity(80);
+ c.extend_from_slice(&0u32.to_be_bytes()); // creation_time
+ c.extend_from_slice(&0u32.to_be_bytes()); // modification_time
+ c.extend_from_slice(&1u32.to_be_bytes()); // track_ID
+ c.extend_from_slice(&0u32.to_be_bytes()); // reserved
+ c.extend_from_slice(&0u32.to_be_bytes()); // duration = 0
+ c.extend_from_slice(&[0u8; 8]); // reserved
+ c.extend_from_slice(&0u16.to_be_bytes()); // layer
+ c.extend_from_slice(&0u16.to_be_bytes()); // alternate_group
+ c.extend_from_slice(&0u16.to_be_bytes()); // volume
+ c.extend_from_slice(&0u16.to_be_bytes()); // reserved
+ c.extend_from_slice(&IDENTITY_MATRIX);
+ c.extend_from_slice(&(width << 16).to_be_bytes());
+ c.extend_from_slice(&(height << 16).to_be_bytes());
+ full_box(b"tkhd", 0, 3, &c)
+ };
+
+ let mdhd = {
+ let mut c = Vec::with_capacity(20);
+ c.extend_from_slice(&0u32.to_be_bytes()); // creation_time
+ c.extend_from_slice(&0u32.to_be_bytes()); // modification_time
+ c.extend_from_slice(&timescale.to_be_bytes());
+ c.extend_from_slice(&0u32.to_be_bytes()); // duration = 0
+ c.extend_from_slice(&0x55C4u16.to_be_bytes()); // language "und"
+ c.extend_from_slice(&0u16.to_be_bytes());
+ full_box(b"mdhd", 0, 0, &c)
+ };
+
+ let hdlr = build_hdlr();
+
+ // avcC box
+ let avcc = {
+ let mut c = Vec::with_capacity(11 + sps.len() + pps.len());
+ c.push(1);
+ c.push(sps[1]);
+ c.push(sps[2]);
+ c.push(sps[3]);
+ c.push(0xFF);
+ c.push(0xE1);
+ c.extend_from_slice(&(sps.len() as u16).to_be_bytes());
+ c.extend_from_slice(sps);
+ c.push(1);
+ c.extend_from_slice(&(pps.len() as u16).to_be_bytes());
+ c.extend_from_slice(pps);
+ mp4_box(b"avcC", &[&c])
+ };
+
+ // avc1 sample entry
+ let avc1 = {
+ let mut c = Vec::with_capacity(78 + avcc.len());
+ c.extend_from_slice(&[0u8; 6]);
+ c.extend_from_slice(&1u16.to_be_bytes());
+ c.extend_from_slice(&[0u8; 2]);
+ c.extend_from_slice(&[0u8; 2]);
+ c.extend_from_slice(&[0u8; 12]);
+ c.extend_from_slice(&(width as u16).to_be_bytes());
+ c.extend_from_slice(&(height as u16).to_be_bytes());
+ c.extend_from_slice(&0x0048_0000u32.to_be_bytes());
+ c.extend_from_slice(&0x0048_0000u32.to_be_bytes());
+ c.extend_from_slice(&0u32.to_be_bytes());
+ c.extend_from_slice(&1u16.to_be_bytes());
+ c.extend_from_slice(&[0u8; 32]);
+ c.extend_from_slice(&0x0018u16.to_be_bytes());
+ c.extend_from_slice(&0xFFFFu16.to_be_bytes());
+ c.extend_from_slice(&avcc);
+ mp4_box(b"avc1", &[&c])
+ };
+
+ let stsd = {
+ let mut c = Vec::with_capacity(4 + avc1.len());
+ c.extend_from_slice(&1u32.to_be_bytes());
+ c.extend_from_slice(&avc1);
+ full_box(b"stsd", 0, 0, &c)
+ };
+
+ // Empty sample tables (required by spec for fmp4 init segment)
+ let stts = full_box(b"stts", 0, 0, &0u32.to_be_bytes());
+ let stsz = {
+ let mut c = Vec::with_capacity(8);
+ c.extend_from_slice(&0u32.to_be_bytes()); // sample_size
+ c.extend_from_slice(&0u32.to_be_bytes()); // sample_count
+ full_box(b"stsz", 0, 0, &c)
+ };
+ let stsc = full_box(b"stsc", 0, 0, &0u32.to_be_bytes());
+ let stco = full_box(b"stco", 0, 0, &0u32.to_be_bytes());
+
+ let stbl = mp4_box(b"stbl", &[&stsd, &stts, &stsz, &stsc, &stco]);
+
+ let vmhd = build_vmhd();
+ let dinf = build_dinf();
+ let minf = mp4_box(b"minf", &[&vmhd, &dinf, &stbl]);
+ let mdia = mp4_box(b"mdia", &[&mdhd, &hdlr, &minf]);
+ let trak = mp4_box(b"trak", &[&tkhd, &mdia]);
+
+ // mvex with trex
+ let trex = {
+ let mut c = Vec::with_capacity(20);
+ c.extend_from_slice(&1u32.to_be_bytes()); // track_ID
+ c.extend_from_slice(&1u32.to_be_bytes()); // default_sample_description_index
+ c.extend_from_slice(&0u32.to_be_bytes()); // default_sample_duration
+ c.extend_from_slice(&0u32.to_be_bytes()); // default_sample_size
+ c.extend_from_slice(&0u32.to_be_bytes()); // default_sample_flags
+ full_box(b"trex", 0, 0, &c)
+ };
+ let mvex = mp4_box(b"mvex", &[&trex]);
+
+ mp4_box(b"moov", &[&mvhd, &trak, &mvex])
+}
+
+/// Flush a fragment (moof + mdat pair) to the writer.
+fn flush_fragment(
+ writer: &mut BufWriter<File>,
+ sequence_number: &mut u32,
+ fragment_samples: &mut Vec<SampleInfo>,
+ fragment_mdat: &mut Vec<u8>,
+ base_decode_time: i64,
+) -> io::Result<()> {
+ if fragment_samples.is_empty() {
+ return Ok(());
+ }
+
+ // Build moof with placeholder data_offset, measure size, rebuild with correct offset
+ let moof_size = compute_moof_size(fragment_samples.len());
+ let mdat_hdr = 8u32; // fragment mdat is always small enough for 4-byte size
+ let data_offset = (moof_size + mdat_hdr) as i32;
+
+ let moof = build_moof(
+ *sequence_number,
+ base_decode_time,
+ fragment_samples,
+ data_offset,
+ );
+ debug_assert_eq!(moof.len(), moof_size as usize);
+
+ // mdat box
+ let mdat_total = 8 + fragment_mdat.len();
+ let mut mdat = Vec::with_capacity(mdat_total);
+ mdat.extend_from_slice(&(mdat_total as u32).to_be_bytes());
+ mdat.extend_from_slice(b"mdat");
+ mdat.extend_from_slice(fragment_mdat);
+
+ writer.write_all(&moof)?;
+ writer.write_all(&mdat)?;
+
+ *sequence_number += 1;
+ fragment_samples.clear();
+ fragment_mdat.clear();
+
+ Ok(())
+}
+
+/// Compute moof box size deterministically from sample count.
+/// moof = 8 (box hdr) + mfhd(16) + traf(8 + tfhd(16) + tfdt(20) + trun(12 + 16*n))
+fn compute_moof_size(n_samples: usize) -> u32 {
+ let mfhd = 16u32; // full_box(12) + seq_num(4)
+ let tfhd = 16u32; // full_box(12) + track_id(4)
+ let tfdt = 20u32; // full_box(12) + base_decode_time(8) [version 1]
+ // trun: full_box(12) + sample_count(4) + data_offset(4) + per-sample(16) * n
+ let trun = 12 + 4 + 4 + (16 * n_samples as u32);
+ let traf = 8 + tfhd + tfdt + trun;
+ 8 + mfhd + traf
+}
+
+fn build_moof(
+ seq_num: u32,
+ base_decode_time: i64,
+ samples: &[SampleInfo],
+ data_offset: i32,
+) -> Vec<u8> {
+ let mfhd = build_mfhd(seq_num);
+ let traf = build_traf(base_decode_time, samples, data_offset);
+ mp4_box(b"moof", &[&mfhd, &traf])
+}
+
+fn build_mfhd(seq_num: u32) -> Vec<u8> {
+ full_box(b"mfhd", 0, 0, &seq_num.to_be_bytes())
+}
+
+fn build_traf(
+ base_decode_time: i64,
+ samples: &[SampleInfo],
+ data_offset: i32,
+) -> Vec<u8> {
+ let tfhd = build_tfhd();
+ let tfdt = build_tfdt(base_decode_time);
+ let trun = build_trun(samples, data_offset);
+ mp4_box(b"traf", &[&tfhd, &tfdt, &trun])
+}
+
+fn build_tfhd() -> Vec<u8> {
+ // flags = 0x020000 (default-base-is-moof)
+ let mut c = Vec::with_capacity(4);
+ c.extend_from_slice(&1u32.to_be_bytes()); // track_ID
+ full_box(b"tfhd", 0, 0x020000, &c)
+}
+
+fn build_tfdt(base_decode_time: i64) -> Vec<u8> {
+ // version 1: 64-bit decode time
+ full_box(b"tfdt", 1, 0, &(base_decode_time as u64).to_be_bytes())
+}
+
+fn build_trun(samples: &[SampleInfo], data_offset: i32) -> Vec<u8> {
+ // flags: data-offset-present(0x1) | sample-duration-present(0x100)
+ // | sample-size-present(0x200) | sample-flags-present(0x400)
+ // | sample-composition-time-offsets-present(0x800)
+ let flags: u32 = 0x1 | 0x100 | 0x200 | 0x400 | 0x800;
+
+ let n = samples.len();
+ let mut c = Vec::with_capacity(4 + 4 + n * 16);
+ c.extend_from_slice(&(n as u32).to_be_bytes()); // sample_count
+ c.extend_from_slice(&data_offset.to_be_bytes()); // data_offset
+
+ for i in 0..n {
+ // sample_duration: delta to next sample's DTS
+ let duration = if i + 1 < n {
+ (samples[i + 1].dts - samples[i].dts) as u32
+ } else if i > 0 {
+ (samples[i].dts - samples[i - 1].dts) as u32
+ } else {
+ 1
+ };
+ c.extend_from_slice(&duration.to_be_bytes());
+
+ // sample_size
+ c.extend_from_slice(&samples[i].size.to_be_bytes());
+
+ // sample_flags: bit 16 set = non-sync (non-keyframe), bit 25 = depends_on_other
+ let sample_flags: u32 = if samples[i].is_keyframe {
+ 0x02000000 // sample_depends_on = 2 (does not depend on others)
+ } else {
+ 0x01010000 // sample_depends_on = 1 (depends) | sample_is_non_sync = 1
+ };
+ c.extend_from_slice(&sample_flags.to_be_bytes());
+
+ // sample_composition_time_offset (signed, version 1 trun would be needed
+ // but we use version 0 with unsigned — works for non-negative offsets,
+ // use version 1 for signed)
+ c.extend_from_slice(&samples[i].cts_offset.to_be_bytes());
+ }
+
+ // version 1 for signed composition time offsets
+ full_box(b"trun", 1, flags, &c)
+}
+
+// ── Identity matrix (3x3, 16.16 / 2.30 fixed-point) ───────────────
+
+const IDENTITY_MATRIX: [u8; 36] = {
+ let mut m = [0u8; 36];
+ // a = 1.0 (16.16) at bytes 0..4
+ m[0] = 0x00;
+ m[1] = 0x01;
+ m[2] = 0x00;
+ m[3] = 0x00;
+ // d = 1.0 (16.16) at bytes 16..20
+ m[16] = 0x00;
+ m[17] = 0x01;
+ m[18] = 0x00;
+ m[19] = 0x00;
+ // w = 1.0 (2.30) at bytes 32..36
+ m[32] = 0x40;
+ m[33] = 0x00;
+ m[34] = 0x00;
+ m[35] = 0x00;
+ m
+};
+
+// ── Box construction helpers ───────────────────────────────────────
+
+fn mp4_box(box_type: &[u8; 4], parts: &[&[u8]]) -> Vec<u8> {
+ let payload_len: usize = parts.iter().map(|p| p.len()).sum();
+ let total = 8 + payload_len;
+ let mut buf = Vec::with_capacity(total);
+ buf.extend_from_slice(&(total as u32).to_be_bytes());
+ buf.extend_from_slice(box_type);
+ for part in parts {
+ buf.extend_from_slice(part);
+ }
+ buf
+}
+
+fn full_box(box_type: &[u8; 4], version: u8, flags: u32, content: &[u8]) -> Vec<u8> {
+ let total = 12 + content.len();
+ let mut buf = Vec::with_capacity(total);
+ buf.extend_from_slice(&(total as u32).to_be_bytes());
+ buf.extend_from_slice(box_type);
+ buf.push(version);
+ let flag_bytes = flags.to_be_bytes();
+ buf.extend_from_slice(&flag_bytes[1..4]);
+ buf.extend_from_slice(content);
+ buf
+}
+
diff --git a/rust/bridge/crates/manimgx-encode/Cargo.toml b/rust/bridge/crates/manimgx-encode/Cargo.toml
new file mode 100644
index 00000000..d66b7497
--- /dev/null
+++ b/rust/bridge/crates/manimgx-encode/Cargo.toml
@@ -0,0 +1,13 @@
+[package]
+name = "manimgx-encode"
+version = "0.1.0"
+edition = "2021"
+build = "build.rs"
+
+[dependencies]
+manimgx-core = { path = "../manimgx-core" }
+log = { workspace = true }
+
+[build-dependencies]
+pkg-config = "0.3"
+bindgen = { version = "0.70", default-features = false, features = ["runtime"] }
diff --git a/rust/bridge/crates/manimgx-encode/src/lib.rs b/rust/bridge/crates/manimgx-encode/src/lib.rs
new file mode 100644
index 00000000..f80ad3b3
--- /dev/null
+++ b/rust/bridge/crates/manimgx-encode/src/lib.rs
@@ -0,0 +1,2 @@
+mod x264;
+pub use x264::{X264FrameMsg, X264Writer};
diff --git a/rust/bridge/crates/manimgx-encode/src/x264.rs b/rust/bridge/crates/manimgx-encode/src/x264.rs
new file mode 100644
index 00000000..e99af877
--- /dev/null
+++ b/rust/bridge/crates/manimgx-encode/src/x264.rs
@@ -0,0 +1,298 @@
+#[allow(non_upper_case_globals, non_camel_case_types, non_snake_case, dead_code)]
+mod bindings {
+ include!(concat!(env!("OUT_DIR"), "/x264_bindings.rs"));
+}
+use bindings::*;
+
+use std::sync::mpsc::{channel, Sender};
+use std::thread::{self, JoinHandle};
+
+/// Message sent from the render loop to the encoder thread.
+pub enum X264FrameMsg {
+ /// A new frame: pointer into a pool NV12 buffer.
+ Frame {
+ ptr: *const u8,
+ len: usize,
+ pts: i64,
+ buf_idx: usize,
+ },
+ /// Duplicate frame: re-encode from the scratch buffer.
+ Dup { pts: i64 },
+ /// Flush delayed frames and shut down.
+ Flush,
+}
+
+// SAFETY: ptr points to a pinned buffer (MTLBuffer or Vec<u8>) in shared storage.
+// The buffer remains valid until the encoder thread sends buf_idx back
+// via release_tx, at which point the pool reclaims it. The main thread
+// only reuses pool buffers after they are released.
+unsafe impl Send for X264FrameMsg {}
+
+/// In-process x264 encoder. Spawns an encoder thread that receives NV12
+/// frames via an unbounded channel and muxes directly to MP4.
+pub struct X264Writer {
+ sender: Sender<X264FrameMsg>,
+ handle: Option<JoinHandle<()>>,
+}
+
+impl X264Writer {
+ pub fn new(
+ output: &str,
+ width: u32,
+ height: u32,
+ fps: u32,
+ preset: &str,
+ crf: u32,
+ release_tx: Sender<usize>,
+ muxer: &str,
+ ) -> Self {
+ use manimgx_core::mp4_muxer::MuxerStrategy;
+ let strategy = match muxer {
+ "ram" => MuxerStrategy::Ram,
+ "fmp4" => MuxerStrategy::Fmp4,
+ _ => MuxerStrategy::Disk,
+ };
+
+ let output_owned = output.to_string();
+ let width_i = width as i32;
+ let height_i = height as i32;
+ let fps_i = fps as i32;
+ let crf_f = crf as f32;
+ let preset_owned = preset.to_string();
+
+ // Unbounded channel: elastic pool provides backpressure instead
+ let (sender, receiver) = channel::<X264FrameMsg>();
+
+ let handle = thread::spawn(move || {
+ unsafe {
+ encoder_thread_main(
+ &receiver,
+ &output_owned,
+ width_i,
+ height_i,
+ fps_i,
+ crf_f,
+ &preset_owned,
+ &release_tx,
+ strategy,
+ );
+ }
+ });
+
+ Self {
+ sender,
+ handle: Some(handle),
+ }
+ }
+
+ /// Send a frame to the encoder thread (zero-copy from pool buffer).
+ pub fn send(&self, msg: X264FrameMsg) {
+ self.sender.send(msg).expect("x264 encoder thread died");
+ }
+
+ /// Flush encoder, join thread. MP4 is finalized in the encoder thread.
+ pub fn finish(mut self) {
+ let _ = self.sender.send(X264FrameMsg::Flush);
+ if let Some(handle) = self.handle.take() {
+ handle.join().expect("x264 encoder thread panicked");
+ }
+ }
+}
+
+/// Encoder thread main loop. Runs entirely on a dedicated thread.
+///
+/// SAFETY: All x264 FFI calls happen here. x264 copies input plane data
+/// internally via plane_copy at the start of x264_encoder_encode, so the
+/// pool buffer is safe to release after the call returns. No zerolatency
+/// tune needed — frame-level threading is safe with the elastic pool.
+unsafe fn encoder_thread_main(
+ receiver: &std::sync::mpsc::Receiver<X264FrameMsg>,
+ output_path: &str,
+ width: i32,
+ height: i32,
+ fps: i32,
+ crf: f32,
+ preset: &str,
+ release_tx: &Sender<usize>,
+ muxer_strategy: manimgx_core::mp4_muxer::MuxerStrategy,
+) {
+ // 1. Configure x264 params (no tune — frame-level threading for speed)
+ let mut param: x264_param_t = std::mem::zeroed();
+
+ let preset_cstr = std::ffi::CString::new(preset).unwrap();
+ let ret = x264_param_default_preset(
+ &mut param,
+ preset_cstr.as_ptr(),
+ std::ptr::null(),
+ );
+ assert!(ret == 0, "x264_param_default_preset failed");
+
+ param.i_width = width;
+ param.i_height = height;
+ param.i_csp = X264_CSP_NV12 as i32;
+ param.i_fps_num = fps as u32;
+ param.i_fps_den = 1;
+ param.i_timebase_num = 1;
+ param.i_timebase_den = fps as u32;
+ param.b_repeat_headers = 1;
+ param.b_annexb = 1;
+ param.rc.f_rf_constant = crf;
+ param.vui.i_sar_width = 1;
+ param.vui.i_sar_height = 1;
+ param.i_log_level = X264_LOG_NONE;
+
+ let profile_cstr = c"high";
+ let ret = x264_param_apply_profile(&mut param, profile_cstr.as_ptr());
+ assert!(ret == 0, "x264_param_apply_profile failed");
+
+ // 2. Open encoder
+ // x264_encoder_open is a version-mangled macro; use the actual symbol
+ let encoder = x264_encoder_open_165(&mut param);
+ assert!(!encoder.is_null(), "x264_encoder_open failed");
+
+ // 3. Init MP4 muxer
+ use manimgx_core::mp4_muxer::Mp4Muxer;
+ let mut muxer = Mp4Muxer::new(output_path, width as u32, height as u32, fps as f64, muxer_strategy)
+ .expect("Failed to create MP4 muxer");
+ // 4. Allocate dup scratch buffer (W*H*3/2 bytes for NV12)
+ let nv12_size = (width * height * 3 / 2) as usize;
+ let mut dup_scratch = vec![0u8; nv12_size];
+
+ // 5. Init picture struct once
+ let mut pic: x264_picture_t = std::mem::zeroed();
+ x264_picture_init(&mut pic);
+ pic.img.i_csp = X264_CSP_NV12 as i32;
+ pic.img.i_plane = 2;
+ // Strides: Y plane = width, UV plane = width (interleaved U/V)
+ pic.img.i_stride[0] = width;
+ pic.img.i_stride[1] = width;
+
+ let mut pic_out: x264_picture_t = std::mem::zeroed();
+
+ // Helper: pass raw NAL slices directly to muxer (zero Annex B roundtrip)
+ macro_rules! mux_nals {
+ ($frame_size:expr, $pp_nal:expr, $i_nal:expr, $pic_out:expr) => {
+ if $frame_size > 0 {
+ let is_keyframe = $pic_out.b_keyframe != 0;
+
+ // Build slice of raw NAL payloads, stripping Annex B start codes
+ let mut nal_slices: Vec<&[u8]> = Vec::with_capacity($i_nal as usize);
+ for i in 0..$i_nal as isize {
+ let nal = &*$pp_nal.offset(i);
+ let data = std::slice::from_raw_parts(nal.p_payload, nal.i_payload as usize);
+ // x264 NALs include Annex B start code; strip to get raw NAL unit
+ let raw = if data.len() > 4
+ && data[0] == 0 && data[1] == 0 && data[2] == 0 && data[3] == 1
+ {
+ &data[4..]
+ } else if data.len() > 3
+ && data[0] == 0 && data[1] == 0 && data[2] == 1
+ {
+ &data[3..]
+ } else {
+ data
+ };
+ nal_slices.push(raw);
+ }
+
+ let pts_secs = $pic_out.i_pts as f64 / fps as f64;
+ let dts_secs = $pic_out.i_dts as f64 / fps as f64;
+ muxer.write_video_nals(pts_secs, dts_secs, &nal_slices, is_keyframe)
+ .expect("Failed to write frame to MP4 muxer");
+ }
+ };
+ }
+
+ // 6. Encode loop
+ loop {
+ let msg = match receiver.recv() {
+ Ok(msg) => msg,
+ Err(_) => break, // channel closed
+ };
+
+ match msg {
+ X264FrameMsg::Frame { ptr, len, pts, buf_idx } => {
+ debug_assert_eq!(len, nv12_size);
+
+ // Set plane pointers into the pool buffer
+ pic.img.plane[0] = ptr as *mut u8;
+ pic.img.plane[1] = ptr.add((width * height) as usize) as *mut u8;
+ pic.i_pts = pts;
+
+ let mut pp_nal: *mut x264_nal_t = std::ptr::null_mut();
+ let mut i_nal: i32 = 0;
+
+ let frame_size = x264_encoder_encode(
+ encoder,
+ &mut pp_nal,
+ &mut i_nal,
+ &mut pic,
+ &mut pic_out,
+ );
+ assert!(frame_size >= 0, "x264_encoder_encode failed");
+
+ // Memcpy NV12 data to dup scratch BEFORE releasing buffer
+ // (so we have a copy for potential Dup frames)
+ std::ptr::copy_nonoverlapping(ptr, dup_scratch.as_mut_ptr(), nv12_size);
+
+ // Release pool buffer back to the main thread
+ let _ = release_tx.send(buf_idx);
+
+ mux_nals!(frame_size, pp_nal, i_nal, pic_out);
+ }
+
+ X264FrameMsg::Dup { pts } => {
+ // Encode from the dup scratch buffer (not from pool buffer)
+ pic.img.plane[0] = dup_scratch.as_ptr() as *mut u8;
+ pic.img.plane[1] = dup_scratch.as_ptr().add((width * height) as usize) as *mut u8;
+ pic.i_pts = pts;
+
+ let mut pp_nal: *mut x264_nal_t = std::ptr::null_mut();
+ let mut i_nal: i32 = 0;
+
+ let frame_size = x264_encoder_encode(
+ encoder,
+ &mut pp_nal,
+ &mut i_nal,
+ &mut pic,
+ &mut pic_out,
+ );
+ assert!(frame_size >= 0, "x264_encoder_encode (dup) failed");
+
+ mux_nals!(frame_size, pp_nal, i_nal, pic_out);
+ }
+
+ X264FrameMsg::Flush => {
+ // Drain delayed frames
+ loop {
+ let delayed = x264_encoder_delayed_frames(encoder);
+ if delayed == 0 {
+ break;
+ }
+
+ let mut pp_nal: *mut x264_nal_t = std::ptr::null_mut();
+ let mut i_nal: i32 = 0;
+
+ let frame_size = x264_encoder_encode(
+ encoder,
+ &mut pp_nal,
+ &mut i_nal,
+ std::ptr::null_mut(),
+ &mut pic_out,
+ );
+ if frame_size < 0 {
+ break;
+ }
+
+ mux_nals!(frame_size, pp_nal, i_nal, pic_out);
+ }
+
+ x264_encoder_close(encoder);
+ break;
+ }
+ }
+ }
+
+ // Finalize MP4 (writes moov atom, applies fast-start)
+ muxer.finish().expect("Failed to finalize MP4 file");
+}
diff --git a/src/manimgx/rendering/__init__.py b/src/manimgx/rendering/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/manimgx/rendering/film.py b/src/manimgx/rendering/film.py
new file mode 100644
index 00000000..7b113b99
--- /dev/null
+++ b/src/manimgx/rendering/film.py
@@ -0,0 +1,548 @@
+"""Film: a scene's frames, as the player draws them — a view and one record per object (`feed`) —
+and its plays, sounds, sections and captions. Shapes and brushes reach the player once, keyed by
+content; a frame equal to the previous one lengthens it, unless it begins a section (a keyframe).
+Frames go to a video, to a callback (which draws those it wants), or nowhere (their records are
+still made); each play, as it ends, to a callback. The sounds are mixed as the video is written.
+"""
+
+import contextlib
+import json
+import os
+from collections.abc import Callable
+from dataclasses import asdict, dataclass
+from fractions import Fraction
+from typing import TYPE_CHECKING, Literal
+
+from manimgx import _engine
+from manimgx.config import config
+from manimgx.rendering import feed
+from manimgx.rendering.feed import CameraView, Feeder
+
+if TYPE_CHECKING:
+ import numpy as np
+
+ from manimgx.animation.timeline import Animation
+ from manimgx.audio.sound import Clip
+ from manimgx.drawing.geometry import Path
+ from manimgx.mobject import Mobject
+ from manimgx.scene import Camera
+
+
+class Frame:
+ """A frame of a film, as the film sends it: shown as frames `index` to
+ `index + repeat - 1` of the video.
+
+ A frame the world holds still for is sent once, shown `repeat` times. Its pixels are
+ drawn only when asked for, by [`pixels`][manimgx.rendering.film.Frame.pixels].
+
+ Args:
+ index: Where it is in the film: the number of the first frame it is shown as.
+ repeat: How many frames it is shown for.
+ draw: The function that draws its pixels.
+ key: Whether it begins a section of the film.
+ """
+
+ __slots__ = ("_draw", "index", "key", "repeat")
+
+ def __init__(
+ self, index: int, repeat: int, draw: Callable[[], bytes], key: bool = False
+ ) -> None:
+ self.index = index
+ """Where it is in the film: the number of the first frame it is shown as, from
+ 0."""
+ self.repeat = repeat
+ """How many frames it is shown for: more than 1 for a hold."""
+ self.key = key
+ """Whether it begins a [section][manimgx.rendering.film.Section] of the film: the picture
+ the section before it ends on."""
+ self._draw = draw
+
+ def pixels(self) -> bytes:
+ """Draw the frame, now.
+
+ Drawing is what a frame costs: ask only for the frames you keep, and before the
+ film sends its next frame.
+
+ Returns:
+ Its pixels: RGBA, a byte a channel, row after row from the top.
+ """
+ return self._draw()
+
+
+type FrameSink = Callable[[Frame], object]
+"""A function handed each frame of a film as the film sends it, a
+[`Frame`][manimgx.rendering.film.Frame] (see [`Scene.render`][manimgx.Scene.render]); what it returns
+is ignored. It may raise [`Cut`][manimgx.rendering.film.Cut] to end the film there."""
+
+
+@dataclass(frozen=True, slots=True)
+class Play:
+ """One play, or wait, of a scene, as its film keeps it: its number, when it began
+ and ended, and where the scene's code played it."""
+
+ index: int
+ """Its number, from 0: plays and waits are counted together."""
+ start: Fraction
+ """When it began, in seconds of scene time, exactly."""
+ end: Fraction
+ """When it ended, in seconds of scene time, exactly."""
+ where: tuple[str, int] | None
+ """Where the scene's code played it: the file and line of the innermost call outside
+ manimgx; None if there is none."""
+
+
+type SectionType = Literal[
+ "default.normal",
+ "presentation.normal",
+ "presentation.skip",
+ "presentation.loop",
+ "presentation.complete_loop",
+]
+"""How a presentation plays a section (Manim's section types): `normal` stops at its end
+until the presenter goes on; `skip` goes on by itself; `loop` plays it again and again until
+the presenter goes on; `complete_loop` too, finishing the round it is in first."""
+
+
+@dataclass(frozen=True, slots=True)
+class Section:
+ """A section of a film, as [`next_section`][manimgx.Scene.next_section] begins one: it
+ lasts until the next section begins, or the film ends."""
+
+ name: str
+ """Its name."""
+ start: Fraction
+ """When it begins, in seconds of scene time: a frame's time, exactly."""
+ frame: int
+ """Its first frame's number: a keyframe of the video, where a player can start."""
+ type: SectionType
+ """How a presentation plays it."""
+ notes: str
+ """What the presenter reads during it."""
+
+
+@dataclass(frozen=True, slots=True)
+class Caption:
+ """A caption of a film: `text`, shown from `start` to `end`, in seconds of scene
+ time."""
+
+ start: float
+ end: float
+ text: str
+
+
+def _wav(sound: "np.ndarray") -> bytes:
+ """A soundtrack as a WAV file: 16-bit, which every browser plays."""
+ import io
+ import wave
+
+ import numpy as np
+
+ from manimgx.audio.sound import RATE
+
+ out = io.BytesIO()
+ with wave.open(out, "wb") as w:
+ w.setnchannels(sound.shape[1])
+ w.setsampwidth(2)
+ w.setframerate(RATE)
+ w.writeframes((np.clip(sound, -1, 1) * 32767).round().astype("<i2").tobytes())
+ return out.getvalue()
+
+
+type Take = Callable[[bytes], object]
+"""A function handed a film's take as it is recorded (see [`Film`][manimgx.rendering.film.Film]):
+bytes of the stream manimgx's player reads — uploads, frames and notes, then the film's
+sound and captions — in order, frame by frame; what it returns is ignored. It may raise
+[`Cut`][manimgx.rendering.film.Cut] to end the film there: it is then sent nothing more (a
+[`Window`][manimgx.Window] closed by its viewer does)."""
+
+
+type PlayHook = Callable[[Play, tuple[Animation, ...]], object]
+"""A function called as each play or wait of a film ends (see
+[`Scene.render`][manimgx.Scene.render]), with the [`Play`][manimgx.rendering.film.Play] and the
+animations it played, the world as the play left it; what it returns is ignored. It may
+raise [`Cut`][manimgx.rendering.film.Cut] to end the film there."""
+
+
+class Cut(Exception):
+ """An early end to a film: raised by a frame sink, a play hook or a take, it stops
+ the scene there.
+
+ The film closes as it is: its video, if any, is written up to the last frame sent.
+ """
+
+
+@dataclass(frozen=True, slots=True)
+class Export:
+ """How a film's video was made: what [`Film.export`][manimgx.Film.export] holds once
+ the video is written."""
+
+ seconds: float
+ """How long the video took, in seconds: from its start, as the scene began
+ rendering, to its file written."""
+ x264: float
+ """Of those, the seconds spent in x264, the H.264 encoder (on a thread of its
+ own)."""
+ converted: float
+ """The share of the video's 16 × 16 pixel blocks converted for the encoder, from 0
+ to 1: the others had not changed since the frame before, and were skipped."""
+ bytes: int
+ """The size of the file, in bytes."""
+
+
+class Film:
+ """A scene's film: its frames, as they are sent, its plays, and its sounds, sections
+ and captions.
+
+ [`Scene.render`][manimgx.Scene.render] makes one and returns it. Each frame is sent
+ once: encoded into the video, if there is one, and handed to `frames`, if given; a
+ frame equal to the one before is not sent again, but lengthens it. Each play, as it
+ ends, is kept, and handed to `plays`, if given. The sounds the scene placed are mixed
+ into the video's sound track as it is written.
+
+ A film can instead be recorded as a take: the engine's work written down — each shape
+ once, then each frame's view and records, and at the end its sound and captions — for
+ manimgx's player to play, at any moment: in a [`Window`][manimgx.Window], live as the
+ scene runs (`manimgx preview`), or in the browser, where Python has no GPU (Pyodide).
+
+ Args:
+ video: The MP4 file the frames are encoded into as they come, if any.
+ frames: A function handed each frame, a [`Frame`][manimgx.rendering.film.Frame] (see
+ [`FrameSink`][manimgx.rendering.film.FrameSink]).
+ plays: A function called as each play ends (see
+ [`PlayHook`][manimgx.rendering.film.PlayHook]).
+ take: A function handed the take's bytes as they are recorded, frame by frame,
+ if the film is recorded as a take (see [`Take`][manimgx.rendering.film.Take]).
+ preset: The x264 preset the video is encoded with: faster presets make larger
+ files.
+ crf: The video's quality, as x264's constant rate factor: lower is better, and
+ 18 looks lossless.
+ """
+
+ def __init__(
+ self,
+ video: str | os.PathLike[str] | None = None,
+ *,
+ frames: FrameSink | None = None,
+ plays: PlayHook | None = None,
+ take: Take | None = None,
+ preset: str = "ultrafast",
+ crf: float = 18.0,
+ ) -> None:
+ fps = config.frame_rate
+ if video is not None and fps != int(fps):
+ raise ValueError(
+ f"a video needs a whole number of frames per second, not {fps}"
+ )
+ width, height = config.pixel_width, config.pixel_height
+ if video is not None and (width % 2 or height % 2): # H.264's 4:2:0 halves both
+ raise ValueError(
+ f"a video needs an even width and height, not {width}x{height}"
+ )
+ self.fps = Fraction(fps).limit_denominator(1000)
+ """How many frames a second the film has: the configuration's when it began."""
+ # the GPU draws the film; or its take is recorded, to be drawn by manimgx's player: by
+ # choice, or where the engine has no GPU (in Pyodide)
+ self._player: _engine.Player | None = None
+ self._recorder: _engine.Recorder | None = None
+ drawn: _engine.Player | _engine.Recorder
+ if take is None and (gpu := feed.Player) is not None:
+ if video is not None or frames is not None:
+ _engine.start_gpu() # the film draws: the GPU comes up as it begins
+ self._player = drawn = gpu(width, height)
+ if video is not None:
+ drawn.begin_export(
+ os.fspath(video), fps=int(fps), preset=preset, crf=crf
+ )
+ elif video is None and frames is None:
+ self._recorder = drawn = _engine.Recorder(width, height, fps)
+ else:
+ raise ValueError(
+ "a film recorded as a take is drawn by manimgx's player, not here: it"
+ " has no video or pixels"
+ + ("" if feed.Player else " (this Python has no GPU)")
+ )
+ self._take = take
+ self.feeder = Feeder(width, height, drawn)
+ self.video = None if video is None else os.fspath(video)
+ """The path of the video being written; None once it is written, and if there is
+ none."""
+ self.frames = frames
+ """The function each drawn frame is handed to, if any."""
+ self.frame_count = 0
+ """How many frames the film has so far, a hold counting every frame it lasts."""
+ self.plays: list[Play] = []
+ """The plays and waits the scene has run, in order: each a
+ [`Play`][manimgx.rendering.film.Play]."""
+ self.sections: list[Section] = [
+ Section("unnamed", Fraction(0), 0, "default.normal", "")
+ ]
+ """The film's sections, in order: each a [`Section`][manimgx.rendering.film.Section],
+ lasting until the next begins. The first begins with the film."""
+ self.subcaptions: list[Caption] = []
+ """The captions the scene added (see
+ [`add_subcaption`][manimgx.Scene.add_subcaption]); [`captions`]
+ [manimgx.Film.captions] adds those of its speech."""
+ self.clips: list[Clip] = []
+ """The sounds the scene placed, in the order it placed them: each a
+ [`Clip`][manimgx.audio.sound.Clip], from its start in scene time."""
+ self.export: Export | None = None
+ """How the video was made, once it is written: an
+ [`Export`][manimgx.rendering.film.Export]; None until then, and with no video."""
+ self._hook = plays
+ self._pending: tuple[bytes, bytes, list[CameraView], int] | None = (
+ None # sent once it ends
+ )
+ self._first = 0 # the index of the pending frame
+ self._key = False # the next frame begins a section: a keyframe of its own
+ self._pending_key = False # the pending frame is one
+
+ def soundtrack(self) -> "np.ndarray | None":
+ """The film's sound: its clips mixed over its length, at
+ [`RATE`][manimgx.audio.sound.RATE] samples a second, one column per channel; None if
+ the scene placed no sound."""
+ from manimgx.audio.sound import mix
+
+ return mix(self.clips, self.frame_count / self.fps)
+
+ def section(
+ self, name: str, start: Fraction, type: SectionType, notes: str
+ ) -> None:
+ """Begin a section at the next frame, which starts at `start`: the scene calls it
+ (see [`next_section`][manimgx.Scene.next_section]). A section with no frame yet
+ gives way to it.
+
+ Args:
+ name: Its name.
+ start: When it begins: the next frame's time.
+ type: How a presentation plays it.
+ notes: What the presenter reads during it.
+ """
+ if self.sections[-1].frame == self.frame_count:
+ self.sections.pop()
+ self.sections.append(Section(name, start, self.frame_count, type, notes))
+ self._key = True
+ self._note({"section": asdict(self.sections[-1])})
+
+ def cut(self) -> list[tuple["Clip", float]]:
+ """The sounds the film's end cuts short: each clip, with the seconds it loses."""
+ end = self.frame_count / self.fps
+ out = []
+ for clip in self.clips:
+ if clip.end is None and clip.sound.duration != float("inf"):
+ lost = float(clip.start) + clip.sound.duration - float(end)
+ if lost > 1e-3:
+ out.append((clip, lost))
+ return out
+
+ def subtitles(self) -> str:
+ """The film's [`captions`][manimgx.Film.captions] as subtitles, in SubRip (`.srt`)
+ form: what players, editors and video sites read beside a video."""
+
+ def stamp(t: float) -> str:
+ ms = round(t * 1000)
+ return (
+ f"{ms // 3_600_000:02d}:{ms // 60_000 % 60:02d}:{ms // 1000 % 60:02d},{ms % 1000:03d}"
+ )
+
+ return "".join(
+ f"{i}\n{stamp(c.start)} --> {stamp(c.end)}\n{c.text}\n\n"
+ for i, c in enumerate(self.captions(), 1)
+ )
+
+ def captions(self) -> list[Caption]:
+ """The film's captions, in order of their start: those the scene added, and its
+ speech's, a line of a few words at a time as they are said."""
+ from manimgx.audio import Speech, lines
+
+ spoken = [
+ Caption(float(clip.start) + a, float(clip.start) + b, text)
+ for clip in self.clips
+ if isinstance(clip.sound, Speech)
+ for a, b, text in lines(clip.sound)
+ ]
+ return sorted(self.subcaptions + spoken, key=lambda c: c.start)
+
+ def played(self, play: Play, animations: "tuple[Animation, ...]") -> None:
+ """Keep a play that has ended, and hand it to the play hook with the animations
+ it played: the scene calls it as each play ends, the world as the play left it.
+
+ Args:
+ animations: What it played.
+ """
+ # the film keeps the play, not the animations: they hold their objects' copies
+ self.plays.append(play)
+ if self._recorder is not None:
+ self._note({"play": asdict(play)})
+ if self._hook is not None:
+ self._hook(play, animations)
+
+ def picture(self, camera: "Camera", mobjects: "list[Mobject]") -> bytes:
+ """Draw the world as `camera` sees it now: a picture, not a frame of the film.
+
+ Args:
+ camera: The camera it is seen through.
+ mobjects: The mobjects drawn, in the order they are drawn.
+
+ Returns:
+ Its pixels: RGBA, a byte a channel, row after row from the top.
+ """
+ view, records, cameras = self.feeder.frame(camera, mobjects)
+ if self._player is None:
+ raise RuntimeError("a film recorded as a take is drawn by manimgx's player")
+ return self._player.render(view, records, cameras)
+
+ def record(
+ self, camera: "Camera", mobjects: "list[Mobject]", repeat: int = 1
+ ) -> None:
+ """Record a frame: the mobjects as `camera` sees them, shown for `repeat`
+ frames.
+
+ The scene calls it for each frame it computes.
+
+ Args:
+ camera: The camera the frame is seen through.
+ mobjects: The mobjects drawn, in the order they are drawn (see
+ [`display_list`][manimgx.Scene.display_list]).
+ repeat: How many frames it is shown for.
+ """
+ view, records, cameras = self.feeder.frame(camera, mobjects)
+ self._add(view, records, cameras, repeat)
+
+ def tween(
+ self,
+ camera: "Camera",
+ mobjects: "list[Mobject]",
+ leaves: "list[tuple[Mobject, list[Mobject], Path, np.ndarray, np.ndarray]]",
+ ) -> None:
+ """Record, at once, the frames of a play that only carries its leaves between
+ keyframes: the scene calls it for such a play.
+
+ Args:
+ camera: The camera the frames are seen through.
+ mobjects: The mobjects drawn, in the order they are drawn.
+ leaves: For each moving leaf: the leaf, its keyframes, its path, and per
+ frame the interval it is in and the time along it (-1 marking the frames
+ the entry does not claim).
+ """
+ for view, records in self.feeder.tween(camera, mobjects, leaves):
+ self._add(view, records, [], 1)
+
+ def _add(
+ self, view: bytes, records: bytes, cameras: list[CameraView], repeat: int
+ ) -> None:
+ pending = self._pending
+ if (
+ pending is not None
+ and not self._key
+ and pending[:3] == (view, records, cameras)
+ ):
+ self._pending = (view, records, cameras, pending[3] + repeat)
+ else:
+ self._send()
+ self._pending = (view, records, cameras, repeat)
+ self._first = self.frame_count
+ self._pending_key, self._key = self._key, False
+ self.frame_count += repeat
+
+ def _send(self) -> None:
+ pending, self._pending = self._pending, None
+ if pending is None:
+ return
+ view, records, cameras, repeat = pending
+ if self._recorder is not None:
+ self._recorder.frame(view, records, repeat, cameras)
+ self._flush()
+ if (player := self._player) is None:
+ return
+ if self.video is not None:
+ player.push(view, records, repeat, cameras, self._pending_key)
+ if self.frames is not None:
+ self.frames(
+ Frame(
+ self._first,
+ repeat,
+ lambda: player.render(view, records, cameras),
+ self._pending_key,
+ )
+ )
+
+ def close(self) -> None:
+ """Close the film: send its last frame, and write its video, if any.
+
+ [`Scene.render`][manimgx.Scene.render] calls it as the scene ends. A
+ [`Cut`][manimgx.rendering.film.Cut] raised for the last frame ends the film all the same;
+ any other error abandons the video.
+ """
+ try:
+ self._send()
+ except Cut:
+ pass
+ except BaseException:
+ self.abort()
+ raise
+ with contextlib.suppress(Cut): # its take cut it as it ended: it hears no more
+ self._end()
+
+ def _end(self) -> None:
+ """Write the closed film's video, if any, and tell its take how it ends."""
+ if self.video is not None and self._player is not None:
+ self.video = None
+ sound = self.soundtrack()
+ if sound is None:
+ self.export = Export(*self._player.end_export())
+ else:
+ from manimgx.audio.sound import BITRATE, RATE
+
+ channels = sound.shape[1]
+ self.export = Export(
+ *self._player.end_export(
+ sound.tobytes(), channels, RATE, BITRATE * channels
+ )
+ )
+ if self._recorder is not None:
+ # what the player plays and shows beside the frames; then the take's end
+ if (sound := self.soundtrack()) is not None:
+ self._recorder.sound(_wav(sound))
+ if captions := self.captions():
+ self._note({"captions": [asdict(c) for c in captions]})
+ self._recorder.end()
+ self._flush()
+
+ def abort(self) -> None:
+ """Stop the film without writing its video; its take, if it is recorded as one, ends
+ saying that its scene failed.
+
+ [`Scene.render`][manimgx.Scene.render] calls it when the scene fails.
+ """
+ if self.video is not None and self._player is not None:
+ self.video = None
+ self._player.abort_export()
+ if self._recorder is not None:
+ # its take keeps what was made until the scene failed, and ends saying so: a player
+ # drops it, unless it shows it already
+ pending, self._pending = self._pending, None
+ if pending is not None:
+ view, records, cameras, repeat = pending
+ self._recorder.frame(view, records, repeat, cameras)
+ self._recorder.end(failed=True)
+ with contextlib.suppress(Cut): # cut already: it hears nothing more
+ self._flush()
+
+ def _note(self, note: dict[str, object]) -> None:
+ """Tell whoever shows the take the film's own records, as JSON (an exact time as a
+ float): a play that ended, a section, the captions."""
+ if self._recorder is not None:
+ self._recorder.note(json.dumps(note, default=float))
+ self._flush()
+
+ def _flush(self) -> None:
+ """Hand the take what was recorded since (with nobody to hand it to, drop it); once
+ it cuts the film, it is handed nothing more."""
+ if self._recorder is not None:
+ data = self._recorder.drain()
+ if self._take is not None and data:
+ try:
+ self._take(data)
+ except Cut:
+ self._take = None
+ raise
diff --git a/src/manimgx/scene.py b/src/manimgx/scene.py
index 7b9ab4c5..4960f69b 100644
--- a/src/manimgx/scene.py
+++ b/src/manimgx/scene.py
@@ -23,6 +23,7 @@ import pathlib
from collections.abc import Callable, Sequence
from fractions import Fraction
from typing import TYPE_CHECKING, NamedTuple, Self, TypedDict, Unpack, cast
+from warnings import deprecated
import numpy as np
@@ -54,6 +55,7 @@ from manimgx.rendering.film import (
PlayHook,
SectionType,
Take,
+ X264Preset,
)
from manimgx.typing import Point3D, Point3DLike, Vector3DLike
@@ -155,7 +157,7 @@ class Camera:
three_d: Whether it sees in three dimensions: with perspective and depth, from
its orbit.
frame_width: The width of its frame, in scene units; None for the configured one
- (about 14.2). Its height is the configured one (8); a width out of the
+ (about 14.2 at 16:9). Its height is the configured one; a width out of the
video's proportions stretches the picture.
phi: The angle between its line of sight and the z axis, in radians: 0 looks
straight down on the xy plane.
@@ -200,9 +202,10 @@ class Camera:
ValueTracker(theta),
ValueTracker(gamma),
)
- self.focal_distance_tracker, self.zoom_tracker = ValueTracker(
- focal_distance
- ), ValueTracker(zoom)
+ self.focal_distance_tracker, self.zoom_tracker = (
+ ValueTracker(focal_distance),
+ ValueTracker(zoom),
+ )
self.light_source = Point(light_source_start_point)
"""Where the light comes from: a point in the scene, which lights the mobjects
shaded in three dimensions (`shade_in_3d`). Move it like any mobject."""
@@ -285,6 +288,7 @@ class Camera:
"""The height of the view, in scene units: its frame's."""
return self.frame.height
+ @deprecated("Manim CE's machinery: manimgx calls it itself", category=None)
def get_mobjects_indicating_movement(self) -> list[Mobject]:
"""The mobjects the view is made of: moving any of them moves the camera.
@@ -337,11 +341,13 @@ class Camera:
raise ValueError(
"Could not determine bounding box of the mobjects given to 'auto_zoom'."
)
- left, right = min(m.get_critical_point(LEFT)[0] for m in mobs), max(
- m.get_critical_point(RIGHT)[0] for m in mobs
+ left, right = (
+ min(m.get_critical_point(LEFT)[0] for m in mobs),
+ max(m.get_critical_point(RIGHT)[0] for m in mobs),
)
- up, down = max(m.get_critical_point(UP)[1] for m in mobs), min(
- m.get_critical_point(DOWN)[1] for m in mobs
+ up, down = (
+ max(m.get_critical_point(UP)[1] for m in mobs),
+ min(m.get_critical_point(DOWN)[1] for m in mobs),
)
target = (
(self.frame.animate if animate else self.frame)
@@ -353,6 +359,7 @@ class Camera:
return target.set(height=up - down + margin)
# ── the 3D orbit ───────────────────────────────────────────────────────────
+ @deprecated("Manim CE's machinery: manimgx calls it itself", category=None)
def get_value_trackers(self) -> list[ValueTracker]:
"""The five trackers of the camera's orbit.
@@ -483,24 +490,20 @@ class ZoomedCameraConfig(TypedDict, total=False):
class Scene:
- """A scene: the mobjects on screen, an exact clock, and the film they make.
-
- Methods returning `Self` change and return the scene, so calls can chain.
+ """A scene: one video, and what happens in it.
- Subclass it and describe, in [`construct`][manimgx.Scene.construct], what happens
- and when; [`render`][manimgx.Scene.render] runs it and records the film. The scene
- holds mobjects ([`add`][manimgx.Scene.add] puts one in, from that moment on), and
- each frame draws those it holds. Its clock moves only in
- [`play`][manimgx.Scene.play] and [`wait`][manimgx.Scene.wait]: whatever `construct`
- does between two of them happens at one instant.
+ Make a class from it, and write what happens in its
+ [`construct`][manimgx.Scene.construct] method: manimgx runs it once, from top to
+ bottom, and [`render`][manimgx.Scene.render] records the video. A mobject shows from
+ the moment the scene holds it ([`add`][manimgx.Scene.add] puts one in). Time passes
+ only in [`play`][manimgx.Scene.play] and [`wait`][manimgx.Scene.wait]: whatever
+ `construct` does between them happens at one moment.
- Scene time is exact: a rational number of seconds, never rounded. A play or wait of
- `d` seconds that begins at time `T` owns the frames whose times fall in
- `[T, T + d)`, each showing the world at its own instant, frame `k` at exactly
- `k / fps`; then the world is brought to `T + d` itself, where `construct` goes on
- and the next frame finds it. When `construct` returns, a closing frame shows the
- scene as it ends, so its last animation is seen landing. Nothing depends on the
- frame rate: a frame is a photograph of the world at one instant.
+ Each frame shows the scene at its own exact time, so a scene is the same at every
+ frame rate: a second of animation is 60 frames at 60 frames a second, and 30 at 30.
+ When `construct` ends, a last frame shows the scene as it ends, so that its last
+ animation is seen landing. The methods that change a scene give it back, so that
+ their calls chain.
Examples:
```python
@@ -548,6 +551,12 @@ class Scene:
# the play's instants no frame shows, with what each concerns (`_exact`, `_ticks`)
self._events: dict[Fraction, Concern | None] = {}
self._playing: list[Mobject] = [] # what the play running acts on (`_running`)
+ # while animations begin together (`_together`): what the scene held, by id, and
+ # the list of mobjects it was found in (`_introduce`)
+ self._beginning = False
+ self._holding: tuple[list[Mobject], set[int]] | None = None
+ # the play running: its animations may hide parts of the scene (`display_list`)
+ self._animation: Animation | None = None
self.num_plays = 0
"""How many plays and waits the scene has run."""
self.film = Film()
@@ -555,6 +564,9 @@ class Scene:
and returns it."""
@property
+ @deprecated(
+ "Manim CE's: the scene is its own renderer: use the scene", category=None
+ )
def renderer(self) -> Self:
"""The scene itself: Manim code reaches the camera and the time through
`self.renderer`, and a scene has both."""
@@ -562,10 +574,10 @@ class Scene:
@property
def time(self) -> float:
- """The scene's time, in seconds: the instant the world is at.
+ """The scene's time, in seconds.
- In `construct`, it is 0 when the scene begins, then the end of each play or wait
- once it returns; during a play, as animations and updaters run, it is the instant
+ In `construct`, it is 0 when the scene begins, and the end of each play or wait
+ once it returns. During a play, while animations and updaters run, it is the time
of the frame being made.
"""
return float(clock.now)
@@ -602,6 +614,8 @@ class Scene:
self,
video: str | os.PathLike[str] | None = None,
*,
+ preset: X264Preset = "ultrafast",
+ crf: float = 18.0,
frames: FrameSink | None = None,
plays: PlayHook | None = None,
take: Take | None = None,
@@ -627,6 +641,9 @@ class Scene:
video: The MP4 file to write, if any, at the size and frame rate of
[`config`][manimgx.config.config] (a whole number of frames a second,
and an even width and height).
+ preset: The x264 encoding preset; faster presets make larger files.
+ crf: The x264 constant rate factor, from 0 to 51; lower values give
+ higher quality.
frames: A function handed each frame as it is sent (a
[`FrameSink`][manimgx.rendering.film.FrameSink]): a [`Frame`][manimgx.rendering.film.Frame],
which knows its place in the film and draws its pixels when asked.
@@ -642,7 +659,9 @@ class Scene:
The film: how many frames it has, its plays, sections, sounds and captions,
and how its video was made.
"""
- self.film = Film(video, frames=frames, plays=plays, take=take)
+ self.film = Film(
+ video, frames=frames, plays=plays, take=take, preset=preset, crf=crf
+ )
clock.reset()
try:
self.setup()
@@ -663,22 +682,24 @@ class Scene:
self.film.close()
return self.film
+ @deprecated("Manim CE's machinery: manimgx calls it itself", category=None)
def display_list(self) -> list[Mobject]:
"""The mobjects a frame draws, in the order it draws them.
They are the members with points of the scene's mobjects, in family order (a
- mobject before its submobjects), the foreground mobjects last; then sorted by
- z-index, which keeps that order among equal ones. A member held twice is drawn
- once, at its last place.
+ mobject before its submobjects), the foreground mobjects last, but the parts the
+ play running hides (its animations' [`hidden`][manimgx.Animation.hidden]); then
+ sorted by z-index, which keeps that order among equal ones. A member held twice
+ is drawn once, at its last place.
Returns:
A new list.
"""
- leaves = [
- m
- for m in _family([*self.mobjects, *self.foreground_mobjects])
- if m.has_points()
- ]
+ members = _family([*self.mobjects, *self.foreground_mobjects])
+ if self._animation is not None and (parts := self._animation.hidden):
+ hidden = {id(m) for m in _family(parts)}
+ members = [m for m in members if id(m) not in hidden]
+ leaves = [m for m in members if m.has_points()]
leaves.sort(key=lambda m: m.z_index)
return leaves
@@ -836,11 +857,9 @@ class Scene:
self._since[func] = t
func(float(t - since))
if opening is not None:
- opening()
- for mob, recorder, updaters in recorders or ():
- if not mob.updating_suspended and (
- updaters is mob.updaters or _has_updater(mob.updaters, recorder)
- ):
+ self._together(opening)
+ for mob, recorder, _ in recorders or (): # if still there when its turn comes
+ if not mob.updating_suspended and _has_updater(mob.updaters, recorder):
mob._bring(recorder, t)
def _pure_tweens(
@@ -855,6 +874,7 @@ class Scene:
Animation,
AnimationGroup,
Wait,
+ _held,
_updating,
walk,
)
@@ -890,6 +910,7 @@ class Scene:
and kind.interpolate is Animation.interpolate
and kind.interpolate_mobject is Animation.interpolate_mobject
and kind.interpolate_keyframes is Transform.interpolate_keyframes
+ and kind.hidden is Animation.hidden # (it hides nothing)
and not _updating(node.mobject) # (no updaters act while it plays)
and not node.moving_target()
):
@@ -927,11 +948,15 @@ class Scene:
return None
present = {id(m) for m in self.mobjects}
if isinstance(anim, AnimationGroup):
- anim.begin_all()
+ self._together(anim.begin_all)
# what the parts brought into the scene as they began (not the parts aligning a
# mobject split out of it: those were there, and show until their part's window
# opens), in the order they begin, as frame by frame
- opens = {id(t.mobject): b for (t, _), b in zip(tweens, begins, strict=True)}
+ opens = {
+ id(mob): b
+ for (t, _), b in zip(tweens, begins, strict=True)
+ for mob in _held(t.mobject)
+ }
new = [root for root in self.mobjects if id(root) not in present]
new.sort(key=lambda root: opens.get(id(root), 0))
self.mobjects = [r for r in self.mobjects if id(r) in present] + new
@@ -1027,9 +1052,13 @@ class Scene:
)
return self.add(*mobjects)
- add_foreground_mobject = add_foreground_mobjects
- """The same as
- [`add_foreground_mobjects`][manimgx.Scene.add_foreground_mobjects]."""
+ @deprecated(
+ "add_foreground_mobject is add_foreground_mobjects: use it", category=None
+ )
+ def add_foreground_mobject(self, *mobjects: Mobject) -> Self:
+ """The same as
+ [`add_foreground_mobjects`][manimgx.Scene.add_foreground_mobjects]."""
+ return self.add_foreground_mobjects(*mobjects)
def remove_foreground_mobjects(self, *mobjects: Mobject) -> Self:
"""Take mobjects out of the front: they stay in the scene, where they are in its
@@ -1038,9 +1067,13 @@ class Scene:
self.foreground_mobjects = _restructure(self.foreground_mobjects, mobjects)
return self
- remove_foreground_mobject = remove_foreground_mobjects
- """The same as
- [`remove_foreground_mobjects`][manimgx.Scene.remove_foreground_mobjects]."""
+ @deprecated(
+ "remove_foreground_mobject is remove_foreground_mobjects: use it", category=None
+ )
+ def remove_foreground_mobject(self, *mobjects: Mobject) -> Self:
+ """The same as
+ [`remove_foreground_mobjects`][manimgx.Scene.remove_foreground_mobjects]."""
+ return self.remove_foreground_mobjects(*mobjects)
def bring_to_front(self, *mobjects: Mobject) -> Self:
"""Draw mobjects over the others, but under the foreground mobjects: the same as
@@ -1095,7 +1128,9 @@ class Scene:
if not (replace_in(self.mobjects) or replace_in(self.foreground_mobjects)):
raise ValueError(f"Could not find {old} in scene")
+ self._holding = None # (what it holds changed in place)
+ @deprecated("Manim CE's machinery: manimgx calls it itself", category=None)
def get_mobject_family_members(self) -> list[Mobject]:
"""Every mobject in the scene, with all its submobjects, each once.
@@ -1141,21 +1176,18 @@ class Scene:
def play(self, *animations: Animation, **options: Unpack[TransformOptions]) -> None:
"""Play animations, together, from the scene's present time.
- Each animation plays in a window of its own that begins now and lasts its run
- time: the play lasts as long as the longest, and each animation finishes at the
- end of its own window, whatever else still plays. A play of `d` seconds from
- time `T` owns the frames whose times fall in `[T, T + d)`, each showing the
- world at its own instant; then the world is brought to `T + d`, where
- `construct` goes on. To play animations one after another, or staggered, play a
+ Each animation starts now and lasts its own run time, and ends when its time is up,
+ whatever else still plays: the play lasts as long as the longest one. Then
+ `construct` goes on, at the time the play ended. To play animations one after
+ another, or each a little after the one before it, play a
[`Succession`][manimgx.Succession] or a [`LaggedStart`][manimgx.LaggedStart].
- As the play begins, it brings into the scene what its animations act on, if the
- scene lacks it, each by itself, in the order given; but an animation that
- introduces its mobject ([`Create`][manimgx.Create], [`FadeIn`][manimgx.FadeIn], …)
- brings it in as it begins, and a replacement's target comes in as the
- replacement finishes. A remover ([`FadeOut`][manimgx.FadeOut], …) takes its mobject
- out as it finishes. A part of a composition begins and finishes as its window opens
- and closes. A [`Wait`][manimgx.Wait] played alone is a [`wait`][manimgx.Scene.wait].
+ A play brings into the scene what its animations change, if the scene doesn't
+ hold it yet, in the order given. An animation that brings its mobject in
+ ([`Create`][manimgx.Create], [`FadeIn`][manimgx.FadeIn], …) adds it as it starts,
+ and a replacement adds the mobject it turns into as it ends. One that takes its
+ mobject out ([`FadeOut`][manimgx.FadeOut], …) removes it as it ends. A
+ [`Wait`][manimgx.Wait] played alone is a [`wait`][manimgx.Scene.wait].
Args:
*animations: The animations, or iterables of them; at least one.
@@ -1209,11 +1241,11 @@ class Scene:
)
)
end = start + _exact(anim.run_time)
- self.compositor = Compositor()
+ self.compositor, self._animation = Compositor(), anim
try:
self._play(anim, start, end)
finally:
- self.compositor = None
+ self.compositor, self._animation = None, None
self.film.played(Play(index, start, self.clock, where), tuple(anims))
def _play(self, anim: Animation, start: Fraction, end: Fraction) -> None:
@@ -1348,15 +1380,54 @@ class Scene:
for mob in concern.mobjects:
mob.advance(t, recursive=False)
if opening is not None:
- opening()
+ self._together(opening)
clock.stepping = clock.framing = True
+ def _together(self, begin: Callable[[], object]) -> None:
+ """Run `begin`, in which animations begin together: they all find the scene as it
+ was, and what they bring in (`_introduce`) is looked for in what it holds, found
+ once for them all."""
+ self._beginning, self._holding = True, None
+ try:
+ begin()
+ finally:
+ self._beginning, self._holding = False, None
+
+ def _introduce(self, mobjects: Sequence[Mobject]) -> None:
+ """Bring in, as an animation that introduces them begins, those of `mobjects` the
+ scene lacks (with something to draw or to run), each by itself, as `add` does: one
+ none of whose family the scene holds joins it without its being searched again."""
+ holding = self._holding
+ if holding is None or holding[0] is not self.mobjects:
+ holding = (self.mobjects, {id(m) for m in _family(self.mobjects)})
+ held = holding[1]
+ lacking = [
+ mob
+ for mob in mobjects
+ if id(mob) not in held
+ and any(m.has_points() or m.updaters for m in mob.get_family())
+ ]
+ if lacking:
+ family = _family(lacking)
+ if self.foreground_mobjects or any(id(m) in held for m in family):
+ self.add(*lacking) # (what the scene held of them leaves its place)
+ holding = None
+ else:
+ if any(m.updaters for m in family): # their updaters run from now on
+ for m in family:
+ m._stamp(clock.now, recursive=False)
+ self.mobjects = [*self.mobjects, *remove_list_redundancies(lacking)]
+ held.update(id(m) for m in family)
+ holding = (self.mobjects, held)
+ if self._beginning:
+ self._holding = holding
+
def _bring(self, anim: Animation) -> None:
"""Bring into the scene, as a play begins, what its animations act on that it lacks,
in their order, each by itself (what it holds stays in place): all but what an
animation introduces (it joins as that animation begins) and what a replacement
puts in (as it finishes)."""
- from manimgx.animation.timeline import AnimationGroup, _lacks
+ from manimgx.animation.timeline import AnimationGroup, _held, _lacks
from manimgx.animation.transform import Transform
promised: set[int] = set()
@@ -1367,11 +1438,12 @@ class Scene:
for part in anim.animations:
visit(part)
elif anim.is_introducer():
- promised.add(id(anim.mobject))
+ promised.update(id(mob) for mob in _held(anim.mobject))
else:
- if id(anim.mobject) not in promised and _lacks(anim.mobject, members):
- self.add(anim.mobject)
- members.extend(anim.mobject.get_family())
+ for mob in _held(anim.mobject):
+ if id(mob) not in promised and _lacks(mob, members):
+ self.add(mob)
+ members.extend(mob.get_family())
if (
isinstance(anim, Transform)
and anim.replace_mobject_with_target_in_scene
@@ -1389,12 +1461,11 @@ class Scene:
) -> None:
"""Let time pass, playing nothing: the updaters keep running.
- The wait owns the frames whose times fall in its `duration` from now, each
- showing the world at its own instant; then `construct` goes on at its end. With
- a `stop_condition`, it ends at the first frame at which the condition holds, and
- the scene goes on from that frame's time. With `frozen_frame`, the picture holds
- instead: the video goes on for `duration`, but the world stands still, no
- updater runs, and time-based updaters go on afterwards as if no time had passed
+ The video goes on for `duration` seconds, and `construct` goes on at their end.
+ With a `stop_condition`, the wait ends at the first frame at which the condition
+ holds, and the scene goes on from that frame's time. With `frozen_frame`, the
+ picture holds instead: the video goes on for `duration`, but nothing moves, no
+ updater runs, and time-based updaters go on afterward as if no time had passed
(see [`pause`][manimgx.Scene.pause]).
Args:
@@ -1626,35 +1697,18 @@ class Scene:
return clip
+@deprecated(
+ "MovingCameraScene is Scene: every scene's camera moves (self.camera.frame)",
+ category=None,
+)
class MovingCameraScene(Scene):
- """A scene whose camera moves: the name Manim code knows it by, as every scene's
- camera can move.
-
- The camera's [`frame`][manimgx.Camera.frame] is a rectangle in the scene whose
- center and size are the view: move it, scale it or animate it, and the view pans and
- zooms.
-
- Examples:
- ```python
- import manimgx as m
-
-
- class MovingCameraSceneExample(m.MovingCameraScene):
- def construct(self) -> None:
- square = m.Square(color=m.BLUE, fill_opacity=0.5).shift(3 * m.LEFT)
- triangle = m.Triangle(color=m.YELLOW, fill_opacity=0.5)
- triangle.shift(3 * m.RIGHT)
- self.add(square, triangle)
- frame = self.camera.frame
- frame.save_state()
- self.play(frame.animate.move_to(square).set(width=4))
- self.play(frame.animate.move_to(triangle))
- self.play(m.Restore(frame))
- ```
+ """A scene whose camera moves: the name Manim CE knows it by. Every scene's camera
+ moves, so it is a [`Scene`][manimgx.Scene]: animate `self.camera.frame` to pan and
+ zoom.
"""
-class ZoomedScene(MovingCameraScene):
+class ZoomedScene(Scene):
"""A scene with a second camera, whose picture is shown in the frame: a magnifying
glass.
@@ -1675,9 +1729,9 @@ class ZoomedScene(MovingCameraScene):
corner, in scene units.
zoomed_camera_config: [The zoomed camera's look][manimgx.scene.ZoomedCameraConfig]:
its frame's outline, and its picture's background.
- zoomed_camera_image_mobject_config: Keywords for the display, an
- [`ImageMobjectFromCamera`][manimgx.ImageMobjectFromCamera]: its style, and
- its outline's (`default_display_frame_config`).
+ zoomed_camera_image_mobject_config: Keywords for the display, the picture of
+ what the zoomed camera sees: its style, and its outline's
+ (`default_display_frame_config`).
zoomed_camera_frame_starting_position: Where the zoomed camera's frame starts.
zoom_factor: The size of the zoomed camera's frame, as a fraction of the
display's: the display magnifies `1 / zoom_factor` times.
@@ -1799,7 +1853,7 @@ class ZoomedScene(MovingCameraScene):
Returns:
The animation, to play.
"""
- from manimgx.animation.motion import ApplyMethod
+ from manimgx.animation.motion import Restore
kwargs.setdefault("run_time", 2)
frame = self.zoomed_camera.frame
@@ -1808,7 +1862,7 @@ class ZoomedScene(MovingCameraScene):
frame.stretch_to_fit_height(self.camera.frame_height)
frame.center()
frame.set_stroke(width=0)
- return ApplyMethod(frame.restore, **kwargs)
+ return Restore(frame, **kwargs)
def get_zoomed_display_pop_out_animation(
self, **kwargs: Unpack[TransformOptions]
@@ -1825,12 +1879,12 @@ class ZoomedScene(MovingCameraScene):
Returns:
The animation, to play.
"""
- from manimgx.animation.motion import ApplyMethod
+ from manimgx.animation.motion import Restore
display = self.zoomed_display
display.save_state()
display.replace(self.zoomed_camera.frame, stretch=True)
- return ApplyMethod(display.restore, **kwargs)
+ return Restore(display, **kwargs)
def get_zoom_factor(self) -> float:
"""How small the zoomed camera's frame is next to the display.
@@ -2317,7 +2371,7 @@ class VectorScene(Scene):
Args:
animate: Whether to draw it in ([`Create`][manimgx.Create], its lines
overlapping).
- **kwargs: [Number plane keywords][manimgx.mobjects.plotting.NumberPlaneOptions].
+ **kwargs: [Number plane keywords][manimgx.NumberPlane].
Returns:
The plane. It is not the scene's [`plane`][manimgx.VectorScene.plane] unless
@@ -2354,7 +2408,7 @@ class VectorScene(Scene):
Args:
numerical_vector: The point's coordinates on
[`plane`][manimgx.VectorScene.plane]: x and y (a z is ignored).
- **kwargs: [Arrow keywords][manimgx.mobjects.shapes.ArrowTips].
+ **kwargs: [Arrow keywords][manimgx.Arrow].
Returns:
A new arrow, not added to the scene.
@@ -2395,8 +2449,9 @@ class VectorScene(Scene):
It is shown growing from the origin ([GrowArrow][manimgx.GrowArrow]) if `animate`
says so, or else if the scene's `grows_vectors` does (a vector scene's does, a
- transformation scene's doesn't); then the scene takes it up
- ([added_vector][manimgx.VectorScene.added_vector]).
+ transformation scene's doesn't); then the scene takes it up: a
+ [LinearTransformationScene][manimgx.LinearTransformationScene] moves it with the
+ plane.
Args:
vector: An arrow, or the coordinates of a vector's tip, in scene units.
@@ -2416,6 +2471,7 @@ class VectorScene(Scene):
self.added_vector(vector)
return vector
+ @deprecated("Manim CE's machinery: vector_to_coords calls it", category=None)
def added_vector(self, vector: Arrow) -> None:
"""Take up a vector that [add_vector][manimgx.VectorScene.add_vector] added: a
vector scene does nothing with it, and a
@@ -2567,6 +2623,7 @@ class VectorScene(Scene):
self.add(mathtex_label)
return mathtex_label
+ @deprecated("Manim CE's machinery: vector_to_coords calls it", category=None)
def position_x_coordinate(
self, x_coord: Mobject, x_line: Line, vector: Vector3DLike
) -> Mobject:
@@ -2585,6 +2642,7 @@ class VectorScene(Scene):
x_coord.set_color(X_COLOR)
return x_coord
+ @deprecated("Manim CE's machinery: vector_to_coords calls it", category=None)
def position_y_coordinate(
self, y_coord: Mobject, y_line: Line, vector: Vector3DLike
) -> Mobject:
@@ -2697,9 +2755,9 @@ class LinearTransformationScene(VectorScene):
include_background_plane: Whether a plane stays still in the background.
include_foreground_plane: Whether a plane over it moves with the
transformations: the scene's `plane`.
- background_plane_kwargs: [Number plane keywords][manimgx.mobjects.plotting.NumberPlaneOptions]
+ background_plane_kwargs: [Number plane keywords][manimgx.NumberPlane]
for the background plane, over its own (grey lines).
- foreground_plane_kwargs: [Number plane keywords][manimgx.mobjects.plotting.NumberPlaneOptions]
+ foreground_plane_kwargs: [Number plane keywords][manimgx.NumberPlane]
for the moving plane, over its own (it reaches past the frame, so that the
frame stays covered as it moves).
show_coordinates: Whether the background plane's axes are numbered.
@@ -2804,6 +2862,7 @@ class LinearTransformationScene(VectorScene):
self.i_hat, self.j_hat = self.basis_vectors
self.add(self.basis_vectors)
+ @deprecated("Manim CE's machinery: apply_matrix calls it", category=None)
def add_special_mobjects(
self, mob_list: list[Mobject], *mobs_to_add: Mobject
) -> None:
@@ -2993,6 +3052,7 @@ class LinearTransformationScene(VectorScene):
self.title = title
return self
+ @deprecated("Manim CE's machinery: apply_matrix calls it", category=None)
def get_matrix_transformation(
self, matrix: npt.ArrayLike
) -> Callable[[Point3D], Point3D]:
@@ -3007,6 +3067,7 @@ class LinearTransformationScene(VectorScene):
"""
return self.get_transposed_matrix_transformation(np.array(matrix).T)
+ @deprecated("Manim CE's machinery: apply_matrix calls it", category=None)
def get_transposed_matrix_transformation(
self, transposed_matrix: npt.ArrayLike
) -> Callable[[Point3D], Point3D]:
@@ -3029,6 +3090,7 @@ class LinearTransformationScene(VectorScene):
raise ValueError("Matrix has bad dimensions")
return lambda point: np.dot(point, matrix)
+ @deprecated("Manim CE's machinery: apply_matrix calls it", category=None)
def get_piece_movement(self, pieces: Iterable[Mobject]) -> Transform:
"""The animation that moves mobjects whole into their targets (their `target`
each), all together.
@@ -3050,6 +3112,7 @@ class LinearTransformationScene(VectorScene):
self.add(self.ghost_vectors[-1])
return Transform(start, target, lag_ratio=0)
+ @deprecated("Manim CE's machinery: apply_matrix calls it", category=None)
def get_moving_mobject_movement(self, func: MappingFunction) -> Transform:
"""The animation that moves the moving mobjects whole to where a function takes
their centers.
@@ -3066,6 +3129,7 @@ class LinearTransformationScene(VectorScene):
m.target.move_to(func(m.get_center()))
return self.get_piece_movement(self.moving_mobjects)
+ @deprecated("Manim CE's machinery: apply_matrix calls it", category=None)
def get_vector_movement(self, func: MappingFunction) -> Transform:
"""The animation that redraws the moving vectors to where a function takes their
tips; a vector that ends up shorter than 0.1 gets a tip as small.
@@ -3084,6 +3148,7 @@ class LinearTransformationScene(VectorScene):
v.target = target
return self.get_piece_movement(self.moving_vectors)
+ @deprecated("Manim CE's machinery: apply_matrix calls it", category=None)
def get_transformable_label_movement(self) -> Transform:
"""The animation that moves each transformable label to where its vector goes,
rewritten: it follows `get_vector_movement`, which moves the vectors.
diff --git a/tests/unit/rendering/test_film.py b/tests/unit/rendering/test_film.py
new file mode 100644
index 00000000..ad969b3b
--- /dev/null
+++ b/tests/unit/rendering/test_film.py
@@ -0,0 +1,145 @@
+"""A film is a row of sections, each beginning at a frame; its captions are those the scene added
+and those of its speech, in order.
+
+- A section begins at a frame: after a play that ends between frames, the world holds still
+ until the next one (and nothing moves meanwhile), whatever the frame rate. A section with no
+ frame gives way to the next; the first begins with the film.
+- A section's first frame is sent alone, never merged into the hold before it, as a key.
+- Subtitles are the captions in SubRip form, numbered, their times to the millisecond.
+"""
+
+from collections.abc import Callable
+from fractions import Fraction
+
+import numpy as np
+import pytest
+from hypothesis import given, settings
+from hypothesis import strategies as st
+
+import manimgx as m
+from manimgx.audio import Speech, Word
+from manimgx.audio.sound import RATE
+from manimgx.config import config
+from manimgx.rendering.film import Frame
+
+
+def film_of(
+ story: Callable[[m.Scene], None],
+ fps: float = 10,
+ frames: list[Frame] | None = None,
+) -> m.Film:
+ class Made(m.Scene):
+ def construct(self) -> None:
+ story(self)
+
+ saved = config.frame_rate
+ config.frame_rate = fps
+ try:
+ return Made().render(frames=None if frames is None else frames.append)
+ finally:
+ config.frame_rate = saved
+
+
+class TestSections:
+ @settings(max_examples=30)
+ @given(
+ run_time=st.sampled_from([0.25, 0.55, 1.0, 1.37]),
+ fps=st.sampled_from([10, 24, 30, 60]),
+ )
+ def test_a_section_begins_at_a_frame(self, run_time: float, fps: int) -> None:
+ def construct(self: m.Scene) -> None:
+ self.play(m.FadeIn(m.Dot()), run_time=run_time)
+ self.next_section("next", notes="go on")
+ self.play(m.FadeOut(m.Dot()))
+
+ film = film_of(construct, fps)
+ first, section = film.sections
+ assert (first.name, first.start, first.frame) == ("unnamed", 0, 0)
+ assert section.start == Fraction(section.frame, fps)
+ assert section.start >= Fraction(run_time).limit_denominator(10**6)
+ assert section.start - Fraction(run_time).limit_denominator(10**6) < Fraction(
+ 1, fps
+ )
+ assert (section.name, section.notes, section.type) == (
+ "next",
+ "go on",
+ "default.normal",
+ )
+
+ def test_the_world_holds_until_the_section_begins(self) -> None:
+ dot = m.Dot()
+
+ def construct(self: m.Scene) -> None:
+ dot.add_updater(lambda d, dt: d.shift(dt * m.RIGHT))
+ self.add(dot)
+ self.wait(0.55)
+ self.next_section()
+
+ film_of(construct, 10)
+ assert dot.get_x() == pytest.approx(
+ 0.55
+ ) # it did not move between 0.55 and 0.6
+
+ def test_a_section_with_no_frame_gives_way(self) -> None:
+ def construct(self: m.Scene) -> None:
+ self.next_section("a")
+ self.next_section("b", "presentation.loop")
+ self.play(m.FadeIn(m.Dot()))
+
+ film = film_of(construct)
+ assert [(s.name, s.frame, s.type) for s in film.sections] == [
+ ("b", 0, "presentation.loop")
+ ]
+
+ def test_a_section_begins_with_a_key_frame_of_its_own(self) -> None:
+ sent: list[Frame] = []
+
+ def construct(self: m.Scene) -> None:
+ self.add(m.Square())
+ self.wait(1) # one hold across the boundary, unless split
+ self.next_section("still")
+ self.wait(1)
+
+ film = film_of(construct, 10, sent)
+ _, still = film.sections
+ keys = [f.index for f in sent if f.key]
+ assert keys == [still.frame] == [10]
+
+
+class TestCaptions:
+ def test_captions_are_added_and_spoken_in_order(self) -> None:
+ speech = Speech(
+ np.full(RATE, 0.1, np.float32),
+ text="Hello there.",
+ words=[Word("Hello", 0.1, 0.4), Word("there.", 0.5, 0.9)],
+ rate=RATE,
+ )
+
+ def construct(self: m.Scene) -> None:
+ self.add_subcaption("first", duration=0.5)
+ self.wait(1)
+ self.add_sound(speech)
+ self.wait(1)
+
+ film = film_of(construct)
+ assert [(c.start, c.end, c.text) for c in film.captions()] == [
+ (0.0, 0.5, "first"),
+ (pytest.approx(1.1), pytest.approx(1.9), "Hello there."),
+ ]
+ assert film.subtitles().startswith(
+ "1\n00:00:00,000 --> 00:00:00,500\nfirst\n\n2\n00:00:01,100 -->"
+ " 00:00:01,900\n"
+ )
+ assert film_of(lambda self: self.wait(1)).subtitles() == "" # none, nothing
+
+ def test_the_end_cuts_what_still_sounds(self) -> None:
+ long = m.Sound(np.zeros(3 * RATE, np.float32), rate=RATE)
+
+ def story(self: m.Scene) -> None:
+ self.add_sound(long)
+ self.wait(1)
+
+ film = film_of(story)
+ ((clip, lost),) = film.cut()
+ assert clip.sound is long
+ assert lost == pytest.approx(3 - film.frame_count / 10)