From 71ff23265b238e16cddd979725c2625ead4b8f49 Mon Sep 17 00:00:00 2001 From: dvdsk Date: Thu, 27 Mar 2025 19:04:43 +0100 Subject: [PATCH 01/17] increment version --- CHANGELOG.md | 2 ++ Cargo.toml | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d6ddee85..201b9dc5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +# Version 0.21 (TODO) + ### Added - Added `Source::amplify_decibel()` method to control volume by decibels. - Added `Source::amplify_normalized()` method to perceptually modify volume. diff --git a/Cargo.toml b/Cargo.toml index aa774a7f..c5f0a4b8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "rodio" -version = "0.20.1" +version = "0.21.0" license = "MIT OR Apache-2.0" description = "Audio playback library" keywords = ["audio", "playback", "gamedev"] From f3aad1db8681670180ef169b6920137c2a4a877d Mon Sep 17 00:00:00 2001 From: dvdsk Date: Tue, 1 Apr 2025 01:20:24 +0200 Subject: [PATCH 02/17] finishes upgrade guid for new release --- UPGRADE.md | 44 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/UPGRADE.md b/UPGRADE.md index 717222fb..f14bca3d 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -1,15 +1,24 @@ This guide will help you update your code when upgrading from older versions of rodio. -# rodio 0.20.1 or earlier to current GitHub version +# rodio 0.21 to current GitHub version + +nothing + +# rodio 0.20 or earlier to 0.21 ## Features - If you use disable the rodio features with `default_features = false` in `Cargo.toml` you need to add a new feature `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 enable the `claxon`, `hound` and `lewton` features in `Cargo.toml` for respectively FLAC, WAV and Ogg Vorbis. + to revert to the old decoders, you need to disable default-features and enable the `claxon`, `hound` and `lewton` features in `Cargo.toml` for respectively FLAC, WAV and Ogg Vorbis. ## Source implementations - Source had a required method `current_frame_len`. In the latest version of rodio *frame* has been renamed to *span*. You will need to change every occurrence of `current_frame_len` to `current_span_len`. +- Source was generic over sample type. It no longer is. + - Remove any generics (`::`, `::` or `::`) that cause errors. + - Remove `SampleConvertor` it is no longer needed and has been removed. + - Remove any calls to `source.convert_samples()` they are no longer needed and + removed ## OutputStream - The output stream is now more configurable. Where you used `OutputStream::try_default()` you have a choice: @@ -19,5 +28,32 @@ This guide will help you update your code when upgrading from older versions of default (audio) stream. If that fails it tries all other combinations of device and settings. The old behavior was only trying all settings of the default device. -- 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)`. + - 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`. It now 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.1* code: +```rust +let (_stream, handle) = rodio::OutputStream::try_default()?; +let sink = rodio::Sink::try_new(&handle)?; +``` +becomes this in Rodio *0.21.0*: +```rust +let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?; +let sink = rodio::Sink::connect_new(&stream_handle.mixer()); +``` + +The `SpatialSink` changes mirror those in `Sink` described above. + +## Dynamic mixer +Replace `DynamicMixerController` with `Mixer` and `DynamicMixer` with `MixerSource`. + +## Decoder +`Decoder::new_mp4` no longer takes an `Mp4Type` as hint. You can remove the argument +>>>>>>> f306766 (finishes upgrade guid for new release) From 2dd18f1c5c73b644c95c8c9e2e0b22ce918c4ebf Mon Sep 17 00:00:00 2001 From: dvdsk Date: Tue, 1 Apr 2025 01:20:49 +0200 Subject: [PATCH 03/17] adds missing entry to CHANGELOG --- CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 201b9dc5..557ca9ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -44,13 +44,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Breaking: `DynamicMixerController` renamed to `Mixer`, `DynamicMixer` renamed to `MixerSource`. - Breaking: `Sink::try_new` renamed to `connect_new` and does not return error anymore. `Sink::new_idle` was renamed to `new`. +- Breaking: `symphonia::SeekError` has a new variant `AccurateSeekNotSupported` + and variants `Retrying` and `Refining` have been removed. - Breaking: In the `Source` trait, the method `current_frame_len()` was renamed to `current_span_len()`. - Breaking: `Decoder` now outputs `f32` samples. - Breaking: The term 'frame' was renamed to 'span' in the crate and documentation. - Breaking: `LoopedDecoder` now returns `None` if seeking fails during loop reset. - Breaking: `ReadSeekSource::new()` now takes `Settings`. -- Breaking: Sources now use `f32` samples. To convert to and from other types of samples use - functions from `dasp_sample` crate. For example `DaspSample::from_sample(sample)`. +- Breaking: Sources now use `f32` samples. To convert to and from other types of samples use functions from `dasp_sample` crate. For example `DaspSample::from_sample(sample)`. - `OutputStreamConfig` is now public. - `OutputStream` now prints when it is dropped, can be disabled with `OutputStream::log_on_drop(false)`. - Update `cpal` to [0.16](https://github.com/RustAudio/cpal/blob/master/CHANGELOG.md#version-0160-2025-06-07). From 124c7b0a7ac6b6bfa40905169572f09f72c0c7a8 Mon Sep 17 00:00:00 2001 From: dvdsk Date: Tue, 1 Apr 2025 01:31:26 +0200 Subject: [PATCH 04/17] mention upgrade guide in README.md --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bff02064..88f5c0b6 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,12 @@ See [the feature flags](https://docs.rs/crate/rodio/latest/features) for more de [The documentation](http://docs.rs/rodio) contains an introduction to the library. +# [Breaking Changes](UPGRADE.md) +We have written an upgrade [guide](UPGRADE.md), it will help you upgrade to rodio 0.21. + # [Examples](https://github.com/RustAudio/rodio/tree/f1eaaa4a6346933fc8a58d5fd1ace170946b3a94/examples) -We are currently making large improvements to rodio. This does mean the updated examples do not work with the current crates.io release. You will have to look at the examples from commit `f1eaaa4a`. They are available [on github](https://github.com/RustAudio/rodio/tree/f1eaaa4a6346933fc8a58d5fd1ace170946b3a94/examples). +We are always making changes to rodio. That can mean the examples do not work with the current crates.io release. You will have to look at the examples from commit `f1eaaa4a`. They are available [on github](https://github.com/RustAudio/rodio/tree/f1eaaa4a6346933fc8a58d5fd1ace170946b3a94/examples). ## Requirements @@ -40,7 +43,7 @@ It is possible to build `rodio` without support for audio playback. In this conf In order to use `rodio` in this configuration disable default features and add the necessary ones. In this case the `Cargo.toml` dependency would look like: ```toml [dependencies] -rodio = { version = "0.20.1", default-features = false, features = ["symphonia-all"] } +rodio = { version = "0.21.0", default-features = false, features = ["symphonia-all"] } ``` ### Cross compling aarch64/arm From bb7586668daa6706880b3464bfc7cdb38798de1b Mon Sep 17 00:00:00 2001 From: dvdsk Date: Tue, 1 Apr 2025 01:47:12 +0200 Subject: [PATCH 05/17] adds 0.21 release announcement --- outreach/v0.21_announcement.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 outreach/v0.21_announcement.md diff --git a/outreach/v0.21_announcement.md b/outreach/v0.21_announcement.md new file mode 100644 index 00000000..4f72e43c --- /dev/null +++ b/outreach/v0.21_announcement.md @@ -0,0 +1,29 @@ + + +# Announcing rodio 0.21 + + +Rodio is an audio playback library. It can decode audio files, synthesize new +sounds, apply effects to sounds & mix them. Rodio has been part of the Rust +ecosystem for 9 years now! 🎉. + +## New release +Its been 5 months since our last release. Since the our team has grown to 3 +maintainers! Thank you Petr and Roderick! And a big thanks for the countless +other contributors helping out. Thanks to them this release: + +- Makes the API easier to use + - Its now impossible to accidentally drop the `Outputstream`. + - Our types are no longer generic over sample type. +- The decoders have been improved enabling *gapless* playback and offering many + configuration options through a new builder. +- You can use rodio without `cpal` to generate `wav` files! + +There have also been many fixes and smaller additions, take a look at the +[changelog](https://github.com/RustAudio/rodio/blob/89dac52/CHANGELOG.md)! + +## The future +We keep working on easy audio playback. We hope to announce something new soon! From de82b41b3c73d92c3f6a1f2d58e47e2f52fcefb6 Mon Sep 17 00:00:00 2001 From: dvdsk Date: Mon, 12 May 2025 08:45:17 +0200 Subject: [PATCH 06/17] feedback from roderick and petr --- CHANGELOG.md | 52 +++++++++++++++++----------------- README.md | 2 +- UPGRADE.md | 2 +- outreach/v0.21_announcement.md | 4 +-- 4 files changed, 29 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 557ca9ea..36b70403 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -# Version 0.21 (TODO) +## Version [0.21] (TODO) ### Added - Added `Source::amplify_decibel()` method to control volume by decibels. @@ -45,13 +45,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Breaking: `Sink::try_new` renamed to `connect_new` and does not return error anymore. `Sink::new_idle` was renamed to `new`. - Breaking: `symphonia::SeekError` has a new variant `AccurateSeekNotSupported` - and variants `Retrying` and `Refining` have been removed. + and variants `Retrying` and `Refining` have been removed. Catching this error + may allow a caller to retry in coarse seek mode. - Breaking: In the `Source` trait, the method `current_frame_len()` was renamed to `current_span_len()`. - Breaking: `Decoder` now outputs `f32` samples. - Breaking: The term 'frame' was renamed to 'span' in the crate and documentation. - Breaking: `LoopedDecoder` now returns `None` if seeking fails during loop reset. - Breaking: `ReadSeekSource::new()` now takes `Settings`. - Breaking: Sources now use `f32` samples. To convert to and from other types of samples use functions from `dasp_sample` crate. For example `DaspSample::from_sample(sample)`. +- Breaking: `WhiteNoise` and `PinkNoise` have been renamed to `noise::WhiteUniform` and + `noise::Pink`. - `OutputStreamConfig` is now public. - `OutputStream` now prints when it is dropped, can be disabled with `OutputStream::log_on_drop(false)`. - Update `cpal` to [0.16](https://github.com/RustAudio/cpal/blob/master/CHANGELOG.md#version-0160-2025-06-07). @@ -61,9 +64,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Breaking: As optional features are now available: CAF and MKV containers, MP1/MP2 and ADPCM decoders. Previously, the ADPCM decoder was enabled when `symphonia-wav` was. - docs.rs will now document all features, including those that are not enabled by default. -- Breaking: `WhiteNoise` and `PinkNoise` have been renamed to `noise::WhiteUniform` and - `noise::Pink`. -- `noise::Pink` is not deterministically seekable, so will now return `Err` when seeking. ### Fixed - `ChannelVolume` no longer clips/overflows when converting from many channels to @@ -87,12 +87,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Removed - Breaking: Removed `Mp4Type` enum in favor of using MIME type string "audio/mp4" for MP4 format detection with `Decoder::new_mp4` (#612). -# Version 0.20.1 (2024-11-08) +## Version [0.20.1] - 2024-11-08 ### Fixed - Builds without the `symphonia` feature did not compile -# Version 0.20.0 (2024-11-08) +## Version [0.20.0] - 2024-11-08 ### Added - Support for *ALAC/AIFF* @@ -120,7 +120,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - `SamplesBuffer` is now `Clone` -# Version 0.19.0 (2024-06-29) +## Version [0.19.0] - 2024-06-29 ### Added - Adds a new source `track_position`. It keeps track of duration since the @@ -130,12 +130,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Mp4a with decodable tracks after undecodable tracks now play. This matches VLC's behaviour. -# Version 0.18.1 (2024-05-23) +## Version [0.18.1] - 2024-05-23 ### Fixed - Seek no longer hangs if the sink is empty. -# Version 0.18.0 (2024-05-05) +## Version [0.18.0] - 2024-05-05 ### Changed - `Source` trait is now also implemented for `Box` and `&mut Source` @@ -156,32 +156,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `mp3::is_mp3()` no longer changes the position in the stream when the stream is mp3 -# Version 0.17.3 (2023-10-23) +## Version [0.17.3] - 2023-10-23 - Build fix for `minimp3` backend. -# Version 0.17.2 (2023-10-17) +## Version [0.17.2] - 2023-10-17 - Add `EmptyCallback` source. - Fix index out of bounds bug. - Use non-vulnerable `minimp3` fork. - Add filter functions with additional q parameter. -# Version 0.17.1 (2023-02-25) +## Version [0.17.1] - 2023-02-25 - Disable `symphonia`'s default features. -# Version 0.17.0 (2023-02-17) +## Version [0.17.0] - 2023-02-17 - Update `cpal` to [0.15](https://github.com/RustAudio/cpal/blob/master/CHANGELOG.md#version-0150-2022-01-29). - Default to `symphonia` for mp3 decoding. -# Version 0.16.0 (2022-09-14) +## Version [0.16.0] - 2022-09-14 - Update `cpal` to [0.14](https://github.com/RustAudio/cpal/blob/master/CHANGELOG.md#version-0140-2022-08-22). - Update `symphonia` to [0.5](https://github.com/pdeljanov/Symphonia/releases/tag/v0.5.1). -# Version 0.15.0 (2022-01-23) +## Version [0.15.0] - 2022-01-23 - Remove requirement that the argument `Decoder::new` and `LoopedDecoder::new` implement `Send`. - Add optional symphonia backend. @@ -190,7 +190,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `SineWave::new()` now takes a `f32` instead of a `u32`. - Add `len()` method to `SpatialSink`. -# Version 0.14.0 (2021-05-21) +## Version [0.14.0] - 2021-05-21 - Re-export `cpal` in full. - Replace panics when calling `OutputStream::try_default`, `OutputStream::try_from_device` with new @@ -198,49 +198,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `OutputStream::try_default` will now fallback to non-default output devices if an `OutputStream` cannot be created from the default device. -# Version 0.13.1 (2021-03-28) +## Version [0.13.1] - 2021-03-28 - Fix panic when no `pulseaudio-alsa` was installed. -# Version 0.13.0 (2020-11-03) +## Version [0.13.0] - 2020-11-03 - Update `cpal` to [0.13](https://github.com/RustAudio/cpal/blob/master/CHANGELOG.md#version-0130-2020-10-28). - Add Android support. -# Version 0.12.0 (2020-10-05) +## Version [0.12.0] - 2020-10-05 - Breaking: Update `cpal` to [0.12](https://github.com/RustAudio/cpal/blob/master/CHANGELOG.md#version-0120-2020-07-09). - Breaking: Rework API removing global "rodio audio processing" thread & adapting to the upstream cpal API changes. - Add new_X format specific methods to Decoder. - Fix resampler dependency on internal `Vec::capacity` behaviour. -# Version 0.11.0 (2020-03-16) +## Version [0.11.0] - 2020-03-16 - Update `lewton` to [0.10](https://github.com/RustAudio/lewton/blob/master/CHANGELOG.md#release-0100---january-30-2020). - Breaking: Update `cpal` to [0.11](https://github.com/RustAudio/cpal/blob/master/CHANGELOG.md#version-0110-2019-12-11) -# Version 0.10.0 (2019-11-16) +## Version [0.10.0] - 2019-11-16 - Removal of nalgebra in favour of own code. - Fix a bug that switched channels when resuming after having paused. - Attempt all supported output formats if the default format fails in `Sink::new`. - Breaking: Update `cpal` to [0.10](https://github.com/RustAudio/cpal/blob/master/CHANGELOG.md#version-0100-2019-07-05). -# Version 0.9.0 (2019-06-08) +## Version [0.9.0] - 2019-06-08 - Remove exclusive `&mut` borrow requirements in `Sink` & `SpatialSink` setters. - Use `nalgebra` instead of `cgmath` for `Spatial` source. -# Version 0.8.1 (2018-09-18) +## Version [0.8.1] - 2018-09-18 - Update `lewton` dependency to [0.9](https://github.com/RustAudio/lewton/blob/master/CHANGELOG.md#release-090---august-16-2018) - Change license from `Apache-2.0` only to `Apache-2.0 OR MIT` -# Version 0.8.0 (2018-06-22) +## Version [0.8.0] - 2018-06-22 - Add mp3 decoding capabilities via `minimp3` -# Version 0.7.0 (2018-04-19) +## Version [0.7.0] - 2018-04-19 - Update `cpal` dependency to 0.8, and adopt the new naming convention - BREAKING CHANGES: diff --git a/README.md b/README.md index 88f5c0b6..868bb411 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ We have written an upgrade [guide](UPGRADE.md), it will help you upgrade to rodi # [Examples](https://github.com/RustAudio/rodio/tree/f1eaaa4a6346933fc8a58d5fd1ace170946b3a94/examples) -We are always making changes to rodio. That can mean the examples do not work with the current crates.io release. You will have to look at the examples from commit `f1eaaa4a`. They are available [on github](https://github.com/RustAudio/rodio/tree/f1eaaa4a6346933fc8a58d5fd1ace170946b3a94/examples). +We are always making changes to rodio. This can mean that the examples do not work with the current crates.io release. You will have to look at the examples from commit `f1eaaa4a`. They are available [on github](https://github.com/RustAudio/rodio/tree/f1eaaa4a6346933fc8a58d5fd1ace170946b3a94/examples). ## Requirements diff --git a/UPGRADE.md b/UPGRADE.md index f14bca3d..795eaa0a 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -46,7 +46,7 @@ let sink = rodio::Sink::try_new(&handle)?; becomes this in Rodio *0.21.0*: ```rust let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?; -let sink = rodio::Sink::connect_new(&stream_handle.mixer()); +let sink = rodio::Sink::connect_new(stream_handle.mixer()); ``` The `SpatialSink` changes mirror those in `Sink` described above. diff --git a/outreach/v0.21_announcement.md b/outreach/v0.21_announcement.md index 4f72e43c..5c45c0f0 100644 --- a/outreach/v0.21_announcement.md +++ b/outreach/v0.21_announcement.md @@ -11,15 +11,13 @@ sounds, apply effects to sounds & mix them. Rodio has been part of the Rust ecosystem for 9 years now! 🎉. ## New release -Its been 5 months since our last release. Since the our team has grown to 3 +It's been 5 months since our last release. Since the our team has grown to 3 maintainers! Thank you Petr and Roderick! And a big thanks for the countless other contributors helping out. Thanks to them this release: - Makes the API easier to use - Its now impossible to accidentally drop the `Outputstream`. - Our types are no longer generic over sample type. -- The decoders have been improved enabling *gapless* playback and offering many - configuration options through a new builder. - You can use rodio without `cpal` to generate `wav` files! There have also been many fixes and smaller additions, take a look at the From 9921a70241a795a4993af5d0df4b2600c33690df Mon Sep 17 00:00:00 2001 From: dvdsk Date: Mon, 12 May 2025 09:32:42 +0200 Subject: [PATCH 07/17] changelog: note symphonia decoder total duration fix --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 36b70403..c7e45654 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -75,7 +75,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 correctly. - Removed unwrap() calls in MP3, WAV, FLAC and Vorbis format detection for better error handling. - `LoopedDecoder::size_hint` now correctly indicates an infinite stream. -- Symphonia decoder `total_duration` for Vorbis now return the correct value (#696). +- Symphonia decoder `total_duration` no longer returns None when it could + return Some - Symphonia decoder for MP4 now seeks correctly (#577). - White noise was not correctly uniformly distributed. - Pink noise was not correctly distributed on sampling rates other than 44100 Hz. From 15af73dd624e48e55017dff75296060465cbf6d9 Mon Sep 17 00:00:00 2001 From: dvdsk Date: Mon, 19 May 2025 15:33:06 +0200 Subject: [PATCH 08/17] upgrade guide: mention Decoder::new behavior for symphonia --- UPGRADE.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/UPGRADE.md b/UPGRADE.md index 795eaa0a..3c1880a5 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -43,7 +43,7 @@ The following Rodio *0.20.1* code: let (_stream, handle) = rodio::OutputStream::try_default()?; let sink = rodio::Sink::try_new(&handle)?; ``` -becomes this in Rodio *0.21.0*: +Should be written like this in Rodio *0.21.0*: ```rust let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?; let sink = rodio::Sink::connect_new(stream_handle.mixer()); @@ -55,5 +55,18 @@ The `SpatialSink` changes mirror those in `Sink` described above. Replace `DynamicMixerController` with `Mixer` and `DynamicMixer` with `MixerSource`. ## Decoder -`Decoder::new_mp4` no longer takes an `Mp4Type` as hint. You can remove the argument ->>>>>>> f306766 (finishes upgrade guid for new release) +- `Decoder::new_mp4` no longer takes an `Mp4Type` as hint. You can remove the argument +- Symphonia now longer assumes all sources are seek-able. Use + `DecoderBuilder::with_seekable` or `try_from` on a `File` or `Bufreader`. + +The following Rodio *0.20.1* 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.0*: +```rust +let file = File::open("music.ogg")?; +let source = Decoder::try_from(music.ogg)?; +``` From be8117f38cef7cb6b36e2ebe8a752a219b4dd884 Mon Sep 17 00:00:00 2001 From: dvdsk Date: Thu, 5 Jun 2025 00:04:15 +0200 Subject: [PATCH 09/17] reword announcement + discuss added features --- outreach/v0.21_announcement.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/outreach/v0.21_announcement.md b/outreach/v0.21_announcement.md index 5c45c0f0..8cb8f2c6 100644 --- a/outreach/v0.21_announcement.md +++ b/outreach/v0.21_announcement.md @@ -5,7 +5,6 @@ # Announcing rodio 0.21 - Rodio is an audio playback library. It can decode audio files, synthesize new sounds, apply effects to sounds & mix them. Rodio has been part of the Rust ecosystem for 9 years now! 🎉. @@ -13,15 +12,19 @@ ecosystem for 9 years now! 🎉. ## New release It's been 5 months since our last release. Since the our team has grown to 3 maintainers! Thank you Petr and Roderick! And a big thanks for the countless -other contributors helping out. Thanks to them this release: +other contributors helping out. Thanks to you all this release: -- Makes the API easier to use +- Makes the API easier to use: - Its now impossible to accidentally drop the `Outputstream`. - Our types are no longer generic over sample type. +- Adds new functionality: + - Amplify using decibals or perceptually. + - Add a distortion effect. - You can use rodio without `cpal` to generate `wav` files! There have also been many fixes and smaller additions, take a look at the [changelog](https://github.com/RustAudio/rodio/blob/89dac52/CHANGELOG.md)! ## The future -We keep working on easy audio playback. We hope to announce something new soon! +The rust audio organization will keep working on audio in Rust. We hope to +release an announcement regarding that soon! From d18fcd95c66628bcc76d22c23b9f9073d7ec67e3 Mon Sep 17 00:00:00 2001 From: dvdsk Date: Sat, 5 Jul 2025 15:18:44 +0200 Subject: [PATCH 10/17] add all the new faetures to the announcement --- Cargo.lock | 2 +- UPGRADE.md | 4 +++- outreach/v0.21_announcement.md | 17 ++++++++++++----- 3 files changed, 16 insertions(+), 7 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index ea450272..312f2641 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -923,7 +923,7 @@ checksum = "ba39f3699c378cd8970968dcbff9c43159ea4cfbd88d43c00b22f2ef10a435d2" [[package]] name = "rodio" -version = "0.20.1" +version = "0.21.0" dependencies = [ "approx", "atomic_float", diff --git a/UPGRADE.md b/UPGRADE.md index 3c1880a5..c33b6516 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -1,4 +1,6 @@ -This guide will help you update your code when upgrading from older versions of rodio. +This guide will help you update your code when upgrading from older versions of +rodio. While we do our best we might have missed things. PR's that improve this +guide are very welcome! # rodio 0.21 to current GitHub version diff --git a/outreach/v0.21_announcement.md b/outreach/v0.21_announcement.md index 8cb8f2c6..32c838e8 100644 --- a/outreach/v0.21_announcement.md +++ b/outreach/v0.21_announcement.md @@ -15,15 +15,22 @@ maintainers! Thank you Petr and Roderick! And a big thanks for the countless other contributors helping out. Thanks to you all this release: - Makes the API easier to use: - - Its now impossible to accidentally drop the `Outputstream`. + - We now warn when audio could be stopped without the dev intending. - Our types are no longer generic over sample type. + - The features have been overhauled and we now have better defaults. - Adds new functionality: + - Many rodio parts are now more configurable and customizable - Amplify using decibals or perceptually. - - Add a distortion effect. -- You can use rodio without `cpal` to generate `wav` files! + - A distortion effect. + - A limiter. + - Many more noise generators +- You can use rodio without `cpal` to analyze audio or generate `wav` files! -There have also been many fixes and smaller additions, take a look at the -[changelog](https://github.com/RustAudio/rodio/blob/89dac52/CHANGELOG.md)! +There have also been many fixes and smaller additions, take a look at the full +[changelog](https://github.com/RustAudio/rodio/blob/master/CHANGELOG.md)! + +## Breaking changes +As we made quite a few breaking changes we now have an [upgrade guide](https://github.com/RustAudio/rodio/blob/master/UPGRADE.md)! ## The future The rust audio organization will keep working on audio in Rust. We hope to From 30c0a8de661fe4c4d81477da72d8faaa32bf7627 Mon Sep 17 00:00:00 2001 From: dvdsk Date: Sat, 5 Jul 2025 15:30:01 +0200 Subject: [PATCH 11/17] small format fixes + mention some more changes --- CHANGELOG.md | 5 +++-- outreach/v0.21_announcement.md | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c7e45654..44b78dec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,6 +47,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Breaking: `symphonia::SeekError` has a new variant `AccurateSeekNotSupported` and variants `Retrying` and `Refining` have been removed. Catching this error may allow a caller to retry in coarse seek mode. +- Breaking: `symphonia::SeekError` has a new variant `RandomAccessNotSupported`. This error usually means that you are trying to seek backward without `is_seekable` or `byte_len` set: use `Decoder::try_from` or `DecoderBuilder` for that. - Breaking: In the `Source` trait, the method `current_frame_len()` was renamed to `current_span_len()`. - Breaking: `Decoder` now outputs `f32` samples. - Breaking: The term 'frame' was renamed to 'span' in the crate and documentation. @@ -75,8 +76,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 correctly. - Removed unwrap() calls in MP3, WAV, FLAC and Vorbis format detection for better error handling. - `LoopedDecoder::size_hint` now correctly indicates an infinite stream. -- Symphonia decoder `total_duration` no longer returns None when it could - return Some +- Symphonia decoder `total_duration` no longer returns `None` when it could + return `Some` - Symphonia decoder for MP4 now seeks correctly (#577). - White noise was not correctly uniformly distributed. - Pink noise was not correctly distributed on sampling rates other than 44100 Hz. diff --git a/outreach/v0.21_announcement.md b/outreach/v0.21_announcement.md index 32c838e8..455c451d 100644 --- a/outreach/v0.21_announcement.md +++ b/outreach/v0.21_announcement.md @@ -19,7 +19,8 @@ other contributors helping out. Thanks to you all this release: - Our types are no longer generic over sample type. - The features have been overhauled and we now have better defaults. - Adds new functionality: - - Many rodio parts are now more configurable and customizable + - Many rodio parts such as the decoder and outputstream are now easily + configurable using builders. - Amplify using decibals or perceptually. - A distortion effect. - A limiter. From e5e240419f4a5dda726bef7e9392b5d7b24e04ed Mon Sep 17 00:00:00 2001 From: dvdsk Date: Sat, 5 Jul 2025 15:32:19 +0200 Subject: [PATCH 12/17] formatting --- CHANGELOG.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 44b78dec..ec3cdb9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -56,15 +56,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Breaking: Sources now use `f32` samples. To convert to and from other types of samples use functions from `dasp_sample` crate. For example `DaspSample::from_sample(sample)`. - Breaking: `WhiteNoise` and `PinkNoise` have been renamed to `noise::WhiteUniform` and `noise::Pink`. +- Breaking: As optional features are now available: CAF and MKV containers, MP1/MP2 and ADPCM decoders. Previously, the ADPCM decoder was enabled when `symphonia-wav` was. +- docs.rs will now document all features, including those that are not enabled by default. - `OutputStreamConfig` is now public. - `OutputStream` now prints when it is dropped, can be disabled with `OutputStream::log_on_drop(false)`. - Update `cpal` to [0.16](https://github.com/RustAudio/cpal/blob/master/CHANGELOG.md#version-0160-2025-06-07). -- The default decoders have changed to Symphonia. The previous decoders are still available as - optional features: use `claxon` for FLAC, `lewton` for Vorbis, and `hound` for WAV. +- The default decoders have changed to Symphonia. The previous decoders are still available as optional features: use `claxon` for FLAC, `lewton` for Vorbis, and `hound` for WAV. - Support for decoding MP4 containers with AAC audio is now enabled by default. -- Breaking: As optional features are now available: CAF and MKV containers, MP1/MP2 and ADPCM - decoders. Previously, the ADPCM decoder was enabled when `symphonia-wav` was. -- docs.rs will now document all features, including those that are not enabled by default. ### Fixed - `ChannelVolume` no longer clips/overflows when converting from many channels to From 2655c04c1897374fee5fc33d8247cd037b194863 Mon Sep 17 00:00:00 2001 From: Roderick van Domburg Date: Sat, 12 Jul 2025 16:00:06 +0200 Subject: [PATCH 13/17] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- UPGRADE.md | 2 +- outreach/v0.21_announcement.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 868bb411..22b5ed24 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ See [the feature flags](https://docs.rs/crate/rodio/latest/features) for more de [The documentation](http://docs.rs/rodio) contains an introduction to the library. # [Breaking Changes](UPGRADE.md) -We have written an upgrade [guide](UPGRADE.md), it will help you upgrade to rodio 0.21. +We have written an upgrade [guide](UPGRADE.md). It will help you upgrade to rodio 0.21. # [Examples](https://github.com/RustAudio/rodio/tree/f1eaaa4a6346933fc8a58d5fd1ace170946b3a94/examples) diff --git a/UPGRADE.md b/UPGRADE.md index c33b6516..6262c5ce 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -58,7 +58,7 @@ Replace `DynamicMixerController` with `Mixer` and `DynamicMixer` with `MixerSour ## Decoder - `Decoder::new_mp4` no longer takes an `Mp4Type` as hint. You can remove the argument -- Symphonia now longer assumes all sources are seek-able. Use +- Symphonia no longer assumes all sources are seek-able. Use `DecoderBuilder::with_seekable` or `try_from` on a `File` or `Bufreader`. The following Rodio *0.20.1* code diff --git a/outreach/v0.21_announcement.md b/outreach/v0.21_announcement.md index 455c451d..fd975ba3 100644 --- a/outreach/v0.21_announcement.md +++ b/outreach/v0.21_announcement.md @@ -10,7 +10,7 @@ sounds, apply effects to sounds & mix them. Rodio has been part of the Rust ecosystem for 9 years now! 🎉. ## New release -It's been 5 months since our last release. Since the our team has grown to 3 +It's been 8 months since our last release. Since then our team has grown to 3 maintainers! Thank you Petr and Roderick! And a big thanks for the countless other contributors helping out. Thanks to you all this release: @@ -21,7 +21,7 @@ other contributors helping out. Thanks to you all this release: - Adds new functionality: - Many rodio parts such as the decoder and outputstream are now easily configurable using builders. - - Amplify using decibals or perceptually. + - Amplify using decibels or perceptually. - A distortion effect. - A limiter. - Many more noise generators From 1176a0ed54e6cacbcedd9464bbb85a9fdd176cf9 Mon Sep 17 00:00:00 2001 From: Roderick van Domburg Date: Sat, 12 Jul 2025 16:29:06 +0200 Subject: [PATCH 14/17] docs: update UPGRADE.md for rodio 0.21 with clearer instructions - Clarify required code changes for upgrading to 0.21 - Add missing details on features, decoders, and trait changes - Improve examples and explanations for Sink, Decoder, and Mixer updates - Reorganize sections for better readability --- UPGRADE.md | 80 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 45 insertions(+), 35 deletions(-) diff --git a/UPGRADE.md b/UPGRADE.md index 6262c5ce..4962dbff 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -1,51 +1,50 @@ This guide will help you update your code when upgrading from older versions of -rodio. While we do our best we might have missed things. PR's that improve this +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.21 to current GitHub version -nothing +Nothing. # rodio 0.20 or earlier to 0.21 ## Features -- If you use disable the rodio features with `default_features = false` in `Cargo.toml` you need to - add a new feature `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 disable default-features and enable the `claxon`, `hound` and `lewton` features in `Cargo.toml` for respectively FLAC, WAV and Ogg Vorbis. - -## Source implementations -- Source had a required method `current_frame_len`. In the latest version of rodio *frame* has been renamed to *span*. You will need to change every occurrence of `current_frame_len` to `current_span_len`. -- Source was generic over sample type. It no longer is. - - Remove any generics (`::`, `::` or `::`) that cause errors. - - Remove `SampleConvertor` it is no longer needed and has been removed. - - Remove any calls to `source.convert_samples()` they are no longer needed and - removed +- 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 -- The output stream is now more configurable. Where you used `OutputStream::try_default()` you have a choice: - - *(recommended)* Get an error when the default stream could not be opened: `OutputStreamBuilder::open_default_stream()?` - - Stay close to the old behavior using: - `OutputStreamBuilder::open_stream_or_fallback()`, which tries to open the - default (audio) stream. If that fails it tries all other combinations of - device and settings. The old behavior was only trying all settings of the - default device. +- 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 + returns an error when the default stream could not be opened, or + - `OutputStreamBuilder::open_stream_or_fallback()`, which tries to open the + default audio stream. If that fails it tries all other combinations of + device and settings. This is close to the old behavior, except that + previously only all settings of the default device were tried. - 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`. It now takes an `&Mixer` -instead of a `OutputStreamHandle`. You get an `&Mixer` by calling `mixer()` on -`OutputStream`. -- Replace `Sink::new_idle` with `Sink::new`, +- 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.1* code: +The following Rodio *0.20* code: ```rust let (_stream, handle) = rodio::OutputStream::try_default()?; let sink = rodio::Sink::try_new(&handle)?; ``` -Should be written like this in Rodio *0.21.0*: +Should be written like this in Rodio *0.21*: ```rust let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?; let sink = rodio::Sink::connect_new(stream_handle.mixer()); @@ -53,22 +52,33 @@ let sink = rodio::Sink::connect_new(stream_handle.mixer()); The `SpatialSink` changes mirror those in `Sink` described above. -## Dynamic mixer -Replace `DynamicMixerController` with `Mixer` and `DynamicMixer` with `MixerSource`. - ## Decoder -- `Decoder::new_mp4` no longer takes an `Mp4Type` as hint. You can remove the argument -- Symphonia no longer assumes all sources are seek-able. Use - `DecoderBuilder::with_seekable` or `try_from` on a `File` or `Bufreader`. +- `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.1* code +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.0*: +Should be written like this in Rodio *0.21*: ```rust let file = File::open("music.ogg")?; let source = Decoder::try_from(music.ogg)?; ``` + +## DynamicMixer +- Replace `DynamicMixerController` with `Mixer` and `DynamicMixer` with + `MixerSource`. + +## 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 (`::`, `::` or `::`) that cause errors. + - Remove any use of `SampleConvertor`. + - Remove any calls to `convert_samples`. From f92da99babcc7d3db95e0f9641b95a8bd25c3684 Mon Sep 17 00:00:00 2001 From: Roderick van Domburg Date: Sat, 12 Jul 2025 16:35:35 +0200 Subject: [PATCH 15/17] docs: fix example in UPGRADE.md --- UPGRADE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/UPGRADE.md b/UPGRADE.md index 4962dbff..4ebbb7ea 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -7,7 +7,7 @@ changes and new features, see [CHANGELOG.md]. # rodio 0.21 to current GitHub version -Nothing. +No changes are required. # rodio 0.20 or earlier to 0.21 @@ -67,7 +67,7 @@ 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(music.ogg)?; +let source = Decoder::try_from(file)?; ``` ## DynamicMixer From d7908a4711ef0f578b0adca378081a1d8d7aca25 Mon Sep 17 00:00:00 2001 From: Roderick van Domburg Date: Sat, 12 Jul 2025 16:39:02 +0200 Subject: [PATCH 16/17] docs: deprecate Source::white and Source::pink methods --- UPGRADE.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/UPGRADE.md b/UPGRADE.md index 4ebbb7ea..15c4fd6f 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -74,6 +74,10 @@ let source = Decoder::try_from(file)?; - 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. From 48d7b2003b392faa78f38fd64db409e9c033abdd Mon Sep 17 00:00:00 2001 From: dvdsk Date: Sat, 12 Jul 2025 17:35:22 +0200 Subject: [PATCH 17/17] puts release date in CHANGELOG --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ec3cdb9c..8dcce2a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -## Version [0.21] (TODO) +## Version [0.21] (2025-07-12) ### Added - Added `Source::amplify_decibel()` method to control volume by decibels.