Maintainers
Pricing
Enterprise
More
More
Documentation
Try Live
Rankings
Install
Blog
Docs7
Ask
New
Add Docs
qoaudio
https://docs.rs/qoaudio
Admin
qoaudio is a Rust library for decoding Quite OK Audio (QOA) format files.
Tokens:
6,415
Snippets:
79
Trust Score:
9.1
Update:
1 month ago
Context
Chat
Benchmark
Latest
Show doc for...
Code
Info
Show Results
Tokens:
Raw
Copy
Link
Tokens:
Raw
Copy
Link
### QoaDecoder::open Source: https://docs.rs/qoaudio/latest/qoaudio/struct.QoaDecoder.html Opens a file, wraps it with a BufReader, and creates a new decoder. ```APIDOC ## QoaDecoder::open ### Description Opens a file, wraps it with a BufReader, and creates a new decoder. ### Method open ### Signature pub fn open<P: AsRef<Path>>(path: P) -> Result<QoaDecoder<BufReader<File>>, DecodeError> ### Parameters - **path** (P) - Required - The path to the QOA file. ### Returns - **Result<QoaDecoder<BufReader<File>>, DecodeError>** - A new decoder or a DecodeError if the file cannot be opened or the header is invalid. ``` -------------------------------- ### open_and_decode_all Source: https://docs.rs/qoaudio/latest/qoaudio/fn.open_and_decode_all.html Opens the file at the given path and decodes all QOA audio data from it, wrapping the file in a BufReader. Returns a `DecodedQoa` on success or a `DecodeError` on failure. ```APIDOC ## Function open_and_decode_all ### Description Same as `decode_all` but opens the file and wraps it in a `BufReader` first. ### Signature ```rust pub fn open_and_decode_all<P: AsRef<Path>>( path: P, ) -> Result<DecodedQoa, DecodeError> ``` ### Parameters - **path** (`P: AsRef<Path>`) - The path to the QOA file to open and decode. ### Returns - **Ok(DecodedQoa)** - The decoded QOA audio data. - **Err(DecodeError)** - An error that occurred while opening or decoding the file. ### Errors - Returns a `DecodeError` if the file cannot be opened or if decoding fails. ``` -------------------------------- ### Test streaming frame decoding Source: https://docs.rs/qoaudio/latest/src/qoaudio/lib.rs.html Demonstrates how to initialize a streaming decoder and manually process individual frames by reading frame headers and sizes. ```rust #[test] fn test_decode_streaming_frames() { let mut qoa = QoaDecoder::new_streaming().unwrap(); assert!(matches!(qoa.mode(), ProcessingMode::Streaming)); // Read first frame from sample file. // We skip the standard file header and read the frame size present in the header. We // use the frame size to capture the entire frame. let frame_header = read_u64_be(Cursor::new(QOA_BYTES[QOA_HEADER_SIZE..16].to_vec())).unwrap(); let frame_size = (frame_header & 0x00ffff) as u16; let first_frame_end = 8 + frame_size as usize; let samples = qoa .decode_frame(&QOA_BYTES[QOA_HEADER_SIZE..first_frame_end]) .unwrap(); // We know the first frame has 5120 samples per channel. assert_eq!(samples.len(), 5120 * 2); // Read second frame from sample file. let frame_header = read_u64_be(Cursor::new( QOA_BYTES[first_frame_end..first_frame_end + QOA_HEADER_SIZE].to_vec(), )) .unwrap(); let frame_size = (frame_header & 0x00ffff) as u16; let second_frame_end = first_frame_end + frame_size as usize; let samples = qoa .decode_frame(&QOA_BYTES[first_frame_end..second_frame_end]) .unwrap(); // We know the first frame has 5120 samples per channel. assert_eq!(samples.len(), 5120 * 2); } ``` -------------------------------- ### open_and_decode_all Source: https://docs.rs/qoaudio Same as `decode_all` but opens the file and wraps it in a BufReader first. This function takes a file path, opens the file, and decodes all samples. ```APIDOC ## Function: open_and_decode_all ### Description Same as `decode_all` but open the file and wrap in a BufReader first. ### Parameters - `path` (impl AsRef<Path>) - Required - The path to the QOA file to open and decode. ### Returns - `Result<DecodedQoa, DecodeError>` - The fully decoded QOA file or an error. ``` -------------------------------- ### QoaDecoder::new Source: https://docs.rs/qoaudio/latest/qoaudio/struct.QoaDecoder.html Creates a new QoaDecoder from a reader, reading the file header and first frame header. It is recommended to wrap a File with a BufReader for performance. ```APIDOC ## QoaDecoder::new ### Description Creates a new QoaDecoder from a reader, reading the file header and first frame header. It is recommended to wrap a File with a BufReader for performance. ### Method new ### Signature pub fn new(reader: R) -> Result<Self, DecodeError> where R: Read ### Parameters - **reader** (R) - Required - The reader to read QOA data from. ### Returns - **Result<Self, DecodeError>** - A new QoaDecoder instance or a DecodeError if the header is invalid. ``` -------------------------------- ### open_and_decode_all Source: https://docs.rs/qoaudio/latest/qoaudio Same as decode_all but opens the file and wraps it in a BufReader first. This function takes a file path and returns a Result containing a DecodedQoa or a DecodeError. ```APIDOC ## open_and_decode_all ### Description Same as `decode_all` but open the file and wrap in a BufReader first. ### Function Signature `open_and_decode_all(path: impl AsRef<Path>) -> Result<DecodedQoa, DecodeError>` ### Parameters - **path** (impl AsRef<Path>) - Required - The path to the QOA file to open and decode. ### Returns - **Result<DecodedQoa, DecodeError>** - On success, returns a fully decoded QOA file. On failure, returns a DecodeError. ``` -------------------------------- ### Test decoding all samples Source: https://docs.rs/qoaudio/latest/src/qoaudio/lib.rs.html Shows the use of the decode_all convenience function to process an entire QOA data stream at once. ```rust #[test] fn test_decode_all() { let decoded = decode_all(Cursor::new(QOA_BYTES)).unwrap(); assert_eq!(decoded.sample_rate, 44100); assert_eq!(decoded.num_channels, 2); assert_eq!(decoded.samples.len(), 2394122 * 2); } ``` -------------------------------- ### DecodedQoa Source: https://docs.rs/qoaudio/latest/qoaudio/index.html A fully decoded QOA file, containing all audio samples. ```APIDOC ## DecodedQoa ### Description A fully decoded QOA file. Contains the decoded audio data. ### Fields - **samples** (Vec<i16>) - The decoded audio samples. - **sample_rate** (u32) - The sample rate of the audio. - **channels** (u8) - The number of audio channels. ### Example ```rust let decoded = qoaudio::decode_all(file)?; println!("Sample rate: {}", decoded.sample_rate); ``` ``` -------------------------------- ### QoaItem Source: https://docs.rs/qoaudio/latest/qoaudio/index.html Return type of `QoaDecoder::next`. ```APIDOC ## QoaItem ### Description Return type of `QoaDecoder::next`. Represents a decoded item, such as a sample or a frame. ### Variants - **Sample** (i16) - A single decoded audio sample. - **Frame** (FrameHeader) - A frame header. ### Example ```rust match decoder.next() { Some(QoaItem::Sample(s)) => { /* process sample */ }, Some(QoaItem::Frame(h)) => { /* process frame header */ }, None => { /* end of stream */ }, } ``` ``` -------------------------------- ### Constants Source: https://docs.rs/qoaudio/latest/qoaudio/index.html Constants used by the QOA format. ```APIDOC ## Constants ### Description Constants used by the QOA format. ### Constants - **MAX_SLICES_PER_CHANNEL_PER_FRAME** (usize) - Maximum number of slices per channel per frame. - **QOA_HEADER_SIZE** (usize) - Size of the QOA header in bytes. - **QOA_LMS_LEN** (usize) - Length of the LMS (Least Mean Squares) filter. - **QOA_MAGIC** (u32) - Magic number identifying a QOA file. - **QOA_SLICE_LEN** (usize) - Length of a slice in samples. ### Example ```rust println!("QOA magic: {:#x}", qoaudio::QOA_MAGIC); ``` ``` -------------------------------- ### decode_all Source: https://docs.rs/qoaudio Decodes all samples of a QOA file read from a reader. This function takes a reader and returns a DecodedQoa containing the fully decoded audio data. ```APIDOC ## Function: decode_all ### Description Decode all samples of a QOA file read from `reader`. ### Parameters - `reader` (impl Read) - Required - The source of QOA data to decode. ### Returns - `Result<DecodedQoa, DecodeError>` - The fully decoded QOA file or an error. ``` -------------------------------- ### QoaDecoder::into_inner Source: https://docs.rs/qoaudio/latest/qoaudio/struct.QoaDecoder.html Consumes the QoaDecoder and returns the inner reader. ```APIDOC ## QoaDecoder::into_inner ### Description Consumes the QoaDecoder and returns the inner reader. ### Method into_inner ### Signature pub fn into_inner(self) -> R ### Returns - **R** - The inner reader. ``` -------------------------------- ### QoaDecoder::current_frame_header Source: https://docs.rs/qoaudio/latest/qoaudio/struct.QoaDecoder.html Returns the header of the frame currently being processed. ```APIDOC ## QoaDecoder::current_frame_header ### Description Returns the header of the frame currently being processed. ### Method current_frame_header ### Signature pub fn current_frame_header(&self) -> &FrameHeader ### Returns - **&FrameHeader** - A reference to the current frame header. ``` -------------------------------- ### impl Iterator for QoaDecoder<R> Source: https://docs.rs/qoaudio/latest/qoaudio/struct.QoaDecoder.html The QoaDecoder implements the Iterator trait, allowing consumers to iterate over decoded audio samples. The next method returns the next sample or frame header, signaling errors via the Item type. ```APIDOC ## Iterator for `QoaDecoder<R>` ### Description Implements the `Iterator` trait for `QoaDecoder<R>` where `R: Read`. This allows iterating over decoded QOA audio samples. ### Method `next` ### Syntax ```rust fn next(&mut self) -> Option<Self::Item> ``` ### Description Get the next sample or the frame header if a new frame is starting. If an error is returned, iteration should be considered finished and `next` should not be called again. ### Return Value Returns `Option<Self::Item>` where `Self::Item = Result<QoaItem, DecodeError>`. `Some(result)` contains either the next `QoaItem` (sample or frame header) or a `DecodeError`. `None` indicates the end of iteration. ### Notes - The iterator yields `Result<QoaItem, DecodeError>` values, allowing callers to handle decoding errors. - After an error is returned, iteration should be stopped. ``` -------------------------------- ### FrameHeader Source: https://docs.rs/qoaudio/latest/qoaudio/index.html The metadata at the beginning of each frame of slices. ```APIDOC ## FrameHeader ### Description The metadata at the beginning of each frame of slices. ### Fields - **sample_rate** (u32) - The sample rate of the audio in this frame. - **channels** (u8) - The number of channels in this frame. - **samples_per_channel** (u16) - The number of samples per channel in this frame. ### Example ```rust // FrameHeader is typically used internally by the decoder. ``` ``` -------------------------------- ### decode_all Source: https://docs.rs/qoaudio/latest/qoaudio Decodes all samples of a QOA file read from a reader. This function takes a reader that implements Read and returns a Result containing a DecodedQoa or a DecodeError. ```APIDOC ## decode_all ### Description Decode all samples of a QOA file read from `reader`. ### Function Signature `decode_all(reader: impl Read) -> Result<DecodedQoa, DecodeError>` ### Parameters - **reader** (impl Read) - Required - The reader from which to read the QOA file. ### Returns - **Result<DecodedQoa, DecodeError>** - On success, returns a fully decoded QOA file. On failure, returns a DecodeError. ``` -------------------------------- ### QoaDecoder::total_duration Source: https://docs.rs/qoaudio/latest/qoaudio/struct.QoaDecoder.html Returns the total duration of the audio if known. ```APIDOC ## QoaDecoder::total_duration ### Description Returns the total duration of the audio if known. ### Method total_duration ### Signature pub fn total_duration(&self) -> Option<Duration> ### Returns - **Option<Duration>** - The total duration if known, otherwise None. ``` -------------------------------- ### QoaDecoder::new_streaming Source: https://docs.rs/qoaudio/latest/qoaudio/struct.QoaDecoder.html Creates a new decoder for use in streaming mode, allowing decoding a single frame at a time. ```APIDOC ## QoaDecoder::new_streaming ### Description Creates a new decoder for use in streaming mode, allowing decoding a single frame at a time. ### Method new_streaming ### Signature pub fn new_streaming() -> Result<Self, DecodeError> ### Returns - **Result<Self, DecodeError>** - A new streaming decoder or a DecodeError. ``` -------------------------------- ### DecodeError Display formatting with match on variants Source: https://docs.rs/qoaudio/latest/src/qoaudio/lib.rs.html Formats DecodeError variants including NoSamples, InvalidFrameHeader, IncompatibleFrame, and IoError with a custom message. This is for error reporting during decoding. ```rust DecodeError::NoSamples => write!(f, "File has no samples"), DecodeError::InvalidFrameHeader => write!(f, "File has invalid frame header"), DecodeError::IncompatibleFrame => write!(f, "Incompatible frame header"), DecodeError::IoError(e) => write!(f, "IO error: {}", e), } ``` -------------------------------- ### QoaDecoder Source: https://docs.rs/qoaudio/latest/qoaudio/index.html A decoder for QOA files that can be used to iterate over decoded samples. ```APIDOC ## QoaDecoder ### Description Decoder of QOA files. Provides an iterator interface to decode samples. ### Methods - `new(reader: impl Read) -> Result<Self, DecodeError>` - Creates a new decoder from a reader. - `next(&mut self) -> Option<QoaItem>` - Returns the next decoded item (e.g., a sample or frame). ### Example ```rust let file = File::open("audio.qoa")?; let mut decoder = QoaDecoder::new(file)?; for item in decoder { // process item } ``` ``` -------------------------------- ### ProcessingMode Source: https://docs.rs/qoaudio/latest/qoaudio/index.html The decoding mode of the QOA file. ```APIDOC ## ProcessingMode ### Description The decoding mode of the QOA file. ### Variants - **Streaming** - Decode in streaming mode. - **Buffered** - Decode in buffered mode. ### Example ```rust // ProcessingMode is used internally by the decoder. ``` ``` -------------------------------- ### QOA_HEADER_SIZE Source: https://docs.rs/qoaudio/latest/qoaudio/constant.QOA_HEADER_SIZE.html A constant that defines the size of the QOA header in bytes. It is used to allocate or parse the header portion of QOA audio data. ```APIDOC ## QOA_HEADER_SIZE ### Description A constant that defines the size of the QOA header in bytes. It is used to allocate or parse the header portion of QOA audio data. ### Declaration ```rust pub const QOA_HEADER_SIZE: usize = 8; ``` ### Type `usize` ### Value `8` ``` -------------------------------- ### QoaItem Enum Definition Source: https://docs.rs/qoaudio/latest/qoaudio/enum.QoaItem.html The QoaItem enum is the return type of QoaDecoder::next. It has two variants: Sample(i16) for audio sample data and FrameHeader(FrameHeader) for frame header information. ```APIDOC ## QoaItem Enum ### Description The QoaItem enum represents the return type of QoaDecoder::next. It can be either a Sample containing an i16 audio sample or a FrameHeader containing frame header information. ### Variants - **Sample(i16)** - Represents an audio sample. - **FrameHeader(FrameHeader)** - Represents a frame header. ### Trait Implementations - **Debug** - Formats the value using the given formatter. ``` -------------------------------- ### QoaDecoder::next Source: https://docs.rs/qoaudio The `next` method of the `QoaDecoder` struct returns the next decoded item from the QOA file. It is part of the iterator interface for decoding. ```APIDOC ## Method: QoaDecoder::next ### Description Returns the next item in the decoding process. The return type is `QoaItem`. ### Returns - `Option<QoaItem>` - The next decoded item, or `None` when the end of the file is reached. ``` -------------------------------- ### QoaItem enum definition Source: https://docs.rs/qoaudio/latest/qoaudio/enum.QoaItem.html Defines the QoaItem enum with variants Sample(i16) and FrameHeader(FrameHeader). It is the return type of QoaDecoder::next. ```rust pub enum QoaItem { Sample(i16), FrameHeader(FrameHeader), } ``` -------------------------------- ### QoaDecoder::mode Source: https://docs.rs/qoaudio/latest/qoaudio/struct.QoaDecoder.html Returns the processing mode of the decoder, indicating whether it is streaming or fixed. ```APIDOC ## QoaDecoder::mode ### Description Returns the processing mode of the decoder, indicating whether it is streaming or fixed. ### Method mode ### Signature pub fn mode(&self) -> &ProcessingMode ### Returns - **&ProcessingMode** - A reference to the current processing mode. ``` -------------------------------- ### QoaDecoder::decode_frame Source: https://docs.rs/qoaudio/latest/qoaudio/struct.QoaDecoder.html Decodes a single frame in streaming mode. ```APIDOC ## QoaDecoder::decode_frame ### Description Decodes a single frame in streaming mode. ### Method decode_frame ### Signature pub fn decode_frame(&mut self, frame_data: &[u8]) -> Result<Vec<i16>, DecodeError> ### Parameters - **frame_data** (&[u8]) - Required - The raw frame data to decode. ### Returns - **Result<Vec<i16>, DecodeError>** - A vector of decoded samples or a DecodeError. ``` -------------------------------- ### ProcessingMode enum definition Source: https://docs.rs/qoaudio/latest/qoaudio/enum.ProcessingMode.html Defines the decoding mode for a QOA file. Use FixedSamples when the total sample count is known and the sample rate and channel count are fixed; use Streaming when the total sample count is unknown and the sample rate and channels can change per frame. ```rust pub enum ProcessingMode { FixedSamples { channels: u8, sample_rate: u32, samples: u32, }, Streaming, } ``` -------------------------------- ### DecodeError Source: https://docs.rs/qoaudio/latest/qoaudio/index.html An enumeration of possible errors that can occur during decoding. ```APIDOC ## DecodeError ### Description An enumeration of possible errors that can occur during decoding. ### Variants - **IoError** (std::io::Error) - An I/O error occurred. - **InvalidHeader** - The QOA header is invalid. - **InvalidFrame** - A frame is invalid. - **Unsupported** - The QOA file uses unsupported features. ### Example ```rust match decode_all(file) { Ok(decoded) => { /* ... */ }, Err(e) => eprintln!("Decode error: {:?}", e), } ``` ``` -------------------------------- ### ProcessingMode Source: https://docs.rs/qoaudio/latest/qoaudio/enum.ProcessingMode.html Enum representing the decoding mode of a QOA file. It has two variants: FixedSamples and Streaming. ```APIDOC ## Enum ProcessingMode ### Description Represents the decoding mode of a QOA file. ### Variants #### FixedSamples Total number of samples is known and sample rate and number of channels is fixed for the entire file. ##### Fields - `channels: u8` - Number of channels. - `sample_rate: u32` - The sample rate for all channels in HZ (e.g. 44100). - `samples: u32` - Number of samples per channel in the entire file. #### Streaming Total number of samples is not known and the sample rate and number of channels can change each frame. ### Trait Implementations - `Clone` - `Debug` - `PartialEq` - `StructuralPartialEq` ```
