rodio

If you are upgrading from 0.22 to a newer version on GitHub, note the following breaking changes:

Output Configuration

stream::supported_output_configs has been removed. To select a non-default device configuration:

1. Call device.supported_output_configs() directly.
2. Pass the chosen SupportedStreamConfig to DeviceSinkBuilder::with_supported_config.

Done Callback

Done no longer decrements an Arc<AtomicUsize>. It now uses a callback.

• New Signature: Done<I, F> where I: Source and F: FnMut(&mut I).
• To retain old behavior: Replace the Arc<AtomicUsize> argument in Done::new with a closure: move |_| { number.fetch_sub(1, std::sync::atomic::Ordering::Relaxed) }.

Zero Samples

Zero::new_samples() now returns Result<Zero, ZeroError> instead of Zero. Passing a num_samples value that is not a multiple of channels will now return an Err instead of producing a mis-aligned source.

Upgrading from 0.20 or earlier to 0.21.1 involves several significant changes to features, output streams, and decoders.

Features and Decoders

• Playback: Playback logic is now a feature enabled by default. If you use default_features = false, you must explicitly add features = ["playback"] to your Cargo.toml.
• Decoders: The default decoders are now Symphonia (MPL licensed). To use the old decoders, set default_features = false and enable claxon (FLAC), hound (WAV), and lewton (Ogg Vorbis) in Cargo.toml.

OutputStream Changes

• OutputStreamHandle has been removed.
• OutputStreamHandle::play_raw is removed; use OutputStream.mixer().add() instead.
• Recommended way to open a stream: Use OutputStreamBuilder::open_default_stream()?.
• Legacy behavior: To replicate old behavior, use open_stream_or_fallback()? by manually getting the default device via cpal and passing it to OutputStreamBuilder::from_device(default_device)?.
• Logging: The output stream now prints to stderr or logs on drop. To disable this, use stream.log_on_drop(false).

Sink and SpatialSink

• Replace Sink::try_new with Sink::connect_new, passing an &Mixer (obtained via OutputStream.mixer()).
• Replace Sink::new_idle with Sink::new.

Example Migration (0.20 to 0.21):

Old (0.20):

let (_stream, handle) = rodio::OutputStream::try_default()?;
let player = rodio::Player::try_new(&handle)?;

New (0.21):

let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
let player = rodio::Player::connect_new(stream_handle.mixer());

Decoder Changes

• Decoder::new_mp4 no longer accepts an Mp4Type hint.
• Symphonia decoders no longer assume sources are seekable. Use DecoderBuilder::with_seekable or try_from on a File. You no longer need BufReader.

Example Migration (0.20 to 0.21):

Old (0.20):

let file = File::open("music.ogg")?;
let reader = BufReader::new(file);
let source = Decoder::new(reader);

New (0.21):

let file = File::open("music.ogg")?;
let source = Decoder::try_from(file)?;

Other Changes

• DynamicMixer: Replace DynamicMixerController with Mixer and DynamicMixer with MixerSource.
• Noise: Source::white and Source::pink are deprecated. Use WhiteUniform::new and Pink::new.
• Source Trait:
  • current_frame_len is renamed to current_span_len.
  • The Source trait is no longer generic over sample types (f32, u16, i16). It now works exclusively with f32. Remove any sample type generics, SampleConvertor usage, or convert_samples calls.

Playing audio in rodio typically involves three steps:

1. Get an OS-Sink handle: Obtain a handle to a physical device (e.g., the system default) using DeviceSinkBuilder::open_default_sink().
2. Create a Source: Create an object representing the sound, such as a Decoder from a file, a sine wave, or a custom type implementing the Source trait.
3. Add to the Sink: Add the source to the OS-Sink using the mixer() method on the sink handle.

Note: Playback occurs in a separate background thread. If the OS-Sink handle is dropped, playback stops. You must ensure the handle (and the Player if using one) lives as long as you want the sound to play.

use std::fs::File;
use rodio::{Decoder, MixerDeviceSink, source::Source};

// Get an OS-Sink handle to the default physical sound device.
let handle = rodio::DeviceSinkBuilder::open_default_sink()
        .expect("open default audio stream");
let player = rodio::Player::connect_new(&handle.mixer());

// Load a sound from a file
let file = File::open("examples/music.ogg").unwrap();

// Decode that sound file into a source
let source = Decoder::try_from(file).unwrap();

// Play the sound directly on the device
handle.mixer().add(source);

// Keep the main thread alive while playing
std::thread::sleep(std::time::Duration::from_secs(5));