Use builder to init output stream

examples/automatic_gain_control.rs

@@ -8,8 +8,9 @@ use std::thread;
 use std::time::Duration;
 
 fn main() {
-    let (_stream, handle) = rodio::OutputStream::try_default().unwrap();
-    let sink = rodio::Sink::try_new(&handle).unwrap();
+    let stream_handle =
+        rodio::OutputStreamBuilder::try_default_stream().expect("open default audio stream");
+    let sink = rodio::Sink::connect_new(&stream_handle.mixer());
 
     // Decode the sound file into a source
     let file = BufReader::new(File::open("assets/music.flac").unwrap());
@@ -24,14 +25,15 @@ fn main() {
     let agc_enabled = Arc::new(AtomicBool::new(true));
     let agc_enabled_clone = agc_enabled.clone();
     let controlled = agc_source.periodic_access(Duration::from_millis(5), move |agc_source| {
+        #[cfg(not(feature = "experimental"))]
         agc_source.set_enabled(agc_enabled_clone.load(Ordering::Relaxed));
     });
 
     // Add the source now equipped with automatic gain control and controlled via
-    // periodic_access to the sink for playback
+    // periodic_access to the sink for the playback.
     sink.append(controlled);
 
-    // after 5 seconds of playback disable automatic gain control using the
+    // After 5 seconds of playback disable automatic gain control using the
     // shared AtomicBool `agc_enabled`. You could do this from another part
     // of the program since `agc_enabled` is of type Arc<AtomicBool> which
     // is freely clone-able and move-able.
@@ -41,6 +43,6 @@ fn main() {
     thread::sleep(Duration::from_secs(5));
     agc_enabled.store(false, Ordering::Relaxed);
 
-    // Keep the program running until playback is complete
+    // Keep the program running until the playback is complete.
     sink.sleep_until_end();
 }

examples/basic.rs

@@ -1,30 +1,46 @@
+use rodio::source::SineWave;
+use rodio::Source;
 use std::io::BufReader;
 use std::thread;
 use std::time::Duration;
+#[cfg(feature = "tracing")]
+use tracing;
 
 fn main() {
-    let (_stream, stream_handle) = rodio::OutputStream::try_default().unwrap();
-
-    let file = std::fs::File::open("assets/beep.wav").unwrap();
-    let beep1 = stream_handle.play_once(BufReader::new(file)).unwrap();
-    beep1.set_volume(0.2);
+    let stream_handle =
+        rodio::OutputStreamBuilder::try_default_stream().expect("open default audio stream");
+    let mixer = stream_handle.mixer();
+
+    let beep1 = {
+        // Play a WAV file.
+        let file = std::fs::File::open("assets/beep.wav").unwrap();
+        let sink = rodio::play(&mixer, BufReader::new(file)).unwrap();
+        sink.set_volume(0.2);
+        sink
+    };
     println!("Started beep1");
-
     thread::sleep(Duration::from_millis(1500));
 
-    let file = std::fs::File::open("assets/beep2.wav").unwrap();
-    let beep2 = stream_handle.play_once(BufReader::new(file)).unwrap();
-    beep2.set_volume(0.3);
-    beep2.detach();
+    {
+        // Generate sine wave.
+        let wave = SineWave::new(740.0)
+            .amplify(0.2)
+            .take_duration(Duration::from_secs(3));
+        mixer.add(wave);
+    }
     println!("Started beep2");
-
     thread::sleep(Duration::from_millis(1500));
-    let file = std::fs::File::open("assets/beep3.ogg").unwrap();
-    let beep3 = stream_handle.play_once(file).unwrap();
-    beep3.set_volume(0.2);
-    println!("Started beep3");
 
+    let beep3 = {
+        // Play an OGG file.
+        let file = std::fs::File::open("assets/beep3.ogg").unwrap();
+        let sink = rodio::play(&mixer, BufReader::new(file)).unwrap();
+        sink.set_volume(0.2);
+        sink
+    };
+    println!("Started beep3");
     thread::sleep(Duration::from_millis(1500));
+
     drop(beep1);
     println!("Stopped beep1");
 

examples/mix_multiple_sources.rs

@@ -1,12 +1,13 @@
+use rodio::mixer;
 use rodio::source::{SineWave, Source};
-use rodio::{dynamic_mixer, OutputStream, Sink};
 use std::time::Duration;
 
 fn main() {
     // Construct a dynamic controller and mixer, stream_handle, and sink.
-    let (controller, mixer) = dynamic_mixer::mixer::<f32>(2, 44_100);
-    let (_stream, stream_handle) = OutputStream::try_default().unwrap();
-    let sink = Sink::try_new(&stream_handle).unwrap();
+    let (controller, mixer) = mixer::mixer::<f32>(2, 44_100);
+    let stream_handle =
+        rodio::OutputStreamBuilder::try_default_stream().expect("open default audio stream");
+    let sink = rodio::Sink::connect_new(&stream_handle.mixer());
 
     // Create four unique sources. The frequencies used here correspond
     // notes in the key of C and in octave 4: C4, or middle C on a piano,

examples/music_flac.rs

@@ -1,8 +1,9 @@
 use std::io::BufReader;
 
 fn main() {
-    let (_stream, handle) = rodio::OutputStream::try_default().unwrap();
-    let sink = rodio::Sink::try_new(&handle).unwrap();
+    let stream_handle =
+        rodio::OutputStreamBuilder::try_default_stream().expect("open default audio stream");
+    let sink = rodio::Sink::connect_new(&stream_handle.mixer());
 
     let file = std::fs::File::open("assets/music.flac").unwrap();
     sink.append(rodio::Decoder::new(BufReader::new(file)).unwrap());

examples/music_m4a.rs

@@ -1,8 +1,9 @@
 use std::io::BufReader;
 
 fn main() {
-    let (_stream, handle) = rodio::OutputStream::try_default().unwrap();
-    let sink = rodio::Sink::try_new(&handle).unwrap();
+    let stream_handle =
+        rodio::OutputStreamBuilder::try_default_stream().expect("open default audio stream");
+    let sink = rodio::Sink::connect_new(&stream_handle.mixer());
 
     let file = std::fs::File::open("assets/music.m4a").unwrap();
     sink.append(rodio::Decoder::new(BufReader::new(file)).unwrap());

examples/music_mp3.rs

@@ -1,8 +1,9 @@
 use std::io::BufReader;
 
 fn main() {
-    let (_stream, handle) = rodio::OutputStream::try_default().unwrap();
-    let sink = rodio::Sink::try_new(&handle).unwrap();
+    let stream_handle =
+        rodio::OutputStreamBuilder::try_default_stream().expect("open default audio stream");
+    let sink = rodio::Sink::connect_new(&stream_handle.mixer());
 
     let file = std::fs::File::open("assets/music.mp3").unwrap();
     sink.append(rodio::Decoder::new(BufReader::new(file)).unwrap());

examples/music_ogg.rs

@@ -1,8 +1,9 @@
 use std::io::BufReader;
 
 fn main() {
-    let (_stream, handle) = rodio::OutputStream::try_default().unwrap();
-    let sink = rodio::Sink::try_new(&handle).unwrap();
+    let stream_handle =
+        rodio::OutputStreamBuilder::try_default_stream().expect("open default audio stream");
+    let sink = rodio::Sink::connect_new(&stream_handle.mixer());
 
     let file = std::fs::File::open("assets/music.ogg").unwrap();
     sink.append(rodio::Decoder::new(BufReader::new(file)).unwrap());

examples/music_wav.rs

@@ -1,8 +1,9 @@
 use std::io::BufReader;
 
 fn main() {
-    let (_stream, handle) = rodio::OutputStream::try_default().unwrap();
-    let sink = rodio::Sink::try_new(&handle).unwrap();
+    let stream_handle =
+        rodio::OutputStreamBuilder::try_default_stream().expect("open default audio stream");
+    let sink = rodio::Sink::connect_new(&stream_handle.mixer());
 
     let file = std::fs::File::open("assets/music.wav").unwrap();
     sink.append(rodio::Decoder::new(BufReader::new(file)).unwrap());

examples/noise_generator.rs

@@ -6,29 +6,26 @@ fn main() {
     use std::thread;
     use std::time::Duration;
 
-    let (_stream, stream_handle) = rodio::OutputStream::try_default().unwrap();
+    let stream_handle =
+        rodio::OutputStreamBuilder::try_default_stream().expect("open default audio stream");
 
     let noise_duration = Duration::from_millis(1000);
     let interval_duration = Duration::from_millis(1500);
 
-    stream_handle
-        .play_raw(
-            white(cpal::SampleRate(48000))
-                .amplify(0.1)
-                .take_duration(noise_duration),
-        )
-        .unwrap();
+    stream_handle.mixer().add(
+        white(cpal::SampleRate(48000))
+            .amplify(0.1)
+            .take_duration(noise_duration),
+    );
     println!("Playing white noise");
 
     thread::sleep(interval_duration);
 
-    stream_handle
-        .play_raw(
-            pink(cpal::SampleRate(48000))
-                .amplify(0.1)
-                .take_duration(noise_duration),
-        )
-        .unwrap();
+    stream_handle.mixer().add(
+        pink(cpal::SampleRate(48000))
+            .amplify(0.1)
+            .take_duration(noise_duration),
+    );
     println!("Playing pink noise");
 
     thread::sleep(interval_duration);

examples/reverb.rs

@@ -3,8 +3,9 @@ use std::io::BufReader;
 use std::time::Duration;
 
 fn main() {
-    let (_stream, handle) = rodio::OutputStream::try_default().unwrap();
-    let sink = rodio::Sink::try_new(&handle).unwrap();
+    let stream_handle =
+        rodio::OutputStreamBuilder::try_default_stream().expect("open default audio stream");
+    let sink = rodio::Sink::connect_new(&stream_handle.mixer());
 
     let file = std::fs::File::open("assets/music.ogg").unwrap();
     let source = rodio::Decoder::new(BufReader::new(file)).unwrap();

examples/seek_mp3.rs

@@ -2,8 +2,9 @@ use std::io::BufReader;
 use std::time::Duration;
 
 fn main() {
-    let (_stream, handle) = rodio::OutputStream::try_default().unwrap();
-    let sink = rodio::Sink::try_new(&handle).unwrap();
+    let stream_handle =
+        rodio::OutputStreamBuilder::try_default_stream().expect("open default audio stream");
+    let sink = rodio::Sink::connect_new(&stream_handle.mixer());
 
     let file = std::fs::File::open("assets/music.mp3").unwrap();
     sink.append(rodio::Decoder::new(BufReader::new(file)).unwrap());
@@ -16,7 +17,7 @@ fn main() {
 
     sink.sleep_until_end();
 
-    // wont do anything since the sound has ended already
+    // This doesn't do anything since the sound has ended already.
     sink.try_seek(Duration::from_secs(5)).unwrap();
     println!("seek example ended");
 }

examples/signal_generator.rs

@@ -5,79 +5,64 @@ fn main() {
     use std::thread;
     use std::time::Duration;
 
-    let (_stream, stream_handle) = rodio::OutputStream::try_default().unwrap();
+    let stream_handle =
+        rodio::OutputStreamBuilder::try_default_stream().expect("open default audio stream");
 
     let test_signal_duration = Duration::from_millis(1000);
     let interval_duration = Duration::from_millis(1500);
+    let sample_rate = cpal::SampleRate(48000);
 
     println!("Playing 1000 Hz tone");
-    stream_handle
-        .play_raw(
-            SignalGenerator::new(cpal::SampleRate(48000), 1000.0, Function::Sine)
-                .amplify(0.1)
-                .take_duration(test_signal_duration),
-        )
-        .unwrap();
+    stream_handle.mixer().add(
+        SignalGenerator::new(sample_rate, 1000.0, Function::Sine)
+            .amplify(0.1)
+            .take_duration(test_signal_duration),
+    );
 
     thread::sleep(interval_duration);
 
     println!("Playing 10,000 Hz tone");
-    stream_handle
-        .play_raw(
-            SignalGenerator::new(cpal::SampleRate(48000), 10000.0, Function::Sine)
-                .amplify(0.1)
-                .take_duration(test_signal_duration),
-        )
-        .unwrap();
+    stream_handle.mixer().add(
+        SignalGenerator::new(sample_rate, 10000.0, Function::Sine)
+            .amplify(0.1)
+            .take_duration(test_signal_duration),
+    );
 
     thread::sleep(interval_duration);
 
     println!("Playing 440 Hz Triangle Wave");
-    stream_handle
-        .play_raw(
-            SignalGenerator::new(cpal::SampleRate(48000), 440.0, Function::Triangle)
-                .amplify(0.1)
-                .take_duration(test_signal_duration),
-        )
-        .unwrap();
+    stream_handle.mixer().add(
+        SignalGenerator::new(sample_rate, 440.0, Function::Triangle)
+            .amplify(0.1)
+            .take_duration(test_signal_duration),
+    );
 
     thread::sleep(interval_duration);
 
     println!("Playing 440 Hz Sawtooth Wave");
-    stream_handle
-        .play_raw(
-            SignalGenerator::new(cpal::SampleRate(48000), 440.0, Function::Sawtooth)
-                .amplify(0.1)
-                .take_duration(test_signal_duration),
-        )
-        .unwrap();
+    stream_handle.mixer().add(
+        SignalGenerator::new(sample_rate, 440.0, Function::Sawtooth)
+            .amplify(0.1)
+            .take_duration(test_signal_duration),
+    );
 
     thread::sleep(interval_duration);
 
     println!("Playing 440 Hz Square Wave");
-    stream_handle
-        .play_raw(
-            SignalGenerator::new(cpal::SampleRate(48000), 440.0, Function::Square)
-                .amplify(0.1)
-                .take_duration(test_signal_duration),
-        )
-        .unwrap();
+    stream_handle.mixer().add(
+        SignalGenerator::new(sample_rate, 440.0, Function::Square)
+            .amplify(0.1)
+            .take_duration(test_signal_duration),
+    );
 
     thread::sleep(interval_duration);
 
     println!("Playing 20-10000 Hz Sweep");
-    stream_handle
-        .play_raw(
-            chirp(
-                cpal::SampleRate(48000),
-                20.0,
-                10000.0,
-                Duration::from_secs(1),
-            )
+    stream_handle.mixer().add(
+        chirp(sample_rate, 20.0, 10000.0, Duration::from_secs(1))
             .amplify(0.1)
             .take_duration(test_signal_duration),
-        )
-        .unwrap();
+    );
 
     thread::sleep(interval_duration);
 }

examples/spatial.rs

@@ -18,9 +18,16 @@ fn main() {
 
     let total_duration = iter_duration * 2 * repeats;
 
-    let (_stream, handle) = rodio::OutputStream::try_default().unwrap();
+    let stream_handle =
+        rodio::OutputStreamBuilder::try_default_stream().expect("open default audio stream");
+
     let mut positions = ([0., 0., 0.], [-1., 0., 0.], [1., 0., 0.]);
-    let sink = rodio::SpatialSink::try_new(&handle, positions.0, positions.1, positions.2).unwrap();
+    let sink = rodio::SpatialSink::connect_new(
+        &stream_handle.mixer(),
+        positions.0,
+        positions.1,
+        positions.2,
+    );
 
     let file = std::fs::File::open("assets/music.ogg").unwrap();
     let source = rodio::Decoder::new(BufReader::new(file))