rakata_formats/wav/

writer.rs

//! WAV binary writer.

use std::io::Write;

use super::{
    Wav, WavAudioFormat, WavError, WavType, WavWriteMode, WavWriteOptions, DATA_CHUNK_ID,
    FMT_CHUNK_ID, MP3_IN_WAV_HEADER, RIFF_MAGIC, SFX_HEADER_SIZE, SFX_MAGIC, WAVE_MAGIC,
};

/// Writes WAV data to a writer using [`WavWriteMode::Game`].
///
/// # Errors
///
/// The same as [`write_wav_with_options`] under that mode.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(writer, wav))
)]
pub fn write_wav<W: Write>(writer: &mut W, wav: &Wav) -> Result<(), WavError> {
    write_wav_with_options(writer, wav, WavWriteOptions::default())
}

/// Writes WAV data to a writer with explicit options.
///
/// # Errors
///
/// [`WavError::InvalidChunk`] when a derived header field overflows its
/// on-disk width: the data size, the byte rate from sample rate times block
/// align, the RIFF size, or the block align from channels times bytes per
/// sample. In game mode, [`WavError::MismatchedPayload`] when the form cannot
/// hold the payload, and [`WavError::EmptyMp3`] for an MP3-in-WAV with no MP3.
/// The payload is built before anything is written, so these leave the writer
/// untouched. [`WavError::Io`] when the writer fails.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(writer, wav, options))
)]
pub fn write_wav_with_options<W: Write>(
    writer: &mut W,
    wav: &Wav,
    options: WavWriteOptions,
) -> Result<(), WavError> {
    let clean_payload = match wav.audio_format {
        WavAudioFormat::Wave => build_clean_wave_payload(wav)?,
        WavAudioFormat::Mp3 => wav.data.clone(),
    };

    let out = match options.mode {
        WavWriteMode::Clean => clean_payload,
        WavWriteMode::Game => obfuscate_for_game(&clean_payload, wav)?,
    };
    writer.write_all(&out)?;
    Ok(())
}

/// Serializes WAV data to a byte vector using [`WavWriteMode::Game`].
///
/// # Errors
///
/// The same as [`write_wav_to_vec_with_options`] under that mode.
#[cfg_attr(feature = "tracing", tracing::instrument(level = "debug", skip(wav)))]
pub fn write_wav_to_vec(wav: &Wav) -> Result<Vec<u8>, WavError> {
    write_wav_to_vec_with_options(wav, WavWriteOptions::default())
}

/// Serializes WAV data to a byte vector with explicit options.
///
/// # Errors
///
/// [`WavError::InvalidChunk`] on the terms [`write_wav_with_options`] gives.
/// The `Vec` target has no I/O to fail at.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(wav, options))
)]
pub fn write_wav_to_vec_with_options(
    wav: &Wav,
    options: WavWriteOptions,
) -> Result<Vec<u8>, WavError> {
    let mut out = Vec::new();
    write_wav_with_options(&mut out, wav, options)?;
    Ok(out)
}

fn build_clean_wave_payload(wav: &Wav) -> Result<Vec<u8>, WavError> {
    let data_size = u32::try_from(wav.data.len())
        .map_err(|_| WavError::InvalidChunk("audio payload exceeds 4GiB RIFF limit".into()))?;

    let block_align = if wav.block_align != 0 {
        wav.block_align
    } else {
        default_block_align(wav.channels, wav.bits_per_sample)?
    };
    let bytes_per_sec = if wav.bytes_per_sec != 0 {
        wav.bytes_per_sec
    } else {
        wav.sample_rate
            .checked_mul(u32::from(block_align))
            .ok_or_else(|| {
                WavError::InvalidChunk("sample_rate * block_align overflows u32".into())
            })?
    };

    let fmt_chunk_size: u32 = 16;
    let riff_size = 4_u32
        .checked_add(8)
        .and_then(|value| value.checked_add(fmt_chunk_size))
        .and_then(|value| value.checked_add(8))
        .and_then(|value| value.checked_add(data_size))
        .ok_or_else(|| WavError::InvalidChunk("RIFF size overflows u32".into()))?;

    let mut out = Vec::with_capacity(
        usize::try_from(8_u64 + u64::from(riff_size))
            .unwrap_or(0)
            .max(usize::from(44_u16)),
    );
    out.extend_from_slice(&RIFF_MAGIC);
    out.extend_from_slice(&riff_size.to_le_bytes());
    out.extend_from_slice(&WAVE_MAGIC);
    out.extend_from_slice(&FMT_CHUNK_ID);
    out.extend_from_slice(&fmt_chunk_size.to_le_bytes());
    out.extend_from_slice(&wav.encoding.raw().to_le_bytes());
    out.extend_from_slice(&wav.channels.to_le_bytes());
    out.extend_from_slice(&wav.sample_rate.to_le_bytes());
    out.extend_from_slice(&bytes_per_sec.to_le_bytes());
    out.extend_from_slice(&block_align.to_le_bytes());
    out.extend_from_slice(&wav.bits_per_sample.to_le_bytes());
    out.extend_from_slice(&DATA_CHUNK_ID);
    out.extend_from_slice(&data_size.to_le_bytes());
    out.extend_from_slice(&wav.data);

    Ok(out)
}

fn default_block_align(channels: u16, bits_per_sample: u16) -> Result<u16, WavError> {
    let bytes_per_sample = bits_per_sample / 8;
    channels
        .checked_mul(bytes_per_sample)
        .ok_or_else(|| WavError::InvalidChunk("channels * bytes_per_sample overflows u16".into()))
}

fn obfuscate_for_game(clean_payload: &[u8], wav: &Wav) -> Result<Vec<u8>, WavError> {
    // TODO(wav-decode): Keep codec-level decode/resample helpers out of this container module;
    // add optional PCM/ADPCM decoding in higher-level playback/tooling APIs.
    Ok(match (wav.wav_type, wav.audio_format) {
        (WavType::Standard, WavAudioFormat::Wave) => clean_payload.to_vec(),
        (WavType::Sfx, WavAudioFormat::Wave) => {
            // Deliberately asymmetric with the reader, which does not
            // require this prefix because the engine does not either. It is
            // emitted anyway: every retail SFX carries it, so writing it
            // keeps this output comparable with shipped files, and other
            // tools do key on it even though the game does not.
            let mut out = Vec::with_capacity(SFX_HEADER_SIZE + clean_payload.len());
            out.resize(SFX_HEADER_SIZE, 0);
            out[0..4].copy_from_slice(&SFX_MAGIC);
            out.extend_from_slice(clean_payload);
            out
        }
        (WavType::Vo, WavAudioFormat::Mp3) => {
            if clean_payload.is_empty() {
                return Err(WavError::EmptyMp3);
            }
            let mut out = Vec::with_capacity(MP3_IN_WAV_HEADER.len() + clean_payload.len());
            out.extend_from_slice(&MP3_IN_WAV_HEADER);
            out.extend_from_slice(clean_payload);
            out
        }
        (form @ (WavType::Standard | WavType::Sfx), payload @ WavAudioFormat::Mp3)
        | (form @ WavType::Vo, payload @ WavAudioFormat::Wave) => {
            return Err(WavError::MismatchedPayload { form, payload });
        }
    })
}

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

    /// The header as `wav.md` lays it out, row by row.
    fn header_from_the_page() -> Vec<u8> {
        let mut header = Vec::new();
        header.extend_from_slice(b"RIFF");
        header.extend_from_slice(&50_u32.to_le_bytes());
        header.extend_from_slice(b"WAVE");
        header.extend_from_slice(b"fmt ");
        header.extend_from_slice(&18_u32.to_le_bytes());
        // 8-bit mono PCM at 22,050 Hz, so one byte per frame.
        header.extend_from_slice(&1_u16.to_le_bytes());
        header.extend_from_slice(&1_u16.to_le_bytes());
        header.extend_from_slice(&22_050_u32.to_le_bytes());
        header.extend_from_slice(&22_050_u32.to_le_bytes());
        header.extend_from_slice(&1_u16.to_le_bytes());
        header.extend_from_slice(&8_u16.to_le_bytes());
        header.extend_from_slice(&0_u16.to_le_bytes());
        header.extend_from_slice(b"fact");
        header.extend_from_slice(&4_u32.to_le_bytes());
        header.extend_from_slice(&0_u32.to_le_bytes());
        header.extend_from_slice(b"data");
        header.extend_from_slice(&0_u32.to_le_bytes());
        header
    }

    #[test]
    fn mp3_in_wav_output_opens_with_the_header_vanilla_writes() {
        let mp3 = vec![0xFF, 0xFB, 0x38, 0xC4, 0x00, 0x01];
        let bytes = write_wav_to_vec(&Wav::new_mp3(WavType::Vo, mp3.clone())).expect("write");

        let header = header_from_the_page();
        assert_eq!(header.len(), 58, "the page's table spans bytes 0 to 0x3A");
        assert_eq!(&bytes[..58], header.as_slice());
        assert_eq!(&bytes[58..], mp3.as_slice());
    }

    #[test]
    fn mp3_in_wav_output_reads_back_and_writes_the_same_bytes() {
        let first = write_wav_to_vec(&Wav::new_mp3(WavType::Vo, vec![0xFF, 0xFB, 0x90, 0x40]))
            .expect("first write");
        let reread = read_wav_from_bytes(&first).expect("read");
        assert_eq!(reread.audio_format, WavAudioFormat::Mp3);
        let second = write_wav_to_vec(&reread).expect("second write");
        assert_eq!(first, second);
    }

    #[test]
    fn a_wave_payload_has_no_mp3_in_wav_form() {
        let wave = Wav::new_wave(
            WavType::Vo,
            WavWaveMetadata {
                encoding: WavEncodingCode::from(WavEncoding::Pcm),
                channels: 1,
                sample_rate: 22_050,
                bytes_per_sec: 22_050,
                block_align: 1,
                bits_per_sample: 8,
            },
            vec![0x80; 4],
        );
        assert!(matches!(
            write_wav_to_vec(&wave),
            Err(WavError::MismatchedPayload {
                form: WavType::Vo,
                payload: WavAudioFormat::Wave,
            })
        ));
    }

    #[test]
    fn an_mp3_payload_has_no_plain_or_prefixed_form() {
        for form in [WavType::Standard, WavType::Sfx] {
            let mp3 = Wav::new_mp3(form, vec![0xFF, 0xFB, 0x90, 0x40]);
            assert!(
                matches!(
                    write_wav_to_vec(&mp3),
                    Err(WavError::MismatchedPayload {
                        payload: WavAudioFormat::Mp3,
                        ..
                    })
                ),
                "{form}"
            );
        }
    }

    #[test]
    fn an_mp3_in_wav_with_no_mp3_is_refused() {
        // The header alone would read back as a plain empty WAVE.
        assert!(matches!(
            write_wav_to_vec(&Wav::new_mp3(WavType::Vo, Vec::new())),
            Err(WavError::EmptyMp3)
        ));
    }

    #[test]
    fn clean_mode_writes_any_pair() {
        let options = WavWriteOptions {
            mode: WavWriteMode::Clean,
        };
        let mp3 = Wav::new_mp3(WavType::Sfx, vec![0xFF, 0xFB]);
        assert_eq!(
            write_wav_to_vec_with_options(&mp3, options).expect("clean write"),
            vec![0xFF, 0xFB]
        );
    }
}