Audio System
Relevant source files
The following files were used as context for generating this wiki page:
The Audio System manages native and browser sound effects, voiced dialogue (speech), and Red Book CD music playback. It interfaces with the Bevy game engine and the Rodio playback library to provide high-fidelity audio reconstruction from original game data. The system operates across several layers, including asset preparation, logic-driven cues, and a shared sample pool for efficient resource management.
Sources: crates/cyrus-audio/Cargo.toml, crates/cyrus-audio/README.md:1-5
System Architecture
The audio system is divided into two primary plugins: SoundPlugin and MusicPlugin. These plugins handle distinct audio categories but share common request and playback-state interfaces. The architecture separates the logical generation of audio cues—found in the game world and scripts—from the physical playback handled by host-specific backends.
The diagram shows how audio requests flow through specific plugins into the underlying playback backend.
Sources: crates/cyrus-audio/README.md:1-5, crates/cyrus-audio/src/music.rs:36-66
Music System
The music system reproduces background tracks from the game CD. It reads Red Book audio tracks defined in the game's .ins (cue sheet) and .gog (image) files. Tracks are started or stopped based on world entry defined in WORLD.INI or specific game states like the book menu or credits.
CD Track Logic
- Track 2: Standard track for the book menu.
- Track Numbers: Positive integers start specific tracks.
- -1 or Missing: Keeps the current track playing.
- 0 or Negative: Stops music playback.
Volume and Gain
The system applies a linear gain rule based on the redbook_volume setting (0..=127). The value is mapped to a gain where 0 is silent and 127 is full level (mapped to twice the value out of 255 for DOSBox parity).
Sources: crates/cyrus-audio/src/music.rs:1-25, crates/cyrus-assets/src/music.rs:107-119
Sound and Effects
Sound effects (SFX) are managed through a sixteen-slot sample pool. This pool handles logical SoundCue objects emitted by scripts or animation systems.
Sample Playback and Panning
Active decoders observe PannedGains, allowing live volume and pan updates without restarting samples. The system retains the original PCM width (8-bit or 16-bit) during preparation and applies specific scalar gain rules during decoding to ensure parity with the original engine.
Surface Remapping
Animation cues utilize SURFACE.INI to remap effect IDs based on the actor's current ground surface.
- Surface 0: Bypasses remapping.
- Known Surfaces: Select the corresponding row in the remapping table.
- Missing State: Remains unsupported.
| Component | Responsibility |
|---|---|
SoundBank | Stores MAIN.SFX metadata and surface remaps. |
Channels | Manages the sixteen-slot shared sample pool. |
Panned | Handles stereo-frame boundaries and gain scaling. |
SoundSettings | Stores SYSTEM.INI audio switches and volumes. |
Sources: crates/cyrus-audio/README.md:7-15, crates/cyrus-audio/src/sound/script.rs:250-290, crates/cyrus-assets/src/sound.rs:8-58
Dialogue and Speech
The speech system handles voiced RTX entries via a DialogueCache. It supports subtitles through text wrapping and manages voice lifetimes based on sample feedback or text length fallbacks.
The sequence diagram illustrates the lifecycle of a dialogue request from script to playback.
Implementation Details
- Preparation: Per-label preparation runs off the update thread on native and via worker cache in browsers.
- Playback: Starts voices at header volume and center pan.
- Subtitles: Uses the installed
REDSELfont for wrapping and presentation.
Sources: crates/cyrus-audio/README.md:85-115, crates/cyrus-audio/src/sound/script.rs:564-610
State Restoration and Snapshots
The Audio System supports session restoration through snapshots. This is critical for maintaining continuity across game loads or browser reloads.
- MusicSnapshot: Retains the current CD track, linear gain, pause state, and decoder progress.
- SamplePlaybackSnapshot: Composes logical sample ownership with specific source-decoder checkpoints.
- Validation: Reconstruction validates source identity and PCM width without immediately starting playback to ensure data integrity.
Sources: crates/cyrus-audio/README.md:17-27, crates/cyrus-audio/src/music.rs:371-415
Summary
The Cyrus Audio System provides a robust framework for reconstructing 1998-era game audio within a modern Rust/Bevy environment. By utilizing shared sample pools, precise PCM width preservation, and dedicated handlers for CD music and dialogue, the system achieves faithful reproduction of the original player experience while leveraging modern hardware capabilities.