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

7.9 KiB
Raw Permalink Blame History

SoundCraft roadmap: milestones and what's next

Last reviewed: 2026-11-14 · Last updated: 2026-11-18 · Change: minor (MIDI input landed, the gate row needs checking on macOS and Windows; strict external-WAV AAF import; previously trivial: 28 built-in processors with the Frequency Shifter; G-05 estimate after Linux/X11 plugin editors; M15: partial pt-BR catalog; readiness estimates unchanged) · Target: Avid Pro Tools Ultimate 2026.4.1

Forward-looking plan. Status and numbers: ../ROADMAP.md and target-app-parity.md; the ranked work list: gaps.md. Hours are Opus 5.5 agent-hours.

Current focus

  1. Merge or close the open bug-fix PRs (#123–#134, #146, #148, #75) and fix the rest of the correctness backlog (G-04). ≈ 15–25 h.
  2. Audio interface basics (G-01): device selection, buffer size, duplex stream, ASIO. ≈ 25–40 h.
  3. MIDI devices (G-02): input to armed tracks and instruments is in (checked on Linux); macOS and Windows checks, output, thru to gear, clock remain. ≈ 12–22 h.
  4. macOS plugin hosting (G-05): library-validation entitlement now (#153), then AU editors and embedded CLAP editors on macOS. ≈ 10–15 h.
  5. A PR CI that runs cargo xtask ci on Linux, macOS and Windows (G-14). ≈ 5–10 h.

Alpha gate

The core workflows a Pro Tools professional does every day, checked end to end on macOS (the main platform). Any no keeps SoundCraft pre-alpha, and those rows are the alpha checklist.

Workflow Works end to end? Evidence Hours to pass
Record audio from a chosen interface at a chosen buffer size, monitor, punch, keep the takes no Device, rate and buffer are chosen in the Playback Engine window and, in the desktop app, by setup.playback_engine (headless returns applied: false). The mix still runs in fixed 512-sample blocks. Separate input and output streams. Takes held in RAM until stop (PR #84). 35–55
Record MIDI from a controller and play it back through an instrument unverified Built: keyboards play record-enabled instrument tracks live and are recorded into MIDI clips. On Linux, live play was checked with a hardware keyboard (Akai MPK mini 3) and recording with a virtual one; the row passes once it is checked on macOS and Windows too (G-02). 2–4
Edit: select, trim, fade, comp playlists, Slip/Shuffle/Grid yes (rough) Every Edit menu command; property-tested with undo; open bugs #3, #5, #140 don't block the workflow —
Mix with built-in and third-party plugins, sends, busses, automation partial (passes on CLAP/AU) 28 built-in processors; CLAP and AU host on the signed macOS build, but its missing entitlement blocks third-party VST3 (#153). No AU plugin windows yet; VST3 windows on macOS, Windows and Linux/X11 1–2 (entitlement)
Bounce mix and stems; save and reopen the session yes (rough) WAV/BWF/AIFF/FLAC bounce, stems, .scraft save/reopen with plugin state; bugs #59, #103 in bus bounce and aux latency (PRs open) —
Exchange a session with Pro Tools or a picture editor no Strict external-WAV AAF import works, but AAF export, OMF and .ptx do not (#40, G-03) 50–90

Result: pre-alpha. Three workflows fail. Passing them is ~110–180 h, about 70 % of it parallelizable (interfaces, MIDI and AAF are independent crates).

Milestones

Status: ✅ done · 🟡 in progress · ⬜ not started.

# Milestone Status Remaining (h)
M0–M4 Workspace, gates, model, I/O, DSP, mix engine, command engine, Edit/Mix UI, playback, metering, plugins, bounce ✅ —
M5 Editing depth (tools, modes, playlists, fades, comping, clip groups) ✅ (bugs open, G-04) in G-04
M6 Recording, punch, loop record, monitoring 🟡 first cut; device choice and record-to-disk missing 40–60
M7 MIDI and notation editing 🟡 50–80
M8 CLI, control channel, MCP, agent acceptance test ✅ 3
M9 AudioSuite breadth ✅, Elastic Audio 🟡, Beat Detective 🟡 🟡 40–60
M10 Public releases on all platforms ✅ v0.3.0 (2026-10-08) and v0.4.0 (2026-10-10) released for every platform —
M11 Third-party plugin hosting (CLAP, VST3, AU), video, surround 🟡 mostly done 40–60
M12 Hardware: audio interfaces, MIDI devices, sync, control surfaces ⬜ 110–180
M13 Interchange: AAF/OMF import/export, disk streaming, record to disk 🟡 strict external-WAV AAF import; export, OMF and disk streaming missing 65–115
M14 Fidelity harness against Pro Tools (null tests, plugin responses) ⬜ 20–30
M15 Localization: catalog, fonts/RTL, the 8 Pro Tools languages first 🟡 partial (pt-BR catalog; needs native review; PRs #141, #143 open) 45–80
M16 Built-in plugin depth, sidechain, ARA ⬜ 110–170
M17 Immersive delivery (ADM BWF, object renderer, binaural) and video depth ⬜ 80–130

M8 follow-up (2026-10-14): MCP batches above 1000 calls are rejected before execution (#460). The limit is advertised in the tool schema and description; stage and readiness estimates are unchanged.

To beta (~350–570 h, about 60–70 % parallelizable)

Beta needs ~75 % ready for real work and no blocking gap in session interchange.

Step Gaps Est. (h)
Correctness backlog and a PR CI G-04, G-14 40–65
Audio interfaces, MIDI devices, sync G-01, G-02, G-11 60–100
AAF/OMF interchange, disk streaming, record to disk G-03, G-06 65–115
Plugin hosting completeness on every OS, sidechain G-05, G-13 35–60
Fidelity harness and the fixes it finds G-07 40–60
Built-in plugin essentials (EQ/dynamics/reverb/delay depth) G-08 (half) 40–60
UI feel pass: shortcuts, plugin windows, meters G-19 (half) 30–50
Localization of the 8 Pro Tools languages (catalog, CJK fonts) G-09 (part) 40–60

Needs a human: hardware for G-01/G-02/G-10/G-11, native-speaker review, and owner decisions on AAX, .ptx and Avid cloud features.

After beta (to full parity, a further ~600–900 h)

Control surfaces (G-10), immersive delivery (G-12), the rest of the built-in plugin catalogue (G-08), Elastic Audio depth (G-15), session templates and browser (G-16), video depth (G-17), speech-to-text (G-18), notation and instrument depth (G-20), compressed export (G-21), and the remaining languages.

There is no cargo xtask scorecard in this repo; the measured number is cargo xtask parity (parity-checklist.md).

Revision history

Date Change Summary
2026-11-18 minor MIDI input devices landed (G-02 shrunk); the MIDI gate row is unverified until checked on macOS and Windows
2026-11-14 minor M13 is in progress with strict external-WAV AAF import; the exchange gate still fails without AAF export, OMF or .ptx; estimates unchanged
2026-11-09 trivial 28 built-in processors with the Frequency Shifter
2026-11-05 trivial M15: a pt-BR catalog covers menus and text/localized_format! strings; remains native review, CJK/RTL and the other languages. Estimates unchanged
2026-10-30 trivial G-05 down to 10–15 h and the mix row's VST3 windows updated: VST3 and embedded CLAP editors are hosted on Linux/X11 (#527)
2026-10-25 trivial Record-workflow evidence: setup.playback_engine applies the device and buffer in the desktop app; headless returns applied: false
2026-10-24 trivial 27 built-in processors, as the plugin registry holds; the sampler (#108) is no longer listed under plugin essentials
2026-10-14 trivial M8: reject oversized MCP batches before execution (#460)
2026-10-10 minor Added the alpha gate (3 of 6 core workflows fail → pre-alpha)
2026-10-10 major Created from ROADMAP.md's milestones and alpha list; added M12–M17 and the beta plan with estimates