# Rodio: a Rust audio playback library that hides the audio thread

> Rodio wraps cpal for output and Symphonia for decoding behind a source graph you can stack, mix and seek. It is mid-rewrite, its documentation admits the core engine is under-documented, and its examples are pinned to a specific commit.

**RustAudio/rodio** — Rust audio playback library

- Repository: https://github.com/RustAudio/rodio
- Stars: 2,478 · Forks: 335
- Language: Rust
- License: Apache-2.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/rustaudio-rodio

## What Rodio solves for Rust programs that need to make sound

Getting audio out of a machine from Rust means dealing with a platform audio host, a callback that runs on a real-time thread, a ring buffer between your code and that callback, and a decoder for whatever file format you loaded. Rodio exists to collapse that into a source graph. The README states playback is handled by cpal and format decoding by Symphonia by default, with optional decoders for FLAC (claxon), MP3 (minimp3), Vorbis (lewton) and WAV (hound).

The audience is Rust application developers, not audio engineers. The stated goals are a simple API where you should not need to know anything about audio, a zero cost abstraction, and extensibility so missing pieces are easy to add. Those goals explain the design: you build a Source, hand it to an output stream, and the library owns the callback and the buffering.

It is the wrong tool if you are writing a DAW, a plugin host, or anything that needs sample-accurate scheduling across multiple devices. Rodio is a playback and recording library, and its own description says exactly that.

## The source graph, cpal and the decoder split

The architecture visible in the repository is three layers. At the bottom, cpal opens the device and runs the real-time callback. In the middle, Rodio's engine pulls samples from a Source and pushes them to that callback. At the top, decoders turn compressed or container formats into samples. The examples directory shows the shape of the top layer: music_mp3.rs, music_flac.rs, music_ogg.rs, music_opus.rs, music_wav.rs, music_m4a.rs.

Sources compose. The examples include mix_multiple_sources.rs, low_pass.rs, reverb.rs, distortion.rs, automatic_gain_control.rs, resample.rs and limit_wav.rs. Each of those is a wrapper that takes a source and returns a source, which is why the README can claim zero cost: the wrappers are generic and the compiler inlines the chain into the callback.

On Linux the host selection order is documented as PipeWire, then PulseAudio, then ALSA, falling back when a host is not compiled in or not available at runtime. ALSA is always required as the base layer. That ordering is a runtime decision, not a build-time one, which means a binary built with the pipewire feature can still land on ALSA on a machine without PipeWire running.

## Installing Rodio and playing a file

Add the crate with Cargo. The version in the repository manifest is 0.22.2, and the README's minimal-build example pins 0.22.1, so check crates.io for the current release rather than copying a version blindly.

```bash
cargo add rodio
```

On Debian or Ubuntu you need the ALSA development headers before the default build will link, because ALSA is always required as the base audio layer. On Fedora the package is named differently.

```bash
sudo apt install libasound2-dev
```

The pulseaudio feature, which is on by default, needs no development libraries because pulseaudio-rs is pure Rust. The optional pipewire feature does need libpipewire-0.3-dev and libdbus-1-dev on Debian and Ubuntu.

If you only need to decode and process audio, disable default features. The README gives this manifest shape and points at the into_file example, which is useful on machines where ALSA is not available.

```toml
[dependencies]
rodio = { version = "0.22.1", default-features = false, features = ["symphonia-all"] }
```

One caveat before you start: the README warns that the examples may not work with the current crates.io release, and directs readers to the examples at commit f7aa48d. If a snippet from master does not compile against your pinned version, that is the documented reason.

## The rewrite warning is the first thing to read

The README opens with a warning that Rodio's core audio engine is being rewritten, that the current state should be working but is under-documented, and that the work is expected to take at least a month. A tracking issue is linked, and an older checkout is offered for the pre-rewrite work.

This is the honest limitation. It is not that Rodio is broken; it is that the documentation for the current engine is admitted to be incomplete, and the examples are pinned to a commit rather than to the release. Anyone adopting Rodio should expect to read source and the tracking issue, not just docs.rs.

There is a second, quieter limitation in the manifest. The default feature set includes playback and recording, but the README's prose covers playback. If you need recording, the feature exists and depends on cpal and rtrb, but do not expect the README to walk you through it.

The MSRV policy is a rolling one: at least six months, and any new minimum must have been released at least six months before Rodio raises it. The manifest currently declares rust-version 1.95. If you are on an older toolchain, that is a hard build failure, not a warning.

## Cross-compiling Rodio to aarch64, and why it is awkward

The ALSA dependency is what makes cross-compilation hard, and the README says so directly, pointing at cpal's own guides and then supplying the aarch64 instructions cpal omits. The steps on a Debian-like host install a cross toolchain and clang, add the Rust target, enable arm64 in dpkg, install the multi-arch ALSA headers, then build with the pkg-config sysroot and linker overridden.

```bash
sudo apt-get install crossbuild-essential-arm64 clang
rustup target add aarch64-unknown-linux-gnu
sudo dpkg --add-architecture arm64
sudo apt install libasound2-dev:arm64
PKG_CONFIG_SYSROOT_DIR=/usr/aarch64-linux-gnu RUSTFLAGS="-C linker=aarch64-linux-gnu-gcc" cargo build --target aarch64-unknown-linux-gnu
```

The README notes this generalises to other Linux targets if you change the architecture and multi-arch packages exist, and suggests the cross project for non-Debian hosts or for repeatability. If your target is a headless device with no audio host at all, the minimal build is the better route: excluding cpal removes the ALSA requirement entirely.

## Rodio against Symphonia used directly

Symphonia is the real alternative, and it is already a dependency. The difference is where the boundary sits. Symphonia decodes; it does not open an output device, run a callback, mix sources or resample. Using it directly means writing the cpal integration yourself, including the buffer between your decoding thread and the real-time callback, and handling seek, end-of-stream and format detection on your own.

Rodio gives you that integration plus the source combinators. The cost is a layer of API you do not control, and an API that is currently moving: UPGRADE.md exists specifically to carry users to 0.21, which tells you the project has made breaking changes and intends to keep doing so.

There is a middle path the manifest makes explicit. With default-features disabled and symphonia-all enabled, you get decoding and processing without cpal. That is the configuration to pick if you want Rodio's source graph but you are feeding a different output backend, or writing to a file through the wav_output feature.

## Licence and the cost of keeping up

The Cargo manifest declares MIT OR Apache-2.0, and the repository root carries LICENSE-APACHE and LICENSE-MIT. That is the usual permissive Rust dual licence and imposes no copyleft obligation on your application. The README's licence section is truncated mid-sentence at the Apache line, so read the two licence files rather than the README if the exact terms matter to you. This is not legal advice.

Upgrade cost is the real maintenance line item. UPGRADE.md exists for the 0.21 transition, the README points at it, and the engine rewrite is explicitly expected to change things. The examples being pinned to commit f7aa48d is the practical consequence: a snippet you copy from the repository may not match the crate you depend on. Budget for reading UPGRADE.md and the tracking issue at each version bump, and pin your dependency version rather than floating it.

Contributions are welcome according to the README, with review of pull requests, documentation and features all listed as wanted, and an AI policy at rust.audio/community/ai that contributors are asked to read first.

## Conclusion

Adopt Rodio if you are writing a Rust application that needs to play decoded audio files or mix generated sources, and you accept that the core engine is being rewritten and that the documentation for current behaviour is thin. Do not adopt it if you need stable APIs across versions without reading UPGRADE.md, or if you need a documented recording path today, since the README does not describe one. Before committing, check the tracking issue for the engine rewrite, read UPGRADE.md for the 0.21 changes, and build the into_file example with default-features disabled to confirm your target can compile Rodio without a working audio host.

## FAQ

### What is Rodio in Rust?

Rodio is a Rust audio playback and recording library. The README states that playback is handled by cpal and format decoding by Symphonia by default, with optional decoders for FLAC, MP3, Vorbis and WAV.

### How do I install Rodio?

Add it with cargo add rodio. On Debian and Ubuntu you also need libasound2-dev, because the README says ALSA is always required as the base audio layer; on Fedora the package is alsa-lib-devel.

### Can Rodio be built without audio output support?

Yes. The README describes a minimal build that disables default features and enables only the decoders you need, which excludes the cpal dependency and its requirements. The into_file example is given as one that works in that configuration.

### Why do the Rodio examples not compile against the crates.io release?

The README warns that changes to Rodio mean the examples may not work with the current crates.io release, and directs readers to the examples at commit f7aa48d on GitHub instead.

## Sources

- [Issues](https://github.com/RustAudio/rodio/issues)
- [License: Apache-2.0](https://github.com/RustAudio/rodio/blob/master/LICENSE)
- [README](https://github.com/RustAudio/rodio/blob/master/README.md)
- [RustAudio/rodio on GitHub](https://github.com/RustAudio/rodio)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rustaudio-rodio