adds more details to track_position/get_pos docs

Author: dvdsk

src/sink.rs

@@ -121,7 +121,8 @@ impl Sink {
 
         let source = source
             .speed(1.0)
-            .track_position()
+            // must be placed before pausable but after speed & delay
+            .track_position() 
             .pausable(false)
             .amplify(1.0)
             .skippable()
@@ -319,6 +320,12 @@ impl Sink {
     }
 
     /// Returns the position of the sound that's being played.
+    ///
+    /// This takes into account any speedup or delay applied.
+    ///
+    /// Example: if you apply a speedup of *2* to an mp3 decoder source and
+    /// [`get_pos()`](Sink::get_pos) returns *5s* then the position in the mp3
+    /// recording is *10s* from its start.
     #[inline]
     pub fn get_pos(&self) -> f64 {
         *self.controls.position.lock().unwrap()

src/source/mod.rs

@@ -335,6 +335,16 @@ where
         skippable::skippable(self)
     }
 
+    /// Start tracking the elapsed duration since the start of the underlying
+    /// source.
+    ///
+    /// If a speedup and or delay is applied after this that will not be reflected
+    /// in the position returned by [`get_pos`](TrackPosition::get_pos).
+    ///
+    /// This can get confusing when using [`get_pos()`](TrackPosition::get_pos)
+    /// together with [`Source::try_seek()`] as the the latter does take all
+    /// speedup's and delay's into account. Its recommended therefore to apply
+    /// track_position after speedup's and delay's.
     fn track_position(self) -> TrackPosition<Self>
     where
         Self: Sized,

src/source/position.rs

@@ -4,7 +4,8 @@ use crate::{Sample, Source};
 
 use super::SeekError;
 
-/// Internal function that builds a `TrackPosition` object.
+/// Internal function that builds a `TrackPosition` object. See trait docs for
+/// details
 pub fn track_position<I>(source: I) -> TrackPosition<I> {
     TrackPosition {
         input: source,
@@ -51,7 +52,16 @@ where
     I: Source,
     I::Item: Sample,
 {
-    /// Returns the position of the source.
+    /// Returns the position of the underlying source relative to its start.
+    ///
+    /// If a speedup and or delay is applied after applying a
+    /// [`Source::track_position`] it will not be reflected in the position
+    /// returned by [`get_pos`](TrackPosition::get_pos).
+    ///
+    /// This can get confusing when using [`get_pos()`](TrackPosition::get_pos)
+    /// together with [`Source::try_seek()`] as the the latter does take all
+    /// speedup's and delay's into account. Its recommended therefore to apply
+    /// track_position after speedup's and delay's.
     #[inline]
     pub fn get_pos(&self) -> f64 {
         self.samples_counted as f64 / self.input.sample_rate() as f64 / self.input.channels() as f64

src/spatial_sink.rs

@@ -197,6 +197,12 @@ impl SpatialSink {
     }
 
     /// Returns the position of the sound that's being played.
+    ///
+    /// This takes into account any speedup or delay applied.
+    ///
+    /// Example: if you apply a speedup of *2* to an mp3 decoder source and
+    /// [`get_pos()`](Sink::get_pos) returns *5s* then the position in the mp3
+    /// recording is *10s* from its start.
     #[inline]
     pub fn get_pos(&self) -> f64 {
         self.sink.get_pos()