Struct FlacSampleReader

Source

pub struct FlacSampleReader<R> { /* private fields */ }

Expand description

A FLAC reader which outputs PCM samples as signed integers

§Example

use flac_codec::{
    encode::{FlacSampleWriter, Options},
    decode::FlacSampleReader,
};
use std::io::{Cursor, Seek};

let mut flac = Cursor::new(vec![]);  // a FLAC file in memory

let mut writer = FlacSampleWriter::new(
    &mut flac,           // our wrapped writer
    Options::default(),  // default encoding options
    44100,               // sample rate
    16,                  // bits-per-sample
    1,                   // channel count
    Some(1000),          // total samples
).unwrap();

// write 1000 samples
let written_samples = (0..1000).collect::<Vec<i32>>();
assert!(writer.write(&written_samples).is_ok());

// finalize writing file
assert!(writer.finalize().is_ok());

flac.rewind().unwrap();

// open reader around written FLAC file
let mut reader = FlacSampleReader::new(flac).unwrap();

// read 1000 samples
let mut read_samples = vec![0; 1000];
assert!(matches!(reader.read(&mut read_samples), Ok(1000)));

// ensure they match
assert_eq!(read_samples, written_samples);

Implementations§

Source §

impl<R: Read> FlacSampleReader<R>

Source

pub fn new(reader: R) -> Result<Self, Error>

Opens new FLAC reader which wraps the given reader

The reader must be positioned at the start of the FLAC stream. If the file has non-FLAC data at the beginning (such as ID3v2 tags), one should skip such data before initializing a FlacByteReader.

Source

pub fn metadata(&self) -> &BlockList

Returns FLAC metadata blocks

Source

pub fn read(&mut self, samples: &mut [i32]) -> Result<usize, Error>

Attempts to fill the buffer with samples and returns quantity read

Returned samples are interleaved by channel, like: [left₀ , right₀ , left₁ , right₁ , left₂ , right₂ , …]

§Errors

Returns error if some error occurs reading FLAC file

Source

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

Reads all samples from source FLAC, placing them in buf

If successful, returns the total number of samples read

Source

pub fn fill_buf(&mut self) -> Result<&[i32], Error>

Returns complete buffer of all read samples

Analogous to std::io::BufRead::fill_buf, this should be paired with FlacSampleReader::consume to consume samples in the filled buffer once used.

Returned samples are interleaved by channel, like: [left₀ , right₀ , left₁ , right₁ , left₂ , right₂ , …]

§Errors

Returns error if some error occurs reading FLAC file to fill buffer.

Source

pub fn consume(&mut self, amt: usize)

Informs the reader that amt samples have been consumed.

Analagous to std::io::BufRead::consume, which marks samples as having been read.

May panic if attempting to consume more bytes than are available in the buffer.

Source §

impl<R: Read + Seek> FlacSampleReader<R>

Source

pub fn new_seekable(reader: R) -> Result<Self, Error>

Opens a new seekable FLAC reader which wraps the given reader

If a stream is both readable and seekable, it’s vital to use this method to open it if one also wishes to seek within the FLAC stream. Otherwise, an I/O error will result when attempting to seek.

FlacSampleReader::open calls this method to ensure all File-based streams are also seekable.

The reader must be positioned at the start of the FLAC stream. If the file has non-FLAC data at the beginning (such as ID3v2 tags), one should skip such data before initializing a FlacSampleReader.

§Example

use flac_codec::{
    encode::{FlacSampleWriter, Options},
    decode::FlacSampleReader,
};
use std::io::{Cursor, Seek};

let mut flac = Cursor::new(vec![]);  // a FLAC file in memory

let mut writer = FlacSampleWriter::new(
    &mut flac,           // our wrapped writer
    Options::default(),  // default encoding options
    44100,               // sample rate
    16,                  // bits-per-sample
    1,                   // channel count
    Some(1000),          // total samples
).unwrap();

// write 1000 samples
let written_samples = (0..1000).collect::<Vec<i32>>();
assert!(writer.write(&written_samples).is_ok());

// finalize writing file
assert!(writer.finalize().is_ok());

flac.rewind().unwrap();

// open reader around written FLAC file
let mut reader = FlacSampleReader::new_seekable(flac).unwrap();

// read 1000 samples
let mut read_samples_1 = vec![0; 1000];
assert!(matches!(reader.read(&mut read_samples_1), Ok(1000)));

// ensure they match
assert_eq!(read_samples_1, written_samples);

// rewind reader to halfway through file
assert!(reader.seek(500).is_ok());

// read 500 samples
let mut read_samples_2 = vec![0; 500];
assert!(matches!(reader.read(&mut read_samples_2), Ok(500)));

// ensure output matches back half of input
assert_eq!(read_samples_2.len(), 500);
assert!(written_samples.ends_with(&read_samples_2));