feat(audio): migrate Ogg Vorbis encoding to craft-audio (PR #26)

- Add vorbis-encode feature with dep:vorbis_rs = "0.5"
- Implement encode_ogg() via VorbisEncoderBuilder matching original behavior:
  - Fixed stream serial 0x4C43_5246, VBR target bitrate (64-500 kbit/s)
  - 4096-frame blocks, panic catch with QualityVbr fallback (target_quality: 0.6)
- Add EncodeFormat::Ogg variant (cfg-gated on vorbis-encode)
- Update ENCODE_EXTENSIONS and encode_format_for() to include .ogg
This commit is contained in:
Dylan M. Taylor authored and Dylan Taylor committed 2026-11-14 10:02:09 -05:00
1 parent a207d20700
commit b9c1dfa18f
5 files changed
+164 -7

No files matched your search

Generated
+34
View File
@@ -222,6 +222,16 @@ version = "1.0.104"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
[[package]]
name = "aotuv_lancer_vorbis_sys"
version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5bc4fd1a61860d2f1198b60bedd30910eaffa978f1ee6214dfb24ac70d589225"
dependencies = [
"cc",
"ogg_next_sys",
]
[[package]]
name = "arbitrary"
version = "1.5.0"
@@ -1349,6 +1359,7 @@ dependencies = [
"serde_json",
"symphonia",
"thiserror 2.0.21",
"vorbis_rs",
]
[[package]]
@@ -6563,6 +6574,15 @@ dependencies = [
"phf 0.11.3",
]
[[package]]
name = "ogg_next_sys"
version = "0.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed2d7a48e247c2bb07e633aefb65a38648ea58c7eedd4e4408a5861721ab049b"
dependencies = [
"cc",
]
[[package]]
name = "once_cell"
version = "1.21.4"
@@ -10279,6 +10299,20 @@ version = "0.9.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
[[package]]
name = "vorbis_rs"
version = "0.5.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "49c5da94d280f7a27e8c937e9b73df2da3e23a2583f48471fd8fb4c72f9c1933"
dependencies = [
"aotuv_lancer_vorbis_sys",
"errno",
"getrandom 0.4.3",
"ogg_next_sys",
"thiserror 2.0.21",
"tinyvec",
]
[[package]]
name = "wait-timeout"
version = "0.2.1"
+3
View File
@@ -30,6 +30,8 @@ lossless-encode = ["pcm-encode", "flac-encode"]
pcm-encode = []
# Encode FLAC files.
flac-encode = ["craft-media/bitstream"]
# Encode Ogg Vorbis files (desktop only: builds the reference libvorbis from its C sources).
vorbis-encode = ["dep:vorbis_rs"]
# Codec modules on their own, for packet-level use.
aac-decode = ["craft-media/bitstream"]
aac-encode = ["craft-media/bitstream"]
@@ -59,6 +61,7 @@ thiserror = { workspace = true }
serde = { workspace = true, optional = true }
log = { version = "0.4", optional = true }
rayon = { workspace = true, optional = true }
vorbis_rs = { version = "0.5", optional = true }
# symphonia keeps its AAC decoder for AAC in CAF, a container craft-media does not read.
symphonia = { version = "0.6.1", optional = true, default-features = false, features = ["mp3", "flac", "vorbis", "ogg", "wav", "pcm", "aiff", "isomp4", "aac", "alac", "adpcm", "caf", "mkv"] }
+19 -1
View File
@@ -54,8 +54,12 @@ mod read;
mod track;
#[cfg(any(feature = "decode-native", feature = "pcm-encode"))]
mod wav;
#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))]
#[cfg(any(feature = "pcm-encode", feature = "flac-encode", feature = "vorbis-encode"))]
mod write;
#[cfg(feature = "vorbis-encode")]
pub use write::encode_ogg;
#[cfg(feature = "vorbis-encode")]
pub use write::OGG_BITRATES;
/// The FLAC packet encoder (RFC 9639), for a caller that muxes FLAC itself (into MP4, Matroska or
/// its own `.flac` writer): planar integer samples in, frames out, and the STREAMINFO to patch in
@@ -226,12 +230,20 @@ pub enum EncodeFormat {
Aiff,
/// FLAC (integer depths).
Flac,
/// Ogg Vorbis (variable bitrate). Whole-buffer only: use [`encode_ogg`] directly.
#[cfg(feature = "vorbis-encode")]
Ogg,
}
impl EncodeFormat {
/// Every format, in the order menus list them. Whether [`encode`] writes one depends on its
/// feature.
#[cfg(not(feature = "vorbis-encode"))]
pub const ALL: &[EncodeFormat] = &[EncodeFormat::Wav, EncodeFormat::Aiff, EncodeFormat::Flac];
/// Every format, in the order menus list them. Whether [`encode`] writes one depends on its
/// feature.
#[cfg(feature = "vorbis-encode")]
pub const ALL: &[EncodeFormat] = &[EncodeFormat::Wav, EncodeFormat::Aiff, EncodeFormat::Flac, EncodeFormat::Ogg];
/// The extension a new file of this format gets, lower case and without the dot: `"wav"`,
/// `"aif"`, `"flac"`. [`encode_format_for`] maps it back.
@@ -240,6 +252,8 @@ impl EncodeFormat {
EncodeFormat::Wav => "wav",
EncodeFormat::Aiff => "aif",
EncodeFormat::Flac => "flac",
#[cfg(feature = "vorbis-encode")]
EncodeFormat::Ogg => "ogg",
}
}
@@ -249,6 +263,8 @@ impl EncodeFormat {
EncodeFormat::Wav => "audio/wav",
EncodeFormat::Aiff => "audio/aiff",
EncodeFormat::Flac => "audio/flac",
#[cfg(feature = "vorbis-encode")]
EncodeFormat::Ogg => "audio/ogg",
}
}
@@ -258,6 +274,8 @@ impl EncodeFormat {
EncodeFormat::Wav => Container::Wav,
EncodeFormat::Aiff => Container::Aiff,
EncodeFormat::Flac => Container::Flac,
#[cfg(feature = "vorbis-encode")]
EncodeFormat::Ogg => Container::Ogg,
}
}
}
+50 -6
View File
@@ -10,6 +10,10 @@ mod pcm;
mod raw;
#[cfg(feature = "pcm-encode")]
mod wav;
#[cfg(feature = "vorbis-encode")]
pub(crate) mod vorbis;
#[cfg(feature = "vorbis-encode")]
pub use vorbis::OGG_BITRATES;
use crate::{AudioBuffer, AudioError, ChannelLayout, EncodeFormat, EncodeOptions, Result};
#[cfg(feature = "pcm-encode")]
@@ -47,20 +51,54 @@ pub fn encode(buf: &AudioBuffer, opts: &EncodeOptions) -> Result<Vec<u8>> {
/// Refuses a format whose writer is not built, before anything else about the request is checked.
fn check_built(format: EncodeFormat) -> Result<()> {
let (built, feature) =
if format == EncodeFormat::Flac { (cfg!(feature = "flac-encode"), "flac-encode") } else { (cfg!(feature = "pcm-encode"), "pcm-encode") };
let (built, feature) = match format {
EncodeFormat::Flac => (cfg!(feature = "flac-encode"), "flac-encode"),
#[cfg(feature = "vorbis-encode")]
EncodeFormat::Ogg => (cfg!(feature = "vorbis-encode"), "vorbis-encode"),
_ => (cfg!(feature = "pcm-encode"), "pcm-encode"),
};
if built { Ok(()) } else { Err(AudioError::Unsupported(format!("writing {format:?} needs the `{feature}` feature"))) }
}
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "pcm-encode", feature = "flac-encode"))]
#[cfg(all(feature = "pcm-encode", feature = "flac-encode", feature = "vorbis-encode"))]
pub const ENCODE_EXTENSIONS: &[&str] = &["wav", "wave", "bwf", "aif", "aiff", "aifc", "flac", "ogg"];
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "pcm-encode", feature = "flac-encode", not(feature = "vorbis-encode")))]
pub const ENCODE_EXTENSIONS: &[&str] = &["wav", "wave", "bwf", "aif", "aiff", "aifc", "flac"];
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "pcm-encode", not(feature = "flac-encode")))]
#[cfg(all(feature = "pcm-encode", feature = "vorbis-encode", not(feature = "flac-encode")))]
pub const ENCODE_EXTENSIONS: &[&str] = &["wav", "wave", "bwf", "aif", "aiff", "aifc", "ogg"];
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "pcm-encode", not(feature = "flac-encode"), not(feature = "vorbis-encode")))]
pub const ENCODE_EXTENSIONS: &[&str] = &["wav", "wave", "bwf", "aif", "aiff", "aifc"];
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "flac-encode", not(feature = "pcm-encode")))]
#[cfg(all(feature = "flac-encode", feature = "vorbis-encode", not(feature = "pcm-encode")))]
pub const ENCODE_EXTENSIONS: &[&str] = &["flac", "ogg"];
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "flac-encode", not(feature = "pcm-encode"), not(feature = "vorbis-encode")))]
pub const ENCODE_EXTENSIONS: &[&str] = &["flac"];
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "vorbis-encode", not(feature = "pcm-encode"), not(feature = "flac-encode")))]
pub const ENCODE_EXTENSIONS: &[&str] = &["ogg"];
/// Encode `buf` as an Ogg Vorbis stream at about `kbps` (variable, as Vorbis is): stereo, or mono
/// for a mono buffer. A bitrate the encoder has no setup for at that rate and channel count falls
/// back to a quality that suits it. Whole-buffer only: no streaming encoder is provided for Vorbis.
///
/// ```
/// # #[cfg(feature = "vorbis-encode")] {
/// use craft_audio::{AudioBuffer, encode_ogg};
///
/// let buf = AudioBuffer::new(48_000, 2, 48_000); // one second of stereo silence
/// let ogg = encode_ogg(&buf, 192).unwrap();
/// assert_eq!(&ogg[..4], b"OggS");
/// # }
/// ```
#[cfg(feature = "vorbis-encode")]
pub fn encode_ogg(buf: &AudioBuffer, kbps: u32) -> Result<Vec<u8>> {
vorbis::encode(buf, kbps)
}
/// The format [`encode`] writes for a file extension or format name (`wav`, `aiff`, `flac`,
/// case-insensitive, with or without the dot), or `None` when it cannot write it. `aifc` is
@@ -82,6 +120,8 @@ pub fn encode_format_for(name: &str) -> Option<EncodeFormat> {
"aif" | "aiff" | "aifc" => Some(EncodeFormat::Aiff),
#[cfg(feature = "flac-encode")]
"flac" => Some(EncodeFormat::Flac),
#[cfg(feature = "vorbis-encode")]
"ogg" => Some(EncodeFormat::Ogg),
_ => None,
}
}
@@ -123,11 +163,13 @@ fn failed_write_error() -> AudioError {
/// assert_eq!(&flac[..4], b"fLaC");
/// # }
/// ```
#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))]
pub struct FileEncoder<W: Write + Seek> {
writer: Writer<W>,
channels: usize,
}
#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))]
impl<W: Write + Seek> std::fmt::Debug for FileEncoder<W> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let format = match &self.writer {
@@ -142,6 +184,7 @@ impl<W: Write + Seek> std::fmt::Debug for FileEncoder<W> {
}
}
#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))]
enum Writer<W> {
#[cfg(feature = "pcm-encode")]
Wav(wav::Writer<W>),
@@ -151,6 +194,7 @@ enum Writer<W> {
Flac(flac::Writer<W>),
}
#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))]
impl<W: Write + Seek> FileEncoder<W> {
/// Starts a file of `channels` channels at `sample_rate` at the current position of `out`.
/// `opts.layout`, when set, must have `channels` channels.
@@ -252,7 +296,7 @@ pub fn wav_float_header(sample_rate: u32, channels: u16, frames: u64) -> Result<
// With only one of `pcm-encode` and `flac-encode`, the other's formats are refused, not silently
// written as something else.
#[cfg(all(test, not(all(feature = "pcm-encode", feature = "flac-encode"))))]
#[cfg(all(test, any(feature = "pcm-encode", feature = "flac-encode"), not(all(feature = "pcm-encode", feature = "flac-encode"))))]
mod tests {
use super::*;
+58
View File
@@ -0,0 +1,58 @@
//! Ogg Vorbis encoding (RFC 5334): the reference libvorbis encoder, built from its C sources by
//! `vorbis_rs`. Stereo or mono, variable bitrate at the requested kbit/s (64–500), with a
//! fallback to a quality preset when the bitrate is not supported for the rate and channel count.
use crate::{AudioBuffer, AudioError, Result};
/// The bitrates an Ogg Vorbis export is asked for, in kbit/s.
pub const OGG_BITRATES: (u32, u32) = (64, 500);
/// The block size the encoder processes at a time: small enough that memory stays bounded
/// regardless of file length.
const BLOCK: usize = 4096;
fn encode_error(e: vorbis_rs::VorbisError) -> AudioError {
AudioError::Encode(e.to_string())
}
/// Encode `buf` as an Ogg Vorbis stream at about `kbps` (variable, as Vorbis is): stereo, or mono
/// for a mono buffer. A bitrate the encoder has no setup for at that rate and channel count falls
/// back to a quality that suits it. `Err` says why there is nothing.
#[cfg(not(target_arch = "wasm32"))]
pub fn encode(buf: &AudioBuffer, kbps: u32) -> Result<Vec<u8>> {
use std::num::{NonZeroU8, NonZeroU32};
let channels = buf.channels.len().clamp(1, 2);
let (Some(rate), Some(count)) = (NonZeroU32::new(buf.sample_rate), NonZeroU8::new(channels as u8)) else {
return Err(AudioError::Encode("there is no audio to encode".into()));
};
let target = NonZeroU32::new(kbps.clamp(OGG_BITRATES.0, OGG_BITRATES.1) * 1000).unwrap_or(NonZeroU32::MIN);
let encode = |strategy: vorbis_rs::VorbisBitrateManagementStrategy| -> Result<Vec<u8>> {
let mut encoder = vorbis_rs::VorbisEncoderBuilder::new_with_serial(rate, count, Vec::new(), 0x4C43_5246)
.bitrate_management_strategy(strategy)
.build()
.map_err(encode_error)?;
let frames = buf.frames();
let mut at = 0usize;
while at < frames {
let end = (at + BLOCK).min(frames);
let block: Vec<&[f32]> = buf.channels.iter().take(channels).map(|side| side.get(at..end).unwrap_or_default()).collect();
encoder.encode_audio_block(&block).map_err(encode_error)?;
at = end;
}
encoder.finish().map_err(encode_error)
};
// The library is C: whatever it does wrong ends here as an error, never as a crash of the app.
let attempt = |strategy| std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| encode(strategy))).unwrap_or_else(|_| Err(AudioError::Encode("the Vorbis encoder failed".into())));
match attempt(vorbis_rs::VorbisBitrateManagementStrategy::Vbr { target_bitrate: target }) {
Ok(bytes) => Ok(bytes),
Err(_) => attempt(vorbis_rs::VorbisBitrateManagementStrategy::QualityVbr { target_quality: 0.6 }).map_err(|e| AudioError::Encode(format!("the Vorbis encoder refused the audio: {e}"))),
}
}
#[cfg(target_arch = "wasm32")]
pub fn encode(_buf: &AudioBuffer, _kbps: u32) -> Result<Vec<u8>> {
Err("Ogg Vorbis files are exported by the desktop app".into())
}