From dc2b83d7f426cb3286b3a1fa67229f27c1ca4d40 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sat, 14 Nov 2026 18:13:31 -0500 Subject: [PATCH] Document Vorbis rate semantics and validate standalone options --- crates/audio/src/lib.rs | 3 ++- crates/audio/src/write/mod.rs | 35 +++++++++++++++++++++++--------- crates/audio/src/write/vorbis.rs | 3 +++ 3 files changed, 30 insertions(+), 11 deletions(-) diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 697568201..33dcdee3b 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -472,7 +472,8 @@ pub enum RateControl { /// set of rates (MP3, AC-3) uses the highest one not above it; a rate outside what the /// stream can carry is moved to the nearest one inside. AAC is written at 6 kbit/s or a /// quarter of the sample rate per channel at least: from about half of that down its encoder - /// codes silence. + /// codes silence. Vorbis treats this as a VBR target (64–500 kbit/s), falling back to + /// a quality preset when that target is unsupported; it does not promise a constant bitrate. Bitrate(u32), /// A constant quality from 0.0 (smallest) to 1.0 (best), at whatever bit rate each frame /// needs. AAC only; values outside the range are clamped, and NaN is an error. diff --git a/crates/audio/src/write/mod.rs b/crates/audio/src/write/mod.rs index 597a02e07..ce4b90773 100644 --- a/crates/audio/src/write/mod.rs +++ b/crates/audio/src/write/mod.rs @@ -367,15 +367,6 @@ impl FileEncoder { } } -#[cfg(any( - feature = "pcm-encode", - feature = "flac-encode", - feature = "aac-encode", - feature = "alac-encode", - feature = "mp3-encode", - feature = "ac3-encode", - feature = "eac3-encode" -))] impl EncodeOptions { /// Whether a file of `channels` channels at `sample_rate` can be written with these options: /// `Ok`, or the error [`FileEncoder::new`] and [`encode`] would return, with nothing written. @@ -407,7 +398,31 @@ impl EncodeOptions { } // The encoder a file would get, on a sink that is thrown away: what it accepts and the // rate it settles on are then the writer's by construction. - Ok(FileEncoder::new(std::io::Cursor::new(Vec::new()), self, sample_rate, channels)?.bitrate()) + #[cfg(any( + feature = "pcm-encode", + feature = "flac-encode", + feature = "aac-encode", + feature = "alac-encode", + feature = "mp3-encode", + feature = "ac3-encode", + feature = "eac3-encode" + ))] + { + Ok(FileEncoder::new(std::io::Cursor::new(Vec::new()), self, sample_rate, channels)?.bitrate()) + } + #[cfg(not(any( + feature = "pcm-encode", + feature = "flac-encode", + feature = "aac-encode", + feature = "alac-encode", + feature = "mp3-encode", + feature = "ac3-encode", + feature = "eac3-encode" + )))] + { + let _ = (sample_rate, channels); + Err(AudioError::Unsupported("streaming encoders are not built".into())) + } } } diff --git a/crates/audio/src/write/vorbis.rs b/crates/audio/src/write/vorbis.rs index a5e09ad88..f0e267d50 100644 --- a/crates/audio/src/write/vorbis.rs +++ b/crates/audio/src/write/vorbis.rs @@ -64,6 +64,7 @@ pub fn encode(buf: &AudioBuffer, kbps: u32) -> Result> { } } +/// Ogg Vorbis encoding is unavailable on WASM; returns an unsupported-format error. #[cfg(target_arch = "wasm32")] pub fn encode(_buf: &AudioBuffer, _kbps: u32) -> Result> { Err(AudioError::Unsupported("Ogg Vorbis files are exported by the desktop app".into())) @@ -91,6 +92,8 @@ mod tests { for channels in [1, 2] { let audio = AudioBuffer::new(48_000, channels, 512); let opts = crate::EncodeOptions::new(crate::EncodeFormat::Ogg); + assert!(opts.check(48_000, channels).is_ok()); + assert_eq!(opts.bitrate(48_000, channels).unwrap(), None); let direct = encode(&audio, 192).unwrap(); let generic = crate::encode(&audio, &opts).unwrap(); assert!(direct.starts_with(b"OggS"));