Files
Vic Herrera 0acf57228b Import external-WAV AAF as editable session data (pure Rust) (#799)
* Import external-WAV AAF as editable session data

File > Import > Session Data analyzes an AAF and imports the selected audio
tracks as new tracks, one clip per edit. Clips keep their offset into the
complete source, so handles stay available; the import is one undo step and
Save collects the full sources.

crates/interchange (layer 3, no filesystem/process/UI access):
- build_session(Plan): versioned rational-time plan -> Session. Endpoints are
  rounded to samples independently, so adjacent edits never drift.
- aaf::read_aaf: reads the AAF object model from structured storage with the
  cfb crate (MIT): properties streams, strong reference vectors/sets and
  dictionary weak references. Media goes through a MediaResolver trait.

crates/engine: file.preview_aaf (read-only) and file.import_aaf (undoable).
The resolver opens only files named in the chosen media folder, checks
file_access and reads WAV headers without loading samples; import re-probes
and decodes before touching the session.

crates/ui-egui: Session Data window with track selection, media folder,
absolute/relative mapping, sample offset and report.

Supported: SourceClip/Filler sequences resolved through MasterMobs to
WAVEDescriptor SourceMobs with one external locator; mono/stereo PCM WAV;
composition timecode including 24000/1001 and drop-frame. Gain, fades,
transitions, selectors, nested sequences, embedded essence, split channels,
mixed sample rates and non-local locators fail explicitly.

Addresses #40.

* AAF import: resolve each source once, offer composition choice, start folder picker

- file_source returns early for a known source, so each WAV is probed and
  each relink is reported once however many edits use it. The per-slot
  PhysicalTrackNumber check still runs first.
- When an AAF holds several compositions, the Session Data window lists them
  and passes the chosen MobID to file.preview_aaf.
- "Choose media folder..." opens at the current media folder instead of
  receiving a label as its start path.

* AAF import: lock the composition selector while analysis runs

A selection change during analysis could leave a plan for the previous
composition in the window and enable Import with it.

* AAF import: drop a running analysis when the file or media folder changes

window.import_aaf (and opening an .aaf) can set a new path while the
previous file is still being analyzed; its late plan could then be shown and
imported for the new path.

* AAF import: forget the chosen composition when the path is edited

* AAF import: keep the media folder with a typed AAF path

A typed path now moves a media folder that was derived from the previous
AAF, so same-named WAVs are not taken from the old folder. A folder the user
chose elsewhere is kept.

* AAF import: bound hostile input, confine locators, report missing media

Review follow-up for the AAF reader (untrusted input):
- Cap the structured-storage directory at MAX_DIRECTORY_ENTRIES on open;
  document every bound (sector chains via cfb, 32 MiB streams, MAX_ITEMS
  collections, 32-link source chains with cycle detection).
- Locators are data: refuse `..` anywhere (also percent-encoded and inside
  absolute paths), NUL bytes, paths that name no file, and relative
  locators with a root or drive prefix; relative ones stay under the AAF's
  folder.
- A missing media file no longer aborts the import: it is reported with
  the number of edits skipped, the other edits keep their positions, and
  the import fails only when no referenced file exists.
- Tests: looped directory, mini-FAT and mini-stream chains terminate with
  an error; locators patched into the fixture cannot leave the AAF folder;
  an absolute locator is only looked up in the chosen media folder;
  missing media is reported per file.
- Provenance statement in the module docs and README.

* AAF import: confine the plan's media to the media folder at import too

file.import_aaf takes the plan from its caller (UI, MCP, automation), so
the media-folder rule applied while analysing is checked again before any
source is read: the import requires `media_dir`, and every source must be a
file directly inside it once both paths are canonical (symlinks resolved).
The UI passes the folder it analysed with.

Test: a plan edited to point outside the folder (absolute path, `..`
traversal, symlink) or without `media_dir` is refused without an edit.

* AAF reader: decode UTF-16 with as_chunks for clippy 1.99

clippy::chunks_exact_to_as_chunks (Rust 1.99, used by the gate) rejects
chunks_exact(2) with a constant size. as_chunks is stable since 1.88, below
the workspace minimum.

* AAF reader: state its provenance accurately

The storage layout, class and property identifiers and MobID text form
were learned by reading pyaaf2 (MIT), not from the published AAF
specifications. No pyaaf2, AAF SDK or copyleft code was copied.

* aaf: bound property expansion

Cache parsed objects and share property payloads. Enforce a 128 MiB aggregate property budget and reject duplicate local references before expansion, with a compact AAF regression. Migrate AAF media handling to craft-audio after integrating current main.

* docs: record strict AAF import support
2026-11-19 10:43:36 -06:00
..