[add] audio examples and make audio features enabled by default.

Author: vmarcella

demos/audio/Cargo.toml

@@ -8,7 +8,8 @@ publish = false
 lambda-rs = { path = "../../crates/lambda-rs" }
 
 [features]
-default = []
+default = ["audio"]
+audio = ["audio-output-device", "audio-sound-buffer"]
 audio-output-device = ["lambda-rs/audio-output-device"]
 audio-sound-buffer = ["lambda-rs/audio-sound-buffer"]
 audio-sound-buffer-wav = ["lambda-rs/audio-sound-buffer-wav"]

demos/audio/src/bin/.gitkeep

@@ -0,0 +1,75 @@
+#![allow(clippy::needless_return)]
+//! Audio demo that plays the bundled "slash" OGG Vorbis fixture.
+//!
+//! This demo validates that `SoundBuffer` decoding and audio output playback
+//! can be composed together using only the `lambda-rs` API surface.
+
+use std::{
+  sync::{
+    atomic::{
+      AtomicUsize,
+      Ordering,
+    },
+    Arc,
+  },
+  time::Duration,
+};
+
+use lambda::audio::{
+  AudioOutputDeviceBuilder,
+  SoundBuffer,
+};
+
+fn main() {
+  const SLASH_VORBIS_STEREO_48000_OGG: &[u8] = include_bytes!(concat!(
+    env!("CARGO_MANIFEST_DIR"),
+    "/../../crates/lambda-rs-platform/assets/audio/slash_vorbis_stereo_48000.ogg"
+  ));
+
+  let buffer =
+    SoundBuffer::from_ogg_bytes(SLASH_VORBIS_STEREO_48000_OGG).unwrap();
+
+  let cursor = Arc::new(AtomicUsize::new(0));
+  let buffer = Arc::new(buffer);
+
+  let cursor_for_callback = cursor.clone();
+  let buffer_for_callback = buffer.clone();
+
+  let _device = AudioOutputDeviceBuilder::new()
+    .with_label("play-sound")
+    .with_sample_rate(buffer.sample_rate())
+    .with_channels(buffer.channels())
+    .build_with_output_callback(move |writer, _info| {
+      let writer_channels = writer.channels() as usize;
+      let writer_frames = writer.frames();
+
+      writer.clear();
+
+      if writer_channels == 0 {
+        return;
+      }
+
+      let write_samples = writer_frames.saturating_mul(writer_channels);
+      let start =
+        cursor_for_callback.fetch_add(write_samples, Ordering::Relaxed);
+
+      let source_samples = buffer_for_callback.samples();
+
+      for frame in 0..writer_frames {
+        for channel in 0..writer_channels {
+          let sample_index = start
+            .saturating_add(frame.saturating_mul(writer_channels))
+            .saturating_add(channel);
+          let value = source_samples.get(sample_index).copied().unwrap_or(0.0);
+          writer.set_sample(frame, channel, value);
+        }
+      }
+
+      return;
+    })
+    .unwrap();
+
+  std::thread::sleep(Duration::from_secs_f32(buffer.duration_seconds() + 0.20));
+  drop(_device);
+  return;
+}

demos/audio/src/bin/play_sound.rs

@@ -0,0 +1,68 @@
+#![allow(clippy::needless_return)]
+//! Audio output demo that plays a short sine wave tone.
+//!
+//! This demo assumes `lambda-demos-audio` is built with its default features.
+
+use std::{
+  thread,
+  time::Duration,
+};
+
+use lambda::audio::{
+  enumerate_output_devices,
+  AudioOutputDeviceBuilder,
+};
+
+fn main() {
+  let devices = match enumerate_output_devices() {
+    Ok(devices) => devices,
+    Err(error) => {
+      eprintln!("Failed to enumerate audio output devices: {error:?}");
+      return;
+    }
+  };
+
+  println!("Available output devices:");
+  for device in devices {
+    let default_marker = if device.is_default { " (default)" } else { "" };
+    println!("  - {}{default_marker}", device.name);
+  }
+
+  let frequency_hz = 440.0f32;
+  let amplitude = 0.10f32;
+  let mut phase_radians = 0.0f32;
+
+  let device = AudioOutputDeviceBuilder::new()
+    .with_label("sine-wave")
+    .build_with_output_callback(move |writer, callback_info| {
+      let phase_delta = std::f32::consts::TAU * frequency_hz
+        / (callback_info.sample_rate as f32);
+
+      for frame_index in 0..writer.frames() {
+        let sample = (phase_radians.sin()) * amplitude;
+        for channel_index in 0..(writer.channels() as usize) {
+          writer.set_sample(frame_index, channel_index, sample);
+        }
+
+        phase_radians += phase_delta;
+        if phase_radians > std::f32::consts::TAU {
+          phase_radians -= std::f32::consts::TAU;
+        }
+      }
+
+      return;
+    });
+
+  let _device = match device {
+    Ok(device) => device,
+    Err(error) => {
+      eprintln!("Failed to initialize audio output device: {error:?}");
+      return;
+    }
+  };
+
+  println!("Playing 440 Hz sine wave for 2 seconds...");
+  thread::sleep(Duration::from_secs(2));
+  println!("Done.");
+  return;
+}

demos/audio/src/bin/sine_wave.rs

@@ -0,0 +1,74 @@
+#![allow(clippy::needless_return)]
+//! Sound buffer loading demo that decodes a WAV or OGG Vorbis file.
+//!
+//! This demo assumes `lambda-demos-audio` is built with its default features.
+
+use std::path::{
+  Path,
+  PathBuf,
+};
+
+use lambda::audio::{
+  AudioError,
+  SoundBuffer,
+};
+
+fn main() {
+  let path = match parse_path_argument() {
+    Ok(path) => path,
+    Err(message) => {
+      eprintln!("{message}");
+      std::process::exit(2);
+    }
+  };
+
+  let buffer = match load_sound_buffer(&path) {
+    Ok(buffer) => buffer,
+    Err(error) => {
+      eprintln!("failed to load sound buffer: {error}");
+      std::process::exit(1);
+    }
+  };
+
+  println!("path: {}", path.display());
+  println!("sample_rate: {}", buffer.sample_rate());
+  println!("channels: {}", buffer.channels());
+  println!("duration_seconds: {:.3}", buffer.duration_seconds());
+  return;
+}
+
+fn parse_path_argument() -> Result<PathBuf, String> {
+  let mut args = std::env::args_os();
+  let program_name = args
+    .next()
+    .and_then(|value| value.into_string().ok())
+    .unwrap_or_else(|| "sound_buffer".to_string());
+
+  let path = args.next().ok_or_else(|| {
+    return format!("usage: {program_name} <path-to-wav-or-ogg>");
+  })?;
+
+  return Ok(PathBuf::from(path));
+}
+
+fn load_sound_buffer(path: &Path) -> Result<SoundBuffer, AudioError> {
+  let extension = path
+    .extension()
+    .and_then(|value| value.to_str())
+    .map(|value| value.to_ascii_lowercase())
+    .unwrap_or_default();
+
+  match extension.as_str() {
+    "wav" => {
+      return SoundBuffer::from_wav_file(path);
+    }
+    "ogg" | "oga" => {
+      return SoundBuffer::from_ogg_file(path);
+    }
+    _ => {
+      return Err(AudioError::UnsupportedFormat {
+        details: format!("unsupported file extension: {extension:?}"),
+      });
+    }
+  }
+}