Struct claxon::FlacReader

pub struct FlacReader<R: Read> { /* fields omitted */ }

A FLAC decoder that can decode the stream from the underlying reader.

TODO: Add an example.

Methods

impl<R: Read> FlacReader<R>

pub fn new(reader: R) -> Result<FlacReader<R>>

Create a reader that reads the FLAC format.

The header and metadata blocks are read immediately. Audio frames will be read on demand.

Claxon rejects files that claim to contain excessively large metadata blocks, to protect against denial of service attacks where a small damaged or malicous file could cause gigabytes of memory to be allocated. Error::Unsupported is returned in that case.

pub fn new_ext(reader: R, options: FlacReaderOptions) -> Result<FlacReader<R>>

Create a reader that reads the FLAC format, with reader options.

The header and metadata blocks are read immediately, but only as much as specified in the options. See FlacReaderOptions for more details.

Claxon rejects files that claim to contain excessively large metadata blocks, to protect against denial of service attacks where a small damaged or malicous file could cause gigabytes of memory to be allocated. Error::Unsupported is returned in that case.

pub fn streaminfo(&self) -> StreamInfo

Returns the streaminfo metadata.

This contains information like the sample rate and number of channels.

pub fn vendor(&self) -> Option<&str>

Returns the vendor string of the Vorbis comment block, if present.

This string usually contains the name and version of the program that encoded the FLAC stream, such as reference libFLAC 1.3.2 20170101 or Lavf57.25.100.

Important traits for Tags<'a>

impl<'a> Iterator for Tags<'a> type Item = (&'a str, &'a str);

pub fn tags<'a>(&'a self) -> Tags<'a>

Returns name-value pairs of Vorbis comments, such as ("ARTIST", "Queen").

The name is supposed to be interpreted case-insensitively, and is guaranteed to consist of ASCII characters. Claxon does not normalize the casing of the name. Use get_tag() to do a case-insensitive lookup.

Names need not be unique. For instance, multiple ARTIST comments might be present on a collaboration track.

See https://www.xiph.org/vorbis/doc/v-comment.html for more details.

Important traits for GetTag<'a>

impl<'a> Iterator for GetTag<'a> type Item = &'a str;

pub fn get_tag<'a>(&'a self, tag_name: &'a str) -> GetTag<'a>

Look up a Vorbis comment such as ARTIST in a case-insensitive way.

Returns an iterator, because tags may occur more than once. There could be multiple ARTIST tags on a collaboration track, for instance.

Note that tag names are ASCII and never contain '='; trying to look up a non-ASCII tag will return no results. Furthermore, the Vorbis comment spec dictates that tag names should be handled case-insensitively, so this method performs a case-insensitive lookup.

See also tags() for access to the raw tags. See https://www.xiph.org/vorbis/doc/v-comment.html for more details.

pub fn blocks<'r>(&'r mut self) -> FrameReader<&'r mut BufferedReader<R>>

Returns an iterator that decodes a single frame on every iteration. TODO: It is not an iterator.

This is a low-level primitive that gives you control over when decoding happens. The representation of the decoded audio is somewhat specific to the FLAC format. For a higher-level interface, see samples().

Important traits for FlacSamples<R>

impl<R: ReadBytes> Iterator for FlacSamples<R> type Item = Result<i32>;

pub fn samples<'r>(&'r mut self) -> FlacSamples<&'r mut BufferedReader<R>>

Returns an iterator over all samples.

The channel data is is interleaved. The iterator is streaming. That is, if you call this method once, read a few samples, and call this method again, the second iterator will not start again from the beginning of the file. It will continue somewhere after where the first iterator stopped, and it might skip some samples. (This is because FLAC divides a stream into blocks, which have to be decoded entirely. If you drop the iterator, you lose the unread samples in that block.)

This is a user-friendly interface that trades performance for ease of use. If performance is an issue, consider using blocks() instead.

This is a high-level interface to the decoder. The cost of retrieving the next sample can vary significantly, as sometimes a new block has to be decoded. Additionally, there is a cost to every iteration returning a Result. When a block has been decoded, iterating the samples in that block can never fail, but a match on every sample is required nonetheless. For more control over when decoding happens, and less error handling overhead, use blocks().

pub fn into_inner(self) -> R

Destroys the FLAC reader and returns the underlying reader.

Because the reader employs buffering internally, anything in the buffer will be lost.

impl FlacReader<File>

pub fn open<P: AsRef<Path>>(filename: P) -> Result<FlacReader<File>>

Attempts to create a reader that reads from the specified file.

This is a convenience constructor that opens a File, and constructs a FlacReader from it. There is no need to wrap the file in a BufReader, as the FlacReader employs buffering already.

pub fn open_ext<P: AsRef<Path>>(
    filename: P,
    options: FlacReaderOptions
) -> Result<FlacReader<File>>

Attemps to create a reader that reads from the specified file.

This is a convenience constructor that opens a File, and constructs a FlacReader from it. There is no need to wrap the file in a BufReader, as the FlacReader employs buffering already.