UPdate documentation

Add an example for rodio::play()
Remove experimental API from rustdocs.

src/lib.rs

@@ -38,6 +38,26 @@
 //! // so we need to keep the main thread alive while it's playing.
 //! std::thread::sleep(std::time::Duration::from_secs(5));
 //! ```
+//! You can use [rodio::play()] to do the above
+//! ```no_run
+//! use std::fs::File;
+//! use std::io::BufReader;
+//! use rodio::{Decoder, OutputStream, source::Source};
+//!
+//! // Get an output stream handle to the default physical sound device.
+//! // Note that no sound will be played if _stream is dropped
+//! let stream_handle = rodio::OutputStreamBuilder::try_default_stream()
+//!         .expect("open default audio stream");
+//!
+//! // Load a sound from a file, using a path relative to Cargo.toml
+//! let file = BufReader::new(File::open("examples/music.ogg").unwrap());
+//! rodio::play(&stream_handle.mixer(), file).unwrap();
+//!
+//! // The sound plays in a separate audio thread,
+//! // so we need to keep the main thread alive while it's playing.
+//! std::thread::sleep(std::time::Duration::from_secs(5));
+//! ```
+//!
 //!
 //! ## Sink
 //!

src/source/mod.rs

@@ -310,20 +310,9 @@ where
     ///
     /// let agc_source = source.automatic_gain_control(1.0, 4.0, 0.005, 5.0);
     ///
-    /// // Get a handle to control the AGC's enabled state (optional)
-    /// #[cfg(feature = "experimental")]
-    /// {
-    ///     let agc_control = agc_source.get_agc_control();
+    /// // Add the AGC-controlled source to the sink
+    /// sink.append(agc_source);
     ///
-    ///     // You can toggle AGC on/off at any time (optional)
-    ///     agc_control.store(false, std::sync::atomic::Ordering::Relaxed);
-    ///
-    ///     // Add the AGC-controlled source to the sink    
-    ///     sink.append(agc_source);
-    /// }
-    ///
-    /// // Note: Using agc_control is optional. If you don't need to toggle AGC,
-    /// // you can simply use the agc_source directly without getting agc_control.
     /// ```
     #[inline]
     fn automatic_gain_control(

src/spatial_sink.rs

@@ -5,7 +5,7 @@ use std::time::Duration;
 use cpal::FromSample;
 
 use crate::dynamic_mixer::Mixer;
-use crate::source::Spatial;
+use crate::source::{SeekError, Spatial};
 use crate::{Sample, Sink, Source};
 
 /// A sink that allows changing the position of the source and the listeners

src/stream.rs

@@ -183,12 +183,12 @@ fn clamp_supported_buffer_size(
 }
 
 /// Plays a sound once. Returns a `Sink` that can be used to control the sound.
-pub fn play<R>(stream: &Mixer<f32>, input: R) -> Result<Sink, PlayError>
+pub fn play<R>(mixer: &Mixer<f32>, input: R) -> Result<Sink, PlayError>
 where
     R: Read + Seek + Send + Sync + 'static,
 {
     let input = decoder::Decoder::new(input)?;
-    let sink = Sink::connect_new(stream);
+    let sink = Sink::connect_new(mixer);
     sink.append(input);
     Ok(sink)
 }