Struct creek_core::read::ReadDiskStream

pub struct ReadDiskStream<D: Decoder> { /* fields omitted */ }

A realtime-safe disk-streaming reader of audio files.

Implementations

impl<D: Decoder> ReadDiskStream<D>

pub fn new<P: Into<PathBuf>>(
    file: P,
    start_frame: usize,
    stream_opts: ReadStreamOptions<D>
) -> Result<ReadDiskStream<D>, D::OpenError>

Open a new realtime-safe disk-streaming reader.

• file - The path to the file to open.
• start_frame - The frame in the file to start reading from.
• stream_opts - Additional stream options.

pub fn num_caches(&self) -> usize

Return the total number of caches available in this stream.

This is realtime-safe.

pub fn can_move_cache(&mut self, cache_index: usize) -> bool

Returns whether a cache can be moved seamlessly without silencing current playback (true) or not (false).

This is realtime-safe.

If the position of a cache is changed while the playback stream is currently relying on it, then it will attempt to store the cache in a temporary buffer to allow playback to resume seamlessly.

However, in the case where the cache is moved multiple times in quick succession while being relied on, then any blocks relying on the oldest cache will be silenced. In this case, (false) will be returned.

pub fn cache(
    &mut self,
    cache_index: usize,
    start_frame: usize
) -> Result<bool, ReadError<D::FatalError>>

Request to cache a new area in the file.

This is realtime-safe.

• cache_index - The index of the cache to use. Use ReadDiskStream::num_caches() to see how many caches have been assigned to this stream.
• start_frame - The frame in the file to start filling in the cache from. If any portion lies outside the end of the file, then that portion will be ignored.

If the cache already exists, then it will be overwritten. If the cache already starts from this position, then nothing will be done and (false) will be returned. Otherwise, (true) will be returned.

In the case where the position of a cache is changed while the playback stream is currently relying on it, then it will attempt to store the cache in a temporary buffer to allow playback to resume seamlessly.

However, in the case where the cache is moved multiple times in quick succession while being relied on, then any blocks relying on the oldest cache will be silenced. See ReadDiskStream::can_move_cache() to check if a cache can be seamlessly moved first.

pub fn seek(
    &mut self,
    frame: usize,
    seek_mode: SeekMode
) -> Result<bool, ReadError<D::FatalError>>

Request to seek playback to a new position in the file.

This is realtime-safe.

• frame - The position in the file to seek to. If this lies outside of the end of the file, then playback will return silence.
• seek_mode - Describes how to search for a suitable cache to use.

If a suitable cache is found, then (true) is returned meaning that playback can resume immediately without any buffering. Otherwise (false) is returned meaning that playback will need to buffer first. In this case, you may choose to continue reading (which will return silence), or to pause playback temporarily.

pub fn is_ready(&mut self) -> Result<bool, ReadError<D::FatalError>>

Returns true if the stream is finished buffering and there is data can be read right now, false otherwise.

This is realtime-safe.

In the case where false is returned, then you may choose to continue reading (which will return silence), or to pause playback temporarily.

pub fn block_until_ready(&mut self) -> Result<(), ReadError<D::FatalError>>

Blocks the current thread until the stream is done buffering.

NOTE: This is not realtime-safe. This is only useful for making sure a stream is ready before sending it to a realtime thread.

pub fn fill_buffer_blocking(
    &mut self,
    buffer: &mut [Vec<D::T>]
) -> Result<usize, ReadError<D::FatalError>>

Blocks the current thread until the given buffer is filled.

NOTE: This is not realtime-safe.

This will start reading from the stream’s current playhead (this can be changed beforehand with ReadDiskStream::seek()). This is streaming, meaning the next call to fill_buffer_blocking() or ReadDiskStream::read() will pick up from where the previous call ended.

Returns

This will return the number of frames that were written to the buffer. This may be less than the length of the buffer if the end of the file was reached, so use this as a check if the entire buffer was filled or not.

Error

This will return an error if the number of channels in the buffer does not equal the number of channels in the stream, if the length of each channel is not the same, or if there was an internal error with reading the stream.

pub fn read(
    &mut self,
    frames: usize
) -> Result<ReadData<'_, D::T>, ReadError<D::FatalError>>

Read the next chunk of frames in the stream from the current playhead position.

This is realtime-safe.

This is streaming, meaning the next call to read() will pick up where the previous call left off.

If the stream is currently buffering, (false) will be returned, and the playhead will still advance but will output silence. Otherwise, data can be read and (true) is returned. To check if the stream is ready beforehand, call ReadDiskStream::is_ready().

If the end of a file is reached, then only the amount of frames up to the end will be returned, and playback will return silence on each subsequent call to read().

NOTE: If the number of frames exceeds the block size of the decoder, then that block size will be used instead. This can be retrieved using ReadDiskStream::block_size().

pub fn playhead(&self) -> usize

Return the current frame of the playhead.

This is realtime-safe.

pub fn info(&self) -> &FileInfo<D::FileParams>

Return info about the file.

This is realtime-safe.

pub fn block_size(&self) -> usize

Return the block size used by this decoder.

This is realtime-safe.

Trait Implementations

impl<D: Decoder> Drop for ReadDiskStream<D>

fn drop(&mut self)

Executes the destructor for this type.