# 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.