# ADR 0030: Audio Authoring And Bus Schema

## Status

Accepted

## Context

Audio sources and listeners must round-trip through authored scenes without serializing Bevy's
runtime playback handles or sink state. Source routing must also survive bus display-name changes,
project reloads, PIE, and packaging. Bevy provides playback and spatial-listener primitives, but it
does not define Blacksite's persistent authoring schema or project bus graph.

## Decision

`shared` owns reflected, serializable `AudioSourceDesc`, `AudioListenerDesc`,
`AudioAttenuationDesc`, and `AudioRolloff` types. Dedicated authored audio actors use the
`AudioSource` and `AudioListener` actor kinds. Runtime playback, sink, and listener components are
derived state and are never scene source of truth.

An authored clip uses `EditorAssetRef`. Its registry identity remains authoritative, its imported
sub-asset ID is `audio:source`, and its cached source path supports runtime hydration and package
validation. Source bus references store stable bus IDs rather than display labels.

`settings` owns `AudioSettings` and its bus graph. Every project contains stable `master`, `music`,
and `sfx` IDs; Music and SFX route to Master by default. Additional buses are allowed when their
lowercase stable IDs are unique and their parent chain terminates at Master. Validation rejects
missing required buses, invalid gain values, missing parents, unknown references, and cycles.

The `ProjectSettings.audio` field uses a serde default so older manifests load with the standard
bus graph. New project and sandbox manifests include the audio capability and `assets/audio` root.

## Consequences

- Renaming a bus label is safe; changing a bus ID is a routing migration.
- Editor audition and game playback share one authored contract while retaining independent
  transient runtime state.
- Continuous spatial blend and attenuation behavior belong to the runtime adapter; the schema does
  not claim those controls map one-to-one to native Bevy components.
- DSP graphs, sends, reverb zones, streaming banks, and middleware integration remain future work.
- Gitea issue #47 passed automated, headless, live editor/PIE, and packaged-runtime acceptance; this
  contract is the M7 audio baseline.
