From 0144699ad7157df3e54f28a69e826cd62b775e61 Mon Sep 17 00:00:00 2001 From: ugochukwu-850 Date: Fri, 4 Oct 2024 21:05:09 +0100 Subject: [PATCH 1/7] Added documentation for Issues #566 Documented how playback speed mutation works and the effects with examples --- src/source/speed.rs | 52 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 47 insertions(+), 5 deletions(-) diff --git a/src/source/speed.rs b/src/source/speed.rs index d24cb8ac..5f0e288f 100644 --- a/src/source/speed.rs +++ b/src/source/speed.rs @@ -1,3 +1,50 @@ +//! 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 +//! - Update the pos function by multiplying the 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)); +//! +//! // 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)); +//! +//! // 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 +//! This is due to the higher audio data stream increasing the frequency + use std::time::Duration; use crate::{Sample, Source}; @@ -98,11 +145,6 @@ where #[inline] fn try_seek(&mut self, pos: Duration) -> Result<(), SeekError> { - /* TODO: This might be wrong, I do not know how speed achieves its speedup - * so I can not reason about the correctness. - * */ - - // even after 24 hours of playback f32 has enough precision let pos_accounting_for_speedup = pos.mul_f32(self.factor); self.input.try_seek(pos_accounting_for_speedup) } From 20daf244dbebed120ad5a925b4dcc8302c1c1505 Mon Sep 17 00:00:00 2001 From: ugochukwu-850 Date: Fri, 4 Oct 2024 20:52:28 +0100 Subject: [PATCH 2/7] Added Note on the set_speed function of impact on pitch --- src/sink.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/sink.rs b/src/sink.rs index 148a1588..14f612cf 100644 --- a/src/sink.rs +++ b/src/sink.rs @@ -193,6 +193,8 @@ 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 that changing the speed would affect the pitch accordingly** #[inline] pub fn set_speed(&self, value: f32) { *self.controls.speed.lock().unwrap() = value; From f73dbe317da029f2131e43ea7a2288da583b70e5 Mon Sep 17 00:00:00 2001 From: ugochukwu-850 Date: Wed, 9 Oct 2024 13:14:23 +0100 Subject: [PATCH 3/7] Resolved comments --- src/source/speed.rs | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/src/source/speed.rs b/src/source/speed.rs index 05383f4b..f4ece9b8 100644 --- a/src/source/speed.rs +++ b/src/source/speed.rs @@ -6,15 +6,15 @@ //! 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 -//! - Update the pos function by multiplying the position 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}}; +//!# 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 @@ -25,25 +25,23 @@ //! 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)); -//! -//! // 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)); -//! -//! // here is how you would do it using the sink -//! +//! 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)?; +//! 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 -//! This is due to the higher audio data stream increasing the frequency +//! +//! Since the samples are played faster the audio wave get shorter increasing their frequencies use std::time::Duration; From 0b3d49ce088cfbff4b9668fa5fdbfb417247eacf Mon Sep 17 00:00:00 2001 From: ugochukwu-850 Date: Wed, 9 Oct 2024 13:14:23 +0100 Subject: [PATCH 4/7] Removed redundant comment on the speed trait function --- src/source/mod.rs | 5 ----- 1 file changed, 5 deletions(-) diff --git a/src/source/mod.rs b/src/source/mod.rs index bc664bc1..4c37d411 100644 --- a/src/source/mod.rs +++ b/src/source/mod.rs @@ -413,11 +413,6 @@ 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 - /// - /// In order to speed up a source, 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 - /// - Update the pos function by multiplying the position by the factor #[inline] fn speed(self, ratio: f32) -> Speed where From b7b2aad564f148fdcb67c20c984394ad21cb3056 Mon Sep 17 00:00:00 2001 From: ugochukwu-850 Date: Wed, 9 Oct 2024 13:14:23 +0100 Subject: [PATCH 5/7] Removed redundant comment on the speed trait function --- src/source/speed.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/source/speed.rs b/src/source/speed.rs index f4ece9b8..5287883f 100644 --- a/src/source/speed.rs +++ b/src/source/speed.rs @@ -40,7 +40,7 @@ //! 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; From bb341a5634214d0987caea7c32fc07bf1c6090ca Mon Sep 17 00:00:00 2001 From: ugochukwu-850 Date: Wed, 9 Oct 2024 17:59:25 +0100 Subject: [PATCH 6/7] Resolution of comment on source speed documentation I added docs on the effects of changing the speed on both total_duration and pitch on both the source.speed trait and sink set_speed functions . This should help users understand what each function does --- src/source/mod.rs | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/source/mod.rs b/src/source/mod.rs index 4c37d411..5f748e1c 100644 --- a/src/source/mod.rs +++ b/src/source/mod.rs @@ -412,7 +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 + /// + /// 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 where From 5e038a6e5ace074aa9d1bc9fe9bdb12e9570e048 Mon Sep 17 00:00:00 2001 From: ugochukwu-850 Date: Wed, 9 Oct 2024 18:01:34 +0100 Subject: [PATCH 7/7] Resolution of comment on source speed documentation I added docs on the effects of changing the speed on both total_duration and pitch on both the source.speed trait and sink set_speed functions . This should help users understand what each function does --- src/sink.rs | 8 +++++++- src/source/mod.rs | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/src/sink.rs b/src/sink.rs index 6c831c25..1aabd85d 100644 --- a/src/sink.rs +++ b/src/sink.rs @@ -194,7 +194,13 @@ 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 that changing the speed would affect the pitch accordingly** + /// #### 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; diff --git a/src/source/mod.rs b/src/source/mod.rs index 5f748e1c..bbb25d52 100644 --- a/src/source/mod.rs +++ b/src/source/mod.rs @@ -421,7 +421,7 @@ where /// 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