rakata_formats/wav/

adpcm.rs

//! ADPCM decoding helpers for WAV data.
//!
//! This module provides utilities to decode ADPCM sample data from
//! [`super::Wav`] payloads into normalized floating-point samples.
//!
//! Supported formats:
//! - MS ADPCM (0x0002)
//! - IMA ADPCM (0x0011)

use super::{Wav, WavEncoding};
use thiserror::Error;

/// Normalizes a clamped i32 sample (must be in i16 range) to f32 in `[-1.0, 1.0]`.
///
/// The conversion is lossless: `i16 -> f32` is exact (f32 has a 24-bit mantissa).
fn normalize_sample(sample: i32) -> f32 {
    let narrow = i16::try_from(sample).expect("ADPCM samples are clamped to i16 range");
    f32::from(narrow) / 32768.0
}

/// Errors that can occur during ADPCM decoding.
#[derive(Debug, Error)]
pub enum AdpcmError {
    /// The WAV data is not in a supported ADPCM format.
    #[error("unsupported encoding: {0:?}")]
    UnsupportedEncoding(Option<WavEncoding>),

    /// The block alignment is invalid or zero.
    #[error("invalid block align: {0}")]
    InvalidBlockAlign(u16),

    /// A required coefficient table is missing or invalid.
    #[error("invalid or missing coefficient table")]
    InvalidCoefficients,

    /// The data length is insufficient for the declared block structure.
    #[error("unexpected end of data")]
    UnexpectedEof,
}

/// Decodes the audio data into a vector of normalized `f32` samples.
///
/// Samples are interleaved (e.g., L, R, L, R for stereo).
/// Normalized samples are in the range `[-1.0, 1.0]`.
pub fn decode_adpcm_as_float(wav: &Wav) -> Result<Vec<f32>, AdpcmError> {
    let encoding = wav.encoding.known();

    match encoding {
        Some(WavEncoding::MsAdpcm) => decode_ms_adpcm(wav),
        Some(WavEncoding::ImaAdpcm) => decode_ima_adpcm(wav),
        _ => Err(AdpcmError::UnsupportedEncoding(encoding)),
    }
}

// ============================================================================
// MS ADPCM Implementation
// ============================================================================

/// Step adaptation table: scales the quantization delta after each nibble.
/// Indexed by the raw (unsigned) nibble value [0..15].
const MS_ADAPTATION_TABLE: [i32; 16] = [
    230, 230, 230, 230, 307, 409, 512, 614, 768, 614, 512, 409, 307, 230, 230, 230,
];

fn decode_ms_adpcm(wav: &Wav) -> Result<Vec<f32>, AdpcmError> {
    let channels = usize::from(wav.channels);
    let block_align = usize::from(wav.block_align);

    if block_align == 0 {
        return Err(AdpcmError::InvalidBlockAlign(0));
    }

    // The `fmt` chunk extra bytes (where custom predictor coefficients live) are not
    // stored in the `Wav` struct, so we fall back to the 7 standard MS ADPCM coefficients.
    // KotOR audio files universally use these standard coefficients.
    //
    // TODO: store extra `fmt` bytes in `Wav` to support non-standard coefficient tables.
    let standard_coeffs = [
        (256, 0),
        (512, -256),
        (0, 0),
        (192, 64),
        (240, 0),
        (460, -208),
        (392, -232),
    ];

    let num_blocks = wav.data.len() / block_align;
    let samples_per_block = ms_adpcm_samples_per_block(channels, block_align)?;
    let mut output = Vec::with_capacity(num_blocks * samples_per_block * channels);

    for block_idx in 0..num_blocks {
        let block_offset = block_idx * block_align;
        let block = &wav.data[block_offset..block_offset + block_align];

        if channels == 1 {
            decode_ms_adpcm_block_mono(block, &standard_coeffs, &mut output)?;
        } else if channels == 2 {
            decode_ms_adpcm_block_stereo(block, &standard_coeffs, &mut output)?;
        } else {
            return Err(AdpcmError::UnsupportedEncoding(None));
        }
    }

    Ok(output)
}

fn ms_adpcm_samples_per_block(channels: usize, block_align: usize) -> Result<usize, AdpcmError> {
    // Each channel header is 7 bytes: 1 predictor + 2-byte iDelta + 2×2-byte history samples.
    // Remaining bytes hold nibble-packed data at 2 samples per byte per channel.
    // The 2 history samples from the header are also emitted, giving the +2 below.
    let overhead = 7 * channels;
    if block_align < overhead {
        return Err(AdpcmError::InvalidBlockAlign(
            u16::try_from(block_align).expect("block_align originates from a u16 field"),
        ));
    }
    Ok(2 + (block_align - overhead) * 2 / channels)
}

fn decode_ms_adpcm_block_mono(
    block: &[u8],
    coeffs: &[(i32, i32)],
    output: &mut Vec<f32>,
) -> Result<(), AdpcmError> {
    if block.len() < 7 {
        return Err(AdpcmError::UnexpectedEof);
    }

    let predictor = usize::from(block[0]);
    if predictor >= coeffs.len() {
        return Err(AdpcmError::InvalidCoefficients);
    }
    let (c1, c2) = coeffs[predictor];

    let mut delta = i32::from(i16::from_le_bytes([block[1], block[2]]));
    // samp2 is the older history sample (n−2); samp1 is more recent (n−1).
    let mut samp1 = i32::from(i16::from_le_bytes([block[3], block[4]]));
    let mut samp2 = i32::from(i16::from_le_bytes([block[5], block[6]]));

    // Emit the two history samples in chronological order before the coded data.
    output.push(normalize_sample(samp2));
    output.push(normalize_sample(samp1));

    // Each byte holds two samples: high nibble first, then low nibble.
    for byte in &block[7..] {
        for nibble in [i32::from(byte >> 4), i32::from(byte & 0x0F)] {
            let pred = (samp1 * c1 + samp2 * c2) / 256;

            // Sign-extend the 4-bit nibble: values [8, 15] map to [-8, -1].
            let signed_nibble = if nibble >= 8 { nibble - 16 } else { nibble };
            let clamped = (pred + signed_nibble * delta).clamp(-32768, 32767);

            delta = (delta
                * MS_ADAPTATION_TABLE[usize::try_from(nibble).expect("nibble is 0..15")]
                / 256)
                .max(16);

            // Advance history window.
            samp2 = samp1;
            samp1 = clamped;

            output.push(normalize_sample(samp1));
        }
    }
    Ok(())
}

fn decode_ms_adpcm_block_stereo(
    block: &[u8],
    coeffs: &[(i32, i32)],
    output: &mut Vec<f32>,
) -> Result<(), AdpcmError> {
    if block.len() < 14 {
        return Err(AdpcmError::UnexpectedEof);
    }

    let pred_l = usize::from(block[0]);
    let pred_r = usize::from(block[1]);
    if pred_l >= coeffs.len() || pred_r >= coeffs.len() {
        return Err(AdpcmError::InvalidCoefficients);
    }
    let (c1_l, c2_l) = coeffs[pred_l];
    let (c1_r, c2_r) = coeffs[pred_r];

    let mut delta_l = i32::from(i16::from_le_bytes([block[2], block[3]]));
    let mut delta_r = i32::from(i16::from_le_bytes([block[4], block[5]]));

    // samp1 is the more recent history sample (n−1); samp2 is older (n−2).
    let mut samp1_l = i32::from(i16::from_le_bytes([block[6], block[7]]));
    let mut samp1_r = i32::from(i16::from_le_bytes([block[8], block[9]]));
    let mut samp2_l = i32::from(i16::from_le_bytes([block[10], block[11]]));
    let mut samp2_r = i32::from(i16::from_le_bytes([block[12], block[13]]));

    // Emit the two history pairs in chronological order (samp2 then samp1), interleaved L/R.
    output.push(normalize_sample(samp2_l));
    output.push(normalize_sample(samp2_r));
    output.push(normalize_sample(samp1_l));
    output.push(normalize_sample(samp1_r));

    // Each byte holds one left nibble (high) and one right nibble (low).
    for byte in &block[14..] {
        let nibble_l = i32::from(byte >> 4);
        let nibble_r = i32::from(byte & 0x0F);

        // Left channel.
        let pred = (samp1_l * c1_l + samp2_l * c2_l) / 256;
        let signed_nibble = if nibble_l >= 8 {
            nibble_l - 16
        } else {
            nibble_l
        };
        let clamped_l = (pred + signed_nibble * delta_l).clamp(-32768, 32767);
        delta_l = (delta_l
            * MS_ADAPTATION_TABLE[usize::try_from(nibble_l).expect("nibble is 0..15")]
            / 256)
            .max(16);
        samp2_l = samp1_l;
        samp1_l = clamped_l;

        // Right channel.
        let pred = (samp1_r * c1_r + samp2_r * c2_r) / 256;
        let signed_nibble = if nibble_r >= 8 {
            nibble_r - 16
        } else {
            nibble_r
        };
        let clamped_r = (pred + signed_nibble * delta_r).clamp(-32768, 32767);
        delta_r = (delta_r
            * MS_ADAPTATION_TABLE[usize::try_from(nibble_r).expect("nibble is 0..15")]
            / 256)
            .max(16);
        samp2_r = samp1_r;
        samp1_r = clamped_r;

        output.push(normalize_sample(clamped_l));
        output.push(normalize_sample(clamped_r));
    }
    Ok(())
}

// ============================================================================
// IMA ADPCM Implementation
// ============================================================================

const IMA_INDEX_TABLE: [i8; 16] = [-1, -1, -1, -1, 2, 4, 6, 8, -1, -1, -1, -1, 2, 4, 6, 8];

const IMA_STEP_TABLE: [i32; 89] = [
    7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 21, 23, 25, 28, 31, 34, 37, 41, 45, 50, 55, 60, 66,
    73, 80, 88, 97, 107, 118, 130, 143, 157, 173, 190, 209, 230, 253, 279, 307, 337, 371, 408, 449,
    494, 544, 598, 658, 724, 796, 876, 963, 1060, 1166, 1282, 1411, 1552, 1707, 1878, 2066, 2272,
    2499, 2749, 3024, 3327, 3660, 4026, 4428, 4871, 5358, 5894, 6484, 7132, 7845, 8630, 9493,
    10442, 11487, 12635, 13899, 15290, 16818, 18500, 20350, 22385, 24623, 27086, 29794, 32767,
];

fn decode_ima_adpcm(wav: &Wav) -> Result<Vec<f32>, AdpcmError> {
    let channels = usize::from(wav.channels);
    let block_align = usize::from(wav.block_align);

    let header_bytes = 4 * channels;
    if block_align < header_bytes {
        return Err(AdpcmError::InvalidBlockAlign(wav.block_align));
    }

    // Number of samples per block per channel:
    // Header is 4 bytes per channel (predictor i16, step_index u8, reserved u8).
    // Remaining bytes hold 2 samples per byte per channel.
    // +1 accounts for the sample stored in the header itself.
    let samples_per_block = (block_align - header_bytes) * 2 / channels + 1;

    let num_blocks = wav.data.len() / block_align;
    let mut output = Vec::with_capacity(num_blocks * samples_per_block * channels);

    for block_idx in 0..num_blocks {
        let block_offset = block_idx * block_align;
        let block = &wav.data[block_offset..block_offset + block_align];

        if channels == 1 {
            decode_ima_adpcm_block_mono(block, &mut output)?;
        } else if channels == 2 {
            decode_ima_adpcm_block_stereo(block, &mut output)?;
        } else {
            return Err(AdpcmError::UnsupportedEncoding(None));
        }
    }

    Ok(output)
}

fn decode_ima_adpcm_block_mono(block: &[u8], output: &mut Vec<f32>) -> Result<(), AdpcmError> {
    if block.len() < 4 {
        return Err(AdpcmError::UnexpectedEof);
    }

    let mut predictor = i16::from_le_bytes([block[0], block[1]]).into();
    let mut step_index = i32::from(block[2]).clamp(0, 88);
    // block[3] is reserved; ignored.

    output.push(normalize_sample(predictor));

    // Each byte holds two samples: low nibble first, then high nibble.
    for byte in &block[4..] {
        for nibble in [i32::from(byte & 0x0F), i32::from(byte >> 4)] {
            let step = IMA_STEP_TABLE
                [usize::try_from(step_index).expect("step_index is clamped to 0..88")];
            let mut diff = step >> 3;
            if (nibble & 4) != 0 {
                diff += step;
            }
            if (nibble & 2) != 0 {
                diff += step >> 1;
            }
            if (nibble & 1) != 0 {
                diff += step >> 2;
            }

            if (nibble & 8) != 0 {
                predictor -= diff;
            } else {
                predictor += diff;
            }
            predictor = predictor.clamp(-32768, 32767);
            step_index = (step_index
                + i32::from(IMA_INDEX_TABLE[usize::try_from(nibble).expect("nibble is 0..15")]))
            .clamp(0, 88);

            output.push(normalize_sample(predictor));
        }
    }
    Ok(())
}

fn decode_ima_adpcm_block_stereo(block: &[u8], output: &mut Vec<f32>) -> Result<(), AdpcmError> {
    if block.len() < 8 {
        return Err(AdpcmError::UnexpectedEof);
    }

    // Each channel has a 4-byte header: predictor i16, step_index u8, reserved u8.
    let mut left_pred = i16::from_le_bytes([block[0], block[1]]).into();
    let mut left_step_idx = i32::from(block[2]).clamp(0, 88);

    let mut right_pred = i32::from(i16::from_le_bytes([block[4], block[5]]));
    let mut right_step_idx = i32::from(block[6]).clamp(0, 88);

    output.push(normalize_sample(left_pred));
    output.push(normalize_sample(right_pred));

    // Data is laid out as alternating 4-byte channel words: LLLL RRRR LLLL RRRR ...
    // Each 8-byte chunk produces 8 left samples and 8 right samples, emitted interleaved.
    let mut cursor = 8;
    while cursor + 8 <= block.len() {
        let left_chunk = &block[cursor..cursor + 4];
        let right_chunk = &block[cursor + 4..cursor + 8];
        cursor += 8;

        let mut l_samples = [0f32; 8];
        let mut r_samples = [0f32; 8];

        for (i, &byte) in left_chunk.iter().enumerate() {
            for (j, nibble) in [i32::from(byte & 0x0F), i32::from(byte >> 4)]
                .into_iter()
                .enumerate()
            {
                let step = IMA_STEP_TABLE
                    [usize::try_from(left_step_idx).expect("step_index is clamped to 0..88")];
                let mut diff = step >> 3;
                if (nibble & 4) != 0 {
                    diff += step;
                }
                if (nibble & 2) != 0 {
                    diff += step >> 1;
                }
                if (nibble & 1) != 0 {
                    diff += step >> 2;
                }
                if (nibble & 8) != 0 {
                    left_pred -= diff;
                } else {
                    left_pred += diff;
                }
                left_pred = left_pred.clamp(-32768, 32767);
                left_step_idx = (left_step_idx
                    + i32::from(
                        IMA_INDEX_TABLE[usize::try_from(nibble).expect("nibble is 0..15")],
                    ))
                .clamp(0, 88);
                l_samples[i * 2 + j] = normalize_sample(left_pred);
            }
        }

        for (i, &byte) in right_chunk.iter().enumerate() {
            for (j, nibble) in [i32::from(byte & 0x0F), i32::from(byte >> 4)]
                .into_iter()
                .enumerate()
            {
                let step = IMA_STEP_TABLE
                    [usize::try_from(right_step_idx).expect("step_index is clamped to 0..88")];
                let mut diff = step >> 3;
                if (nibble & 4) != 0 {
                    diff += step;
                }
                if (nibble & 2) != 0 {
                    diff += step >> 1;
                }
                if (nibble & 1) != 0 {
                    diff += step >> 2;
                }
                if (nibble & 8) != 0 {
                    right_pred -= diff;
                } else {
                    right_pred += diff;
                }
                right_pred = right_pred.clamp(-32768, 32767);
                right_step_idx = (right_step_idx
                    + i32::from(
                        IMA_INDEX_TABLE[usize::try_from(nibble).expect("nibble is 0..15")],
                    ))
                .clamp(0, 88);
                r_samples[i * 2 + j] = normalize_sample(right_pred);
            }
        }

        for i in 0..8 {
            output.push(l_samples[i]);
            output.push(r_samples[i]);
        }
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::wav::{WavEncodingCode, WavType, WavWaveMetadata};

    fn make_wav(encoding: WavEncoding, channels: u16, block_align: u16, data: Vec<u8>) -> Wav {
        Wav::new_wave(
            WavType::Vo,
            WavWaveMetadata {
                encoding: WavEncodingCode::from(encoding),
                channels,
                sample_rate: 44100,
                bytes_per_sec: 0,
                block_align,
                bits_per_sample: 4,
            },
            data,
        )
    }

    #[test]
    fn test_ms_adpcm_mono_header() {
        // Minimal MS ADPCM block: 7 bytes, predictor 0, delta 16, both history samples 0.
        let data = vec![
            0x00, // predictor index 0
            0x10, 0x00, // iDelta = 16
            0x00, 0x00, // iSamp1 = 0
            0x00, 0x00, // iSamp2 = 0
        ];
        let wav = make_wav(WavEncoding::MsAdpcm, 1, 7, data);
        let samples = decode_adpcm_as_float(&wav).unwrap();
        assert_eq!(samples.len(), 2);
        assert_eq!(samples[0], 0.0);
        assert_eq!(samples[1], 0.0);
    }

    #[test]
    fn test_ima_adpcm_mono_header() {
        // Minimal IMA ADPCM block: 4 bytes, predictor 0, step index 0.
        let data = vec![
            0x00, 0x00, // predictor = 0
            0x00, 0x00, // step_index = 0, reserved = 0
        ];
        let wav = make_wav(WavEncoding::ImaAdpcm, 1, 4, data);
        let samples = decode_adpcm_as_float(&wav).unwrap();
        assert_eq!(samples.len(), 1);
        assert_eq!(samples[0], 0.0);
    }

    #[test]
    fn test_unsupported_encoding() {
        let wav = make_wav(WavEncoding::Pcm, 1, 2, vec![]);
        let err = decode_adpcm_as_float(&wav).unwrap_err();
        assert!(matches!(err, AdpcmError::UnsupportedEncoding(_)));
    }
}