Crate symphonia

Project Symphonia

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

Support

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.

Formats

The following container formats are supported.

Format	Feature Flag	Gapless*	Default
AIFF	aiff	Yes	No
CAF	caf	No	No
ISO/MP4	isomp4	No	No
MKV/WebM	mkv	No	Yes
OGG	ogg	Yes	Yes
Wave	wav	Yes	Yes

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

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

Codecs

The following codecs are supported.

Codec	Feature Flag	Gapless	Default
AAC-LC	aac	No	No
ADPCM	adpcm	Yes	Yes
ALAC	alac	Yes	No
FLAC	flac	Yes	Yes
MP1	mp1, mpa	No	No
MP2	mp2, mpa	No	No
MP3	mp3, mpa	Yes	No
PCM	pcm	Yes	Yes
Vorbis	vorbis	Yes	Yes

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.

Metadata

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

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

Optimizations

SIMD optimizations are not enabled by default. They may be enabled on a per-instruction set basis using the following feature flags. Enabling any SIMD support feature flags will pull in the rustfft dependency.

Instruction Set	Feature Flag	Default
SSE	opt-simd-sse	No
AVX	opt-simd-avx	No
Neon	opt-simd-neon	No

Tip: All SIMD optimizations can be enabled with the opt-simd feature flag.

Usage

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!

Re-exports

pub use symphonia_core as core;

Modules

default

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.