From 0649a07aa11834fa5bd7052c8b97a861db532a22 Mon Sep 17 00:00:00 2001 From: el-j Date: Tue, 17 Nov 2026 18:15:52 +0100 Subject: [PATCH] craft-audio: ITU-T G.726 ADPCM speech codec (#1531) (#1792) * craft-audio: ITU-T G.726 ADPCM speech codec (#1531) * fix(audio): mask G726 sample codewords before adaptation --------- Co-authored-by: Dylan M. Taylor --- crates/audio/Cargo.toml | 6 + crates/audio/src/g726.rs | 996 ++++++++++++++++++++++++++++++ crates/audio/src/lib.rs | 2 + crates/audio/tests/g726_oracle.rs | 218 +++++++ 4 files changed, 1222 insertions(+) create mode 100644 crates/audio/src/g726.rs create mode 100644 crates/audio/tests/g726_oracle.rs diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index 4a873aab5..63eaefdc8 100644 --- a/crates/audio/Cargo.toml +++ b/crates/audio/Cargo.toml @@ -51,6 +51,8 @@ qoa-decode = [] qoa-encode = [] # ITU-T G.722 wideband sub-band ADPCM speech codec (64 kbit/s). g722 = [] +# ITU-T G.726 ADPCM speech codec (16/24/32/40 kbit/s). +g726 = [] opus-encode = [] # GSM 06.10 full-rate speech: decoder and encoder in the `gsm` module, each on its own. gsm = ["gsm-decode", "gsm-encode"] @@ -147,6 +149,10 @@ required-features = ["qoa"] name = "g722_oracle" required-features = ["g722"] +[[test]] +name = "g726_oracle" +required-features = ["g726"] + [[test]] name = "sbc_oracle" required-features = ["sbc"] diff --git a/crates/audio/src/g726.rs b/crates/audio/src/g726.rs new file mode 100644 index 000000000..6ac02359d --- /dev/null +++ b/crates/audio/src/g726.rs @@ -0,0 +1,996 @@ +//! ITU-T Recommendation G.726 ADPCM speech codec (16, 24, 32, 40 kbit/s). +//! +//! Clean-room implementation based on ITU-T Recommendation G.726 (12/1990) +//! "40, 32, 24, 16 kbit/s Adaptive Differential Pulse Code Modulation (ADPCM)". +//! +//! Provides encoding from 8 kHz 16-bit linear PCM to G.726 bitstreams, and decoding +//! from G.726 bitstreams to 8 kHz 16-bit linear PCM. +//! +//! Supports both standard big-endian bit packing (network order / RFC 3551) and +//! little-endian bit packing (RIFF WAV / AVID format tag 0x0045 / 0x0014). + +const MAX_CHANNELS: usize = 8; +const MAX_INPUT_BYTES: usize = 64 * 1024 * 1024; +const MAX_SAMPLES: usize = 64 * 1024 * 1024; + +/// Bit rate for G.726 ADPCM. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum BitRate { + /// 16 kbit/s (2 bits per sample). + Rate16k, + /// 24 kbit/s (3 bits per sample). + Rate24k, + /// 32 kbit/s (4 bits per sample). + Rate32k, + /// 40 kbit/s (5 bits per sample). + Rate40k, +} + +impl BitRate { + /// Number of bits per code (sample). + #[inline] + #[must_use] + pub const fn code_size(self) -> usize { + match self { + Self::Rate16k => 2, + Self::Rate24k => 3, + Self::Rate32k => 4, + Self::Rate40k => 5, + } + } + + /// Bit rate in bits per second. + #[inline] + #[must_use] + pub const fn bit_rate_bps(self) -> u32 { + match self { + Self::Rate16k => 16_000, + Self::Rate24k => 24_000, + Self::Rate32k => 32_000, + Self::Rate40k => 40_000, + } + } +} + +/// Bit packing order within bytes. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum BitPacking { + /// Big-endian packing: MSB to LSB (standard RFC 3551 / network order). + #[default] + BigEndian, + /// Little-endian packing: LSB to MSB (WAV / RIFF order). + LittleEndian, +} + +/// Errors returned by G.726 operations. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// Channel count must be between 1 and 8. + #[error("unsupported channel count: {0} (must be 1..=8)")] + InvalidChannels(usize), + /// Input exceeds safe maximum memory bound. + #[error("input exceeds safe maximum processing limit")] + InputTooLarge, + /// Output buffer allocation failed. + #[error("memory allocation failed")] + AllocationFailed, +} + +// --------------------------------------------------------------------------- +// G.726 Tables +// --------------------------------------------------------------------------- + +// Table 11..14 (I -> DQS, DQLN) +static OUT_16: [(u8, u16); 4] = [(0, 116), (0, 365), (1, 365), (1, 116)]; + +static OUT_24: [(u8, u16); 8] = [(0, 2048), (0, 135), (0, 273), (0, 373), (1, 373), (1, 273), (1, 135), (1, 2048)]; + +static OUT_32: [(u8, u16); 16] = [ + (0, 2048), + (0, 4), + (0, 135), + (0, 213), + (0, 273), + (0, 323), + (0, 373), + (0, 425), + (1, 425), + (1, 373), + (1, 323), + (1, 273), + (1, 213), + (1, 135), + (1, 4), + (1, 2048), +]; + +static OUT_40: [(u8, u16); 32] = [ + (0, 2048), + (0, 4030), + (0, 28), + (0, 104), + (0, 169), + (0, 224), + (0, 274), + (0, 318), + (0, 358), + (0, 395), + (0, 429), + (0, 459), + (0, 488), + (0, 514), + (0, 539), + (0, 566), + (1, 566), + (1, 539), + (1, 514), + (1, 488), + (1, 459), + (1, 429), + (1, 395), + (1, 358), + (1, 318), + (1, 274), + (1, 224), + (1, 169), + (1, 104), + (1, 28), + (1, 4030), + (1, 2048), +]; + +// FUNCTW: scale factor multipliers WI +static WI_16: [u16; 2] = [4074, 439]; +static WI_24: [u16; 4] = [4092, 30, 137, 582]; +static WI_32: [u16; 8] = [4084, 18, 41, 64, 112, 198, 355, 1122]; +static WI_40: [u16; 16] = [14, 14, 24, 39, 40, 41, 58, 100, 141, 179, 219, 280, 358, 440, 529, 696]; + +#[inline] +fn get_wi(rate: BitRate, code: u8) -> u16 { + match rate { + BitRate::Rate16k => { + let im = if (code >> 1) == 0 { (code & 1) as usize } else { ((3 - code) & 1) as usize }; + WI_16[im] + } + BitRate::Rate24k => { + let im = if (code >> 2) == 0 { (code & 3) as usize } else { ((7 - code) & 3) as usize }; + WI_24[im] + } + BitRate::Rate32k => { + let im = if (code >> 3) == 0 { (code & 7) as usize } else { ((15 - code) & 7) as usize }; + WI_32[im] + } + BitRate::Rate40k => { + let im = if (code >> 4) == 0 { (code & 15) as usize } else { ((31 - code) & 15) as usize }; + WI_40[im] + } + } +} + +#[inline] +fn get_fi(rate: BitRate, code: u8) -> u8 { + match rate { + BitRate::Rate16k => { + let im = if (code >> 1) == 0 { code & 1 } else { (3 - code) & 1 }; + if im == 1 { 7 } else { 0 } + } + BitRate::Rate24k => { + let im = if (code >> 2) == 0 { code & 3 } else { (7 - code) & 3 }; + match im { + 0 => 0, + 1 => 1, + 2 => 2, + _ => 7, + } + } + BitRate::Rate32k => { + let im = if (code >> 3) == 0 { code & 7 } else { (15 - code) & 7 }; + if im <= 2 { + 0 + } else if im <= 5 { + 1 + } else if im == 6 { + 3 + } else { + 7 + } + } + BitRate::Rate40k => { + let im = if (code >> 4) == 0 { code & 15 } else { (31 - code) & 15 }; + if im <= 4 { + 0 + } else if im <= 9 { + 1 + } else { + match im { + 10 => 2, + 11 => 3, + 12 => 4, + 13 => 5, + _ => 6, + } + } + } + } +} + +// Quantizer decision intervals (lo, hi, positive_code, negative_code) +static THRESH_16: [(i32, i32, u8, u8); 1] = [(261, 2047, 1, 2)]; + +static THRESH_24: [(i32, i32, u8, u8); 3] = [(331, 2047, 3, 4), (218, 330, 2, 5), (8, 217, 1, 6)]; + +static THRESH_32: [(i32, i32, u8, u8); 8] = [ + (400, 2047, 7, 8), + (349, 399, 6, 9), + (300, 348, 5, 10), + (246, 299, 4, 11), + (178, 245, 3, 12), + (80, 177, 2, 13), + (0, 79, 1, 14), + (3972, 4095, 1, 14), +]; + +static THRESH_40: [(i32, i32, u8, u8); 16] = [ + (553, 2047, 15, 16), + (528, 552, 14, 17), + (502, 527, 13, 18), + (475, 501, 12, 19), + (445, 474, 11, 20), + (413, 444, 10, 21), + (378, 412, 9, 22), + (339, 377, 8, 23), + (298, 338, 7, 24), + (250, 297, 6, 25), + (198, 249, 5, 26), + (139, 197, 4, 27), + (68, 138, 3, 28), + (0, 67, 2, 29), + (4080, 4095, 2, 29), + (3974, 4079, 1, 30), +]; + +#[inline] +fn quantize_16(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_16 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + if ds == 0 { 0 } else { 3 } +} + +#[inline] +fn quantize_24(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_24 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + 7 +} + +#[inline] +fn quantize_32(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_32 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + 15 +} + +#[inline] +fn quantize_40(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_40 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + 31 +} + +// --------------------------------------------------------------------------- +// G.726 Core State +// --------------------------------------------------------------------------- + +#[derive(Debug, Clone)] +struct Core { + rate: BitRate, + is_40k: bool, + a: [u16; 2], + b: [u16; 6], + dms: i16, + dml: i16, + ap: i16, + yu: i16, + yl: i32, + sr: [u16; 2], + dq: [u16; 6], + pk: [u8; 2], + td: i16, +} + +impl Core { + fn new(rate: BitRate) -> Self { + let is_40k = matches!(rate, BitRate::Rate40k); + let mut core = + Self { rate, is_40k, a: [0; 2], b: [0; 6], dms: 0, dml: 0, ap: 0, yu: 544, yl: 34816, sr: [32, 32], dq: [32; 6], pk: [0; 2], td: 0 }; + core.reset(); + core + } + + fn reset(&mut self) { + self.a = [0; 2]; + self.b = [0; 6]; + self.dms = 0; + self.dml = 0; + self.ap = 0; + self.yu = 544; + self.yl = 34816; + self.sr = [32, 32]; + self.dq = [32; 6]; + self.pk = [0; 2]; + self.td = 0; + } + + #[inline] + fn fmult(an: u16, srn: u16) -> u16 { + let an_s = (an >> 15) & 1; + let an_mag = if an_s == 0 { (an >> 2) & 0x1FFF } else { (16384_u32.wrapping_sub((an >> 2) as u32) & 0x1FFF) as u16 }; + let an_exp = if an_mag > 0 { (16 - an_mag.leading_zeros()).min(13) as u16 } else { 0 }; + let an_mant = if an_mag == 0 { 1 << 5 } else { (((an_mag as u32) << 6) >> an_exp) as u16 & 0x3F }; + + let srn_s = (srn >> 10) & 1; + let srn_exp = (srn >> 6) & 15; + let srn_mant = srn & 63; + + let wan_s = srn_s ^ an_s; + let wan_exp = srn_exp + an_exp; + let wan_mant = (((srn_mant as u32 * an_mant as u32) + 48) >> 4) as u16; + + let wan_mag = + if wan_exp <= 26 { ((wan_mant as u32) << 7) >> (26 - wan_exp) } else { (((wan_mant as u32) << 7) << (wan_exp - 26)) & 0x7FFF } as u16; + + if wan_s == 0 { wan_mag } else { (65536_u32.wrapping_sub(wan_mag as u32) & 0xFFFF) as u16 } + } + + #[inline] + fn quantize(&self, dln: i32, ds: u8) -> u8 { + match self.rate { + BitRate::Rate16k => quantize_16(dln, ds), + BitRate::Rate24k => quantize_24(dln, ds), + BitRate::Rate32k => quantize_32(dln, ds), + BitRate::Rate40k => quantize_40(dln, ds), + } + } + + #[inline] + fn table_lookup(&self, code: u8) -> (u8, u16) { + match self.rate { + BitRate::Rate16k => OUT_16[(code & 3) as usize], + BitRate::Rate24k => OUT_24[(code & 7) as usize], + BitRate::Rate32k => OUT_32[(code & 15) as usize], + BitRate::Rate40k => OUT_40[(code & 31) as usize], + } + } + + #[inline] + fn compute_accum(&self) -> (i16, i16) { + let wa0 = Self::fmult(self.a[0], self.sr[0]); + let wa1 = Self::fmult(self.a[1], self.sr[1]); + let mut sezi: u32 = 0; + for i in 0..6 { + sezi = (sezi + Self::fmult(self.b[i], self.dq[i]) as u32) & 0xFFFF; + } + let sei = (sezi + wa1 as u32 + wa0 as u32) & 0xFFFF; + let sez = (sezi as i16) >> 1; + let se = (sei as i16) >> 1; + (sez, se) + } + + #[inline] + fn compute_mix(&self) -> i32 { + let al = if self.ap >= 256 { 64 } else { self.ap >> 2 } as i32; + let dif = (self.yu as i32 + 16384 - (self.yl >> 6)) & 16383; + let difs = (dif >> 13) & 1; + let difm = if difs == 0 { dif } else { (16384 - dif) & 8191 }; + let prodm = (difm * al) >> 6; + let prod = if difs == 0 { prodm } else { (16384 - prodm) & 8191 }; + ((self.yl >> 6) + prod) & 8191 + } + + #[inline] + fn quantize_sample(&self, sample: i16, se: i16, y: i32) -> u8 { + let sl = (sample >> 2) as i32; + let sl_ext = if sl >= 0 { sl } else { 65536 + sl }; + let se_ext = if se >= 0 { se as i32 } else { 65536 + se as i32 }; + let d = ((sl_ext + 65536 - se_ext) & 0xFFFF) as u16; + + let ds = ((d >> 15) & 1) as u8; + let dqm = if ds == 0 { d } else { (65536_u32.wrapping_sub(d as u32) & 0x7FFF) as u16 }; + let exp = if dqm > 1 { (15 - dqm.leading_zeros()).min(14) } else { 0 }; + let mant = (((dqm as u32) << 7) >> exp) & 127; + let dl = ((exp << 7) + mant) as u16; + let dln = (dl as i32 + 4096 - (y >> 2)) & 4095; + self.quantize(dln, ds) + } + + #[inline] + fn step(&mut self, sample: i16, is_encoder: bool, code_in: u8) -> (u8, i16) { + let (sez, se) = self.compute_accum(); + let y = self.compute_mix(); + + let code = if is_encoder { self.quantize_sample(sample, se, y) } else { code_in }; + + // 4. RECONST & ADDA & ANTILOG + let (dqs, dqln) = self.table_lookup(code); + let dql = (dqln as i32 + (y >> 2)) & 4095; + let dex = (dql >> 7) & 15; + let dmn = dql & 127; + let dqt = 128 + dmn; + let dqmag = if (dql >> 11) == 0 { ((dqt << 7) >> (14 - dex)) as u16 } else { 0 }; + let dq = if self.is_40k { ((dqs as u16) << 15) | (dqmag & 0x7FFF) } else { ((dqs as u16) << 14) | (dqmag & 0x3FFF) }; + + // 5. ADDB & ADDC + let dqi = if dqs == 0 { + dq as u32 + } else if self.is_40k { + 65536_u32.wrapping_sub((dq & 0x7FFF) as u32) & 0xFFFF + } else { + 65536_u32.wrapping_sub((dq & 0x3FFF) as u32) & 0xFFFF + }; + let sei_ext = if se >= 0 { se as u32 } else { (65536 + se as i32) as u32 }; + let sr = ((dqi + sei_ext) & 0xFFFF) as u16; + + let sezi_ext = if sez >= 0 { sez as u32 } else { (65536 + sez as i32) as u32 }; + let dqsez = ((dqi + sezi_ext) & 0xFFFF) as u16; + let pk0 = ((dqsez >> 15) & 1) as u8; + let sigpk = if dqsez == 0 { 1 } else { 0 }; + + // 6. FLOATA & FLOATB + let dq_mag = if self.is_40k { dq & 0x7FFF } else { dq & 0x3FFF }; + let (dq_exp, dq_mant) = if dq_mag == 0 { + (0, 32) + } else { + let max_exp = if self.is_40k { 15 } else { 14 }; + let exp = (16 - dq_mag.leading_zeros()).min(max_exp); + let mant = (((dq_mag as u32) << 6) >> exp) as u16; + (exp as u16, mant) + }; + let dq0 = ((dqs as u16) << 10) | (dq_exp << 6) | (dq_mant & 63); + + let sr_s = ((sr >> 15) & 1) as u8; + let sr_mag = if sr_s == 0 { sr } else { (65536_u32.wrapping_sub(sr as u32) & 0x7FFF) as u16 }; + let (sr_exp, sr_mant) = if sr_mag == 0 { + (0, 32) + } else { + let exp = (16 - sr_mag.leading_zeros()).min(15); + let mant = (((sr_mag as u32) << 6) >> exp) as u16; + (exp as u16, mant) + }; + let sr0 = ((sr_s as u16) << 10) | (sr_exp << 6) | (sr_mant & 63); + + self.update_adaptation_and_predictors(code, y, pk0, sigpk, dqs, dq_mag); + + self.sr = [sr0, self.sr[0]]; + self.dq = [dq0, self.dq[0], self.dq[1], self.dq[2], self.dq[3], self.dq[4]]; + self.pk = [pk0, self.pk[0]]; + + let sr_signed = if sr < 32768 { sr as i32 } else { sr as i32 - 65536 }; + let out_pcm = (sr_signed << 2).clamp(-32768, 32767) as i16; + (code, out_pcm) + } + + #[inline] + fn adapt_scale(&mut self, code: u8, y: i32) { + let wi = get_wi(self.rate, code); + let dif = (((wi as i32) << 5) + 131072 - y) & 131071; + let difs = (dif >> 16) & 1; + let difsx = if difs == 0 { dif >> 5 } else { (dif >> 5) + 4096 }; + let yut = (y + difsx) & 8191; + let yup = yut.clamp(544, 5120); + + let dif = (yup + ((1048576 - self.yl) >> 6)) & 16383; + let difs = (dif >> 13) & 1; + let difsx = if difs == 0 { dif } else { dif + 507904 }; + self.yu = yup as i16; + self.yl = (self.yl + difsx) & 524287; + } + + #[inline] + fn adapt_speed(&mut self, code: u8, y: i32, dq_mag: u16) -> (i16, i16, u8) { + let fi = get_fi(self.rate, code); + let dif = (((fi as i32) << 9) + 8192 - self.dms as i32) & 8191; + let difs = (dif >> 12) & 1; + let difsx = if difs == 0 { dif >> 5 } else { (dif >> 5) + 3840 }; + let dmsp = ((difsx + self.dms as i32) & 4095) as i16; + + let dif = (((fi as i32) << 11) + 32768 - self.dml as i32) & 32767; + let difs = (dif >> 14) & 1; + let difsx = if difs == 0 { dif >> 7 } else { (dif >> 7) + 16128 }; + let dmlp = ((difsx + self.dml as i32) & 16383) as i16; + + let dif = (((dmsp as i32) << 2) + 32768 - dmlp as i32) & 32767; + let difs = (dif >> 14) & 1; + let difm = if difs == 0 { dif } else { (32768 - dif) & 16383 }; + let dthr = (dmlp as i32) >> 3; + + let tdp = if (32768..53760).contains(&self.a[1]) { 1 } else { 0 }; + let ax = if y >= 1536 && tdp == 0 && difm < dthr { 0 } else { 1 }; + + let dif = ((ax << 9) + 2048 - self.ap as i32) & 2047; + let difs = (dif >> 10) & 1; + let difsx = if difs == 0 { dif >> 4 } else { (dif >> 4) + 1920 }; + let app = ((difsx + self.ap as i32) & 1023) as i16; + + let ylint = (self.yl >> 15) as u32; + let ylfrac = ((self.yl >> 10) & 31) as u32; + let thr1 = (32 + ylfrac) << ylint; + let thr2 = if self.is_40k && ylint > 9 { + 31 << 10 + } else if !self.is_40k && ylint > 8 { + 31 << 9 + } else { + thr1 + }; + let dqthr = (thr2 + (thr2 >> 1)) >> 1; + let tr = if (dq_mag as u32) > dqthr && self.td == 1 { 1 } else { 0 }; + let apr = if tr == 1 { 256 } else { app }; + + self.dms = dmsp; + self.dml = dmlp; + self.ap = apr; + self.td = if tr == 1 { 0 } else { tdp }; + + (apr, tdp, tr) + } + + #[inline] + fn update_predictors(&mut self, pk0: u8, sigpk: u8, dqs: u8, dq_mag: u16, tr: u8) { + let pks = pk0 ^ self.pk[0]; + let uga1 = if sigpk == 1 { + 0 + } else if pks == 0 { + 192 + } else { + 65344 + }; + let a1s = (self.a[0] >> 15) & 1; + let ula1 = if a1s == 0 { + (65536_u32.wrapping_sub((self.a[0] >> 8) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.a[0] >> 8) + 65280) as u32) & 0xFFFF) as u16 + }; + let ua1 = (uga1 as u32 + ula1 as u32) & 0xFFFF; + let a1t = ((self.a[0] as u32 + ua1) & 0xFFFF) as u16; + + let pks1 = pk0 ^ self.pk[0]; + let pks2 = pk0 ^ self.pk[1]; + let uga2a = if pks2 == 0 { 16384_u32 } else { 114688_u32 }; + let a1_u = self.a[0]; + let fa1 = if a1s == 0 { + if a1_u <= 8191 { (a1_u as u32) << 2 } else { 8191 << 2 } + } else if a1_u >= 57345 { + ((a1_u as u32) << 2) & 131071 + } else { + 24577 << 2 + }; + let fa = if pks1 == 1 { fa1 } else { (131072_u32.wrapping_sub(fa1)) & 131071 }; + let uga2b = (uga2a + fa) & 131071; + let uga2s = (uga2b >> 16) & 1; + let uga2 = if sigpk == 1 { + 0 + } else if uga2s == 0 { + uga2b >> 7 + } else { + (uga2b >> 7) + 64512 + } as u16; + let a2s = (self.a[1] >> 15) & 1; + let ula2 = if a2s == 0 { + (65536_u32.wrapping_sub((self.a[1] >> 7) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.a[1] >> 7) + 65024) as u32) & 0xFFFF) as u16 + }; + let ua2 = (uga2 as u32 + ula2 as u32) & 0xFFFF; + let a2t = ((self.a[1] as u32 + ua2) & 0xFFFF) as u16; + + let a2p = if (32768..=53248).contains(&a2t) { + 53248 + } else if (12288..=32767).contains(&a2t) { + 12288 + } else { + a2t + }; + + let ome = 15360_u32; + let a1ul = ((ome + 65536 - a2p as u32) & 0xFFFF) as u16; + let a1ll = ((a2p as u32 + 65536 - ome) & 0xFFFF) as u16; + let a1p = if a1t >= 32768 && a1t <= a1ll { + a1ll + } else if a1t >= a1ul && a1t <= 32767 { + a1ul + } else { + a1t + }; + + let a1r = if tr == 1 { 0 } else { a1p }; + let a2r = if tr == 1 { 0 } else { a2p }; + + let mut new_b = [0u16; 6]; + for (i, slot) in new_b.iter_mut().enumerate() { + let un = (dqs ^ ((self.dq[i] >> 10) as u8)) & 1; + let ugbn = if dq_mag == 0 { + 0 + } else if un == 0 { + 128 + } else { + 65408 + }; + let bns = (self.b[i] >> 15) & 1; + let ulbn = if self.is_40k { + if bns == 0 { + (65536_u32.wrapping_sub((self.b[i] >> 9) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.b[i] >> 9) + 65408) as u32) & 0xFFFF) as u16 + } + } else if bns == 0 { + (65536_u32.wrapping_sub((self.b[i] >> 8) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.b[i] >> 8) + 65280) as u32) & 0xFFFF) as u16 + }; + let ubn = (ugbn as u32 + ulbn as u32) & 0xFFFF; + let bnp = ((self.b[i] as u32 + ubn) & 0xFFFF) as u16; + *slot = if tr == 1 { 0 } else { bnp }; + } + + self.a[0] = a1r; + self.a[1] = a2r; + self.b = new_b; + } + + #[inline] + fn update_adaptation_and_predictors(&mut self, code: u8, y: i32, pk0: u8, sigpk: u8, dqs: u8, dq_mag: u16) { + self.adapt_scale(code, y); + let (_, _, tr) = self.adapt_speed(code, y, dq_mag); + self.update_predictors(pk0, sigpk, dqs, dq_mag, tr); + } +} + +// --------------------------------------------------------------------------- +// Decoder & Encoder structs +// --------------------------------------------------------------------------- + +/// G.726 ADPCM decoder. +#[derive(Debug, Clone)] +pub struct Decoder { + core: Core, + packing: BitPacking, + bit_buf: u32, + num_bits: usize, +} + +impl Decoder { + /// Create a new G.726 decoder at the specified bit rate and bit packing. + #[must_use] + pub fn new(rate: BitRate, packing: BitPacking) -> Self { + Self { core: Core::new(rate), packing, bit_buf: 0, num_bits: 0 } + } + + /// Reset decoder internal predictor state. + pub fn reset(&mut self) { + self.core.reset(); + self.bit_buf = 0; + self.num_bits = 0; + } + + /// Decode a single quantized ADPCM code into an 8 kHz 16-bit linear PCM sample. + /// Bits above the configured code width are ignored, as in packed-stream decoding. + #[inline] + pub fn decode_sample(&mut self, code: u8) -> i16 { + // Adaptation must see the same bounded codeword as the reconstruction table; + // otherwise unused high bits can underflow its unsigned inverse-code arithmetic. + let code = code & ((1u8 << self.core.rate.code_size()) - 1); + self.core.step(0, false, code).1 + } + + /// Decode G.726 bitstream bytes into 8 kHz 16-bit linear PCM samples, appending to `dst`. + pub fn decode(&mut self, src: &[u8], dst: &mut Vec) -> Result<(), Error> { + if src.len() > MAX_INPUT_BYTES { + return Err(Error::InputTooLarge); + } + let cs = self.core.rate.code_size(); + let est_samples = (src.len() * 8) / cs; + dst.try_reserve(est_samples).map_err(|_| Error::AllocationFailed)?; + + match self.packing { + BitPacking::BigEndian => { + for &b in src { + self.bit_buf = ((self.bit_buf & ((1 << self.num_bits) - 1)) << 8) | (b as u32); + self.num_bits += 8; + while self.num_bits >= cs { + let code = ((self.bit_buf >> (self.num_bits - cs)) & ((1 << cs) - 1)) as u8; + self.num_bits -= cs; + let s = self.decode_sample(code); + dst.push(s); + } + self.bit_buf &= (1 << self.num_bits) - 1; + } + } + BitPacking::LittleEndian => { + for &b in src { + self.bit_buf |= (b as u32) << self.num_bits; + self.num_bits += 8; + while self.num_bits >= cs { + let code = (self.bit_buf & ((1 << cs) - 1)) as u8; + self.bit_buf >>= cs; + self.num_bits -= cs; + let s = self.decode_sample(code); + dst.push(s); + } + } + } + } + Ok(()) + } +} + +/// G.726 ADPCM encoder. +#[derive(Debug, Clone)] +pub struct Encoder { + core: Core, + packing: BitPacking, + bit_buf: u32, + num_bits: usize, +} + +impl Encoder { + /// Create a new G.726 encoder at the specified bit rate and bit packing. + #[must_use] + pub fn new(rate: BitRate, packing: BitPacking) -> Self { + Self { core: Core::new(rate), packing, bit_buf: 0, num_bits: 0 } + } + + /// Reset encoder internal predictor state. + pub fn reset(&mut self) { + self.core.reset(); + self.bit_buf = 0; + self.num_bits = 0; + } + + /// Encode a single 8 kHz 16-bit linear PCM sample into an ADPCM code word. + #[inline] + pub fn encode_sample(&mut self, sample: i16) -> u8 { + self.core.step(sample, true, 0).0 + } + + /// Encode 8 kHz 16-bit linear PCM samples into G.726 bitstream bytes, appending to `dst`. + pub fn encode(&mut self, src: &[i16], dst: &mut Vec) -> Result<(), Error> { + if src.len() > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + let cs = self.core.rate.code_size(); + let est_bytes = (src.len() * cs).div_ceil(8); + dst.try_reserve(est_bytes).map_err(|_| Error::AllocationFailed)?; + + match self.packing { + BitPacking::BigEndian => { + for &s in src { + let code = self.encode_sample(s); + self.bit_buf = ((self.bit_buf & ((1 << self.num_bits) - 1)) << cs) | ((code as u32) & ((1 << cs) - 1)); + self.num_bits += cs; + while self.num_bits >= 8 { + dst.push(((self.bit_buf >> (self.num_bits - 8)) & 0xFF) as u8); + self.num_bits -= 8; + } + self.bit_buf &= (1 << self.num_bits) - 1; + } + } + BitPacking::LittleEndian => { + for &s in src { + let code = self.encode_sample(s); + self.bit_buf |= (code as u32) << self.num_bits; + self.num_bits += cs; + while self.num_bits >= 8 { + dst.push((self.bit_buf & 0xFF) as u8); + self.bit_buf >>= 8; + self.num_bits -= 8; + } + } + } + } + Ok(()) + } + + /// Flush any remaining buffered bits into `dst`, padding with zeroes. + pub fn flush(&mut self, dst: &mut Vec) -> Result<(), Error> { + if self.num_bits > 0 { + dst.try_reserve(1).map_err(|_| Error::AllocationFailed)?; + match self.packing { + BitPacking::BigEndian => { + let b = ((self.bit_buf << (8 - self.num_bits)) & 0xFF) as u8; + dst.push(b); + } + BitPacking::LittleEndian => { + let b = (self.bit_buf & 0xFF) as u8; + dst.push(b); + } + } + self.bit_buf = 0; + self.num_bits = 0; + } + Ok(()) + } +} + +// --------------------------------------------------------------------------- +// Public Top-Level Functions +// --------------------------------------------------------------------------- + +/// Decode a mono G.726 bitstream into 8 kHz 16-bit linear PCM samples. +pub fn decode(bytes: &[u8], rate: BitRate, packing: BitPacking) -> Result, Error> { + let mut decoder = Decoder::new(rate, packing); + let mut out = Vec::new(); + decoder.decode(bytes, &mut out)?; + Ok(out) +} + +/// Encode mono 8 kHz 16-bit linear PCM samples into a G.726 bitstream. +pub fn encode(samples: &[i16], rate: BitRate, packing: BitPacking) -> Result, Error> { + let mut encoder = Encoder::new(rate, packing); + let mut out = Vec::new(); + encoder.encode(samples, &mut out)?; + encoder.flush(&mut out)?; + Ok(out) +} + +/// Decode an interleaved multi-channel G.726 stream into interleaved 8 kHz 16-bit PCM samples. +pub fn decode_interleaved(bytes: &[u8], channels: usize, rate: BitRate, packing: BitPacking) -> Result, Error> { + if channels == 0 || channels > MAX_CHANNELS { + return Err(Error::InvalidChannels(channels)); + } + if channels == 1 { + return decode(bytes, rate, packing); + } + if bytes.len() > MAX_INPUT_BYTES { + return Err(Error::InputTooLarge); + } + + let mut decoders: Vec = Vec::with_capacity(channels); + for _ in 0..channels { + decoders.push(Decoder::new(rate, packing)); + } + + let cs = rate.code_size(); + let est_samples = (bytes.len() * 8) / cs; + let mut out = Vec::new(); + out.try_reserve(est_samples).map_err(|_| Error::AllocationFailed)?; + + let mut ch_outs: Vec> = Vec::with_capacity(channels); + for _ in 0..channels { + ch_outs.push(Vec::new()); + } + + for (i, &b) in bytes.iter().enumerate() { + let ch = i % channels; + decoders[ch].decode(&[b], &mut ch_outs[ch])?; + } + + let min_len = ch_outs.iter().map(Vec::len).min().unwrap_or(0); + for i in 0..min_len { + for ch_out in ch_outs.iter().take(channels) { + out.push(ch_out[i]); + } + } + + Ok(out) +} + +/// Encode interleaved 8 kHz 16-bit PCM samples into an interleaved multi-channel G.726 stream. +pub fn encode_interleaved(samples: &[i16], channels: usize, rate: BitRate, packing: BitPacking) -> Result, Error> { + if channels == 0 || channels > MAX_CHANNELS { + return Err(Error::InvalidChannels(channels)); + } + if channels == 1 { + return encode(samples, rate, packing); + } + if samples.len() > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + + let mut encoders: Vec = Vec::with_capacity(channels); + for _ in 0..channels { + encoders.push(Encoder::new(rate, packing)); + } + + let cs = rate.code_size(); + let est_bytes = (samples.len() * cs).div_ceil(8); + let mut out = Vec::new(); + out.try_reserve(est_bytes).map_err(|_| Error::AllocationFailed)?; + + let mut ch_samples: Vec> = Vec::with_capacity(channels); + for _ in 0..channels { + ch_samples.push(Vec::new()); + } + + for (i, &s) in samples.iter().enumerate() { + let ch = i % channels; + ch_samples[ch].push(s); + } + + let mut ch_bytes: Vec> = Vec::with_capacity(channels); + for ch in 0..channels { + let mut b = Vec::new(); + encoders[ch].encode(&ch_samples[ch], &mut b)?; + encoders[ch].flush(&mut b)?; + ch_bytes.push(b); + } + + let min_bytes = ch_bytes.iter().map(Vec::len).min().unwrap_or(0); + for i in 0..min_bytes { + for ch_b in ch_bytes.iter().take(channels) { + out.push(ch_b[i]); + } + } + + Ok(out) +} + +// --------------------------------------------------------------------------- +// Unit tests +// --------------------------------------------------------------------------- + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn sample_api_ignores_unused_codeword_bits() { + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + let mask = (1u8 << rate.code_size()) - 1; + let mut actual = Decoder::new(rate, BitPacking::BigEndian); + let mut expected = Decoder::new(rate, BitPacking::BigEndian); + for code in 0..=u8::MAX { + assert_eq!(actual.decode_sample(code), expected.decode_sample(code & mask)); + } + // High bits must not leave a different predictor state for later valid codes. + for code in 0..=mask { + assert_eq!(actual.decode_sample(code), expected.decode_sample(code)); + } + } + } + + #[test] + fn reject_invalid_channels() { + assert!(decode_interleaved(&[], 0, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + assert!(decode_interleaved(&[], 9, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + assert!(encode_interleaved(&[], 0, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + assert!(encode_interleaved(&[], 9, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + } + + #[test] + fn roundtrip_silence_all_rates() { + let pcm = vec![0i16; 64]; + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for packing in [BitPacking::BigEndian, BitPacking::LittleEndian] { + let encoded = encode(&pcm, rate, packing).expect("encode silence"); + let decoded = decode(&encoded, rate, packing).expect("decode silence"); + assert_eq!(decoded.len(), pcm.len()); + for &s in &decoded { + assert!(s.abs() <= 16, "silence sample too large: {s}"); + } + } + } + } + + #[test] + fn hostile_input_does_not_panic() { + let mut decoder = Decoder::new(BitRate::Rate32k, BitPacking::BigEndian); + let mut out = Vec::new(); + let hostile = vec![0xFF; 1024]; + let _ = decoder.decode(&hostile, &mut out); + + let mut decoder = Decoder::new(BitRate::Rate16k, BitPacking::LittleEndian); + let mut out = Vec::new(); + let _ = decoder.decode(&[0x00, 0xAA, 0x55, 0x12, 0x34], &mut out); + } +} diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 339ca07dc..3729ab34b 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -49,6 +49,8 @@ pub mod alac; mod buffer; #[cfg(feature = "g722")] pub mod g722; +#[cfg(feature = "g726")] +pub mod g726; #[cfg(any(feature = "gsm-decode", feature = "gsm-encode"))] pub mod gsm; mod layout; diff --git a/crates/audio/tests/g726_oracle.rs b/crates/audio/tests/g726_oracle.rs new file mode 100644 index 000000000..ec875e2c4 --- /dev/null +++ b/crates/audio/tests/g726_oracle.rs @@ -0,0 +1,218 @@ +#![cfg(feature = "g726")] + +use craft_audio::g726::{BitPacking, BitRate, Decoder, Encoder, decode, decode_interleaved, encode, encode_interleaved}; +use std::process::Command; + +fn pearson_correlation(x: &[i16], y: &[i16]) -> f64 { + let n = x.len().min(y.len()); + if n == 0 { + return 0.0; + } + let x = &x[..n]; + let y = &y[..n]; + let mean_x = x.iter().map(|&v| v as f64).sum::() / (n as f64); + let mean_y = y.iter().map(|&v| v as f64).sum::() / (n as f64); + let mut num = 0.0; + let mut denom_x = 0.0; + let mut denom_y = 0.0; + for (&a, &b) in x.iter().zip(y) { + let da = (a as f64) - mean_x; + let db = (b as f64) - mean_y; + num += da * db; + denom_x += da * da; + denom_y += db * db; + } + let denom = (denom_x * denom_y).sqrt(); + if denom > 0.0 { num / denom } else { 0.0 } +} + +fn find_ffmpeg() -> Option { + for cmd in ["ffmpeg", "/opt/homebrew/bin/ffmpeg", "/usr/bin/ffmpeg"] { + if Command::new(cmd).arg("-version").output().is_ok() { + return Some(cmd.to_string()); + } + } + None +} + +#[test] +fn test_silence_roundtrip() { + let pcm = vec![0i16; 80]; + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for packing in [BitPacking::BigEndian, BitPacking::LittleEndian] { + let enc = encode(&pcm, rate, packing).expect("encode"); + let dec = decode(&enc, rate, packing).expect("decode"); + assert_eq!(dec.len(), pcm.len()); + for &s in &dec { + assert!(s.abs() <= 16, "silence sample too large: {s}"); + } + } + } +} + +#[test] +fn test_sine_wave_roundtrip_fidelity() { + let sample_rate = 8000.0; + let freq = 300.0; + let num_samples = 160; + let mut pcm = Vec::with_capacity(num_samples); + for i in 0..num_samples { + let t = i as f64 / sample_rate; + let s = (4000.0 * (2.0 * std::f64::consts::PI * freq * t).sin()) as i16; + pcm.push(s); + } + + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for packing in [BitPacking::BigEndian, BitPacking::LittleEndian] { + let enc = encode(&pcm, rate, packing).expect("encode sine"); + let dec = decode(&enc, rate, packing).expect("decode sine"); + let corr = pearson_correlation(&pcm, &dec); + assert!(corr > 0.90, "correlation {corr} too low for rate {rate:?} packing {packing:?}"); + } + } +} + +#[test] +fn test_encoder_and_decoder_reset() { + let mut enc = Encoder::new(BitRate::Rate32k, BitPacking::BigEndian); + let mut dec = Decoder::new(BitRate::Rate32k, BitPacking::BigEndian); + + let pcm = vec![1000i16, 2000, 3000, 2000, 1000, 0, -1000, -2000]; + let mut out1 = Vec::new(); + enc.encode(&pcm, &mut out1).expect("enc 1"); + enc.flush(&mut out1).expect("flush 1"); + + let mut dec_pcm1 = Vec::new(); + dec.decode(&out1, &mut dec_pcm1).expect("dec 1"); + + enc.reset(); + dec.reset(); + + let mut out2 = Vec::new(); + enc.encode(&pcm, &mut out2).expect("enc 2"); + enc.flush(&mut out2).expect("flush 2"); + + let mut dec_pcm2 = Vec::new(); + dec.decode(&out2, &mut dec_pcm2).expect("dec 2"); + + assert_eq!(out1, out2); + assert_eq!(dec_pcm1, dec_pcm2); +} + +#[test] +fn test_stereo_multichannel_roundtrip() { + let mut stereo_pcm = Vec::new(); + for i in 0..160 { + let left = (3000.0 * (i as f64 * 0.05).sin()) as i16; + let right = (2000.0 * (i as f64 * 0.03).cos()) as i16; + stereo_pcm.push(left); + stereo_pcm.push(right); + } + + let enc = encode_interleaved(&stereo_pcm, 2, BitRate::Rate32k, BitPacking::BigEndian).expect("encode stereo"); + let dec = decode_interleaved(&enc, 2, BitRate::Rate32k, BitPacking::BigEndian).expect("decode stereo"); + + assert_eq!(dec.len(), stereo_pcm.len()); + let corr = pearson_correlation(&stereo_pcm, &dec); + assert!(corr > 0.90, "stereo correlation {corr} too low"); +} + +#[test] +fn test_hostile_inputs_do_not_crash() { + let mut dec = Decoder::new(BitRate::Rate32k, BitPacking::BigEndian); + let mut out = Vec::new(); + let hostile = vec![0xEE; 1000]; + let _ = dec.decode(&hostile, &mut out); + + let mut enc = Encoder::new(BitRate::Rate40k, BitPacking::LittleEndian); + let mut out_enc = Vec::new(); + let hostile_pcm = vec![i16::MIN, i16::MAX, -1, 1, 0]; + let _ = enc.encode(&hostile_pcm, &mut out_enc); + let _ = enc.flush(&mut out_enc); +} + +#[test] +fn test_ffmpeg_g726_oracle_encoder_and_decoder() { + let ff = match find_ffmpeg() { + Some(f) => f, + None => return, + }; + + let sample_rate = 8000; + let num_samples = 240; + let mut pcm = Vec::with_capacity(num_samples); + for i in 0..num_samples { + let t = i as f64 / sample_rate as f64; + let s = (5000.0 * (2.0 * std::f64::consts::PI * 350.0 * t).sin()) as i16; + pcm.push(s); + } + + let dir = std::env::temp_dir().join("craft_g726_oracle"); + let _ = std::fs::create_dir_all(&dir); + let in_pcm_path = dir.join("input.s16le"); + let mut in_bytes = Vec::with_capacity(pcm.len() * 2); + for &s in &pcm { + in_bytes.extend_from_slice(&s.to_le_bytes()); + } + std::fs::write(&in_pcm_path, &in_bytes).expect("write input pcm"); + + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for (packing, ff_codec, ff_fmt) in [(BitPacking::BigEndian, "g726", "g726"), (BitPacking::LittleEndian, "g726le", "g726le")] { + let cs = rate.code_size(); + let ff_g726_path = dir.join(format!("ff_{}_{}.g726", cs, ff_codec)); + + // 1. FFmpeg encodes PCM to G.726 + let out = Command::new(&ff) + .args(["-y", "-f", "s16le", "-ar", "8000", "-ac", "1", "-i"]) + .arg(&in_pcm_path) + .args(["-c:a", ff_codec, "-code_size", &cs.to_string(), "-f", ff_fmt]) + .arg(&ff_g726_path) + .output() + .expect("ffmpeg encode"); + assert!(out.status.success(), "ffmpeg encode failed: {}", String::from_utf8_lossy(&out.stderr)); + let ff_g726_bytes = std::fs::read(&ff_g726_path).expect("read ff g726"); + + // 2. FFmpeg decodes its own G.726 stream + let ff_pcm_back_path = dir.join(format!("ff_back_{}_{}.s16le", cs, ff_codec)); + let out = Command::new(&ff) + .args(["-y", "-f", ff_fmt, "-code_size", &cs.to_string(), "-i"]) + .arg(&ff_g726_path) + .args(["-f", "s16le", "-ar", "8000", "-ac", "1"]) + .arg(&ff_pcm_back_path) + .output() + .expect("ffmpeg decode"); + assert!(out.status.success(), "ffmpeg decode failed: {}", String::from_utf8_lossy(&out.stderr)); + let ff_back_bytes = std::fs::read(&ff_pcm_back_path).expect("read ff back pcm"); + let ff_back_samples: Vec = ff_back_bytes.as_chunks::<2>().0.iter().map(|c| i16::from_le_bytes(*c)).collect(); + + // 3. Our decoder decodes FFmpeg's stream + let our_decoded = decode(&ff_g726_bytes, rate, packing).expect("our decode"); + let corr = pearson_correlation(&our_decoded, &ff_back_samples); + assert!(corr > 0.998, "correlation {corr} too low between our decoder and FFmpeg decoder for rate {rate:?} packing {packing:?}"); + + // 4. Our encoder encodes PCM to G.726 + let our_g726_bytes = encode(&pcm, rate, packing).expect("our encode"); + let our_g726_path = dir.join(format!("our_{}_{}.g726", cs, ff_codec)); + std::fs::write(&our_g726_path, &our_g726_bytes).expect("write our g726"); + + // 5. FFmpeg decodes our encoded stream + let our_decoded_by_ff_path = dir.join(format!("our_by_ff_{}_{}.s16le", cs, ff_codec)); + let out = Command::new(&ff) + .args(["-y", "-f", ff_fmt, "-code_size", &cs.to_string(), "-i"]) + .arg(&our_g726_path) + .args(["-f", "s16le", "-ar", "8000", "-ac", "1"]) + .arg(&our_decoded_by_ff_path) + .output() + .expect("ffmpeg decode of our stream"); + assert!(out.status.success(), "ffmpeg decode of our stream failed: {}", String::from_utf8_lossy(&out.stderr)); + let our_by_ff_bytes = std::fs::read(&our_decoded_by_ff_path).expect("read our by ff pcm"); + let our_by_ff_samples: Vec = our_by_ff_bytes.as_chunks::<2>().0.iter().map(|c| i16::from_le_bytes(*c)).collect(); + + let corr_input = pearson_correlation(&pcm, &our_by_ff_samples); + assert!( + corr_input > 0.90, + "correlation {corr_input} too low for input vs FFmpeg-decoded our stream for rate {rate:?} packing {packing:?}" + ); + } + } +}