feat(lambda-rs): Implement a SoundBuffer with support for decoding wav and ogg files.

[vmarcella]

Summary

Related Issues

• Resolves [Feature] Sound file loading (WAV, OGG) #111

Changes

Add Symphonia wrapper in lambda-rs-platform for WAV and OGG Vorbis decoding

• Add granular feature flags for audio decoding (audio-decode-wav, audio-decode-vorbis, audio-sound-buffer)
• Add comprehensive error types (AudioError) with decode-specific variants
• Add test audio fixtures (WAV: mono/stereo, 16/24/32-bit; OGG: Vorbis stereo)
• Add sound_buffer_load example demonstrating the loading API
• Add play_slash_sound example demonstrating playback integration
• Add lambda_audio tool for testing audio loading and playback
• Update docs/features.md with new audio feature documentation
• Add docs/specs/audio-file-loading.md specification

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• Feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation (updates to docs, specs, tutorials, or comments)
• Refactor (code change that neither fixes a bug nor adds a feature)
• Performance (change that improves performance)
• Test (adding or updating tests)
• Build/CI (changes to build process or CI configuration)

Affected Crates

• lambda-rs
• lambda-rs-platform
• lambda-rs-args
• lambda-rs-logging
• Other: tools/lambda_audio

Checklist

• Code follows the repository style guidelines (cargo +nightly fmt --all)
• Code passes clippy (cargo clippy --workspace --all-targets -- -D warnings)
• Tests pass (cargo test --workspace)
• New code includes appropriate documentation
• Public API changes are documented
• Breaking changes are noted in this PR description

Testing

Commands run:

cargo build --workspace
cargo test --workspace
cargo build -p lambda-rs --no-default-features --features audio-sound-buffer
cargo run --example sound_buffer_load -- <path-to-audio-file>
cargo run --example play_slash_sound
cargo run -p lambda-audio -- --file <path> --format <wav|ogg>

Manual verification steps (if applicable):

1. Verified WAV loading with various bit depths (16-bit, 24-bit, 32-bit float)
2. Verified WAV loading with mono and stereo configurations
3. Verified OGG Vorbis loading with stereo audio
4. Verified error handling for unsupported/invalid files
5. Verified playback integration with play_slash_sound example
6. Verified lambda_audio tool can load and play audio files

Screenshots/Recordings

Platform Testing

• macOS
• Windows
• Linux

Additional Notes

Feature Flag Structure

The new audio features follow the existing feature flag patterns:

lambda-rs:

• audio-sound-buffer-wav - WAV file loading
• audio-sound-buffer-vorbis - OGG Vorbis loading
• audio-sound-buffer - Umbrella for all sound buffer features
• audio - Updated umbrella including output device and sound buffer

lambda-rs-platform:

• audio-decode-wav - Symphonia WAV decoder
• audio-decode-vorbis - Symphonia Vorbis decoder

Supported Formats

WAV:

• Sample formats: 16-bit PCM, 24-bit PCM, 32-bit float
• Channel configurations: Mono, Stereo
• Sample rates: Any standard rate (44100, 48000, etc.)

OGG Vorbis:

• Channel configurations: Mono, Stereo
• Sample rates: Any standard rate

API Design

The SoundBuffer type provides:

• samples() - Access to interleaved f32 PCM data
• sample_rate() - Audio sample rate
• channels() - Number of audio channels
• duration_seconds() - Computed duration
• frame_count() - Number of audio frames

All decoding errors are mapped to AudioError variants without exposing Symphonia internals.

[github-actions]

✅ Coverage Report

📊 View Full HTML Report (download artifact)

Overall Coverage

Metric	Value
Total Line Coverage	45.12%
Lines Covered	5012 / 11107

Changed Files in This PR

File	Coverage	Lines
crates/lambda-rs-platform/src/audio/cpal/device.rs	72.75%	622/855
crates/lambda-rs-platform/src/audio/cpal/mod.rs	N/A	(no coverage data)
crates/lambda-rs-platform/src/audio/mod.rs	N/A	(no coverage data)
crates/lambda-rs-platform/src/audio/symphonia/mod.rs	82.79%	332/401
crates/lambda-rs-platform/src/cpal/mod.rs	N/A	(no coverage data)
crates/lambda-rs-platform/src/lib.rs	N/A	(no coverage data)
crates/lambda-rs/examples/play_slash_sound.rs	N/A	(no coverage data)
crates/lambda-rs/examples/sound_buffer_load.rs	N/A	(no coverage data)
crates/lambda-rs/src/audio/buffer.rs	95.40%	166/174
crates/lambda-rs/src/audio/devices/mod.rs	N/A	(no coverage data)
crates/lambda-rs/src/audio/devices/output.rs	78.07%	178/228
crates/lambda-rs/src/audio/error.rs	100.00%	76/76
crates/lambda-rs/src/audio/mod.rs	N/A	(no coverage data)
crates/lambda-rs/src/lib.rs	N/A	(no coverage data)
tools/lambda_audio/src/lib.rs	86.37%	355/411
tools/lambda_audio/src/main.rs	100.00%	6/6
tools/lambda_audio/tests/cli.rs	N/A	(no coverage data)

PR Files Coverage: 80.66% (1735/2151 lines)

---

Generated by cargo-llvm-cov · Latest main coverage

_{Last updated: 2026-02-04 21:52:43 UTC · Commit: 74ec0a7}

[Copilot]

Pull request overview

This PR implements sound file loading capabilities for the lambda-rs engine by adding a SoundBuffer type that can decode WAV and OGG Vorbis audio files. The implementation uses the Symphonia library wrapped in lambda-rs-platform to keep vendor details out of the public API, following the established pattern for audio device support.

Changes:

• Adds SoundBuffer with methods to load WAV and OGG Vorbis files from disk or memory
• Implements Symphonia wrapper in lambda-rs-platform with granular feature flags (audio-decode-wav, audio-decode-vorbis)
• Adds comprehensive error handling through AudioError variants for decode failures
• Includes test audio fixtures (WAV: mono/stereo, 16/24/32-bit; OGG: Vorbis stereo) stored via Git LFS
• Adds examples (sound_buffer_load, play_slash_sound) and a lambda_audio CLI tool for testing
• Updates documentation including specs and feature guides

Reviewed changes

Copilot reviewed 35 out of 36 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
crates/lambda-rs/src/audio/buffer.rs	Implements public SoundBuffer API with WAV and OGG Vorbis loading methods
crates/lambda-rs/src/audio/error.rs	Extends AudioError with I/O, decode, and format error variants
crates/lambda-rs/src/audio/mod.rs	Restructures audio module to include buffer alongside device APIs
crates/lambda-rs/src/audio/devices/output.rs	Refactors output device code with additional documentation
crates/lambda-rs/Cargo.toml	Adds granular audio-sound-buffer feature flags
crates/lambda-rs-platform/src/audio/symphonia/mod.rs	Implements Symphonia wrapper with format validation and error mapping
crates/lambda-rs-platform/src/audio/cpal/	Moves cpal module under audio/ for better organization
crates/lambda-rs-platform/Cargo.toml	Adds Symphonia dependency with minimal feature set
tools/lambda_audio/	New CLI tool for inspecting and playing audio files
crates/lambda-rs/examples/	Adds sound_buffer_load.rs and play_slash_sound.rs examples
docs/specs/audio-file-loading.md	Comprehensive specification for the SoundBuffer feature
docs/specs/audio-devices.md	Updates device spec with new module paths and error variants
docs/features.md	Documents new audio decode features
.github/workflows/	Updates CI to handle audio dependencies and tool exclusions
.gitattributes	Adds LFS tracking for audio files

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.