73 lines
4.1 KiB
Markdown
73 lines
4.1 KiB
Markdown
# Audio Authoring And Runtime Parity
|
|
|
|
Working implementation plan for Gitea issue
|
|
[`#47`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/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](../../docs/adr/0030-audio-authoring-and-bus-schema.md) and
|
|
[Audio Authoring](../../docs/editor/audio-authoring.md).
|
|
|
|
## 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
|
|
|
|
1. Add shared descriptors, settings schema/defaults/validation, launcher scaffolding, and migrations.
|
|
2. Add audio clip catalog classification, import target, search/filter/details, and drag payloads.
|
|
3. Add runtime source/listener hydration, deterministic listener selection, and bus controls.
|
|
4. Add inspector cards with undoable edits and scene save/validation allowlists.
|
|
5. Add viewport icons/range visualizers and transient audition/stop using the editor camera listener.
|
|
6. 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.
|