Audio Authoring And Runtime Parity

Working implementation plan for Gitea issue #47. This is the minimum complete audio loop required by the M7 content-production milestone.

Status

Completed and production-accepted in Gitea #47. Permanent behavior is documented in ADR 0030 and Audio Authoring.

Outcome

An author can import a supported audio clip, place or assign it as an authored source, tune playback and spatial behavior, audition it without dirtying the scene, save/reload it, and hear equivalent behavior in PIE and a packaged game. Projects expose stable Master, Music, and SFX buses with runtime gain/mute hooks and validation that also runs headlessly.

Architecture

shared owns reflected, serializable source/listener/attenuation descriptors and stable actor kinds.
settings owns versioned project bus definitions and validation; bus references use stable IDs.
game hydrates authoring descriptors into Bevy audio playback/listener components and applies bus controls. Hydrated components remain derived and are never scene source of truth.
editor owns asset discovery/import UX, inspector controls, drag/drop placement, visualizers, and transient audition state. Audition never mutates an authored descriptor or marks a scene dirty.
Scene and project validation share the same clip-reference, bus-reference, range, and listener rules used by packaging. Missing, excluded, unsupported, or Git LFS pointer clips block release validation.

Supported Content

Ogg Vorbis is the baseline runtime format.
WAV, MP3, and FLAC support is enabled explicitly in the workspace Bevy feature set.
Audio sources support gain, pitch, looping, autoplay, spatial blend, attenuation, and bus routing.
Listener authoring supports enabled state, priority, and ear gap; at runtime exactly one enabled listener is selected deterministically.
Default project buses are master, music, and sfx; Music and SFX route to Master.

Implementation Sequence

Add shared descriptors, settings schema/defaults/validation, launcher scaffolding, and migrations.
Add audio clip catalog classification, import target, search/filter/details, and drag payloads.
Add runtime source/listener hydration, deterministic listener selection, and bus controls.
Add inspector cards with undoable edits and scene save/validation allowlists.
Add viewport icons/range visualizers and transient audition/stop using the editor camera listener.
Add a small sample clip/scene, focused round-trip and PIE tests, live QA, permanent docs, and Gitea acceptance evidence.

Acceptance Gates

Dragging a clip into the viewport creates an audio source; dropping onto a compatible selected source assigns the clip through one undoable command.
Inspector edits survive save/reload and PIE hydration without generated playback state leaking into the authored scene.
Spatial preview follows the editor camera, stops on explicit Stop, mode/project changes, or source deletion, and never changes scene dirty state.
Bus definitions persist with stable IDs, invalid parent cycles/references are rejected, and runtime gain/mute hooks affect routed sources.
Headless validation reports missing/unpackageable clips, unsupported values, invalid buses, and ambiguous enabled listeners with actor/property context.
Focused unit/integration tests, cargo validate-levels, package validation, and live editor/game smoke tests passed for issue #47 closure.

Deliberate Boundaries

This slice does not include DSP graphs, reverb zones, waveform editing, audio streaming banks, middleware integration, or platform-specific compression pipelines.
Continuous spatial blend is represented authoritatively and implemented without claiming Bevy supports a native blend control; the runtime adapter owns the mapping/mix behavior.
A future mixer UI may expose additional buses and sends, but it must preserve the stable bus IDs and parent graph established here.

4.1 KiB Raw Blame History