rodio 0.22.0

Audio playback and recording library
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

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](CHANGELOG.md).

# rodio 0.22 to current github version
Nothing yet!

# 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:
      ```rust
        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:
```rust
let (_stream, handle) = rodio::OutputStream::try_default()?;
let player = rodio::Player::try_new(&handle)?;
```
Should be written like this in Rodio *0.21*:
```rust
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
```rust
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*:
```rust
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`.