Trait SoundReader 

pub trait SoundReader<T: Sample>: Send {
    // Required method
    fn read(&mut self, buf: &mut [MaybeUninit<T>]) -> usize;

    // Provided methods
    fn seek(&mut self, pos: u64) -> Option<u64> { ... }
    fn skip_precise(&mut self, count: u64, buf: &mut [MaybeUninit<T>]) -> bool { ... }
    fn skip_coarse(&mut self, count: u64, buf: &mut [MaybeUninit<T>]) -> u64 { ... }
    fn can_be_cloned(&self) -> bool { ... }
    fn attempt_clone(
        &self,
        _sample_rate: PosFloat,
        _speaker_layout: SpeakerLayout,
    ) -> FormattedSoundStream { ... }
    fn estimate_len(&mut self) -> Option<u64> { ... }
}

This is an object that SMS will hang onto, representing an ongoing decoding of a particular underlying file. SMS will either use this to populate a cache or to stream it directly, depending on the Soundtrack’s configuration.

Required Methods

fn read(&mut self, buf: &mut [MaybeUninit<T>]) -> usize

Produce some sound, placing it into the target buffer.

Return the number of samples (not sample frames) that were written to buf. If this is not exactly equal to the size of the buf, then the stream is assumed to have been ended; either it will be disposed of, or seek will be called.

Provided Methods

fn seek(&mut self, pos: u64) -> Option<u64>

Attempt to seek to the given sample frame count from the beginning of the file. Imprecision is permitted in one direction only: seeking is permitted to end up earlier than the target, but not later. Returns the actual sample frame count, measured from the beginning of the stream, that was seeked to.

This number must be exact! If you can’t provide an exact timestamp, don’t provide seeking! (SMS will work around it.) Again, it’s okay if you can’t seek to an exact timestamp, but you do need to be able to know where you’ve seeked to and not seek too late.

Returns None if seeking failed or is impossible, in which case, SMS will reopen the file instead. Default implementation returns None.

SMS may call seek(0) upon opening your stream, to determine if seeking is something your decoder supports. You should return Some only if you are confident that seeking will succeed in the future.

IMPORTANT NOTE: Do not implement this if you can seek only forward. Do not special case successful seek when coincidentally seeking to where the cursor already is. Do not implement this by calling your own skip routines. If you disregard this warning, SMS will panic the first time it attempts to loop a stream. If you can only seek forward, implement only the skip routines.

You also shouldn’t implement this function if seeking is as expensive as reopening the file, starting decoding from scratch, and calling skip_*. If this is the case, just don’t implement it. SMS has logic that can do that work in a background thread.

fn skip_precise(&mut self, count: u64, buf: &mut [MaybeUninit<T>]) -> bool

Attempt to skip exactly the given number of samples. Failure is not an option. Returns true if there is more sound data to come, false if we have reached the end of the sound.

The default implementation will try to use skip_coarse to skip ahead, and then repeatedly read into the target buffer until the exact number of target samples are consumed.

buf is provided as scratch space.

fn skip_coarse(&mut self, count: u64, buf: &mut [MaybeUninit<T>]) -> u64

Attempt to efficiently skip up to a large number of samples, by discarding partial buffers, skipping packets, seeking in the file, etc. Return the number of samples skipped, possibly including zero.

Default implementation just returns 0.

buf is provided as scratch space.

fn can_be_cloned(&self) -> bool

Returns true if this decoder can be cheaply cloned, false otherwise.

Default implementation assumes non-cloneability.

This function must always return the same value for the same stream. If the observable value ever changes, panic may ensue.

fn attempt_clone( &self, _sample_rate: PosFloat, _speaker_layout: SpeakerLayout, ) -> FormattedSoundStream

If this is a cloneable decoder, clone yourself. If not, panic. (The default implementation panics.)

Sample rate and speaker layout are provided in case you do not keep track of your own sample rate and speaker layout internally.

fn estimate_len(&mut self) -> Option<u64>

Attempt to estimate how many sample frames are in the entire file, from beginning to end. This is a BEST GUESS ESTIMATE and may not reflect the actual value!

SMS will never call this after it has seeked/skipped/read any audio data, so it is safe for implementors to assume the cursor is at the beginning of the file and give less accurate data otherwise.

Implementors