From 1f3e603b7ff53a3da364e41ec4da8d43dc83aab0 Mon Sep 17 00:00:00 2001 From: Tanish Manku Date: Fri, 13 Nov 2026 02:36:14 -0700 Subject: [PATCH] feat(xfl): sound effects and envelopes, named reports, Screen Video stills, top-folder and self-extracting .fla archives (M4) --- .gitattributes | 4 + crates/doc/src/bitmap.rs | 12 + crates/engine/src/cmds_file.rs | 2 + crates/engine/tests/xfl_corpus.rs | 29 ++ crates/xfl/src/import.rs | 312 ++++++++++++++++-- crates/xfl/src/lib.rs | 3 +- crates/xfl/src/tests.rs | 79 ++++- crates/xfl/src/video.rs | 224 +++++++++++++ crates/xfl/src/zip.rs | 38 ++- crates/xfl/src/zip_tests.rs | 37 ++- crates/xfl/tests/corpus.rs | 102 +++++- .../xfl/tests/corpus/sounds/DOMDocument.xml | 64 ++++ .../corpus/sounds/LIBRARY/Sounds/beep.wav | Bin 0 -> 5556 bytes .../corpus/sounds/LIBRARY/Sounds/tone.mp3 | Bin 0 -> 2526 bytes .../xfl/tests/corpus/sounds/LIBRARY/theme.aif | Bin 0 -> 54 bytes .../xfl/tests/corpus/sounds/LIBRARY/voice.wav | Bin 0 -> 304 bytes crates/xfl/tests/corpus/sounds/bin/M 3 1.dat | Bin 0 -> 512 bytes .../tests/corpus/sounds/golden/frame-000.png | Bin 0 -> 2002 bytes crates/xfl/tests/corpus/sounds/sounds.xfl | 1 + crates/xfl/tests/corpus/video/DOMDocument.xml | 47 +++ .../corpus/video/LIBRARY/Clips/screen.flv | Bin 0 -> 185 bytes crates/xfl/tests/corpus/video/bin/M 4 2.dat | Bin 0 -> 91 bytes .../tests/corpus/video/golden/frame-000.png | Bin 0 -> 1892 bytes crates/xfl/tests/corpus/video/video.xfl | 1 + crates/xfl/tests/fla.rs | 18 +- crates/xfl/tests/support/fla.rs | 81 ++++- 26 files changed, 1002 insertions(+), 52 deletions(-) create mode 100644 crates/xfl/src/video.rs create mode 100644 crates/xfl/tests/corpus/sounds/DOMDocument.xml create mode 100644 crates/xfl/tests/corpus/sounds/LIBRARY/Sounds/beep.wav create mode 100644 crates/xfl/tests/corpus/sounds/LIBRARY/Sounds/tone.mp3 create mode 100644 crates/xfl/tests/corpus/sounds/LIBRARY/theme.aif create mode 100644 crates/xfl/tests/corpus/sounds/LIBRARY/voice.wav create mode 100644 crates/xfl/tests/corpus/sounds/bin/M 3 1.dat create mode 100644 crates/xfl/tests/corpus/sounds/golden/frame-000.png create mode 100644 crates/xfl/tests/corpus/sounds/sounds.xfl create mode 100644 crates/xfl/tests/corpus/video/DOMDocument.xml create mode 100644 crates/xfl/tests/corpus/video/LIBRARY/Clips/screen.flv create mode 100644 crates/xfl/tests/corpus/video/bin/M 4 2.dat create mode 100644 crates/xfl/tests/corpus/video/golden/frame-000.png create mode 100644 crates/xfl/tests/corpus/video/video.xfl diff --git a/.gitattributes b/.gitattributes index 80c58656..46a94cd2 100644 --- a/.gitattributes +++ b/.gitattributes @@ -16,3 +16,7 @@ scripts/git-hooks/* text eol=lf *.tiff binary *.DS_Store binary *.ico binary +# XFL corpus media (ADR 0086) +*.flv binary +*.aif binary +*.dat binary diff --git a/crates/doc/src/bitmap.rs b/crates/doc/src/bitmap.rs index 4df45cf5..49d95c9a 100644 --- a/crates/doc/src/bitmap.rs +++ b/crates/doc/src/bitmap.rs @@ -81,6 +81,18 @@ impl Bitmap { Bitmap::from_png(id, name, png).ok_or(ImageError::Unreadable) } + /// A bitmap from straight RGBA8 pixels, row by row (a decoded video frame, say). `None` + /// when the size is empty, over [`MAX_BITMAP_EDGE`] or doesn't match the pixels. + pub fn from_rgba(id: BitmapId, name: impl Into, width: u32, height: u32, rgba: Vec) -> Option { + if width == 0 || height == 0 || width > MAX_BITMAP_EDGE || height > MAX_BITMAP_EDGE || rgba.len() != width as usize * height as usize * 4 { + return None; + } + let png = encode_png(width, height, &rgba)?; + let decoded = OnceLock::new(); + let _ = decoded.set(Some(Arc::new(Pixels { width, height, rgba }))); + Some(Bitmap { id, name: name.into(), width, height, png: Arc::new(png), smoothing: true, decoded: Arc::new(decoded) }) + } + /// The decoded pixels (decoded once and shared by every clone). `None` for unreadable data. pub fn pixels(&self) -> Option> { self.decoded.get_or_init(|| decode_png(&self.png).map(Arc::new)).clone() diff --git a/crates/engine/src/cmds_file.rs b/crates/engine/src/cmds_file.rs index 190caf69..61e33bfb 100644 --- a/crates/engine/src/cmds_file.rs +++ b/crates/engine/src/cmds_file.rs @@ -212,6 +212,8 @@ pub(crate) fn open(s: &mut Session, p: &Value) -> Result { info["kept"] = json!(report.kept); info["runs"] = json!(report.runs); info["missing_fonts"] = json!(report.missing_fonts); + // The sounds and videos that didn't come across, by name and why (ADR 0086). + info["named"] = json!(report.names); info["merged_keyframes"] = json!(merged); return Ok(info); } diff --git a/crates/engine/tests/xfl_corpus.rs b/crates/engine/tests/xfl_corpus.rs index 9ad9484a..c815d62b 100644 --- a/crates/engine/tests/xfl_corpus.rs +++ b/crates/engine/tests/xfl_corpus.rs @@ -40,10 +40,12 @@ const FRAMES: &[(&str, &[u32])] = &[ ("scenes", &[0, 3, 7, 8, 10]), ("scripts", &[0, 4]), ("shapes", &[0]), + ("sounds", &[0]), ("symbols", &[0, 5]), ("text", &[0]), ("textfields", &[0]), ("tweens", &[0, 6, 12]), + ("video", &[0]), ]; /// Render scale: the corpus stages are 320 × 180. @@ -59,6 +61,18 @@ const PROBES: &[(&str, u32, f32, f32, u32)] = &[ ("shapes", 0, 80.0, 30.0, 0x2B6CD9), ("shapes", 0, 95.0, 50.0, 0xF4F1EA), ("shapes", 0, 270.0, 60.0, 0xF29E1F), + // ADR 0086: the sounds package's artwork under its sound layers, on its own stage colour. + ("sounds", 0, 40.0, 60.0, 0x2A9D8F), + ("sounds", 0, 160.0, 90.0, 0xE9C46A), + ("sounds", 0, 10.0, 10.0, 0xF4F1EA), + // The Screen Video's first frame at 1.5 times (20..116 × 20..92), its quarters the right + // way up and round; the VP6 video draws nothing; the rectangle beside it. + ("video", 0, 35.0, 35.0, 0xE63946), + ("video", 0, 100.0, 35.0, 0x2A9D8F), + ("video", 0, 35.0, 80.0, 0x2646C8), + ("video", 0, 100.0, 80.0, 0xE9C46A), + ("video", 0, 200.0, 50.0, 0x264653), + ("video", 0, 10.0, 150.0, 0xFFFFFF), ("primitives", 0, 40.0, 50.0, 0xF2CC8F), ("primitives", 0, 210.0, 40.0, 0xE07A5F), ("primitives", 0, 6.0, 170.0, 0xFFFFFF), @@ -270,6 +284,7 @@ fn every_package_opens_from_a_fla_with_the_same_golden_frames() { let mut t = Session::default(); let got = t.execute("file.open", &json!({"path": path.display().to_string()})).unwrap_or_else(|e| panic!("{case}, {}: {e}", v.name)); assert_eq!(got["report"], want["report"], "{case}, {}", v.name); + assert_eq!(got["named"], want["named"], "{case}, {}", v.name); assert!(t.doc == s.doc, "{case}, {}: the .fla opens differently from the folder", v.name); } // The goldens (imported without fonts, as they were made), rendered from the .fla in @@ -342,3 +357,17 @@ fn every_entry_point_opens_the_corpus_as_a_fla() { .unwrap(); } } + +/// ADR 0086: opening a document headless (the CLI and MCP) says which sounds and videos didn't +/// come across, by name, and the sounds that did are in the Library with their waveforms. +#[test] +fn file_open_names_the_sounds_and_videos_that_did_not_come_across() { + let mut s = Session::default(); + let got = s.execute("file.open", &json!({"path": corpus().join("sounds").display().to_string()})).unwrap(); + assert_eq!(got["named"]["missing sound files"], json!(["lost.wav"])); + assert!(got["report"].as_str().unwrap().contains("3 sounds in formats AniCraft can't decode (theme.aif: AIFF; voice.wav: WAV in IMA ADPCM; Sounds/loop: Animate's own sound data)"), "{}", got["report"]); + assert_eq!(s.doc.sounds.len(), 2); + assert!(s.doc.sounds.iter().all(|x| x.decoded().is_some_and(|d| d.pcm.frames() > 0)), "waveforms ready to draw"); + let got = s.execute("file.open", &json!({"path": corpus().join("video").display().to_string(), "confirm": true})).unwrap(); + assert_eq!(got["named"]["videos AniCraft can't play"], json!(["intro.flv: FLV, On2 VP6, 4.5 s", "gone.mp4: its file is missing, 1.0 s"])); +} diff --git a/crates/xfl/src/import.rs b/crates/xfl/src/import.rs index 72b674ed..bb7c3936 100644 --- a/crates/xfl/src/import.rs +++ b/crates/xfl/src/import.rs @@ -25,6 +25,7 @@ use anicraft_doc::{ Cap, Dash, Join, StrokeStyle, Bitmap, BitmapId, BlendMode, ColorEffect, ColorTransform, Filter, FilterSide, Document, Easing, Element, ElementId, ElementKind, GradientStop, Keyframe, Layer, LayerId, LayerKind, LoopMode, Paint, Rgba, Shape, Stage, Stroke, Symbol, SymbolId, Scene, ShapeHint, SymbolKind, Timeline, Tween, TweenKind, CustomEase, EaseGroup, FrameScript, FrameSound, Language, Linkage, ScaleGrid, SoundSync, SourceScript, Spread, MAX_FOCAL, }; +use anicraft_doc::sound::{EnvelopePoint, SoundEffect, clean_points}; use anicraft_geom::{Affine, FillRule, Path, Vec2}; use anicraft_text::{FaceMatch, Fonts}; use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet}; @@ -66,12 +67,29 @@ pub struct Report { pub missing_fonts: BTreeSet, /// The family that text was laid out in instead. pub fallback_font: Option, + /// The items behind some kinds of `skipped`, by name ("intro.flv, On2 VP6, 4.0 s"), so an + /// artist can tell which sound or video didn't come across (ADR 0086). At most + /// [`MAX_NAMED`] per kind; the count in `skipped` is always whole. + pub names: BTreeMap>, } +/// Most names kept per kind of skipped item. +pub const MAX_NAMED: usize = 64; +/// Most names the summary line shows per kind. +const SHOWN_NAMES: usize = 3; + impl Report { pub(crate) fn skip(&mut self, what: &str) { *self.skipped.entry(what.to_string()).or_default() += 1; } + /// Counts `what` and keeps the item's `name` for the report. + pub(crate) fn skip_named(&mut self, what: &str, name: String) { + self.skip(what); + let names = self.names.entry(what.to_string()).or_default(); + if names.len() < MAX_NAMED { + names.push(name); + } + } pub(crate) fn keep(&mut self, what: &str) { *self.kept.entry(what.to_string()).or_default() += 1; } @@ -94,7 +112,20 @@ impl Report { return format!("Imported everything in the file.{kept}"); } let mut out = format!("Imported.{kept}"); - let mut parts: Vec = self.skipped.iter().map(|(k, n)| format!("{n} {k}")).collect(); + let mut parts: Vec = self + .skipped + .iter() + .map(|(k, n)| match self.names.get(k).filter(|v| !v.is_empty()) { + Some(names) => { + let mut shown: Vec<&str> = names.iter().take(SHOWN_NAMES).map(String::as_str).collect(); + let more = n.saturating_sub(shown.len()); + let more = if more > 0 { format!(" and {more} more") } else { String::new() }; + shown.truncate(SHOWN_NAMES); + format!("{n} {k} ({}{more})", shown.join("; ")) + } + None => format!("{n} {k}"), + }) + .collect(); parts.extend(self.notes.iter().cloned()); if !parts.is_empty() { out.push_str(&format!(" Not yet supported: {}.", parts.join(", "))); @@ -116,6 +147,70 @@ const MAX_LAYERS: usize = 5_000; const MAX_FRAME: u32 = 100_000; const MAX_BITMAPS: usize = 10_000; const MAX_SOUNDS: usize = 10_000; +const MAX_VIDEOS: usize = 10_000; + +/// Names the format of sound data that didn't decode, and why when it is a kind AniCraft reads: +/// "AIFF", "WAV in IMA ADPCM", "Animate's own sound data". +fn sound_format(data: &[u8], from_bin: bool, err: &anicraft_doc::audio::AudioError) -> String { + use anicraft_doc::audio::{AudioError, Format}; + if data.starts_with(b"OggS") && data.windows(8).any(|w| w == b"OpusHead") { + return "Ogg Opus".into(); + } + if let Some(f) = Format::sniff(data) { + let kind = match f { + Format::Wav => "WAV", + Format::Vorbis => "Ogg", + Format::Mp3 => "MP3", + }; + return match err { + AudioError::Unsupported(_) if let Some(codec) = wav_codec(data).filter(|c| !matches!(c, 1 | 3 | 0xFFFE)) => { + let name = match codec { + 0x0002 => "Microsoft ADPCM".to_string(), + 0x0006 => "A-law".to_string(), + 0x0007 => "µ-law".to_string(), + 0x0011 => "IMA ADPCM".to_string(), + 0x0031 => "GSM 6.10".to_string(), + 0x0055 => "MP3".to_string(), + c => format!("codec 0x{c:04X}"), + }; + format!("WAV in {name}") + } + AudioError::Unsupported(what) => format!("{kind} with {what}"), + AudioError::TooLong => format!("{kind} longer than AniCraft plays"), + AudioError::Empty => format!("{kind} holding no audio"), + _ => format!("a damaged {kind} file"), + }; + } + let name = if data.starts_with(b"FORM") && matches!(data.get(8..12), Some(b"AIFF" | b"AIFC")) { + "AIFF" + } else if data.starts_with(b"fLaC") { + "FLAC" + } else if data.get(4..8) == Some(b"ftyp") { + "AAC or MPEG-4 audio" + } else if data.starts_with(b".snd") { + "Sun AU" + } else if from_bin { + "Animate's own sound data" + } else { + "an unknown format" + }; + name.into() +} + +/// The codec of a WAV file's `fmt ` chunk (1 PCM, 3 float, 0x11 IMA ADPCM, …), looked for in +/// its first chunks. +fn wav_codec(data: &[u8]) -> Option { + let mut at = 12usize; + for _ in 0..64 { + let id = data.get(at..at + 4)?; + let size = u32::from_le_bytes(data.get(at + 4..at + 8)?.try_into().ok()?) as usize; + if id == b"fmt " { + return Some(u16::from_le_bytes(data.get(at + 8..at + 10)?.try_into().ok()?)); + } + at = at.checked_add(8)?.checked_add(size)?.checked_add(size & 1)?; + } + None +} /// Bitmap fill matrices scale image pixels by twips (1/20 px): `a = 20` is one pixel per pixel. const TWIPS: f32 = 20.0; @@ -134,6 +229,9 @@ struct Builder<'a> { bitmaps: HashMap, /// Library item name → sound id, for the sounds whose file is in the package (ADR 0057). sounds: HashMap, + /// Library item name -> the still of its first frame, for every video item (`None` when the + /// video could not be read; ADR 0086). + videos: HashMap>, report: Report, /// The fonts text is laid out with; the computer's, found on the first text field. fonts: Option<&'a Fonts>, @@ -327,6 +425,23 @@ impl<'a> Builder<'a> { out.push(self.element(ElementKind::Shape(shape), parent.mul(&matrix(el)), ColorEffect::default())); } + /// A video instance (ADR 0086): its video's first frame, as a bitmap rectangle sized to the + /// instance's frame (`frameRight` and `frameBottom`, in twips) when the video came across + /// as a still; otherwise counted, the video itself being named in the report. + fn video_instance(&mut self, el: &X, parent: &Affine, out: &mut Vec>) { + let still = el.attr("libraryItemName").and_then(|n| self.videos.get(n)).copied(); + let found = still.flatten().and_then(|id| self.doc.bitmap(id).map(|b| (id, b.width as f32, b.height as f32))); + let Some((bitmap, w, h)) = found else { + self.report.skip(if still.is_some() { "instances of videos AniCraft can't play" } else { "instances of missing videos" }); + return; + }; + let size = |k: &str, natural: f32| el.f32(k).map(|t| t / TWIPS).filter(|v| v.is_finite() && *v > 0.0 && *v <= 100_000.0).unwrap_or(natural); + let (fw, fh) = (size("frameRight", w), size("frameBottom", h)); + let fit = Affine::scale(fw / w, fh / h); + let shape = Shape { path: Arc::new(Path::rect(0.0, 0.0, w, h)), fill: Some(Paint::Bitmap { bitmap, repeat: false, matrix: Affine::IDENTITY }), stroke: None, fill_rule: FillRule::NonZero, merge: false, warp: None }; + out.push(self.element(ElementKind::Shape(shape), parent.mul(&matrix(el)).mul(&fit), ColorEffect::default())); + } + /// An instance's filters, by Animate's element names; switched-off filters are left out, /// and unknown ones reported. fn filters(&mut self, el: &X) -> Vec { @@ -497,7 +612,7 @@ impl<'a> Builder<'a> { "DOMRectangleObject" | "DOMOvalObject" => self.primitive(el, parent, out), "DOMBitmapInstance" => self.bitmap_instance(el, parent, out), "DOMStaticText" | "DOMDynamicText" | "DOMInputText" => self.text_field(el, parent, out), - "DOMVideoInstance" => self.report.skip("videos"), + "DOMVideoInstance" => self.video_instance(el, parent, out), _ => self.report.skip("other elements"), } } @@ -799,24 +914,27 @@ impl<'a> Builder<'a> { Ok(()) } - /// Reads the document's sound library items (ADR 0057). Like a bitmap, each one's sound is - /// looked for as the original file in `LIBRARY/` and then as its data file in `bin/`, and is - /// used when it is a WAV, Ogg Vorbis or MP3 file. Animate's own encoding of the data file is - /// not public, so those sounds are reported instead (ADR 0039). + /// Reads the document's sound library items (ADR 0057, ADR 0086). Like a bitmap, each one's + /// sound is looked for as the original file in `LIBRARY/` and then as its data file in + /// `bin/`, and is used when it is a WAV, Ogg Vorbis or MP3 file the decoders read. Animate's + /// own encoding of the data file is not public, so those sounds are reported by name, as is + /// every other sound that doesn't come across, with its format and why (ADR 0039). fn register_sounds(&mut self, root: &X) -> Result<(), XflError> { for item in root.list("media").iter().filter(|i| i.name == "DOMSoundItem").take(MAX_SOUNDS) { let Some(name) = item.attr("name").filter(|n| !self.sounds.contains_key(*n)) else { continue }; let mut candidates = Vec::new(); if let Some(href) = item.attr("href") { - candidates.push(format!("LIBRARY/{href}")); + candidates.push((format!("LIBRARY/{href}"), false)); } if let Some(data) = item.attr("soundDataHRef") { - candidates.push(format!("bin/{data}")); + candidates.push((format!("bin/{data}"), true)); } let short: String = name.rsplit('/').next().unwrap_or(name).chars().take(256).collect(); - let (mut found_data, mut unreadable) = (false, false); + let shown: String = name.chars().take(256).collect(); + // Why the first file found didn't decode, and whether one couldn't be read at all. + let (mut why, mut unreadable) = (None, false); let mut sound = None; - for path in candidates { + for (path, from_bin) in candidates { let bytes = match (self.read)(&path) { Ok(Some(bytes)) => bytes, Ok(None) => continue, @@ -827,29 +945,114 @@ impl<'a> Builder<'a> { continue; } }; - found_data = true; - if let Ok(s) = anicraft_doc::Sound::from_data(anicraft_doc::SoundId(0), short.clone(), bytes) { - sound = Some(s); - break; + // Named from the first bytes, before the data moves into the sound. + let head: Vec = bytes.iter().take(4096).copied().collect(); + match anicraft_doc::Sound::from_data(anicraft_doc::SoundId(0), short.clone(), bytes) { + Ok(s) => { + sound = Some(s); + break; + } + Err(e) => { + why.get_or_insert_with(|| sound_format(&head, from_bin, &e)); + } } } - match sound { - Some(mut s) => { + match (sound, why) { + (Some(mut s), _) => { s.id = anicraft_doc::SoundId(self.doc.alloc_id()); self.place_in_folder(name, anicraft_doc::LibraryItem::Sound(s.id)); self.sounds.insert(name.to_string(), s.id); self.doc.sounds.push(Arc::new(s)); } - None if found_data => self.report.skip("sounds stored in Animate's own format"), - None if unreadable => self.report.skip("sounds whose files couldn't be read"), - None => self.report.skip("missing sound files"), + (None, Some(why)) => self.report.skip_named("sounds in formats AniCraft can't decode", format!("{shown}: {why}")), + (None, None) if unreadable => self.report.skip_named("sounds whose files couldn't be read", shown), + (None, None) => self.report.skip_named("missing sound files", shown), } } Ok(()) } + /// Reads the document's video items (`DOMVideoItem`, ADR 0086). AniCraft has no video + /// playback: a video whose data is an FLV file in the Screen Video codec comes across as a + /// bitmap of its first frame (in the Library beside where the video was, named + /// "