Make accidentally dropping OutputStream impossible

Cargo.toml

@@ -27,6 +27,7 @@ tracing = { version = "0.1.40", optional = true }
 
 atomic_float = { version = "1.1.0", optional = true }
 num-rational = "0.4.2"
+drop_bomb = "0.1.5"
 
 [features]
 default = ["playback", "flac", "vorbis", "wav", "mp3"]

examples/automatic_gain_control.rs

@@ -43,5 +43,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     // Keep the program running until the playback is complete.
     sink.sleep_until_end();
+    stream_handle.close();
     Ok(())
 }

examples/basic.rs

@@ -48,5 +48,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     thread::sleep(Duration::from_millis(1500));
 
+    stream_handle.close();
     Ok(())
 }

examples/callback_on_end.rs

@@ -34,5 +34,6 @@ fn main() -> Result<(), Box<dyn Error>> {
         playlist_pos.load(Ordering::Relaxed)
     );
 
+    stream_handle.close();
     Ok(())
 }

examples/custom_config.rs

@@ -31,5 +31,6 @@ fn main() -> Result<(), Box<dyn Error>> {
     println!("Beep...");
     thread::sleep(Duration::from_millis(1500));
 
+    stream_handle.close();
     Ok(())
 }

examples/distortion.rs

@@ -21,5 +21,6 @@ fn main() -> Result<(), Box<dyn Error>> {
     thread::sleep(Duration::from_secs(3));
     println!("Done.");
 
+    stream_handle.close();
     Ok(())
 }

examples/distortion_mp3.rs

@@ -13,5 +13,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     sink.sleep_until_end();
 
+    stream_handle.close();
     Ok(())
 }

examples/distortion_wav.rs

@@ -13,5 +13,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     sink.sleep_until_end();
 
+    stream_handle.close();
     Ok(())
 }

examples/distortion_wav_alternate.rs

@@ -45,5 +45,6 @@ fn main() -> Result<(), Box<dyn Error>> {
     // Wait for playback to finish
     sink.sleep_until_end();
 
+    stream_handle.close();
     Ok(())
 }

examples/error_callback.rs

@@ -37,5 +37,6 @@ fn main() -> Result<(), Box<dyn Error>> {
         eprintln!("Error with stream {}", err);
     }
 
+    stream_handle.close();
     Ok(())
 }

examples/low_pass.rs

@@ -14,5 +14,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     sink.sleep_until_end();
 
+    stream_handle.close();
     Ok(())
 }

examples/mix_multiple_sources.rs

@@ -37,5 +37,6 @@ fn main() -> Result<(), Box<dyn Error>> {
     // Sleep the thread until sink is empty.
     sink.sleep_until_end();
 
+    stream_handle.close();
     Ok(())
 }

examples/music_flac.rs

@@ -9,5 +9,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     sink.sleep_until_end();
 
+    stream_handle.close();
     Ok(())
 }

examples/music_m4a.rs

@@ -9,5 +9,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     sink.sleep_until_end();
 
+    stream_handle.close();
     Ok(())
 }

examples/music_mp3.rs

@@ -9,5 +9,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     sink.sleep_until_end();
 
+    stream_handle.close();
     Ok(())
 }

examples/music_ogg.rs

@@ -9,5 +9,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     sink.sleep_until_end();
 
+    stream_handle.close();
     Ok(())
 }

examples/music_wav.rs

@@ -9,5 +9,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     sink.sleep_until_end();
 
+    stream_handle.close();
     Ok(())
 }

examples/noise_generator.rs

@@ -26,5 +26,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     thread::sleep(interval_duration);
 
+    stream_handle.close();
     Ok(())
 }

examples/reverb.rs

@@ -13,5 +13,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     sink.sleep_until_end();
 
+    stream_handle.close();
     Ok(())
 }

examples/seek_mp3.rs

@@ -20,5 +20,6 @@ fn main() -> Result<(), Box<dyn Error>> {
     sink.try_seek(Duration::from_secs(5))?;
     println!("seek example ended");
 
+    stream_handle.close();
     Ok(())
 }

examples/signal_generator.rs

@@ -67,5 +67,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     thread::sleep(interval_duration);
 
+    stream_handle.close();
     Ok(())
 }

examples/spatial.rs

@@ -56,5 +56,6 @@ fn main() -> Result<(), Box<dyn Error>> {
     }
     sink.sleep_until_end();
 
+    stream_handle.close();
     Ok(())
 }

examples/stereo.rs

@@ -12,5 +12,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     sink.sleep_until_end();
 
+    stream_handle.close();
     Ok(())
 }

src/stream.rs

@@ -11,22 +11,33 @@ use crate::mixer::{mixer, Mixer, MixerSource};
 use crate::sink::Sink;
 use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
 use cpal::{BufferSize, Sample, SampleFormat, StreamConfig};
+use drop_bomb::DropBomb;
 use std::io::{Read, Seek};
 use std::marker::Sync;
 use std::{error, fmt};
 
 const HZ_44100: SampleRate = 44_100;
 
-/// `cpal::Stream` container.
-/// Use `mixer()` method to control output.
-/// If this is dropped, playback will end, and the associated output stream will be disposed.
+/// `cpal::Stream` container. Use `mixer()` method to control output. This
+/// type **can not be dropped**. It will panic and crash your program if
+/// dropped normally. Instead you must call [`OutputStream::close`].
+///
+/// # Panics
+/// This will panic if dropped. Instead call [`OutputStream::close`]
 pub struct OutputStream {
     config: OutputStreamConfig,
     mixer: Mixer,
     _stream: cpal::Stream,
+    bomb: DropBomb,
 }
 
 impl OutputStream {
+    /// Closes the outputstream and drops it whithout panicking. This will
+    /// stop all audio playing through this `OutputStream`.
+    pub fn close(mut self) {
+        self.bomb.defuse();
+    }
+
     /// Access the output stream's mixer.
     pub fn mixer(&self) -> &Mixer {
         &self.mixer
@@ -449,6 +460,11 @@ impl OutputStream {
                 _stream: stream,
                 mixer: controller,
                 config: *config,
+                bomb: DropBomb::new(
+                    "You can not drop an `OutputStream` you \
+                    must call `close` on it instead. \
+                    See the docs for `OutputStream` for more",
+                ),
             })
         })
     }