Issue#566

src/sink.rs

@@ -193,6 +193,14 @@ impl Sink {
     ///
     /// The value `1.0` is the "normal" speed (unfiltered input). Any value other than `1.0` will
     /// change the play speed of the sound.
+    ///
+    /// #### Note:
+    /// 1. **Increasing the speed would also increase the pitch by the same factor**
+    /// - If you increased set the speed to 0.5,  the frequency would be slower (0.5x the original frequency) .
+    /// - Also if you set the speed to 1.5 the frequency would be faster ( 1.5x the original frequency).
+    /// 2. **Change in the speed would affect your total duration inversely**
+    /// - if you set the speed by 0.5,  your total duration would be (2x the original total duration) longer.
+    /// - Also if you set the speed to 2 the total duration would be (0.5 the original total_duration) shorter
     #[inline]
     pub fn set_speed(&self, value: f32) {
         *self.controls.speed.lock().unwrap() = value;

src/source/mod.rs

@@ -412,6 +412,17 @@ where
     }
 
     /// Changes the play speed of the sound. Does not adjust the samples, only the play speed.
+    ///
+    ///  Creates a [`Speed`] struct that handles the speed control
+    /// #### Note:
+    /// 1. **Increasing the speed would also increase the pitch by the same factor**
+    /// - If you increased set the speed to 0.5,  the frequency would be slower (0.5x the original frequency) .
+    /// - Also if you set the speed to 1.5 the frequency would be faster ( 1.5x the original frequency).
+    /// 2. **Change in the speed would affect your total duration inversely**
+    /// - if you set the speed by 0.5,  your total duration would be (2x the original total duration) longer.
+    /// - Also if you set the speed to 2 the total duration would be (0.5 the original total_duration) shorter
+    ///
+    /// See [`Speed`] for details
     #[inline]
     fn speed(self, ratio: f32) -> Speed<Self>
     where

src/source/speed.rs

@@ -1,3 +1,48 @@
+//! Playback Speed control Module.
+//!
+//! The main concept of this module is the [`Speed`] struct, which
+//! encapsulates playback speed controls of the current sink.
+//!
+//! In order to speed up a sink, the speed struct:
+//! - Increases the current sample rate by the given factor
+//! - Updates the total duration function to cover for the new factor by dividing by the factor
+//! - Updates the try_seek function by multiplying the audio position by the factor
+//!
+//! To speed up a source from sink all you need to do is call the   `set_speed(factor: f32)` function
+//! For example, here is how you speed up your sound by using sink or playing raw
+//!
+//! ```no_run
+//!# use std::fs::File;
+//!# use std::io::BufReader;
+//!# use rodio::{Decoder, Sink, OutputStream, source::{Source, SineWave}};
+//!
+//! // Get an output stream handle to the default physical sound device.
+//! // Note that no sound will be played if _stream is dropped
+//! let (_stream, stream_handle) = OutputStream::try_default().unwrap();
+//! // Load a sound from a file, using a path relative to Cargo.toml
+//! let file = BufReader::new(File::open("examples/music.ogg").unwrap());
+//! // Decode that sound file into a source
+//! let source = Decoder::new(file).unwrap();
+//! // Play the sound directly on the device 2x faster
+//! stream_handle.play_raw(source.convert_samples().speed(2.0));
+
+//! std::thread::sleep(std::time::Duration::from_secs(5));
+//! ```
+//! here is how you would do it using the sink
+//! ```
+//! let source = SineWave::new(440.0)
+//! .take_duration(Duration::from_secs_f32(20.25))
+//! .amplify(0.20);
+//!
+//! let sink = Sink::try_new(&stream_handle)?;
+//! sink.set_speed(2.0);
+//! sink.append(source);
+//! std::thread::sleep(std::time::Duration::from_secs(5));
+//! ```
+//! Notice the increase in pitch as the factor increases
+//!
+//! Since the samples are played faster the audio wave get shorter increasing their frequencies
+
 use std::time::Duration;
 
 use crate::{Sample, Source};