diff --git a/Cargo.lock b/Cargo.lock index a1b1ccab3..1314c7745 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -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" diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index 9b6200198..63e55d232 100644 --- a/crates/audio/Cargo.toml +++ b/crates/audio/Cargo.toml @@ -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"] } diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index f8441a51d..04b813c30 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -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, } } } diff --git a/crates/audio/src/write/mod.rs b/crates/audio/src/write/mod.rs index 2355a7b05..4a82fdcbe 100644 --- a/crates/audio/src/write/mod.rs +++ b/crates/audio/src/write/mod.rs @@ -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> { /// 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> { + 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 { "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 { writer: Writer, channels: usize, } +#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))] impl std::fmt::Debug for FileEncoder { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { let format = match &self.writer { @@ -142,6 +184,7 @@ impl std::fmt::Debug for FileEncoder { } } +#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))] enum Writer { #[cfg(feature = "pcm-encode")] Wav(wav::Writer), @@ -151,6 +194,7 @@ enum Writer { Flac(flac::Writer), } +#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))] impl FileEncoder { /// 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::*; diff --git a/crates/audio/src/write/vorbis.rs b/crates/audio/src/write/vorbis.rs new file mode 100644 index 000000000..6b33e8981 --- /dev/null +++ b/crates/audio/src/write/vorbis.rs @@ -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> { + 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> { + 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> { + Err("Ogg Vorbis files are exported by the desktop app".into()) +}