Skip to content

UPGRADE.md

Latest commit

 

History

History
128 lines (113 loc) · 5.9 KB

UPGRADE.md

File metadata and controls

128 lines (113 loc) · 5.9 KB

This guide will help you update your code when upgrading from older versions of rodio. While we did our best, we might have missed things. PRs that improve this guide are very welcome!

The list below only contains required code changes. For a complete list of changes and new features, see CHANGELOG.md.

rodio 0.22 to current github version

  • Done now calls a callback instead of decrementing an Arc<AtomicUsize>.
    • To retain old behavior replace the Arc<AtomicUsize> argument in Done::new with move |_| { number.fetch_sub(1, std::sync::atomic::Ordering::Relaxed) }.
    • Done has now two generics instead of one: <I: Source, F: FnMut(&mut I)>.
  • Zero::new_samples() now returns Result<Zero, ZeroError> instead of Zero. Previously the function accepted any num_samples value; passing one that is not a multiple of channels now returns an Err instead of producing a mis-aligned source.

rodio 0.21.1 to 0.22

  • Sink terms are replaced with Player and Stream terms replaced with Sink. This is a simple rename, functionality is identical.

    We recommend a search replace for the following terms, in no particular order:

    • OutputStream is now MixerDeviceSink (in anticipation of future QueueDeviceSink)
    • OutputStreamBuilder is now DeviceSinkBuilder
    • open_stream_or_fallback is now open_sink_or_fallback
    • open_default_stream is now open_default_sink
    • open_stream is now open_mixer (in anticipation of future open_queue)
    • Sink is now Player
    • SpatialSink is now SpatialPlayer
    • StreamError is now OsSinkError

  • output_to_wav renamed to wav_to_file and now takes ownership of the Source.

  • SamplesBuffer::new now takes ChannelCount and SampleRate as arguments. Use the nz! macro to easily create those from literals like this: SamplesBuffer::new(nz!(1), nz!(44100)) or construct them at runtime like this: SamplesBuffer::new(NonZero::new(channel_count)?, NonZero::new(sample_rate)?);

rodio 0.20 or earlier to 0.21.1

Features

  • Playback logic has been turned into a feature that is enabled by default. If you have default_features = false in your Cargo.toml and want audio playback, you need to also set features = ["playback"].
  • The default decoders have changed to Symphonia, which itself is licensed under MPL. If you want to revert to the old decoders, you need to set default_features = false and enable the claxon, hound and lewton features in Cargo.toml for respectively FLAC, WAV and Ogg Vorbis.

OutputStream

  • OutputStreamHandle no longer exists, you can remove it from your code.
  • OutputStreamHandle::play_raw has been removed, instead use OutputStream.mixer().add().
  • The output stream is now more configurable. Where you used OutputStream::try_default(), you need to change to either:
    • (recommended) OutputStreamBuilder::open_default_stream()? which tries to open a new output stream for the default output device with its default configuration. Failing that it attempt to open an output stream with alternative configuration and/or non default output devices. Returns the stream for the first configurations tried that succeeds. If all attempts fail returns the initial error.
    • (org behavior) open_stream_or_fallback()? which is used as follows: 
        let default_device = cpal::default_host()
      .default_output_device()
      .ok_or("No default audio output device is found.")?;
  rodio::OutputStreamBuilder::from_device(default_device)?
      .open_stream_or_fallback()?;
      That tries to opening a output stream with the default configuration on the default device. Failing that attempt to open a stream with other available configurations supported by the default device. If all attempts fail returns initial error.
  • The output stream now prints to stderr or logs a message on drop, if that breaks your CLI/UI use stream.log_on_drop(false).

Sink & SpatialSink

  • Replace Sink::try_new with Sink::connect_new, which takes an &Mixer instead of a OutputStreamHandle. You get an &Mixer by calling mixer() on OutputStream.
  • Replace Sink::new_idle with Sink::new.

Example

The following Rodio 0.20 code:

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

Should be written like this in Rodio 0.21:

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

The SpatialSink changes mirror those in Sink described above.

Decoder

  • Decoder::new_mp4 no longer takes an Mp4Type as hint. Remove the hint.
  • The Symphonia decoders no longer assumes all sources are seekable. Use DecoderBuilder::with_seekable or try_from on a File. You do not need to wrap it into a BufReader anymore.

The following Rodio 0.20 code

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

Should be written like this in Rodio 0.21:

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

DynamicMixer

  • Replace DynamicMixerController with Mixer and DynamicMixer with MixerSource.

Noise

  • The Source::white and Source::pink methods have been deprecated. Use WhiteUniform::new and Pink::new instead.

Source trait implementations

  • The Source trait had a required method current_frame_len, which has been renamed to current_span_len. Rename every occurrence.
  • Source was generic over sample types f32, u16, and i16. It no longer is; rodio now works with f32 everywhere. This means:
    • Remove any generics (::<f32>, ::<u16> or ::<i16>) that cause errors.
    • Remove any use of SampleConvertor.
    • Remove any calls to convert_samples.