more ergonomic API, update MSRV

Author: aschey

.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [macos-latest, windows-latest, ubuntu-latest]
-        toolchain: ["1.87"]
+        toolchain: ["1.89"]
         include:
           - os: macos-latest
             MACOS: true

CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+- Added Opus support via `symphonia-adapter-libopus`. 
 
 ## Version [0.22.1] (2026-02-22)
 

Cargo.lock

@@ -8,7 +8,7 @@ repository = "https://github.com/RustAudio/rodio"
 documentation = "https://docs.rs/rodio"
 exclude = ["assets/**", "tests/**"]
 edition = "2021"
-rust-version = "1.87"
+rust-version = "1.89"
 
 [features]
 # Default feature set provides audio playback and common format support
@@ -50,6 +50,9 @@ noise = ["rand", "rand_distr"]
 # Enable WebAssembly support for web browsers
 wasm-bindgen = ["cpal/wasm-bindgen"]
 
+# Base symphonia feature (doesn't enable any codecs)
+symphonia = ["dep:symphonia"]
+
 # To decode an audio source with Rodio, you need to enable the appropriate features for *both* the
 # demuxer and the decoder.
 #
@@ -96,15 +99,15 @@ symphonia-wav = ["symphonia/wav"]
 # Enable SIMD optimisations for Symphonia
 symphonia-simd = ["symphonia/opt-simd"]
 
+# libopus adapter for Symphonia
+symphonia-libopus = ["symphonia", "dep:symphonia-adapter-libopus"]
+
 # Alternative decoders and demuxers
 claxon = ["dep:claxon"]         # FLAC
 hound = ["dep:hound"]           # WAV
 minimp3 = ["dep:minimp3_fixed"] # MP3
 lewton = ["dep:lewton"]         # Ogg Vorbis
 
-# Third party codec example
-libopus = ["dep:symphonia-adapter-libopus"]
-
 [package.metadata.docs.rs]
 all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
@@ -129,7 +132,7 @@ atomic_float = { version = "1.1.0", optional = true }
 rtrb = { version = "0.3.2", optional = true }
 num-rational = "0.4.2"
 
-symphonia-adapter-libopus = {version="0.2", optional = true}
+symphonia-adapter-libopus = { version = "0.2", optional = true }
 
 [dev-dependencies]
 quickcheck = "1"
@@ -138,6 +141,7 @@ rstest_reuse = "0.7"
 approx = "0.5.1"
 divan = "0.1.14"
 inquire = "0.9.3"
+symphonia-adapter-fdk-aac = "0.1"
 
 [[bench]]
 name = "effects"
@@ -235,6 +239,10 @@ required-features = ["playback", "vorbis"]
 name = "music_wav"
 required-features = ["playback", "wav"]
 
+[[example]]
+name = "music_opus"
+required-features = ["playback", "symphonia-libopus"]
+
 [[example]]
 name = "noise_generator"
 required-features = ["playback", "noise"]
@@ -261,4 +269,4 @@ required-features = ["playback", "vorbis"]
 
 [[example]]
 name = "third_party_codec"
-required-features = ["playback", "symphonia", "libopus"]
+required-features = ["playback", "symphonia", "symphonia-isomp4"]

Cargo.toml

@@ -0,0 +1,13 @@
+use std::error::Error;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let stream_handle = rodio::DeviceSinkBuilder::open_default_sink()?;
+    let player = rodio::Player::connect_new(stream_handle.mixer());
+
+    let file = std::fs::File::open("assets/music.opus")?;
+    player.append(rodio::Decoder::try_from(file)?);
+
+    player.sleep_until_end();
+
+    Ok(())
+}

examples/music_opus.rs

@@ -1,23 +1,19 @@
-use std::{error::Error, sync::Arc};
-
 use rodio::decoder::DecoderBuilder;
-use symphonia::{core::codecs::CodecRegistry, default::register_enabled_codecs};
-use symphonia_adapter_libopus::OpusDecoder;
+use std::error::Error;
+use symphonia_adapter_fdk_aac::AacDecoder;
 
 fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::DeviceSinkBuilder::open_default_sink()?;
     let sink = rodio::Player::connect_new(stream_handle.mixer());
 
-    let mut codec_registry = CodecRegistry::new();
-    codec_registry.register_all::<OpusDecoder>();
-    register_enabled_codecs(&mut codec_registry);
-
-    let codec_registry_arc = Arc::new(codec_registry);
-
-    let file = std::fs::File::open("assets/music.opus")?;
+    let file = std::fs::File::open("assets/music.m4a")?;
+    let len = file.metadata()?.len();
     let decoder = DecoderBuilder::new()
-        .with_codec_registry(codec_registry_arc)
         .with_data(file)
+        // Note: the length must be known for Symphonia to properly detect the format for this file
+        // This limitation will be removed in Symphonia 0.6
+        .with_byte_len(len)
+        .with_decoder::<AacDecoder>()
         .build()?;
     sink.append(decoder);
 

examples/third_party_codec.rs

@@ -8,7 +8,7 @@
     inputs: inputs.utils.lib.eachDefaultSystem (
       system: let
         pkgs = inputs.nixpkgs.legacyPackages.${system}.extend inputs.rust-overlay.overlays.default;
-        rust = pkgs.rust-bin.stable."1.87.0".default.override {
+        rust = pkgs.rust-bin.stable."1.89.0".default.override {
           extensions = [ "rust-src" "rust-analyzer" ];
         };
       in {

flake.nix

@@ -40,7 +40,7 @@
 use std::io::{Read, Seek};
 
 #[cfg(feature = "symphonia")]
-use crate::decoder::symphonia::SymphoniaRegistry;
+use crate::decoder::symphonia::Registry;
 
 #[cfg(feature = "symphonia")]
 use self::read_seek_source::ReadSeekSource;
@@ -49,6 +49,8 @@ use ::symphonia::core::{
     codecs::CodecRegistry,
     io::{MediaSource, MediaSourceStream},
 };
+#[cfg(feature = "symphonia")]
+use ::symphonia::default::register_enabled_codecs;
 
 use super::*;
 
@@ -85,7 +87,7 @@ pub struct Settings {
     pub(crate) is_seekable: bool,
 
     #[cfg(feature = "symphonia")]
-    pub(crate) codec_registry: SymphoniaRegistry,
+    pub(crate) codec_registry: Registry,
 }
 
 impl Default for Settings {
@@ -98,7 +100,13 @@ impl Default for Settings {
             mime_type: None,
             is_seekable: false,
             #[cfg(feature = "symphonia")]
-            codec_registry: SymphoniaRegistry::Default,
+            codec_registry: {
+                let mut codec_registry = CodecRegistry::new();
+                register_enabled_codecs(&mut codec_registry);
+                #[cfg(feature = "symphonia-libopus")]
+                codec_registry.register_all::<symphonia_adapter_libopus::OpusDecoder>();
+                Registry::new(codec_registry)
+            },
         }
     }
 }
@@ -242,12 +250,16 @@ impl<R: Read + Seek + Send + Sync + 'static> DecoderBuilder<R> {
         self
     }
 
-    /// Set a custom codec registry
+    /// Adds a third-party decoder.
+    /// If multiple decoders for the same codec are registered, the one registered last will take precedence.
     ///
-    /// See the symphonia documentation of Registry for how to add additional (third party) codecs.
+    /// See the documentation for [CodecRegistry] for more info.
     #[cfg(feature = "symphonia")]
-    pub fn with_codec_registry(mut self, codec_registry: Arc<CodecRegistry>) -> Self {
-        self.settings.codec_registry = SymphoniaRegistry::Custom(codec_registry);
+    pub fn with_decoder<D>(self) -> Self
+    where
+        D: ::symphonia::core::codecs::Decoder,
+    {
+        self.settings.codec_registry.write().register_all::<D>();
         self
     }
 

src/decoder/builder.rs

@@ -1,5 +1,8 @@
 use core::time::Duration;
-use std::{fmt::Debug, sync::Arc};
+use std::{
+    fmt::{self, Debug},
+    sync::{Arc, RwLock, RwLockReadGuard, RwLockWriteGuard},
+};
 use symphonia::{
     core::{
         audio::{AudioBufferRef, SampleBuffer, SignalSpec},
@@ -21,21 +24,25 @@ use crate::{
 };
 
 #[derive(Clone)]
-/// Enum for choosing which codec registry to used with Symphonia decoders.
-pub enum SymphoniaRegistry {
-    /// Use the symphonia default registry symphonia::default::get_codecs()
-    Default,
+pub(crate) struct Registry(Arc<RwLock<CodecRegistry>>);
 
-    ///Use a custom CodecRegistry
-    Custom(Arc<CodecRegistry>),
+impl Debug for Registry {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("Registry")
+    }
 }
 
-impl Debug for SymphoniaRegistry {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            Self::Default => write!(f, "Default"),
-            Self::Custom(_) => write!(f, "Custom"),
-        }
+impl Registry {
+    pub(crate) fn new(registry: CodecRegistry) -> Self {
+        Self(Arc::new(RwLock::new(registry)))
+    }
+
+    pub(crate) fn write(&self) -> RwLockWriteGuard<'_, CodecRegistry> {
+        self.0.write().unwrap()
+    }
+
+    pub(crate) fn read(&self) -> RwLockReadGuard<'_, CodecRegistry> {
+        self.0.read().unwrap()
     }
 }
 
@@ -121,13 +128,12 @@ impl SymphoniaDecoder {
             None => return Ok(None),
         };
 
-        let mut decoder = match &settings.codec_registry {
-            SymphoniaRegistry::Default => symphonia::default::get_codecs(),
-            SymphoniaRegistry::Custom(cr) => cr.as_ref(),
-        }
-        .make(&track.codec_params, &DecoderOptions::default())?;
+        let mut decoder = settings
+            .codec_registry
+            .read()
+            .make(&track.codec_params, &DecoderOptions::default())?;
 
-        let total_duration = stream
+        let total_duration = track
             .codec_params
             .time_base
             .zip(stream.codec_params.n_frames)

src/decoder/symphonia.rs

@@ -118,6 +118,9 @@
 //! or enabling specific codecs using one of the `symphonia-{codec name}` features.
 //! By default, decoders for the most common file types (flac, mp3, mp4, vorbis, wav) are enabled.
 //!
+//! See the [symphonia docs](https://docs.rs/symphonia/latest/symphonia) for the complete
+//! list of supported formats.
+//!
 //! ### Alternative Decoders
 //!
 //! Alternative decoder libraries are available for some filetypes: