Struct MediaSourceStream

pub struct MediaSourceStream { /* private fields */ }

Available on crate feature dep_symphonia only.

MediaSourceStream is the main reader type for Symphonia.

By using type erasure and dynamic dispatch, MediaSourceStream wraps and hides the inner reader from the consumer, allowing any typical Reader to be used with Symphonia in a generic way, selectable at runtime.

MediaSourceStream is designed to provide speed and flexibility in a number of challenging I/O scenarios.

First, to minimize system call and dynamic dispatch overhead on the inner reader, and to amortize that overhead over many bytes, MediaSourceStream implements an exponentially growing read-ahead buffer. The read-ahead length starts at 1kB, and doubles in length as more sequential reads are performed until it reaches 32kB. Growing the read-ahead length over time reduces the excess data buffered on consecutive seek() calls.

Second, to better support non-seekable sources, MediaSourceStream implements a configurable length buffer cache. By default, the buffer caches allows backtracking by up-to the minimum of either buffer_len - 32kB or the total number of bytes read since instantiation or the last buffer cache invalidation. Note that regular a seek() will invalidate the buffer cache.

Implementations

impl MediaSourceStream

pub fn new( source: Box<dyn MediaSource>, options: MediaSourceStreamOptions, ) -> MediaSourceStream

Trait Implementations

impl MediaSource for MediaSourceStream

fn is_seekable(&self) -> bool

Returns if the source is seekable. This may be an expensive operation.

fn byte_len(&self) -> Option<u64>

Returns the length in bytes, if available. This may be an expensive operation.

impl Read for MediaSourceStream

fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl ReadBytes for MediaSourceStream

fn read_byte(&mut self) -> Result<u8, Error>

Reads a single byte from the stream and returns it or an error.

fn read_double_bytes(&mut self) -> Result<[u8; 2], Error>

Reads two bytes from the stream and returns them in read-order or an error.

fn read_triple_bytes(&mut self) -> Result<[u8; 3], Error>

Reads three bytes from the stream and returns them in read-order or an error.

fn read_quad_bytes(&mut self) -> Result<[u8; 4], Error>

Reads four bytes from the stream and returns them in read-order or an error.

fn read_buf(&mut self, buf: &mut [u8]) -> Result<usize, Error>

Reads up-to the number of bytes required to fill buf or returns an error.

fn read_buf_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads exactly the number of bytes required to fill be provided buffer or returns an error.

fn scan_bytes_aligned<'a>( &mut self, _: &[u8], _: usize, _: &'a mut [u8], ) -> Result<&'a mut [u8], Error>

Reads bytes from a stream into a supplied buffer until a byte patter is matched on an aligned byte boundary. Returns a mutable slice to the valid region of the provided buffer.

fn ignore_bytes(&mut self, count: u64) -> Result<(), Error>

Ignores the specified number of bytes from the stream or returns an error.

fn pos(&self) -> u64

Gets the position of the stream.

fn read_u8(&mut self) -> Result<u8, Error>

Reads a single unsigned byte from the stream and returns it or an error.

fn read_i8(&mut self) -> Result<i8, Error>

Reads a single signed byte from the stream and returns it or an error.

fn read_u16(&mut self) -> Result<u16, Error>

Reads two bytes from the stream and interprets them as an unsigned 16-bit little-endian integer or returns an error.

fn read_i16(&mut self) -> Result<i16, Error>

Reads two bytes from the stream and interprets them as an signed 16-bit little-endian integer or returns an error.

fn read_be_u16(&mut self) -> Result<u16, Error>

Reads two bytes from the stream and interprets them as an unsigned 16-bit big-endian integer or returns an error.

fn read_be_i16(&mut self) -> Result<i16, Error>

Reads two bytes from the stream and interprets them as an signed 16-bit big-endian integer or returns an error.

fn read_u24(&mut self) -> Result<u32, Error>

Reads three bytes from the stream and interprets them as an unsigned 24-bit little-endian integer or returns an error.

fn read_i24(&mut self) -> Result<i32, Error>

Reads three bytes from the stream and interprets them as an signed 24-bit little-endian integer or returns an error.

fn read_be_u24(&mut self) -> Result<u32, Error>

Reads three bytes from the stream and interprets them as an unsigned 24-bit big-endian integer or returns an error.

fn read_be_i24(&mut self) -> Result<i32, Error>

Reads three bytes from the stream and interprets them as an signed 24-bit big-endian integer or returns an error.

fn read_u32(&mut self) -> Result<u32, Error>

Reads four bytes from the stream and interprets them as an unsigned 32-bit little-endian integer or returns an error.

fn read_i32(&mut self) -> Result<i32, Error>

Reads four bytes from the stream and interprets them as an signed 32-bit little-endian integer or returns an error.

fn read_be_u32(&mut self) -> Result<u32, Error>

Reads four bytes from the stream and interprets them as an unsigned 32-bit big-endian integer or returns an error.

fn read_be_i32(&mut self) -> Result<i32, Error>

Reads four bytes from the stream and interprets them as a signed 32-bit big-endian integer or returns an error.

fn read_u64(&mut self) -> Result<u64, Error>

Reads eight bytes from the stream and interprets them as an unsigned 64-bit little-endian integer or returns an error.

fn read_i64(&mut self) -> Result<i64, Error>

Reads eight bytes from the stream and interprets them as an signed 64-bit little-endian integer or returns an error.

fn read_be_u64(&mut self) -> Result<u64, Error>

Reads eight bytes from the stream and interprets them as an unsigned 64-bit big-endian integer or returns an error.

fn read_be_i64(&mut self) -> Result<i64, Error>

Reads eight bytes from the stream and interprets them as an signed 64-bit big-endian integer or returns an error.

fn read_f32(&mut self) -> Result<f32, Error>

Reads four bytes from the stream and interprets them as a 32-bit little-endian IEEE-754 floating-point value.

fn read_be_f32(&mut self) -> Result<f32, Error>

Reads four bytes from the stream and interprets them as a 32-bit big-endian IEEE-754 floating-point value.

fn read_f64(&mut self) -> Result<f64, Error>

Reads four bytes from the stream and interprets them as a 64-bit little-endian IEEE-754 floating-point value.

fn read_be_f64(&mut self) -> Result<f64, Error>

Reads four bytes from the stream and interprets them as a 64-bit big-endian IEEE-754 floating-point value.

fn read_boxed_slice(&mut self, len: usize) -> Result<Box<[u8]>, Error>

Reads up-to the number of bytes requested, and returns a boxed slice of the data or an error.

fn read_boxed_slice_exact(&mut self, len: usize) -> Result<Box<[u8]>, Error>

Reads exactly the number of bytes requested, and returns a boxed slice of the data or an error.

fn scan_bytes<'a>( &mut self, pattern: &[u8], buf: &'a mut [u8], ) -> Result<&'a mut [u8], Error>

Reads bytes from the stream into a supplied buffer until a byte pattern is matched. Returns a mutable slice to the valid region of the provided buffer.

impl Seek for MediaSourceStream

fn seek(&mut self, pos: SeekFrom) -> Result<u64, Error>

Seek to an offset, in bytes, in a stream.

fn rewind(&mut self) -> Result<(), Error>

Rewind to the beginning of a stream.

fn stream_len(&mut self) -> Result<u64, Error>

🔬This is a nightly-only experimental API. (seek_stream_len)

Returns the length of this stream (in bytes).

fn stream_position(&mut self) -> Result<u64, Error>

Returns the current seek position from the start of the stream.

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

Seeks relative to the current position.

impl SeekBuffered for MediaSourceStream

fn ensure_seekback_buffer(&mut self, len: usize)

Ensures that len bytes will be available for backwards seeking if len bytes have been previously read.

fn unread_buffer_len(&self) -> usize

Get the number of bytes buffered but not yet read.

fn read_buffer_len(&self) -> usize

Gets the number of bytes buffered and read.

fn seek_buffered(&mut self, pos: u64) -> u64

Seek within the buffered data to an absolute position in the stream. Returns the position seeked to.

fn seek_buffered_rel(&mut self, delta: isize) -> u64

Seek within the buffered data relative to the current position in the stream. Returns the position seeked to.

fn seek_buffered_rev(&mut self, delta: usize)

Seek backwards within the buffered data.