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.rsnew file mode 100644index 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.rsnew file mode 100644index 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(×cale.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(×cale.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.tomlnew file mode 100644index 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.rsnew file mode 100644index 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.rsnew file mode 100644index 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__.pynew file mode 100644index 00000000..e69de29bdiff --git a/src/manimgx/rendering/film.py b/src/manimgx/rendering/film.pynew file mode 100644index 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+ raisediff --git a/src/manimgx/scene.py b/src/manimgx/scene.pyindex 7b9ab4c5..4960f69b 100644--- a/src/manimgx/scene.py+++ b/src/manimgx/scene.py@@ -23,6 +23,7 @@ import pathlibfrom collections.abc import Callable, Sequencefrom fractions import Fractionfrom typing import TYPE_CHECKING, NamedTuple, Self, TypedDict, Unpack, cast+from warnings import deprecatedimport 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, fromits 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 thevideo's proportions stretches the picture.phi: The angle between its line of sight and the z axis, in radians: 0 looksstraight 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 mobjectsshaded 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 = Noneself.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:@propertydef 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 timeof 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] = tfunc(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.interpolateand kind.interpolate_mobject is Animation.interpolate_mobjectand 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 Nonepresent = {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(), animtry:self._play(anim, start, end)finally:- self.compositor = None+ self.compositor, self._animation = None, Noneself.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 ananimation introduces (it joins as that animation begins) and what a replacementputs in (as it finishes)."""- from manimgx.animation.timeline import AnimationGroup, _lacks+ from manimgx.animation.timeline import AnimationGroup, _held, _lacksfrom manimgx.animation.transform import Transformpromised: 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 magnifyingglass.@@ -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 thedisplay'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 Restorekwargs.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 Restoredisplay = self.zoomed_displaydisplay.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 linesoverlapping).- **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: avector 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 thetransformations: 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 theframe 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_vectorsself.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 = titlereturn 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 takestheir 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 theirtips; a vector that ends up shorter than 0.1 gets a tip as small.@@ -3084,6 +3148,7 @@ class LinearTransformationScene(VectorScene):v.target = targetreturn 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.pynew file mode 100644index 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)