Document Vorbis rate semantics and validate standalone options

This commit is contained in:
Dylan M. Taylor
2026-11-14 18:13:31 -05:00
parent 9efb0a1575
commit dc2b83d7f4
3 changed files with 30 additions and 11 deletions
+2 -1
View File
@@ -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.
+25 -10
View File
@@ -367,15 +367,6 @@ impl<W: Write + Seek> FileEncoder<W> {
}
}
#[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()))
}
}
}
+3
View File
@@ -64,6 +64,7 @@ pub fn encode(buf: &AudioBuffer, kbps: u32) -> Result<Vec<u8>> {
}
}
/// Ogg Vorbis encoding is unavailable on WASM; returns an unsupported-format error.
#[cfg(target_arch = "wasm32")]
pub fn encode(_buf: &AudioBuffer, _kbps: u32) -> Result<Vec<u8>> {
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"));