feedback from roderick and petr

Author: dvdsk

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
 - Adds a function to write a `Source` to a `wav` file, see `output_to_wav`.
@@ -39,7 +39,8 @@ 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: `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.
 
 ### Fixed
 - `ChannelVolume` no longer clips/overflows when converting from many channels to
@@ -60,12 +61,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*
@@ -93,7 +94,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
@@ -103,12 +104,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<dyn Source>` and `&mut Source`
@@ -129,32 +130,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.
@@ -163,57 +164,57 @@ 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
   `StreamError` variants.
 - `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:

README.md

@@ -25,7 +25,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
 

UPGRADE.md

@@ -18,7 +18,7 @@ nothing
       removed
 
 ## OutputStream
-The outputstream is now more configurable. Where you used `OutputStream::try_default()` you have a choice:
+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.
 
@@ -37,7 +37,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.

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