> 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/sessions/phase36-session05-sector-theme-audio-pack/spec.md).

# Session Specification

**Session ID**: `phase36-session05-sector-theme-audio-pack` **Phase**: 36 - AI Rogue Audio Asset Finishing **Status**: Not Started **Created**: 2026-06-28

***

## 1. Session Overview

This session ships the actual AI Rogue sector theme ambience pack that Session 04 reserved in the runtime contract. It adds five optimized local Ogg Opus loops, one for each sector theme, so `snapshot.theme` produces audible sector identity while the existing title, depth, victory, and defeat music lane stays unchanged.

This is next because Phase 36 Sessions 01 through 04 completed the balance audit, enemy metadata, enemy/boss SFX pack, and theme ambience routing contract. Session 05 can now focus on asset generation, provenance, media policy evidence, and browser proof instead of redesigning the audio engine.

The product outcome is normal AI Rogue gameplay with distinct but subtle sector ambience. The work must preserve autoplay unlock, mute, music volume, silent fallback, deterministic simulation behavior, browser-local state, public-demo safety, and no remote game-content loading.

***

## 2. Objectives

1. Generate and commit five theme ambience Ogg Opus loops with the exact Session 04 contract basenames.
2. Update music provenance and durable docs so every committed loop has source, render, size, and policy evidence.
3. Prove real runtime loading for all five theme ambience assets through the AI Rogue audio path rather than injected fake URLs.
4. Complete focused automated checks and manual browser review for audible theme identity, failure recovery, mute, music volume, and asset size.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase36-session01-current-audio-balance-audit` - Provides browser-path evidence for current unlock, title, music, SFX, mute, volume, and silent fallback behavior.
* [x] `phase36-session02-enemy-audio-metadata` - Provides the current typed audio metadata precedent and keeps audio presentation-only.
* [x] `phase36-session03-enemy-and-boss-sfx-pack` - Provides the current 57-cue SFX baseline and provenance update pattern.
* [x] `phase36-session04-theme-audio-routing-contract` - Provides the second low-gain ambience lane, theme route IDs, exact basenames, asset location, and 900 KB music-track cap decision.
* [x] `phase35-session10-final-release-gate` - Provides the production default posture, asset checks, public-demo safety boundary, and privacy gate.

### Required Tools Or Knowledge

* Bun 1.3.14 project scripts.
* `ffmpeg` and `ffprobe` for local audio rendering and inspection.
* Existing Web Audio engine behavior in `src/extensions/ai-rogue/runtime/audio.ts`.
* Existing theme contract in `src/extensions/ai-rogue/runtime/themes.ts`.
* Existing browser proof in `tests/e2e/ai-rogue-runtime.spec.ts`.
* Media policy for AI Rogue music and theme ambience in `docs/media-policy.md`.

### Environment Requirements

* Run from the repository root.
* Keep raw masters in gitignored scratch space under `tmp/`.
* Commit only optimized runtime assets and provenance.
* Keep new text artifacts ASCII-only with Unix LF line endings.

***

## 4. Scope

### In Scope (MVP)

* AI Rogue players hear distinct low-gain ambience for `cold-cache`, `corrupted-index`, `kernel-core`, `firewall`, and `model-vault`.
* Five committed files land under `src/assets/ai-rogue/audio/music/`: `theme_cold_cache_ambience.ogg`, `theme_corrupted_index_ambience.ogg`, `theme_kernel_core_ambience.ogg`, `theme_firewall_ambience.ogg`, and `theme_model_vault_ambience.ogg`.
* Theme ambience loops use 48 kHz stereo Ogg Opus, are normalized, loop cleanly, and stay below the 900 KB AI Rogue music-track cap.
* `src/assets/ai-rogue/audio/music/provenance.json` records prompt/source, scratch-path, render, duration, bytes, codec, channel, and sample-rate metadata for the five new loops.
* Browser proof verifies all five real theme ambience files are fetched and started through the runtime audio engine with no injected URL overrides.
* Manual review covers audible identity, fatigue, mute, music volume, autoplay unlock, silent fallback, and load/decode failure behavior.

### Out Of Scope (Deferred)

* Adaptive stingers, ducking, sidechain compression, or transient combat music gain automation - Reason: Sessions 06 and 07 own adaptive music after this asset pack ships.
* Replacing the existing depth/title/victory/defeat music lane - Reason: Session 04 selected ambience beside the existing music lane.
* New Settings UI, saved preference fields, schema migration, or separate ambience volume control - Reason: the ambience lane inherits the existing music volume and master mute contract.
* Remote streaming, CDN loading, hosted writes, collectors, analytics, public demo bridge calls, or public-demo runtime behavior - Reason: Phase 36 requires committed local game media and unchanged safety boundaries.
* Visual asset finishing - Reason: Phase 37 owns visual asset work.

***

## 5. Technical Approach

### Architecture

Use the Session 04 routing contract without changing the audio-engine shape unless real-asset proof exposes a concrete wiring gap. The Vite music asset glob in `audio.ts` already maps the reserved basenames under `src/assets/ai-rogue/audio/music/`, so adding files with the exact names should activate the runtime URL lookup automatically.

Create or update a local generation/optimization path that renders five subtle ambience loops into gitignored scratch files first, then encodes final Ogg Opus assets into the runtime music directory. Use `ffprobe` output and file sizes to populate provenance. If an approved raw generator export already exists in scratch, encode that raw source through the same optimization and provenance path; do not commit raw exports.

Extend browser proof to play every `themeAmbienceForTheme()` route with the real committed URLs. Remove the current test-only two-theme override from the theme asset proof so the e2e checks fail if a committed basename, Vite glob, or decode path drifts.

### Design Patterns

* Contract-first assets: File basenames match the typed Session 04 route IDs.
* Local optimized media: Raw generation stays in `tmp/`; only final Ogg Opus loops and provenance are committed.
* No engine redesign by default: Runtime code changes are limited to concrete issues discovered while proving real assets.
* Silent-safe playback: Missing, failed, or undecodable theme assets remain recoverable no-ops.
* Browser proof over docs-only confidence: All five files must be fetched and source-started through the real Web Audio path.

***

## 6. Deliverables

### Files To Create

| File                                                                                   | Purpose                                                                        | Est. Lines |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------- |
| `scripts/generate-ai-rogue-theme-ambience.ts`                                          | Repeatable local generation and optimization path for the five ambience loops. | \~220      |
| `src/assets/ai-rogue/audio/music/theme_cold_cache_ambience.ogg`                        | Cold Cache coolant ambience loop.                                              | binary     |
| `src/assets/ai-rogue/audio/music/theme_corrupted_index_ambience.ogg`                   | Corrupted Index glitch ambience loop.                                          | binary     |
| `src/assets/ai-rogue/audio/music/theme_kernel_core_ambience.ogg`                       | Kernel Core drive ambience loop.                                               | binary     |
| `src/assets/ai-rogue/audio/music/theme_firewall_ambience.ogg`                          | Firewall alarm ambience loop.                                                  | binary     |
| `src/assets/ai-rogue/audio/music/theme_model_vault_ambience.ogg`                       | Model Vault sub-bass ambience loop.                                            | binary     |
| `.spec_system/specs/phase36-session05-sector-theme-audio-pack/implementation-notes.md` | Record generation, wiring, review, and validation evidence.                    | \~180      |

### Files To Modify

| File                                                                    | Changes                                                                                   | Est. Lines |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------- |
| `src/assets/ai-rogue/audio/music/provenance.json`                       | Add source, render, size, codec, and loop metadata for the five ambience assets.          | \~160      |
| `tests/e2e/ai-rogue-runtime.spec.ts`                                    | Extend browser audio proof to fetch and start all five real theme ambience assets.        | \~80       |
| `src/extensions/ai-rogue/runtime/audio.ts`                              | Adjust only if real committed asset lookup reveals a mapping or export gap.               | \~20       |
| `docs/extensions/ai-rogue/game-feel.md`                                 | Change theme ambience from reserved contract to shipped asset pack with review notes.     | \~60       |
| `docs/media-policy.md`                                                  | Clarify or confirm final theme ambience workflow if render findings require a doc update. | \~20       |
| `.spec_system/PRD/phase_36/session_05_sector_theme_audio_pack.md`       | Record delivered file names, validation evidence, and any non-feature follow-ups.         | \~50       |
| `.spec_system/specs/phase36-session05-sector-theme-audio-pack/tasks.md` | Track implementation progress during the session.                                         | \~60       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Every sector theme has a committed, optimized ambience loop at the Session 04 basename.
* [ ] Starting a run fetches and starts the current theme ambience through the real runtime URL lookup.
* [ ] Descending across all five themes changes ambience while preserving depth music behavior.
* [ ] Mute, music volume, autoplay unlock, silent fallback, and decode/load failure paths continue to recover safely.
* [ ] The product outcome is proven end to end: every actual sector theme is audibly distinct in AI Rogue without changing gameplay rules.

### Testing Requirements

* [ ] Focused audio, adapter, and theme tests remain passing.
* [ ] Browser audio proof covers all five real theme ambience files on desktop and mobile viewports.
* [ ] `ffprobe` verifies final files are Ogg Opus, stereo, 48 kHz, and loop length matches provenance.
* [ ] Asset-size validation passes.
* [ ] Manual browser review findings are recorded.

### Non-Functional Requirements

* [ ] No dependency, lockfile, DB, migration, or persisted browser-state schema change is introduced.
* [ ] No remote game-content loading, hosted write, collector, analytics, public-demo bridge call, or new third-party runtime dependency is added.
* [ ] Every committed audio file has provenance beside the file family.
* [ ] Theme audio remains presentation-only and does not affect simulation decisions, RNG consumption, replay behavior, save contracts, or gameplay balance.

### Quality Gates

* [ ] All touched text files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Primary user-facing surfaces contain product-facing copy only.

***

## 8. Implementation Notes

### Working Assumptions

* The session should ship ambience beds, not replacement theme music loops: Session 04 selected a second low-gain ambience lane and documented replacement theme music as rejected for this phase. Planning can proceed because the selected contract has concrete route IDs, basenames, location, and size cap.
* Runtime mapping changes should be minimal: `audio.ts` already exports `AI_ROGUE_THEME_AMBIENCE_FILE_BASENAMES` and maps the reserved basenames through the music asset glob. Planning can proceed by targeting assets, provenance, and proof first, with runtime edits only if real-file proof finds a concrete gap.
* Local generation is acceptable for this session: `ffmpeg` and `ffprobe` are available in the environment, `tmp/` is gitignored, and the media policy already defines the final Ogg Opus workflow. This avoids requiring credentials or dashboard actions during implementation.

### Conflict Resolutions

* Stub scope versus Session 04 decision: Session 05 says "ambience or music," while Session 04 chose subtle ambience beds and rejected five replacement music loops for this phase. The Session 04 decision wins because it is the completed prerequisite and defines the implemented runtime contract.
* Test override versus real asset proof: Existing e2e coverage proves two injected ambience URLs, not the final committed assets. For this session the real-asset proof wins because the session's value is the committed pack and its Vite/Web Audio lookup.

### Key Considerations

* Keep AI Rogue production default-enabled and preserve the explicit `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` disable path.
* Keep public demo behavior static-only and avoid bridge calls or remote game content.
* Keep client bundle and asset-size headroom visible because Phase 35 recorded tight JS budget and strict media gates.
* Preserve the current theme ambience gain relationship to music volume; do not add a new Settings control.

### Potential Challenges

* Asset fatigue: Keep loops subtle, short enough for size, and low-gain so they do not mask gameplay SFX.
* Seam or click artifacts: Use short fades, inspect with `ffprobe`, and review repeated playback in browser.
* Real-asset test drift: Avoid injected test URLs in the all-theme proof so missing committed files fail clearly.
* Size pressure: Prefer compact ambience beds over full music loops rather than weakening policy.

### Relevant Considerations

* \[P34-P35] **AI Rogue is production default-enabled**: New media must preserve the production default posture and explicit disable path.
* \[P31-P35] **Public-demo and AI Rogue gates stay bundled**: Asset-size, browser, no-remote, and no-bridge checks remain part of runtime media work.
* \[P31-P35] **Pages demo stays static-only**: Theme ambience must not introduce hosted runtime reads, uploads, collectors, analytics, Functions, or writes.
* \[P30/P34-P35] **Route-lazy runtime ownership scales**: Keep audio assets and imports behind the AI Rogue runtime path.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Real committed ambience files may not be found by the Vite music glob.
* Theme loops may mask SFX, ignore mute/music volume expectations, or fatigue during repeated play.
* Asset generation may accidentally commit raw exports, oversized files, or incomplete provenance.

***

## 9. Testing Strategy

### Unit Tests

* Run focused runtime audio, renderer adapter, and theme tests: `bun run test -- src/extensions/ai-rogue/runtime/__tests__/audio.test.ts src/extensions/ai-rogue/runtime/__tests__/renderer-audio-adapter.test.ts src/extensions/ai-rogue/runtime/__tests__/themes.test.ts`
* Add or adjust unit coverage only if real-file proof exposes a mapping gap.

### Integration Tests

* Run the focused browser audio proof: `bunx playwright test tests/e2e/ai-rogue-runtime.spec.ts -g "browser audio pack"`
* Verify both desktop and mobile viewports fetch/start all five theme ambience assets with no page errors or failed requests.

### Runtime Verification

* In browser, start AI Rogue, move through seeded or scripted depths that cover all five themes, and confirm each sector has distinct but restrained ambience.
* Confirm Settings mute and music volume affect the ambience lane.
* Confirm removing Web Audio or forcing decode failure leaves gameplay usable and silent.

### Edge Cases

* Missing or renamed ambience file.
* Failed Ogg fetch or decode.
* Rapid descend across themes.
* Reset, load, victory, defeat, and route destroy while ambience is decoding.
* Muted state and very low music volume before the first unlock.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase36-session04-theme-audio-routing-contract`.
* Depended by: `phase36-session06-adaptive-music-engine-expansion`, `phase36-session07-adaptive-stinger-pack`, and `phase36-session08-final-audio-validation-and-docs`.

***

## Next Steps

Run the `implement` workflow step to begin implementation.


---

# 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/sessions/phase36-session05-sector-theme-audio-pack/spec.md?ask=<question>&goal=<endgoal>
```

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