Symphonium

https://docs.rs/symphonium/0.12.2/symphonium/
Admin
Symphonium is an easy-to-use wrapper around Symphonia for loading audio files and handling...
Tokens:5,930
Snippets:70
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### probe_from_source(source: Box<dyn MediaSource>, hint: Option<Hint>, custom_probe: Option<&Probe>) -> Result<ProbedAudioSource, LoadError>

Source: https://docs.rs/symphonium/0.12.2/symphonium/fn.probe_from_source.html

Loads an audio source from RAM and probes its metadata. This method does not perform audio decoding.

```APIDOC
## probe_from_source

### Description
Loads an audio source from RAM and probes its metadata. This method does not decode the audio file.

### Signature
`pub fn probe_from_source(source: Box<dyn MediaSource>, hint: Option<Hint>, custom_probe: Option<&Probe>) -> Result<ProbedAudioSource, LoadError>`

### Parameters
- **source** (Box<dyn MediaSource>) - The MediaSource to probe.
- **hint** (Option<Hint>) - An optional hint that the probe can use to determine the codec.
- **custom_probe** (Option<&Probe>) - The custom Probe to use. If None, the default symphonia probe is used.

### Returns
- **Result<ProbedAudioSource, LoadError>** - Returns a ProbedAudioSource on success, or a LoadError if the operation fails.
```

--------------------------------

### ProbedAudioSource Methods

Source: https://docs.rs/symphonium/0.12.2/symphonium/struct.ProbedAudioSource.html

Methods available for interacting with a ProbedAudioSource instance.

```APIDOC
## pub fn new(format_reader: Box<dyn FormatReader>, sample_rate: Option<NonZeroU32>, num_channels: NonZeroUsize) -> Self

Creates a new ProbedAudioSource instance.

## pub fn format_reader(&self) -> &dyn FormatReader

Returns a reference to the underlying format reader.

## pub fn sample_rate(&self) -> Option<NonZeroU32>

Returns the sample rate of the audio source, or None if unknown.

## pub fn override_sample_rate(&mut self, sample_rate: NonZeroU32)

Overrides the sample rate of this resource. Useful when the initial sample rate is unknown.

## pub fn num_channels(&self) -> NonZeroUsize

Returns the number of channels in the audio source.
```

--------------------------------

### pub fn probe_from_file<P: AsRef<Path>>(path: P, custom_probe: Option<&Probe>) -> Result<ProbedAudioSource, LoadError>

Source: https://docs.rs/symphonium/0.12.2/symphonium/fn.probe_from_file.html

Loads an audio file from the provided path and probes its metadata. This function does not perform audio decoding.

```APIDOC
## probe_from_file

### Description
Load an audio file from the given path and probe its metadata. This method does not decode the audio file.

### Signature
`pub fn probe_from_file<P: AsRef<Path>>(path: P, custom_probe: Option<&Probe>) -> Result<ProbedAudioSource, LoadError>`

### Parameters
- **path** (P: AsRef<Path>) - Required - The path to the audio file.
- **custom_probe** (Option<&Probe>) - Optional - The custom `Probe` to use. If `None`, the default symphonia probe is used.

### Returns
- **Result<ProbedAudioSource, LoadError>** - Returns a `ProbedAudioSource` on success, or a `LoadError` if the operation fails.
```

--------------------------------

### Decode and process audio files with Symphonium

Source: https://docs.rs/symphonium/0.12.2/symphonium/index.html

Demonstrates how to probe an audio file, decode it with optional resampling and caching, and fill stereo buffers. Also shows the alternative approach for decoding directly to f32 format.

```rust
// A struct used to load audio files.
let target_sample_rate = NonZeroU32::new(44100).unwrap();

// An optional cache to re-use decoders and resamplers.
let cache = SymphoniumCache::default();

// Probe the audio file.
let probed = symphonium::probe_from_file(
    &file_path,
    // A custom codec prober. Set to `None` to use the default one from symphonia.
    None,
)
.unwrap();

// Decode the probed data.
let audio_data = symphonium::decode(
    probed,
    &DecodeConfig::default(),
    // Set to `None` to keep the original sample rate of the file.
    Some(target_sample_rate),
    // Set to `None` if no cache is needed.
    Some(&cache),
    // A custom codec registry. Set to `None` to use the default one from symphonia.
    None,
)
.unwrap();

// Fill a stereo buffer with samples starting at frame 100.
let mut buf_l = vec![0.0f32; 512];
let mut buf_r = vec![0.0f32; 512];
audio_data.fill_stereo(100, &mut buf_l, &mut buf_r);

// Alternatively, if you don't need to save memory, you can
// decode directly to an `f32` format.
let probed = symphonium::probe_from_file(&file_path, None).unwrap();
let audio_data_f32 = symphonium::decode_f32(
        probed,
        &DecodeConfig::default(),
        Some(target_sample_rate),
        Some(&cache),
        None,
    )
    .unwrap();

// Print info about the data (`data` is a `Vec<Vec<f32>>`).
println!("num channels: {}", audio_data_f32.data.len());
println!("num frames: {}", audio_data_f32.data[0].len());
```

--------------------------------

### Enable additional audio format features

Source: https://docs.rs/symphonium/0.12.2/symphonium/index.html

Shows how to add specific audio format support to the project via Cargo.toml feature flags.

```toml
symphonium = { version = "0.11", features = ["mp3", "flac"] }
```

--------------------------------

### DecodedAudioF32::new

Source: https://docs.rs/symphonium/0.12.2/symphonium/struct.DecodedAudioF32.html

Constructs a new DecodedAudioF32 resource with the provided audio data and sample rate information.

```APIDOC
## pub fn new(data: Vec<Vec<f32>>, sample_rate: NonZeroU32, original_sample_rate: NonZeroU32) -> Self

### Description
Constructs a new `DecodedAudioF32` resource.

### Parameters
- **data** (Vec<Vec<f32>>) - The deinterleaved audio data.
- **sample_rate** (NonZeroU32) - The sample rate of this resource.
- **original_sample_rate** (NonZeroU32) - The sample rate of the audio resource before it was resampled (if it was resampled).
```

--------------------------------

### probe_from_source function signature

Source: https://docs.rs/symphonium/0.12.2/symphonium/fn.probe_from_source.html

The function signature for loading and probing an audio source from RAM.

```rust
pub fn probe_from_source(
    source: Box<dyn MediaSource>,
    hint: Option<Hint>,
    custom_probe: Option<&Probe>,
) -> Result<ProbedAudioSource, LoadError>
```

--------------------------------

### probe_from_file Function Signature

Source: https://docs.rs/symphonium/0.12.2/symphonium/fn.probe_from_file.html

The function signature for probing audio metadata from a file path.

```rust
pub fn probe_from_file<P: AsRef<Path>>(
    path: P,
    custom_probe: Option<&Probe>,
) -> Result<ProbedAudioSource, LoadError>
```

--------------------------------

### Define ProbedAudioSource struct

Source: https://docs.rs/symphonium/0.12.2/symphonium/struct.ProbedAudioSource.html

The internal structure definition for ProbedAudioSource.

```rust
pub struct ProbedAudioSource { /* private fields */ }
```

--------------------------------

### DecodedAudio Methods

Source: https://docs.rs/symphonium/0.12.2/symphonium/struct.DecodedAudio.html

Methods available for interacting with the DecodedAudio resource.

```APIDOC
## pub fn new(resource_type: DecodedAudioType, sample_rate: NonZeroU32, original_sample_rate: NonZeroU32) -> Self

Constructs a new DecodedAudio resource.

## pub fn channels(&self) -> usize

Returns the number of channels in this resource.

## pub fn frames(&self) -> usize

Returns the length of this resource in frames.

## pub fn sample_rate(&self) -> NonZeroU32

Returns the sample rate of this resource in samples per second.

## pub fn original_sample_rate(&self) -> NonZeroU32

Returns the sample rate of the audio resource before it was resampled.

## pub fn fill_channel(&self, channel: usize, frame: usize, buf: &mut [f32]) -> Result<usize, FillChannelError>

Fills the buffer with samples from the given channel, starting from the given frame. Remaining samples are filled with zeros if the buffer exceeds resource length.

## pub fn fill_stereo(&self, frame: usize, buf_l: &mut [f32], buf_r: &mut [f32]) -> usize

Fills the stereo buffer with samples starting from the given frame. If the resource is mono, both channels are filled with the same data.
```

--------------------------------

### decode_f32

Source: https://docs.rs/symphonium/0.12.2/symphonium/index.html

Decodes the probed audio source and converts the output to an f32 sample format.

```APIDOC
## decode_f32

### Description
Decode the probed audio source and convert to an f32 sample format.

### Signature
`pub fn decode_f32(source: ProbedAudioSource, config: &DecodeConfig, target_sample_rate: Option<NonZeroU32>, cache: Option<&SymphoniumCache>, registry: Option<&CodecRegistry>) -> Result<DecodedAudioF32, Error>`
```

--------------------------------

### create_resampler

Source: https://docs.rs/symphonium/0.12.2/symphonium/resample/struct.ResamplerKey.html

Creates a new PacketResampler instance based on the configuration defined in the ResamplerKey.

```APIDOC
## pub fn create_resampler(&self) -> PacketResampler<f32, Sequential<f32>>

### Description
Creates a new PacketResampler instance using the parameters defined in the current ResamplerKey instance.

### Returns
- **PacketResampler<f32, Sequential<f32>>** - A configured resampler instance.
```

--------------------------------

### pub fn decode

Source: https://docs.rs/symphonium/0.12.2/symphonium/fn.decode.html

Decodes a probed audio source and optionally resamples it to a target sample rate.

```APIDOC
## pub fn decode

### Description
Decode a probed audio source, and resample if the source sample rate does not match the given target sample rate. The probed audio source can be loaded with `probe_from_file` or `probe_from_source`.

### Signature
```rust
pub fn decode(
    probed: ProbedAudioSource,
    config: &DecodeConfig,
    target_sample_rate: Option<NonZeroU32>,
    cache: Option<&dyn Cache>,
    custom_registry: Option<&CodecRegistry>,
) -> Result<DecodedAudio, LoadError>
```

### Parameters
- **probed** (ProbedAudioSource) - The probed audio source.
- **config** (&DecodeConfig) - Additional decoding settings like resampling quality.
- **target_sample_rate** (Option<NonZeroU32>) - The sample rate the file will be resampled to. If None, or if the resample feature is disabled, no resampling occurs.
- **cache** (Option<&dyn Cache>) - An optional cache to use. If None, no caching will occur.
- **custom_registry** (Option<&CodecRegistry>) - The custom CodecRegistry to use. If None, the default symphonia codec registry is used.

### Returns
- **Result<DecodedAudio, LoadError>** - Returns the decoded audio or a load error.
```

--------------------------------

### Function signature for decode

Source: https://docs.rs/symphonium/0.12.2/symphonium/fn.decode.html

The signature defines the parameters for decoding, including the probed source, configuration, target sample rate, cache, and codec registry.

```rust
pub fn decode(
    probed: ProbedAudioSource,
    config: &DecodeConfig,
    target_sample_rate: Option<NonZeroU32>,
    cache: Option<&dyn Cache>,
    custom_registry: Option<&CodecRegistry>,
) -> Result<DecodedAudio, LoadError>
```

--------------------------------

### DecodedAudioF32::channels

Source: https://docs.rs/symphonium/0.12.2/symphonium/struct.DecodedAudioF32.html

Returns the number of channels in the audio resource.

```APIDOC
## pub fn channels(&self) -> usize

### Description
Returns the number of channels in this resource.
```

--------------------------------

### Accessing DEFAULT_MAX_BYTES

Source: https://docs.rs/symphonium/0.12.2/symphonium/constant.DEFAULT_MAX_BYTES.html

The constant represents the default maximum size of an audio file in bytes.

```rust
pub const DEFAULT_MAX_BYTES: usize = 1_000_000_000;
```

--------------------------------

### DecodeConfig Struct Definition

Source: https://docs.rs/symphonium/0.12.2/symphonium/struct.DecodeConfig.html

The structure definition for DecodeConfig, outlining the available configuration fields for audio decoding.

```rust
pub struct DecodeConfig {
    pub max_bytes: usize,
    pub default_alloc_frames: usize,
    pub verify: bool,
    pub gapless: bool,
    pub cache_decoder: bool,
    pub cache_resampler: bool,
    pub track_index: Option<usize>,
    pub resample_quality: ResampleQuality,
}
```

--------------------------------

### decode

Source: https://docs.rs/symphonium/0.12.2/symphonium/index.html

Decodes a probed audio source, applying resampling if the source sample rate differs from the target.

```APIDOC
## decode

### Description
Decode a probed audio source, and resample if the source sample rate does not match the given target sample rate.

### Signature
`pub fn decode(source: ProbedAudioSource, config: &DecodeConfig, target_sample_rate: Option<NonZeroU32>, cache: Option<&SymphoniumCache>, registry: Option<&CodecRegistry>) -> Result<DecodedAudio, Error>`
```

--------------------------------

### ResamplerKey Struct Definition

Source: https://docs.rs/symphonium/0.12.2/symphonium/resample/struct.ResamplerKey.html

The structure definition for ResamplerKey, containing the necessary fields for configuring a resampler.

```rust
pub struct ResamplerKey {
    pub source_sample_rate: NonZeroU32,
    pub target_sample_rate: NonZeroU32,
    pub channels: u16,
    pub quality: u16,
}
```

--------------------------------

### DecodedAudioF32::frames

Source: https://docs.rs/symphonium/0.12.2/symphonium/struct.DecodedAudioF32.html

Returns the length of the audio resource in frames.

```APIDOC
## pub fn frames(&self) -> usize

### Description
Returns the length of this resource in frames (length of a single channel in samples).
```

--------------------------------

### Define DecodedAudioF32 struct

Source: https://docs.rs/symphonium/0.12.2/symphonium/struct.DecodedAudioF32.html

The structure definition for DecodedAudioF32, containing the audio data and sample rate information.

```rust
pub struct DecodedAudioF32 {
    pub data: Vec<Vec<f32>>,
    pub sample_rate: NonZeroU32,
    pub original_sample_rate: NonZeroU32,
}
```

--------------------------------

### DecodeStretchedConfig Struct Definition

Source: https://docs.rs/symphonium/0.12.2/symphonium/struct.DecodeStretchedConfig.html

The structure definition for configuring audio stretching, requiring both a DecodeConfig and SincInterpolationParameters.

```rust
pub struct DecodeStretchedConfig {
    pub config: DecodeConfig,
    pub resampler_config: SincInterpolationParameters,
}
```

--------------------------------

### decode_stretched

Source: https://docs.rs/symphonium/0.12.2/symphonium/fn.decode_stretched.html

Decodes a probed audio source and applies stretching (pitch/time shift) and optional resampling.

```APIDOC
## decode_stretched

### Description
Decodes the probed audio source and converts it to an f32 sample format. The sample is stretched (pitch/time shifted) by the specified amount.

### Signature
```rust
pub fn decode_stretched(
    probed: ProbedAudioSource,
    stretch: f64,
    target_sample_rate: Option<NonZeroU32>,
    config: &DecodeStretchedConfig,
    cache: Option<&dyn Cache>,
    custom_registry: Option<&CodecRegistry>,
) -> Result<DecodedAudioF32, LoadError>
```

### Parameters
- **probed** (ProbedAudioSource) - The probed audio source (loaded via probe_from_file or probe_from_source).
- **stretch** (f64) - The amount of stretching (new_length / old_length). 1.0 is no change, < 1.0 increases pitch/decreases length, > 1.0 decreases pitch/increases length.
- **target_sample_rate** (Option<NonZeroU32>) - Optional sample rate for resampling. If None, the original sample rate is preserved.
- **config** (&DecodeStretchedConfig) - Extra configuration for the decoding process.
- **cache** (Option<&dyn Cache>) - Optional cache instance to use.
- **custom_registry** (Option<&CodecRegistry>) - Optional custom codec registry. If None, the default symphonia registry is used.

### Returns
- **Result<DecodedAudioF32, LoadError>** - Returns the decoded audio in f32 format or a LoadError if the operation fails.
```

--------------------------------

### decode_f32 Function Signature

Source: https://docs.rs/symphonium/0.12.2/symphonium/fn.decode_f32.html

The function signature for decoding audio into f32 samples, requiring a probed source and configuration parameters.

```rust
pub fn decode_f32(
    probed: ProbedAudioSource,
    config: &DecodeConfig,
    target_sample_rate: Option<NonZeroU32>,
    cache: Option<&dyn Cache>,
    custom_registry: Option<&CodecRegistry>,
) -> Result<DecodedAudioF32, LoadError>
```

--------------------------------

### DecodedAudio Struct Definition

Source: https://docs.rs/symphonium/0.12.2/symphonium/struct.DecodedAudio.html

The primary structure for storing deinterleaved audio samples.

```rust
pub struct DecodedAudio { /* private fields */ }
```

--------------------------------

### Cache Trait Definition

Source: https://docs.rs/symphonium/0.12.2/symphonium/cache/trait.Cache.html

The core trait definition for caching audio decoders and resamplers in symphonium.

```rust
pub trait Cache {
    // Required methods
    fn with_decoder_mut(
        &self,
        probed: ProbedAudioSource,
        options: &AudioDecoderOptions,
        codec_registry: &CodecRegistry,
        track_index: Option<usize>,
        f: &mut dyn FnMut(ProbedAudioSource, &mut dyn AudioDecoder),
    ) -> Result<(), LoadError>;
    fn with_resampler_mut(
        &self,
        key: ResamplerKey,
        probed: ProbedAudioSource,
        f: &mut dyn FnMut(ProbedAudioSource, &mut PacketResampler<f32, Sequential<f32>>),
    );
}
```

--------------------------------

### decode_stretched function signature

Source: https://docs.rs/symphonium/0.12.2/symphonium/fn.decode_stretched.html

The function signature for decoding and stretching audio, requiring a probed source, stretch factor, configuration, and optional cache/registry.

```rust
pub fn decode_stretched(
    probed: ProbedAudioSource,
    stretch: f64,
    target_sample_rate: Option<NonZeroU32>,
    config: &DecodeStretchedConfig,
    cache: Option<&dyn Cache>,
    custom_registry: Option<&CodecRegistry>,
) -> Result<DecodedAudioF32, LoadError>
```

--------------------------------

### DecodedAudioType Enum Definition

Source: https://docs.rs/symphonium/0.12.2/symphonium/enum.DecodedAudioType.html

The structure of the DecodedAudioType enum, representing different audio sample formats.

```rust
pub enum DecodedAudioType {
    U8(Vec<Vec<u8>>),
    S8(Vec<Vec<i8>>),
    U16(Vec<Vec<u16>>),
    S16(Vec<Vec<i16>>),
    U24(Vec<Vec<[u8; 3]>>),
    U32(Vec<Vec<u32>>),
    S32(Vec<Vec<i32>>),
    F32(Vec<Vec<f32>>),
    F64(Vec<Vec<f64>>),
}
```

--------------------------------

### Define FillChannelError struct

Source: https://docs.rs/symphonium/0.12.2/symphonium/struct.FillChannelError.html

The structure definition for FillChannelError, containing fields for the index obtained and the total channel count.

```rust
pub struct FillChannelError {
    pub got_index: usize,
    pub num_channels: usize,
}
```

--------------------------------

### LoadError Enum Definition

Source: https://docs.rs/symphonium/0.12.2/symphonium/error/enum.LoadError.html

The primary enum structure defining all possible error variants for audio loading.

```rust
pub enum LoadError {
Show 13 variants    FileNotFound(Error),
    UnkownFormat(Error),
    NoAudioTrackFound,
    TrackIndexOutOfBounds {
        index: usize,
        num_tracks: usize,
    },
    NoAudioChannelsFound,
    NoAudioCodecFound,
    UnkownSampleType,
    UnkownChannelFormat(usize),
    FileTooLarge(usize),
    CouldNotCreateDecoder(Error),
    ErrorWhileDecoding(Error),
    InvalidResampler {
        needed_channels: usize,
        got_channels: usize,
    },
    ErrorWhileResampling(ResampleError),
}
```

--------------------------------

### Define ResampleQuality Enum

Source: https://docs.rs/symphonium/0.12.2/symphonium/enum.ResampleQuality.html

The structure of the ResampleQuality enum, which provides four levels of resampling quality.

```rust
pub enum ResampleQuality {
    VeryLow,
    Low,
    High,
    HighWithLowLatency,
}
```
Tokens:
Raw