Trait symphonia_core::formats::FormatReader

pub trait FormatReader: Send + Sync {
    // Required methods
    fn try_new(
        source: MediaSourceStream,
        options: &FormatOptions
    ) -> Result<Self>
       where Self: Sized;
    fn cues(&self) -> &[Cue];
    fn metadata(&mut self) -> Metadata<'_>;
    fn seek(&mut self, mode: SeekMode, to: SeekTo) -> Result<SeekedTo>;
    fn tracks(&self) -> &[Track];
    fn next_packet(&mut self) -> Result<Packet>;
    fn into_inner(self: Box<Self>) -> MediaSourceStream ;

    // Provided method
    fn default_track(&self) -> Option<&Track> { ... }
}

A FormatReader is a container demuxer. It provides methods to probe a media container for information and access the tracks encapsulated in the container.

Most, if not all, media containers contain metadata, then a number of packetized, and interleaved codec bitstreams. These bitstreams are usually referred to as tracks. Generally, the encapsulated bitstreams are independently encoded using some codec. The allowed codecs for a container are defined in the specification of the container format.

While demuxing, packets are read one-by-one and may be discarded or decoded at the choice of the caller. The contents of a packet is undefined: it may be a frame of video, a millisecond of audio, or a subtitle, but a packet will never contain data from two different bitstreams. Therefore the caller can be selective in what tracks(s) should be decoded and consumed.

FormatReader provides an Iterator-like interface over packets for easy consumption and filtering. Seeking will invalidate the state of any Decoder processing packets from the FormatReader and should be reset after a successful seek operation.

Required Methods

fn try_new(source: MediaSourceStream, options: &FormatOptions) -> Result<Self>

where Self: Sized,

Attempt to instantiate a FormatReader using the provided FormatOptions and MediaSourceStream. The reader will probe the container to verify format support, determine the number of tracks, and read any initial metadata.

fn cues(&self) -> &[Cue]

Gets a list of all Cues.

fn metadata(&mut self) -> Metadata<'_>

Gets the metadata revision log.

fn seek(&mut self, mode: SeekMode, to: SeekTo) -> Result<SeekedTo>

Seek, as precisely as possible depending on the mode, to the Time or track TimeStamp requested. Returns the requested and actual TimeStamps seeked to, as well as the Track.

After a seek, all Decoders consuming packets from this reader should be reset.

Note: The FormatReader by itself cannot seek to an exact audio frame, it is only capable of seeking to the nearest Packet. Therefore, to seek to an exact frame, a Decoder must decode packets until the requested position is reached. When using the accurate SeekMode, the seeked position will always be before the requested position. If the coarse SeekMode is used, then the seek position may be after the requested position. Coarse seeking is an optional performance enhancement, therefore, a coarse seek may sometimes be an accurate seek.

fn tracks(&self) -> &[Track]

Gets a list of tracks in the container.

fn next_packet(&mut self) -> Result<Packet>

Get the next packet from the container.

If ResetRequired is returned, then the track list must be re-examined and all Decoders re-created. All other errors are unrecoverable.

fn into_inner(self: Box<Self>) -> MediaSourceStream

Destroys the FormatReader and returns the underlying media source stream

Provided Methods

fn default_track(&self) -> Option<&Track>

Gets the default track. If the FormatReader has a method of determining the default track, this function should return it. Otherwise, the first track is returned. If no tracks are present then None is returned.

Implementors