feat(lambda-rs): Add audio device enumeration & playback

[vmarcella]

Summary

This PR introduces a new audio output device API to lambda-rs, enabling applications to enumerate audio output devices and play audio through callbacks. All backend-specific code is encapsulated in lambda-rs-platform. This API is still in very early phases but will be used as the foundation to build out other audio capabilities in lambda.

Related Issues

Changes

• Add cpal (v0.17.1) as a dependency in lambda-rs-platform for cross-platform audio support
• Implement platform-level audio device enumeration and stream creation in lambda-rs-platform::cpal
• Add application-facing audio module to lambda-rs with:
  • AudioOutputDevice handle for managing audio playback
  • AudioOutputDeviceBuilder for configuring and creating output devices
  • enumerate_output_devices() function for discovering available audio endpoints
  • AudioOutputWriter for writing samples in output callbacks
  • AudioCallbackInfo for providing stream configuration to callbacks
  • AudioError for actionable error reporting
• Add audio_sine_wave example demonstrating audio playback with a 440 Hz tone
• Add comprehensive specification document (docs/specs/audio-devices.md)
• Update docs/features.md with audio-related Cargo feature documentation

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:

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 run -p lambda-rs --example audio_sine_wave --features audio-output-device

Manual verification steps (if applicable):

1. Run the audio_sine_wave example to verify that an audible tone plays for 2 seconds
2. Verify device enumeration lists available system audio outputs with correct default marking

Screenshots/Recordings

N/A - Audio feature, verified by audible output.

Platform Testing

• macOS
• Windows
• Linux

Additional Notes

New Cargo Features

This PR introduces the following Cargo features:

Feature	Crate	Default	Description
audio-output-device	lambda-rs	Yes	Enables audio output device enumeration and playback
audio-cpal	lambda-rs-platform	No	Internal cpal backend (activated by audio-output-device)

API Overview

// Enumerate available output devices
let devices = enumerate_output_devices()?;

// Build and play audio through the default device
let device = AudioOutputDeviceBuilder::new()
    .with_label("my_app")
    .with_sample_rate(48000)
    .with_channels(2)
    .build_with_output_callback(|writer, info| {
        // Write audio samples here
    })?;

[Copilot]

Pull request overview

Adds an initial, backend-agnostic audio output device API to lambda-rs (with a cpal-backed implementation in lambda-rs-platform), plus documentation and an example to validate audible playback.

Changes:

• Introduces lambda::audio facade API (device enumeration + callback-based playback) behind new audio features.
• Implements lambda_platform::cpal backend (device discovery, stream config selection, stream creation).
• Adds specs/docs and an audio_sine_wave example; updates feature documentation and locks new deps.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/specs/audio-devices.md	New spec defining the audio device abstraction, API surface, rules, and requirements.
docs/features.md	Documents new audio-related Cargo features and defaults.
crates/lambda-rs/src/lib.rs	Exposes audio module behind audio-output-device feature.
crates/lambda-rs/src/audio.rs	New public audio facade types + builder + enumeration function mapping to platform layer.
crates/lambda-rs/examples/audio_sine_wave.rs	Example demonstrating enumeration + 440 Hz tone playback via callback.
crates/lambda-rs/Cargo.toml	Adds audio features and enables audio by default via default = ["with-wgpu", "audio"].
crates/lambda-rs-platform/src/lib.rs	Exposes internal cpal module behind audio-device feature.
crates/lambda-rs-platform/src/cpal/mod.rs	New module re-exporting internal audio backend surface.
crates/lambda-rs-platform/src/cpal/device.rs	Core cpal-backed implementation: config selection, stream creation, enumeration, writer semantics, tests.
crates/lambda-rs-platform/Cargo.toml	Adds optional cpal = "=0.17.1" dep and feature gates (audio-device, audio).
Cargo.lock	Locks new transitive dependencies introduced by cpal.

---

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

[Copilot]

The stream error callback passed to build_output_stream currently ignores all runtime stream errors (|_error| { return; }), which drops potentially important diagnostics (underruns, device disconnects, etc.). Please log these errors (e.g., via logging::error!) and consider incorporating the builder label to identify the stream/device in the message. Apply this consistently to all build_output_stream invocations in this module.