Build a better game with the right AI prompts.

# Task: Implement the optimized audio and video pipeline

You are a senior game audio programmer, media pipeline engineer, and performance engineer.

Using the existing game's architecture and its audio/video optimization report, implement the optimized media pipeline.

The goal is not simply to compress every file. Classify each asset according to how it is actually used.

## Audio categories

1. Very short critical SFX such as UI clicks, menu sounds, small impacts, confirmations, short footsteps, and short attack sounds. Prioritize extremely low playback latency and low runtime overhead.
2. Frequently repeated gameplay SFX such as footsteps, sword impacts, weapon swings, enemy attacks, and repeated environmental sounds. Optimize repeated playback and avoid creating new audio resources for every event.
3. Medium-length SFX such as explosions, abilities, magical effects, and large weapon impacts. Use compression when it meaningfully reduces storage or download size without unacceptable latency.
4. Voice and dialogue. Prioritize download size, speech quality, and streaming or on-demand playback.
5. Music. Generally compress and stream it instead of fully decoding every track into memory.
6. Ambient and environmental audio. Choose compression, streaming, and caching based on duration and repetition.
7. Cinematic audio. Optimize it with the associated video pipeline.

## Audio rules

- Do not use one format for every sound.
- Use mono for spatialized 3D effects when stereo information is unnecessary.
- Preserve stereo when imaging is important, particularly for music and designed ambience.
- Do not ship unnecessarily high sample rates or 24-bit/32-bit assets.
- Do not load the entire audio library into memory.
- Do not stream extremely short sounds when that increases latency or CPU overhead.
- Stream long-form audio when appropriate.
- Preload only sounds guaranteed to be needed immediately.
- Load less common sounds on demand and release assets that are no longer needed.
- Use asynchronous loading where supported.
- Pool playback objects where the engine benefits from it.
- Avoid excessive creation and destruction of playback objects.
- Implement sensible simultaneous voice limits and sound priorities.
- Virtualize, cull, or drop insignificant distant sounds.
- Aggregate redundant environmental sounds when one layered sound provides the same result.
- Do not sacrifice gameplay-critical audio merely to reduce CPU usage.

## Format guidance

For web delivery, prefer efficient modern compressed audio such as Opus where browser support and the existing pipeline permit it. Consider AAC as a targeted fallback. Use low-latency or uncompressed delivery for extremely short critical sounds only when measurements justify it.

For native mobile, use the engine and platform's recommended compression pipeline. Consider AAC for compatible long-form audio. Keep frequently triggered sounds optimized for low latency.

For video, choose hardware-accelerated codecs and containers supported by each target platform. Keep the audio codec compatible with the video container. Do not introduce a codec that forces software decoding when hardware decoding is available. Provide fallbacks only where compatibility justifies the storage cost.

## Video delivery

- Do not download every video at startup.
- Load video only when required and stream large videos where appropriate.
- Preload only the beginning or required segment when supported.
- Cache frequently reused small videos.
- Release decoded frames and playback resources when no longer needed.
- Match resolution and bitrate to display size and target devices.
- Add quality tiers only when network or device differences require them.
- Respect browser autoplay policies.
- Handle suspended tabs, mobile backgrounding, network failures, interrupted playback, and app lifecycle changes.

## Network and caching

- Use asynchronous requests and the existing CDN where available.
- Use long-lived caching for immutable content-hashed assets.
- Do not repeatedly download the same asset.
- Respect the current versioning and cache-invalidation architecture.
- Do not create a second asset-versioning system when one already exists.

## Fallback behavior

When the preferred format cannot be decoded:

1. Attempt the configured fallback.
2. Log the failure in development builds.
3. Do not crash the game or block unrelated gameplay.
4. Avoid repeatedly attempting a known unsupported format.
5. Cache the successful format decision for the current session where appropriate.

Do not generate fallback files for every asset automatically.

## Preservation requirements

Preserve gameplay behavior, sound timing, spatial audio, mixer and category controls, music transitions, dialogue sequencing, video playback, save data, and unrelated systems. Do not introduce a global media preload.

## Final report

Run relevant tests and profile representative scenes. Report files and assets changed, selected formats, compression settings, preloaded/streamed/on-demand assets, cache behavior, voice limits, pooling, platform differences, fallback behavior, measured download and memory impact, and remaining bottlenecks.

## Player-readable output requirement

Everything shown to a player must be written and presented for a human player, not for a developer or debugger. This includes menus, HUD labels, buttons, prompts, tutorials, objectives, dialogue, tooltips, loading and save states, empty states, confirmations, warnings, errors, rewards, notifications, accessibility messages, and connection or recovery states.

Use concise plain language, the game's established terminology and tone, recognizable icons with text where meaning could be ambiguous, and a clear next action. A player-facing error should explain what happened in useful terms, whether progress is safe, and what the player can do next.

Never expose raw exceptions, stack traces, JSON, database IDs, internal event names, enum or variable names, file paths, debug coordinates, HTTP status codes without explanation, server implementation details, developer TODOs, placeholder text, or raw telemetry on a player-facing surface. Send technical details to development-only logs, diagnostics, telemetry, or an authenticated support view. A short support reference code may be shown to the player only when it helps support locate the private diagnostic record.

Verify representative success, failure, offline, loading, empty, permission, validation, timeout, save, reconnect, and recovery states from the player's perspective. Developer documentation and final engineering reports may remain technical; this requirement applies to anything the game presents to players.

## Required game documentation

Documentation is part of the definition of done for this task.

Before finishing:

1. Read the existing README, docs directory, architecture notes, decision records, and AI instructions that apply to this system.
2. Update the existing relevant documentation instead of creating a competing document or a second source of truth.
3. If no relevant document exists, create a clearly named Markdown document in the game's established documentation directory. Use docs/ when the project has no existing convention.
4. Document the current system, the decisions made, ownership and lifecycle rules, configuration, files or assets changed, commands and tests run, known limitations, and how another developer should extend or troubleshoot the work.
5. Update AI_INSTRUCTIONS.md or the project's equivalent when this task changes architectural boundaries, required workflows, naming rules, or validation commands.
6. Keep documentation accurate to the implementation. Do not claim support, measurements, or test coverage that was not verified.
7. In the final report, list every documentation file created or updated.