<div align="center">
<h1>Symphonia</h1>
[<img alt="Crates.io" src="https://img.shields.io/crates/v/symphonia?style=for-the-badge" height="22"/>](https://crates.io/crates/symphonia)
[<img alt="Docs.rs" src="https://img.shields.io/badge/docs.rs-symphonia-brightgreen?style=for-the-badge" height="22"/>](https://docs.rs/symphonia)
[<img alt="GitHub Actions Status" src="https://img.shields.io/github/actions/workflow/status/pdeljanov/symphonia/ci.yml?branch=main&style=for-the-badge" height="22"/>](https://github.com/pdeljanov/Symphonia/actions/workflows/ci.yml)
[<img alt="Deps.rs" src="https://deps.rs/repo/github/pdeljanov/symphonia/status.svg?style=for-the-badge" height="22"/>](https://deps.rs/repo/github/pdeljanov/symphonia)
[<img alt="Crates.io MSRV" src="https://img.shields.io/crates/msrv/symphonia?style=for-the-badge" height="22"/>](https://blog.rust-lang.org/2025/02/20/Rust-1.85.0/)
[<img alt="MPL License" src="https://img.shields.io/crates/l/symphonia?style=for-the-badge" height="22"/>](https://www.mozilla.org/en-US/MPL/2.0/)
<p>
<strong>
Symphonia is a pure Rust audio decoding and media demuxing library supporting AAC, ADPCM, AIFF, ALAC, CAF, FLAC, MKV, MP1, MP2, MP3, MP4, OGG, Vorbis, WAV, and WebM.
</strong>
</p>
<p>
<h3>
<a href="https://github.com/pdeljanov/Symphonia/blob/main/GETTING_STARTED.md">Getting Started</a>
<span> · </span>
<a href="https://docs.rs/symphonia">Documentation</a>
<span> · </span>
<a href="https://github.com/pdeljanov/Symphonia/tree/main/symphonia/examples">Examples</a>
<span> · </span>
<a href="https://github.com/pdeljanov/Symphonia/blob/main/BENCHMARKS.md">Benchmarks</a>
</h3>
</p>
</div>
---
## Features
* Decode support for the most popular audio codecs with support for gapless playback
* Demux the most common media container formats
* Read most metadata and tagging formats
* Automatic format and decoder detection
* Basic audio primitives for manipulating audio data efficiently
* 100% safe Rust
* Minimal dependencies
* Fast with no compromises in performance!
Additionally, planned features include:
* Providing a C API for integration into other languages
* Providing a WASM API for web usage
## Current Support
Support for individual audio codecs and media formats are provided by separate crates. By default, Symphonia only enables support royalty-free open standard codecs and formats, but others may be enabled using feature flags.
> [!TIP]
> All formats and codecs can be enabled with the `all` feature flag.
### Status
The following status classifications are used to determine the state of development for each format or codec.
| Good | Many media streams play. Some streams may panic, error, or produce audible glitches. Some features may not be supported. |
| Great | Most media streams play. Inaudible glitches may be present. Most common features are supported. |
| Excellent | All media streams play. No audible or inaudible glitches. All required features are supported. |
A status of *Great* indicates that major development is complete and that the feature is in a state that would be acceptable for most applications to use.
A status of *Excellent* is only assigned after the feature passes all compliance tests. If no compliance tests are readily available, then a status of *Excellent* will be assigned if Symphonia's output matches that of a reference implementation, or `ffmpeg`, over a large test corpus.
### Formats (Demuxers)
| AIFF | Great | Yes | `aiff` | No | [`symphonia-format-riff`] |
| CAF | Good | No | `caf` | No | [`symphonia-format-caf`] |
| ISO/MP4 | Great | No | `isomp4` | No | [`symphonia-format-isomp4`] |
| MKV/WebM | Good | No | `mkv` | Yes | [`symphonia-format-mkv`] |
| OGG | Great | Yes | `ogg` | Yes | [`symphonia-format-ogg`] |
| Wave | Excellent | Yes | `wav` | Yes | [`symphonia-format-riff`] |
\* Gapless playback requires support from both the demuxer and decoder.
[`symphonia-format-caf`]: https://crates.io/crates/symphonia-format-caf
[`symphonia-format-isomp4`]: https://crates.io/crates/symphonia-format-isomp4
[`symphonia-format-mkv`]: https://crates.io/crates/symphonia-format-mkv
[`symphonia-format-ogg`]: https://crates.io/crates/symphonia-format-ogg
[`symphonia-format-riff`]: https://crates.io/crates/symphonia-format-riff
> [!TIP]
> All formats can be enabled with the `all-formats` feature flag.
### Codecs (Decoders)
| AAC-LC | Great | No | `aac` | No | [`symphonia-codec-aac`] |
| ADPCM | Good | Yes | `adpcm` | Yes | [`symphonia-codec-adpcm`] |
| ALAC | Great | Yes | `alac` | No | [`symphonia-codec-alac`] |
| FLAC | Excellent | Yes | `flac` | Yes | [`symphonia-bundle-flac`] |
| MP1 | Great | No | `mp1`, `mpa` | No | [`symphonia-bundle-mp3`] |
| MP2 | Great | No | `mp2`, `mpa` | No | [`symphonia-bundle-mp3`] |
| MP3 | Excellent | Yes | `mp3`, `mpa` | No | [`symphonia-bundle-mp3`] |
| PCM | Excellent | Yes | `pcm` | Yes | [`symphonia-codec-pcm`] |
| Vorbis | Excellent | Yes | `vorbis` | Yes | [`symphonia-codec-vorbis`] |
A `symphonia-bundle-*` package is a combination of a decoder and a native demuxer.
[`symphonia-codec-aac`]: https://crates.io/crates/symphonia-codec-aac
[`symphonia-codec-adpcm`]: https://crates.io/crates/symphonia-codec-adpcm
[`symphonia-codec-alac`]: https://crates.io/crates/symphonia-codec-alac
[`symphonia-bundle-flac`]: https://crates.io/crates/symphonia-bundle-flac
[`symphonia-bundle-mp3`]: https://crates.io/crates/symphonia-bundle-mp3
[`symphonia-codec-pcm`]: https://crates.io/crates/symphonia-codec-pcm
[`symphonia-codec-vorbis`]: https://crates.io/crates/symphonia-codec-vorbis
> [!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.
### Tags (Readers)
All metadata readers are provided by the `symphonia-metadata` crate.
For metadata formats that are standalone and not part of the media container, a feature flag may be used to toggle support.
| APEv1 | Great | `ape` | Yes |
| APEv2 | Great | `ape` | Yes |
| ID3v1 | Great | `id3v1` | Yes |
| ID3v2 | Great | `id3v2` | Yes |
| ISO/MP4 | Great | N/A | N/A |
| RIFF | Great | N/A | N/A |
| Vorbis comment (FLAC) | Perfect | N/A | N/A |
| Vorbis comment (OGG) | Perfect | N/A | N/A |
> [!TIP]
> All metadata formats can be enabled with the `all-meta` feature flag.
### Third-party Demuxers and Decoders
Symphonia is a designed around a modular framework that allows the registration of third-party demuxers and decoders. This table provides a list of crates that implement such components.
> [!IMPORTANT]
> This is not an endorsement of the quality, safety, or performance of these implementations. Please exercise your own judgement.
| [`symphonia-adapter-fdk-aac`] | AAC-LC, HE-AAC, & HE-AACv2 via. `libfdk-aac` |
| [`symphonia-adapter-libopus`] | Opus via. `libopus` |
[`symphonia-adapter-fdk-aac`]: https://crates.io/crates/symphonia-adapter-fdk-aac
[`symphonia-adapter-libopus`]: https://crates.io/crates/symphonia-adapter-libopus
## Quality
In addition to the safety guarantees afforded by Rust, Symphonia aims to:
* Decode media as correctly as the leading free-and-open-source software decoders
* Prevent denial-of-service attacks
* Be fuzz-tested
* Provide a powerful, consistent, and easy to use API
## Performance
Symphonia aims to be comparable to, or faster than, popular open-source C-based implementations. Currently, Symphonia's decoders are generally +/-15% the performance of FFMpeg. However, the exact range will depend strongly on the codec, which features of the codec are being leveraged in the encoding, the Rust compiler version, and the CPU architecture being compiled for.
See the [benchmarks](https://github.com/pdeljanov/Symphonia/blob/main/BENCHMARKS.md) for more information.
### Optimizations
All SIMD optimizations are enabled by default. SIMD support will pull in the `rustfft` dependency.
| SSE | `opt-simd-sse` | Yes |
| AVX | `opt-simd-avx` | Yes |
| Neon | `opt-simd-neon` | Yes |
> [!TIP]
> All SIMD optimizations can be enabled with the `opt-simd` feature flag.
## Examples
Basic usage examples may be found [`here`](https://github.com/pdeljanov/Symphonia/tree/main/symphonia/examples).
For a more complete application, see [`symphonia-play`](https://github.com/pdeljanov/Symphonia/blob/main/symphonia-play), a simple music player.
## Tools
Symphonia provides the following tools for debugging purposes:
* [`symphonia-play`](https://github.com/pdeljanov/Symphonia/blob/main/symphonia-play) for probing, decoding, validating, and playing back media streams.
* [`symphonia-check`](https://github.com/pdeljanov/Symphonia/blob/main/symphonia-check) for validating Symphonia's decoded output against various decoders.
## Minimum Supported Rust Version
The minimum supported Rust version (MSRV) for Symphonia 0.6.x releases is 1.85.
This project considers incrementing the MSRV to be a SemVer breaking change.
## Author
The primary author is Philip Deljanov.
## Special Thanks
* Kostya Shishkov (AAC-LC decoder contribution, see `symphonia-codec-aac`)
## License
Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE file for more details.
## Contributing
Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/blob/main/CONTRIBUTING.md).