Ash Audio

A lightweight, modular audio stack for Rust games, targeting Tier 1 needs (indie & AA). It focuses on clarity, extensibility, and fast iteration while leaving room to evolve into AAA-level features in Tier 2.

Features

• Modular architecture – separate crates/modules for backend, voices, buses, mix states, codecs, and spatial helpers.
• CPAL backend – cross-platform output via cpal 0.16.
• Codec registry – decode WAV (hound), OGG (lewton), and FLAC (claxon) out of the box.
• Simple voice management – 64 concurrent voices with basic priority/eviction.
• Bus + mix state system – master/music/sfx/dialog/ui buses with state presets (menu/gameplay/paused/custom).
• Basic spatial audio – stereo panning + distance attenuation helpers with Vec3 math.
• Optional ECS hooks – archetype_ecs integration feature flag to wire the manager into entity systems.
• Examples & tests – runnable examples and integration/codec tests for validation.

Installation

[dependencies]
ash_audio = { version = "0.1.1", features = ["archetype-ecs"] } # optional features

• Requires Rust 1.74+ (Edition 2021) and a platform supported by CPAL.
• Disable archetype-ecs if you just need the runtime manager.

Quick Start

use ash_audio::prelude::*;

fn main() -> Result<()> {
    let mut manager = AudioManager::new()?;

    // Either load from disk or from memory.
    manager.play_sound("assets/music.ogg", "music")?;

    manager.set_mix_state("gameplay")?;
    println!("Active voices: {}", manager.active_voices());

    Ok(())
}

Working with Buses & Mix States

let mut manager = AudioManager::new()?;
manager.set_bus_volume("sfx", 0.5)?;
manager.set_mix_state("paused")?; // applies preset volumes (dialog louder, music ducked)

Spatial Audio Helpers

use ash_audio::types::Vec3;

let mut manager = AudioManager::new()?;
manager.set_listener_position(Vec3::new(0.0, 0.0, 0.0));
manager.set_listener_forward(Vec3::new(0.0, 0.0, 1.0));

let handle = manager.play_sound("assets/ambient.wav", "sfx")?;
manager.set_sound_position(handle, Vec3::new(5.0, 0.0, 2.0))?;

Project Layout

src/
  audio_manager.rs     # High-level API
  backend/             # Backend trait + CPAL implementation
  bus/                 # Bus structs + manager
  codec/               # WAV/OGG/FLAC decoders + registry
  mix_state/           # Mix state definitions + manager
  spatial/             # Stereo helpers
  voice/               # Voice handles + manager
examples/
  basic_playback.rs
  mix_states.rs
  spatial_audio.rs
tests/
  integration_tests.rs
  codec_tests.rs

Examples

Run any example with cargo:

cargo run --example basic_playback
cargo run --example mix_states
cargo run --example spatial_audio

Provide your own audio assets under assets/ (paths referenced inside each example).

Testing & Lints

cargo fmt --all
cargo clippy --all-targets --all-features
cargo test --all-features

Codec tests synthesize WAV buffers, so no external data is required.

Roadmap

1. Tier 1 polish – richer error messages, streaming, looping, per-voice envelopes.
2. Tier 2 – virtualization, advanced DSP graph, convolution effects, asset hot-reload.
3. Engine adapters – ready-made glue for Bevy, Godot, Unity/Unreal plugins.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Made with ❤️ by Saptak Santra and contributors.