> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_36/session_04_theme_audio_routing_contract.md). # Session 04: Theme Audio Routing Contract **Session ID**: `phase36-session04-theme-audio-routing-contract` **Status**: Complete **Estimated Tasks**: 19 **Estimated Duration**: 2-4 hours **Completed**: 2026-06-28 *** ## Objective Define and implement the runtime contract for theme-aware ambience keyed by sector theme while preserving existing depth, title, victory, and defeat music. *** ## Scope ### In Scope (MVP) * Use existing depth music plus a new low-gain theme ambience layer. * Add routing keyed by `snapshot.theme` through theme, snapshot, and renderer audio adapter boundaries. * Document bus, volume, mute, fallback, autoplay unlock, and media-size behavior for theme audio. * Add tests for theme-to-audio selection and fallback behavior. ### Out of Scope * Generating the final five theme ambience audio files. * Adding adaptive stingers or combat music transitions. *** ## Prerequisites * [x] Session 01 balance findings are available. * [x] Current `themes.ts`, snapshot, and audio adapter behavior are understood. *** ## Deliverables 1. Theme-audio routing contract in runtime code and docs. 2. Tests covering theme selection and fallback behavior. 3. Media-policy note for the selected asset type and location. *** ## Success Criteria * [x] Theme routing can choose audio by `snapshot.theme` without breaking depth music, victory, defeat, mute, volume, autoplay unlock, or silent fallback. * [x] Docs state where theme audio assets live and which size policy applies. * [x] Existing audio and runtime tests pass. * [x] The product outcome is proven end to end: changing sector theme changes the selected audio route in AI Rogue, old depth/victory/defeat paths still recover safely, and tests cover fallback behavior. ## Folded Source Detail Routed To This Session ## Current Routing Decision Session 04 implements Option 2: keep the existing title, depth, victory, and defeat primary music lane, then add a second low-gain theme ambience lane keyed by `snapshot.theme`. The reserved route IDs and future file basenames are: * `theme_cold_cache_ambience` * `theme_corrupted_index_ambience` * `theme_kernel_core_ambience` * `theme_firewall_ambience` * `theme_model_vault_ambience` Theme ambience uses the existing master mute and music volume preferences. It does not add a Settings control, save field, schema migration, remote loading, collector, analytics path, or public-demo bridge call. The final five ambience loop files are not shipped in this session. Session 05 should add optimized Ogg Opus loops under `src/assets/ai-rogue/audio/music/` with provenance and the AI Rogue music-track 900 KB per-track cap. ### Source Findings Owned * A4 says `runtime/themes.ts` defines five `audioHint` values. * A4 says `musicTrackForDepth()` maps depth 1, 2, and 3+ to only three sector tracks. * A4 says victory and defeat have one non-looping track each. * A4 says sector themes need theme-aware music or ambience. * A7 says theme ID may be needed for ambience or music routing. * Batch 4 starts with theme-to-audio routing keyed by `snapshot.theme`. ### Contract Decision * Selected: three existing depth music loops plus five subtle ambience beds on a second ambience lane. * Rejected for this phase: five replacement theme-specific music loops, because they would disrupt the already validated title, depth, victory, and defeat music behavior and increase the media budget. ### Required Contract Details * Routing uses an ambience layer keyed by `snapshot.theme`. * Which bus owns theme audio. * How theme audio interacts with depth music, title, victory, defeat, heartbeat, mute, music volume, SFX volume, autoplay unlock, and silent fallback. * Where theme assets live. * Which size policy applies when adding long ambience loops outside `audio/music`. ### Constraints * Avoid remote streaming or runtime downloads. * Do not weaken media policy to make routing easier. * Keep theme audio presentation-only; it must not alter gameplay rules. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_36/session_04_theme_audio_routing_contract.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.