MP3 Codec

MPEG-1/2 Audio Layer I, II, and III decoder and demuxer

Overview

Symphonia provides a complete pure Rust implementation of the MPEG Audio (MP1, MP2, MP3) decoder and demuxer. The implementation supports all three MPEG audio layers with high quality decoding.

Feature Flags

The MP3 bundle supports granular feature flags for each layer:

[dependencies]
# Enable all MPEG audio layers (default)
symphonia = { version = "0.5", features = ["mp1", "mp2", "mp3"] }

# Or use the mpa shorthand for all layers
symphonia = { version = "0.5", features = ["mpa"] }

# Enable only MP3 (Layer III)
symphonia = { version = "0.5", features = ["mp3"] }

Or use the standalone crate:

[dependencies]
symphonia-bundle-mp3 = { version = "0.5", features = ["mp1", "mp2", "mp3"] }

Available Features

• mp1 - MPEG Audio Layer I
• mp2 - MPEG Audio Layer II
• mp3 - MPEG Audio Layer III

By default, the standalone crate enables all three features.

Status

Status: Excellent

• Decoding: Fully supported for all layers
• Gapless Playback: Yes (with LAME headers)
• Streaming: Yes

Codec Type

use symphonia::core::codecs::CODEC_TYPE_MP3;
use symphonia::core::codecs::CODEC_TYPE_MP2;
use symphonia::core::codecs::CODEC_TYPE_MP1;

Decoder

The MPEG Audio decoder is implemented by the MpaDecoder struct (formerly Mp3Decoder):

use symphonia_bundle_mp3::MpaDecoder;
use symphonia::core::codecs::{Decoder, DecoderOptions};

// Create decoder from codec parameters
let mut decoder = MpaDecoder::try_new(&codec_params, &DecoderOptions::default())?;

// Decode a packet
let decoded = decoder.decode(&packet)?;

Format Reader

For raw MPEG audio files, use the MpaReader (formerly Mp3Reader):

use symphonia_bundle_mp3::MpaReader;
use symphonia::core::formats::{FormatReader, FormatOptions};
use symphonia::core::io::MediaSourceStream;

let mss = MediaSourceStream::new(source, Default::default());
let mut reader = MpaReader::try_new(mss, &FormatOptions::default())?;

// Read packets
while let Ok(packet) = reader.next_packet() {
    // Decode packet...
}

Supported Variants

Layer I (MP1)

• MPEG-1 Layer I
• MPEG-2 Layer I
• MPEG-2.5 Layer I
• Bitrates: 32-448 kbps

Layer II (MP2)

• MPEG-1 Layer II
• MPEG-2 Layer II
• MPEG-2.5 Layer II
• Bitrates: 8-384 kbps
• Commonly used in broadcast applications

Layer III (MP3)

• MPEG-1 Layer III
• MPEG-2 Layer III
• MPEG-2.5 Layer III
• Bitrates: 8-320 kbps
• Variable Bitrate (VBR)
• Constant Bitrate (CBR)
• Average Bitrate (ABR)

Sample Rates

MPEG-1:

• 32 kHz
• 44.1 kHz
• 48 kHz

MPEG-2:

• 16 kHz
• 22.05 kHz
• 24 kHz

MPEG-2.5:

• 8 kHz
• 11.025 kHz
• 12 kHz

Channel Modes

• Mono
• Stereo
• Joint Stereo (intensity stereo and/or M/S stereo)
• Dual Channel

Gapless Playback

Supports gapless playback with LAME encoder headers:

use symphonia::core::formats::Packet;

// Decoder automatically handles encoder delay and padding
let decoded = decoder.decode(&packet)?;

// Access trim information from the packet
let start_trim = packet.trim_start();
let end_trim = packet.trim_end();

Metadata Support

Supports ID3v1, ID3v2, and APEv2 tags:

use symphonia::core::meta::MetadataOptions;

let probed = symphonia::default::get_probe()
    .format(&hint, mss, &FormatOptions::default(), &MetadataOptions::default())?;

// Access metadata
if let Some(metadata_rev) = probed.format.metadata().current() {
    for tag in metadata_rev.tags() {
        println!("{}: {}", tag.key, tag.value);
    }
}

// Access embedded images (e.g., album art)
for visual in metadata_rev.visuals() {
    println!("Image type: {:?}", visual.usage);
    println!("Image format: {:?}", visual.media_type);
    // visual.data contains the image bytes
}

Usage Example

use symphonia::core::codecs::{CODEC_TYPE_MP3, DecoderOptions};
use symphonia::core::formats::FormatOptions;
use symphonia::core::io::MediaSourceStream;
use symphonia::core::meta::MetadataOptions;
use symphonia::core::probe::Hint;
use std::fs::File;

fn decode_mp3_file(path: &str) -> Result<(), Box<dyn std::error::Error>> {
    // Open the media source
    let file = Box::new(File::open(path)?);
    let mss = MediaSourceStream::new(file, Default::default());

    // Create a hint
    let mut hint = Hint::new();
    hint.with_extension("mp3");

    // Probe the media source
    let probed = symphonia::default::get_probe()
        .format(&hint, mss, &FormatOptions::default(), &MetadataOptions::default())?;

    let mut format = probed.format;
    let track = &format.tracks()[0];

    println!("Codec: {:?}", track.codec_params.codec);
    println!("Sample Rate: {:?}", track.codec_params.sample_rate);
    println!("Channels: {:?}", track.codec_params.channels);
    println!("Bitrate: {:?}", track.codec_params.max_bitrate);

    // Create the decoder
    let mut decoder = symphonia::default::get_codecs()
        .make(&track.codec_params, &DecoderOptions::default())?;

    // Decode packets
    loop {
        let packet = match format.next_packet() {
            Ok(packet) => packet,
            Err(_) => break,
        };

        let decoded = decoder.decode(&packet)?;
        // Process decoded audio...
    }

    Ok(())
}

Seeking Support

Supports seeking with and without seeking tables:

use symphonia::core::formats::{SeekMode, SeekTo};

// Seek to 30 seconds
let seek_to = SeekTo::Time { time: 30.0, track_id: None };
format.seek(SeekMode::Accurate, seek_to)?;

Performance

• Pure Rust implementation with no unsafe code
• Optimized synthesis filter bank
• Efficient Huffman decoding
• Memory efficient streaming decoder

Limitations

• Free format bitstreams are not supported
• Some exotic non-standard variations may not decode correctly

Documentation

• crates.io
• API Documentation
• MPEG Audio Specification (ISO/IEC 11172-3)

See Also

• Core Concepts
• Decoding Guide
• Metadata