pub struct AudioDecoder { /* private fields */ }Expand description
An audio decoder for extracting audio frames from media files.
The decoder provides frame-by-frame access to audio content with support for resampling and format conversion.
§Construction
Use AudioDecoder::open() to create a builder, then call AudioDecoderBuilder::build():
use ff_decode::AudioDecoder;
use ff_format::SampleFormat;
let decoder = AudioDecoder::open("audio.mp3")?
.output_format(SampleFormat::F32)
.output_sample_rate(48000)
.build()?;§Frame Decoding
Frames can be decoded one at a time or using an iterator:
// Decode one frame
if let Some(frame) = decoder.decode_one()? {
println!("Frame with {} samples", frame.samples());
}
// Use iterator
for frame in decoder.frames().take(100) {
let frame = frame?;
// Process frame...
}§Seeking
The decoder supports seeking to specific positions:
use std::time::Duration;
// Seek to 30 seconds
decoder.seek(Duration::from_secs(30))?;Implementations§
Source§impl AudioDecoder
impl AudioDecoder
Sourcepub fn open(path: impl AsRef<Path>) -> AudioDecoderBuilder
pub fn open(path: impl AsRef<Path>) -> AudioDecoderBuilder
Opens a media file and returns a builder for configuring the decoder.
This is the entry point for creating a decoder. The returned builder allows setting options before the decoder is fully initialized.
§Arguments
path- Path to the media file to decode.
§Examples
use ff_decode::AudioDecoder;
// Simple usage
let decoder = AudioDecoder::open("audio.mp3")?
.build()?;
// With options
let decoder = AudioDecoder::open("audio.mp3")?
.output_format(SampleFormat::F32)
.output_sample_rate(48000)
.build()?;§Note
This method does not validate that the file exists or is a valid
media file. Validation occurs when AudioDecoderBuilder::build() is called.
Sourcepub fn stream_info(&self) -> &AudioStreamInfo
pub fn stream_info(&self) -> &AudioStreamInfo
Returns the audio stream information.
This contains metadata about the audio stream including sample rate, channel count, codec, and format characteristics.
Sourcepub fn sample_rate(&self) -> u32
pub fn sample_rate(&self) -> u32
Returns the sample rate in Hz.
Sourcepub fn duration(&self) -> Duration
pub fn duration(&self) -> Duration
Returns the total duration of the audio.
Returns Duration::ZERO if duration is unknown.
Sourcepub fn decode_one(&mut self) -> Result<Option<AudioFrame>, DecodeError>
pub fn decode_one(&mut self) -> Result<Option<AudioFrame>, DecodeError>
Decodes the next audio frame.
This method reads and decodes a single frame from the audio stream.
§Returns
Ok(Some(frame))- A frame was successfully decodedOk(None)- End of stream reached, no more framesErr(_)- An error occurred during decoding
§Errors
Returns DecodeError if:
- Reading from the file fails
- Decoding the frame fails
- Sample format conversion fails
§Examples
use ff_decode::AudioDecoder;
let mut decoder = AudioDecoder::open("audio.mp3")?.build()?;
while let Some(frame) = decoder.decode_one()? {
println!("Frame with {} samples", frame.samples());
// Process frame...
}Sourcepub fn frames(&mut self) -> AudioFrameIterator<'_> ⓘ
pub fn frames(&mut self) -> AudioFrameIterator<'_> ⓘ
Returns an iterator over decoded frames.
This provides a convenient way to iterate over all frames in the audio. The iterator will continue until end of stream or an error occurs.
§Examples
use ff_decode::AudioDecoder;
let mut decoder = AudioDecoder::open("audio.mp3")?.build()?;
// Process first 100 frames
for frame in decoder.frames().take(100) {
let frame = frame?;
// Process frame...
}Sourcepub fn decode_all(&mut self) -> Result<Vec<u8>, DecodeError>
pub fn decode_all(&mut self) -> Result<Vec<u8>, DecodeError>
Decodes all frames and returns their raw PCM data.
This method decodes the entire audio file and returns all samples as a contiguous byte buffer.
§Performance
- Memory scales with audio duration and quality
- For 10 minutes of stereo 48kHz F32 audio: ~110 MB
§Returns
A byte vector containing all audio samples in the configured output format.
§Errors
Returns DecodeError if:
- Decoding any frame fails
- The file cannot be read
§Examples
use ff_decode::AudioDecoder;
use ff_format::SampleFormat;
let mut decoder = AudioDecoder::open("audio.mp3")?
.output_format(SampleFormat::F32)
.build()?;
let samples = decoder.decode_all()?;
println!("Decoded {} bytes", samples.len());§Memory Usage
Stereo 48kHz F32 audio:
- 1 minute: ~11 MB
- 5 minutes: ~55 MB
- 10 minutes: ~110 MB
Sourcepub fn decode_range(
&mut self,
start: Duration,
end: Duration,
) -> Result<Vec<u8>, DecodeError>
pub fn decode_range( &mut self, start: Duration, end: Duration, ) -> Result<Vec<u8>, DecodeError>
Decodes all frames within a specified time range.
This method seeks to the start position and decodes all frames until the end position is reached. Frames outside the range are skipped.
§Arguments
start- Start of the time range (inclusive).end- End of the time range (exclusive).
§Returns
A byte vector containing audio samples within [start, end).
§Errors
Returns DecodeError if:
- Seeking to the start position fails
- Decoding frames fails
- The time range is invalid (start >= end)
§Examples
use ff_decode::AudioDecoder;
use std::time::Duration;
let mut decoder = AudioDecoder::open("audio.mp3")?.build()?;
// Decode audio from 5s to 10s
let samples = decoder.decode_range(
Duration::from_secs(5),
Duration::from_secs(10),
)?;
println!("Decoded {} bytes", samples.len());Sourcepub fn seek(
&mut self,
position: Duration,
mode: SeekMode,
) -> Result<(), DecodeError>
pub fn seek( &mut self, position: Duration, mode: SeekMode, ) -> Result<(), DecodeError>
Seeks to a specified position in the audio stream.
This method performs efficient seeking without reopening the file.
§Arguments
position- Target position to seek to.mode- Seek mode (Keyframe, Exact, or Backward).
§Errors
Returns DecodeError::SeekFailed if:
- The target position is beyond the audio duration
- The file format doesn’t support seeking
- The seek operation fails internally
§Examples
use ff_decode::{AudioDecoder, SeekMode};
use std::time::Duration;
let mut decoder = AudioDecoder::open("audio.mp3")?.build()?;
// Seek to 30 seconds with keyframe mode (fast)
decoder.seek(Duration::from_secs(30), SeekMode::Keyframe)?;
// Seek to exact position (slower but precise)
decoder.seek(Duration::from_secs(45), SeekMode::Exact)?;
// Decode next frame
if let Some(frame) = decoder.decode_one()? {
println!("Frame at {:?}", frame.timestamp().as_duration());
}