Struct creek_core::read::ReadDiskStream
source · pub struct ReadDiskStream<D: Decoder> { /* private fields */ }
Expand description
A realtime-safe disk-streaming reader of audio files.
Implementations§
source§impl<D: Decoder> ReadDiskStream<D>
impl<D: Decoder> ReadDiskStream<D>
sourcepub fn new<P: Into<PathBuf>>(
file: P,
start_frame: usize,
stream_opts: ReadStreamOptions<D>
) -> Result<ReadDiskStream<D>, D::OpenError>
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.
Panics
This will panic if stream_block_size
, stream_num_look_ahead_blocks
,
or stream_server_msg_channel_size
is 0
.
sourcepub fn num_caches(&self) -> usize
pub fn num_caches(&self) -> usize
Return the total number of caches available in this stream.
This is realtime-safe.
sourcepub fn can_move_cache(&mut self, cache_index: usize) -> bool
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.
sourcepub fn cache(
&mut self,
cache_index: usize,
start_frame: usize
) -> Result<bool, ReadError<D::FatalError>>
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. UseReadDiskStream::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.
sourcepub fn seek(
&mut self,
frame: usize,
seek_mode: SeekMode
) -> Result<bool, ReadError<D::FatalError>>
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.
sourcepub fn is_ready(&mut self) -> Result<bool, ReadError<D::FatalError>>
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.
sourcepub fn block_until_ready(&mut self) -> Result<(), ReadError<D::FatalError>>
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.
sourcepub fn fill_buffer_blocking(
&mut self,
buffer: &mut [Vec<D::T>]
) -> Result<usize, ReadError<D::FatalError>>
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.
sourcepub fn read(
&mut self,
frames: usize
) -> Result<ReadData<'_, D::T>, ReadError<D::FatalError>>
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()
.
sourcepub fn playhead(&self) -> usize
pub fn playhead(&self) -> usize
Return the current frame of the playhead.
This is realtime-safe.
sourcepub fn info(&self) -> &FileInfo<D::FileParams>
pub fn info(&self) -> &FileInfo<D::FileParams>
Return info about the file.
This is realtime-safe.
sourcepub fn block_size(&self) -> usize
pub fn block_size(&self) -> usize
Return the block size used by this decoder.
This is realtime-safe.