Crate symphonia

source ·
Expand description

Project Symphonia

Symphonia is a 100% pure Rust audio decoding and multimedia format demuxing framework.


Supported formats, codecs, and metadata tags are listed below. By default Symphonia only enables royalty-free open standard media formats and codecs. Other formats and codecs must be enabled using feature flags.

Tip: All formats and codecs can be enabled with the all feature flag.


The following container formats are supported.

FormatFeature FlagGapless*Default

* Gapless playback requires support from both the demuxer and decoder.

Tip: All formats can be enabled with the all-codecs feature flag.


The following codecs are supported.

CodecFeature FlagGaplessDefault
MP1mp1, mpaNoNo
MP2mp2, mpaNoNo
MP3mp3, mpaYesNo

Tip: All codecs can be enabled with the all-codecs feature flag. Similarly, all MPEG audio codecs can be enabled with the mpa feature flag.


The following metadata tagging formats are supported. These are always enabled.

  • ID3v1
  • ID3v2
  • ISO/MP4
  • RIFF
  • Vorbis Comment (in OGG & FLAC)


The following steps describe a basic usage of Symphonia:

  1. Instantiate a CodecRegistry and register all the codecs that are of interest. Alternatively, you may use default::get_codecs to get the default registry with all the enabled codecs pre-registered. The registry will be used to instantiate a Decoder later.
  2. Instantiate a Probe and register all the formats that are of interest. Alternatively, you may use default::get_probe to get a default format probe with all the enabled formats pre-registered. The probe will be used to automatically detect the media format and instantiate a compatible FormatReader.
  3. Make sure the MediaSource trait is implemented for whatever source you are using. This trait is already implemented for std::fs::File and std::io::Cursor.
  4. Instantiate a MediaSourceStream with the MediaSource above.
  5. Using the Probe, call format and pass it the MediaSourceStream.
  6. If the probe successfully detects a compatible format, a FormatReader will be returned. This is an instance of a demuxer that can read and demux the provided source into Packets.
  7. At this point it is possible to interrogate the FormatReader for general information about the media and metadata. Examine the Track listing using tracks and select one or more tracks of interest to decode.
  8. To instantiate a Decoder for a selected Track, call the CodecRegistry’s make function and pass it the CodecParameters for that track. This step is repeated once per selected track.
  9. To decode a track, obtain a packet from the FormatReader by calling next_packet and then pass the Packet to the Decoder for that track. The decode function will read a packet and return an AudioBufferRef (an “any-type” AudioBuffer).
  10. The AudioBufferRef may be used to access the decoded audio samples directly, or it can be copied into a SampleBuffer or RawSampleBuffer to export the audio out of Symphonia.
  11. Repeat step 9 and 10 until the end-of-stream error is returned.

An example implementation of a simple audio player (symphonia-play) can be found in the Project Symphonia git repository.

Gapless Playback

Gapless playback is disabled by default. To enable gapless playback, set FormatOptions::enable_gapless to true.

Adding new formats and codecs

Simply implement the Decoder trait for a decoder or the FormatReader trait for a demuxer trait and register with the appropriate registry or probe!



  • The default module provides convenience functions and registries to get an implementer up-and-running as quickly as possible, and to reduce boiler-plate. Using the default module is completely optional and incurs no overhead unless actually used.