Audio System

Everything the player hears goes through one path: a cue is requested by gameplay or QML, the cue registry picks a resource from the manifest, AudioSystem decides whether it may play, and the miniaudio backend mixes it. Music and ambience beds are chosen by tags in the manifest rather than by ID in code, so the asset set can change without touching C++ or QML.

Where each file came from and under what licence is in AUDIO_LICENSES.md.

Where things live

The path of one cue

gameplay code / system            QML (ui/qml/design/UiSound.qml)
  play_cue("combat.hit.sword")      audioSystem.play_cue("ui.click")
  or publish AudioCueEvent                │ source tagged "qml"
        │                                 │
        ▼                                 ▼
CueRegistry::play                                   caller thread, mutex
  unbound? ─────────────► drop: unbound
  cue cooldown? ────────► drop: cue_cooldown
  choose a variant ─────► drop: no_loaded_resource (none loaded)
        │
        ▼
AudioSystem::play_sound  ──► AudioEvent queue
        │
        ▼
AudioSystem audio thread                            process_event
  resource loaded? ─────► drop: resource_not_loaded
  max_instances ────────► drop: instance_limit
  resource cooldown ────► drop: resource_cooldown
  spatialize + sliders ─► drop: muted (volume ≈ 0, incl. out of earshot)
  32-channel priority ──► drop: global_priority
  category cap ─────────► drop: category_priority
  pick mix bus
        │
        ▼
MiniaudioBackend::play_sound ──► lock-free command ring (256)
        │
        ▼
device callback on_audio                            no locks
  music channels + sound-effect slots
  × per-bus gain (GameplayMix) → BusLimiter → device

AudioEventHandler also drops a request as audience_filtered before it reaches the registry when the event belongs to another player (you do not hear an AI opening its own gate). Every request ends in exactly one outcome, so requests always equal accepted plus drops.

The source location is captured with std::source_location, so no call site passes it. An AudioCueEvent records where it was published, not where the handler dispatched it.

The two catalogues

audio_manifest.json — the files

{
    "id": "voice.roman.archer",
    "aliases": ["archer_voice", "roman.archer"],
    "path": "voices/roman/archer.ogg",
    "category": "voice",
    "load_policy": "mission",
    "tags": { "faction": "roman", "unit": "archer" }
}

audio_cues.json — the cues

{
    "id": "ui.click",
    "description": "Menu button, list row or combo box entry is activated.",
    "category": "sfx",
    "importance": "optional",
    "volume": 0.85,
    "priority": 5,
    "cooldown_ms": 40,
    "resources": ["ui.click.primary"],
    "wanted": "Firm wood-on-leather confirm tap with a small low-mid body."
}

Cue IDs used from C++ are constants in game/audio/cue_ids.h. A cue bound to nothing warns once (audio cue requested but bound to nothing); a cue whose resources exist but are not loaded warns check its load_policy.

Variant choice

With more than one resource, CueRegistry avoids the last pool / 2 picks, prefers a variant whose own resource cooldown has elapsed, then draws by weight. A two-take cue therefore never repeats back to back, and a four-take cue never repeats within two plays.

Loading

Loading only queues a decode; the decode worker does the work (see Decode-time mastering). A one-shot asked for before its decode lands is skipped, and a looping bed is held and starts the moment it lands. AudioSystem::is_resource_ready does not mean decoded: it only says the resource is loaded, off cooldown and under its instance limit.

Resident decoded PCM is tracked against a budget (SOI_AUDIO_PCM_BUDGET_MB overrides it; the default is 320 MB); overruns are counted and logged, not refused.

Tracks are held as 32-bit float stereo at the device rate, so a minute of music costs about 22 MB at 48 kHz and twice that at 96 kHz. The two four-minute peaceful beds (music.base.echoes_ancient_outpost, music.base.ancient_peak_fires) are 88 MB each, and the startup and mission sets add roughly 20 MB more, which is why a mission that rotates onto its second long bed sits near 200 MB. The budget is a diagnostic: raise it (or shorten the long beds) rather than expecting the backend to evict anything.

Waiting on a decode

There is one decode worker, and a scripted launch reaches the mission preload while the startup set (about a hundred tracks) is still queued on it. MiniaudioBackend::unload runs with AudioSystem::resource_mutex held, and every load_sound in the mission preload needs that mutex, so any wait inside unload stalls the loading thread. Two rules keep that wait short. finish_job wakes m_decode_idle after every job, so wait_for_track returns when its own track lands instead of when the whole queue drains. And unload first calls cancel_queued_decode, which drops a job that has not started yet, so only a decode already in flight is ever waited for. Before this the mission preload measured anywhere from under 1 ms to 5.6 s on the same map.

Tag-driven selection

AudioCoordinator and AudioEventHandler pick music, beds and voices by querying manifest tags. No track ID for music or ambience appears in code except the final fallback bed.

Frontend music. Tracks tagged screen_context=<context> rotate round-robin per context. The context battle (or empty) stops music.

Mission music. For each ambient state (peaceful, tense, combat, victory, defeat) the handler holds the tracks tagged ambient_state=<state>; for combat, victory and defeat the player's own faction is queried first. A state change rotates to the next track, plays one of the SFX tagged state=<state> (priority 7, two-second group cooldown) and, for victory and defeat, fires state.victory / state.defeat.

Mission ambience. One looping bed, chosen by the first query below that matches anything:

1. Words in the map path, map name, mission ID, title, summary and terrain: harbor/port → biome=harbor; city/market → city; village/hamlet → village; siege → biome=camp, context=siege; road/crossroads (Roman players only) → biome=plains, context=road, faction=roman; desert/zama → biome=plains, faction=carthage.
2. The biome: the mission's terrain_type if set, otherwise the map — rivers or lakes → river, AlpineMix → mountain, GrassDry → plains, SoilRocky → battlefield, SoilFertile → camp, anything else → forest. camp and plains try the player's faction first.
3. biome=battlefield.

Among the matches the bed is picked by a hash of map path, faction and mission ID, so the same mission always gets the same bed. If nothing matches, ambient.battlefield_dry_wind_distant_march_01 plays.

Weather. Weather is a layer, not a bed per sky. WeatherAudio plays ambient.weather_rain or ambient.weather_snow on top of the mission bed at intensity × 0.85, and stops below 0.02. Those two beds carry only the weather, never ground sound.

Unit voices. Selecting or spawning a unit plays the voice resolved in this order: the faction.unit mapping built from tags faction + unit, the unit-type mapping, the manifest ID voice.<faction>.<unit>, then the legacy alias <unit>_voice. Commanders are matched by unit_def. Selection voices play at least 120 ms apart, or 300 ms when the same line would repeat; spawn voices share a 1.5 s group cooldown.

Cues chosen by who is acting. Some actions pick their cue from the units doing them, because a resource pool is drawn at random and a mixed pool plays the wrong animal. A run order counts the selection's foot, cavalry and elephants (CommandController::selection_mounts) and plays combat.charge_elephant if any elephant is selected, combat.charge_cavalry if any cavalry is, and combat.charge otherwise (CommandController::charge_cue). An accepted move order plays order.move_mounted — horses moving off at a walk — only when every selected unit is cavalry (CommandController::move_order_cue). A Roman medicus binds wounds with combat.heal_bind; every other healer plays combat.heal.

Commander chatter. The banks in assets/data/commanders/voices/*.json are on-screen lines. Each line may name a voice_cue, but no bank sets one today, so commanders speak in text only; the three files in voices/commanders/ are their selection barks.

Spatial audio

A cue with "spatial": true fired through play_cue_at is heard relative to the camera. The engine publishes the listener every frame from the render camera (app/core/game_engine.cpp).

Pan is the source's offset along the camera's right vector divided by 26 m, clamped, scaled to ±0.85. Before a camera exists the listener is invalid and every cue plays flat at full volume.

Distant fighting is not simply lost: AudioEventHandler counts impacts that distance silenced, and six inside three seconds become one combat.distant_battle cue. tests/core/audio_battle_load_test.cpp measures this against a paced melee.

The mix

Categories and channels

A new sound above the 32-channel or category cap evicts the lowest-priority, oldest sound only if it outranks it; otherwise it is dropped. Sliders and the listening preset persist through QSettings (INI, organisation djeada, application StandardOfIron, keys audio/*). Invalid saved values are clamped with a warning.

Mix buses

Every playing sound sits on a bus chosen from its cue ID, then its resource ID (a leading sound_ or sfx. is ignored). Voice-category sounds always use the Voice bus.

GameplayMix retargets the gains every mix block (256 frames) and glides toward them (20 ms attack, 350 ms release):

• Density. Combat, Economy and Environment scale by 1 / √(max(1, active / 3)) across those three buses, so a large melee does not sum to a wall.
• Voice ducking. While any voice plays, Music, Ambience, Weather, Combat, Economy and Environment drop to 0.85×.
• Critical ducking. A Voice or Alert sound at priority ≥ 7 drops the same buses to 0.63×.
• Stacking. Voice and Alert divide by √count, so simultaneous callouts stay intelligible.

Listening presets and the limiter

The bus sum goes through BusLimiter: 3 ms look-ahead, 120 ms release, 6 dB soft knee, hard ceiling 0.79. The preset in the settings menu sets how much it compresses below the ceiling:

Decode-time mastering

Each track is processed once, on the decode worker, when it is loaded:

1. Decode to 32-bit float stereo.
2. Resample to the device rate (48 kHz by default) with a polyphase filter (90 dB stopband).
3. Analyse: integrated loudness, presence and air bands, up to four resonances.
4. Apply the material's profile: loudness gain, spectral tilt, resonance notches, limiter to the ceiling.
5. Music and ambience only: seal the loop with a 0.12 s crossfade (at most 10% of the length), so the wrap does not click.
6. Store a mono file once if both channels are identical, then convert to 16-bit.

The device callback only reads finished tracks through an atomic table; decoding never blocks the caller or the mixer.

Loudness is matched within a category, not across them

The material comes from the category; SFX resources whose ID starts with ui. (or contains .ui. or /ui/) count as Interface.

What this means when authoring a file:

• The level baked into an effect is the design decision. The chain never lifts a quiet effect, so a replacement has to land at the RMS of the file it replaces or the mix changes. import_cues.py and tools/audio_field/battle.py both match RMS for this reason.
• Music has limited authority. The lift is capped at 6 dB and by the headroom under the ceiling, so a track baked much below about −19 LUFS stays quiet for good. import_music.py bakes to −14.1 LUFS at −1 dBTP.
• Beds need headroom. A bed delivered near full scale makes the limiter pull several dB, audible as the bed ducking under itself. The recorded beds are levelled to −19.3 LUFS with peaks held well under full scale.
• Nothing may decode above 0 dBFS. Vorbis overshoots peaks. The build tools measure the decoded file and re-encode at lower gain until it lands under the ceiling.

audio_master_preview (make audio-preview) links the same soi_audio_mastering library, so what it renders to artifacts/audio_preview is what the game plays. scripts/promo-edit.py uses it to score reels with mastered audio.

Packaging

• assets.qrc embeds every sfx/ and voices/ file plus both JSON catalogues.
• Music and ambience are not embedded. install(DIRECTORY assets/) installs them beside the binary, and a player's package always carries them.
• The loader looks for assets/audio/ at <app>/assets/audio, <app>/../Resources/assets/audio (macOS bundle) and <app>/../../assets/audio, then falls back to :/assets/audio/. A file on disk wins over the embedded copy.
• The eight synthesised ambience beds are not committed (.gitignore). The synthesize_ambience_assets target renders them into both assets/audio/ambience and the staged build copy. Without Python or an ffmpeg that writes Vorbis the build warns and those beds are missing at runtime; the game runs without them.

Asset pipelines

tools/audio_synth/README.md and tools/audio_field/README.md cover recipes, takes and window selection in detail.

Rebuild traps

• A recipe can outlive its file. When a cue is replaced by an import, its recipe still names the path. synthesize_cues.py, register_cues.py and build_battle.py therefore read the manifest's source tag and skip any file another pipeline owns (--force overrides the two renderers). Recipes for replaced files were deleted in September 2026; delete a recipe when its file is replaced rather than relying on the guard.
• ffmpeg picks a random Ogg stream serial, so re-encoding an unchanged recipe still changes a few header bytes. Regenerate the cue you are working on, not the set.

After any rebuild, git status assets/audio shows what was actually touched.

Debugging

A trace line reads:

audio cue [30.838s rts -318.9,69.6,-196.4] alert.commander_message -> sfx.alert.commander_message: accepted (app/core/game_engine.cpp:1996)

Time since the trace last reset, listener mode (rts, commander, or none), listener position, cue, the resource the pool chose (- if the drop happened before selection), the outcome, and the call site. The summary's never_accepted list is the cues a mission asked for that the player never heard. A cue never requested does not appear at all, which is what the static report covers.

Throttles are wall-clock and not scoped to a mission: cue cooldowns in CueRegistry and resource cooldowns in AudioSystem carry across restarts, scenarios and tests. CueRegistry::reset_cooldowns() and AudioSystem::reset_playback_throttles() clear them without touching bindings or loaded resources. Sounds outlive a test in the same way: the tails of earlier tests can fill a category, and the next low-priority cue is dropped as category_priority. AudioSystem::stop_all_sounds() silences them; the scenario tests call it in SetUp. Two cues sharing one resource share its cooldown too, and the loser is reported as resource_cooldown.

Checks and tests

Tests: audio_system_test, audio_cues_test, audio_backend_test, audio_command_ring_test, audio_mastering_test, audio_gameplay_scenarios_test (production gameplay paths; clears both throttles in SetUp), command_controller_test (a run order never trumpets without elephants), audio_battle_load_test, ambience_assets_test (every bed at the mixer rate, 2–6 kHz at least 3 dB under 100–800 Hz), weather_audio_test, and the commander_voice_* tests.