ot_tools_io/

samples.rs

/*
SPDX-License-Identifier: GPL-3.0-or-later
Copyright © 2024 Mike Robeson [dijksterhuis]
*/

//! Types and ser/de of `*.ot` binary data files.

pub mod configs;
pub mod options;
pub mod slices;

use crate::{
    samples::options::{SampleAttributeTimestrechMode, SampleAttributeTrigQuantizationMode},
    samples::{
        configs::{SampleLoopConfig, SampleTrimConfig},
        slices::{Slice, Slices},
    },
    CalculateChecksum, CheckChecksum, CheckHeader, CheckIntegrity, Decode, Encode,
    OptionEnumValueConvert, RBoxErr,
};
use ot_tools_io_derive::Decodeable;
use serde::{Deserialize, Serialize};
use serde_big_array::BigArray;

// in `hexdump -C` format:
// ```
// FORM....DPS1SMPA
// ......
// ```
/// Standard header bytes in an sample 'attributes' file
pub const SAMPLES_HEADER: [u8; 21] = [
    0x46, 0x4F, 0x52, 0x4D, 0x00, 0x00, 0x00, 0x00, 0x44, 0x50, 0x53, 0x31, 0x53, 0x4D, 0x50, 0x41,
    0x00, 0x00, 0x00, 0x00, 0x00,
];

/// Current/supported datatype version for a sample attributes file
pub const SAMPLES_FILE_VERSION: u8 = 2;

// TODO move to lib.rs
/// Trait for adding the `.swap_bytes()` method.
pub trait SwapBytes {
    /// Type for `Self`
    type T;

    /// Swap the bytes of all struct fields.
    /// Must be applied to the `SampleAttributes` file to deal with litle-endian/big-endian systems.
    fn swap_bytes(self) -> RBoxErr<Self::T>;
}

#[derive(Debug)]
enum SampleAttributeErrors {
    TempoOutOfBounds,
    GainOutOfBounds,
}
impl std::fmt::Display for SampleAttributeErrors {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        match self {
            Self::GainOutOfBounds => write!(f, "invalid gain, must be in range -24.0 <= x <= 24.0"),
            Self::TempoOutOfBounds => write!(
                f,
                "invalid tempo value, must be in range 30.0 <= x <= 300.0"
            ),
        }
    }
}
impl std::error::Error for SampleAttributeErrors {}

/// Convert from a human (device UI) representation of gain (-24.0 <= x <= 24.0)
/// to binary data file representation of gain (0 <= x <= 96).
/// Note that binary gain uses two bytes (hence u16).
fn bin_gain_from_human(human_gain: &f32) -> RBoxErr<u16> {
    // don't use contains range trick here. need to explicitly check range bounds.
    #[allow(clippy::manual_range_contains)]
    if human_gain < &-24.0 || human_gain > &24.0 {
        Err(SampleAttributeErrors::GainOutOfBounds.into())
    } else {
        let new_gain_f32 = (2.0 * (10.0 * (human_gain + 24.0)).round()) * 0.1;
        Ok(new_gain_f32 as u16)
    }
}

/// Convert from a human (device UI) representation of tempo (30.0 <= x <= 300.0)
/// to binary data file representation of gain (720 <= x <= 7200)
/// Note that binary tempo uses four bytes (hence u32).
fn bin_tempo_from_human(human_tempo: &f32) -> RBoxErr<u32> {
    // don't use contains range trick here. need to explicitly check range bounds.
    #[allow(clippy::manual_range_contains)]
    if human_tempo < &30.0 || human_tempo > &300.0 {
        Err(SampleAttributeErrors::TempoOutOfBounds.into())
    } else {
        let bin_tempo_f32 = human_tempo * 24.0;
        Ok(bin_tempo_f32 as u32)
    }
}

/// Struct to create a valid Octatrack `.ot` file.
/// General metadata for the sample's configuration on the OT
/// and the slice array with pointer positions for the sliced WAV.
#[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
pub struct SampleAttributes {
    /// Header
    pub header: [u8; 21],

    /// Datatype's version ID//
    pub datatype_version: u8,

    /// Unknown data
    pub unknown: u8,

    /// Tempo is always the machine UI's BPM multiplied by 24
    pub tempo: u32,

    /// Number of bars for the sample trim length marker.
    /// By default, trim length should be equal to trim end,
    /// and probably loop length too for drum hit sample chains.
    pub trim_len: u32,

    /// Number of bars for the sample loop length marker.
    /// By default, loop length should be equal to trim length for sample chains.
    pub loop_len: u32,

    /// Default timestrech algorithm applied to the sample.
    /// See the `ot_sample::options::SampleTimestrechModes` enum for suitable choices.
    pub stretch: u32,

    /// Default loop mode applied to the sample.
    /// See the `ot_sample::options::SampleLoopModes` enum for suitable choices.
    pub loop_mode: u32,

    /// Gain of the sample.
    /// -24.0 db <= x <= +24 db range in the machine's UI, with increments of 0.5 db changes.
    /// 0 <= x <= 96 range in binary data file.
    pub gain: u16,

    /// Default trig quantization mode applied to the sample.
    /// See the `ot_sample::options::SampleTrigQuantizationModes` enum for suitable choices.
    pub quantization: u8,

    /// Where the trim start marker is placed for the sample, measured in bars.
    /// Default is 0 (start of sample).
    /// TODO: measured in bars? or samples?
    pub trim_start: u32,

    /// Where the trim end marker is placed for the sample.
    /// When the sample is being played in normal mode (i.e. not using slices),
    /// the Octatrack will not play samples past this point.
    /// By default, trim length should be equal to trim end,
    /// and probably loop length too for drum hit sample chains.
    /// TODO: measured in bars? or samples?
    pub trim_end: u32,

    /// Start position for any loops. Default should be the same as trim start.
    /// Measured in bars.
    /// A note from the Octatrack manual on loop point/start behaviour:
    /// > If a loop point is set, the sample will play from the start point to the
    /// > end point, then loop from the loop point to the end point
    pub loop_start: u32,

    /// 64 length array containing `Slice`s.
    /// See the `Slice` struct for more details.
    /// Any empty slice positions should have zero-valued struct fields.
    #[serde(with = "BigArray")]
    pub slices: [Slice; 64],

    /// Number of usuable `Slice`s in this sample.
    /// Used by the Octatrack to ignore zero-valued `Slice`s in the `slices` array when loading the sample.
    pub slices_len: u32,

    /// Checksum value for the struct.
    /// This must be calculated **after** the struct is created on little-endian systems
    /// (requires byte swapping all struct fields to get the correct checksum value).
    pub checksum: u16,
}

impl SwapBytes for SampleAttributes {
    /// Swaps the bytes on all struct fields.
    /// **MUST BE CALLED BEFORE SERIALISATION WHEN SYSTEM IS LITTLE ENDIAN!**
    type T = SampleAttributes;

    /// Swap the bytes of all struct fields.
    /// Must be applied to the `SampleAttributes` file to deal with litle-endian/big-endian systems.
    fn swap_bytes(self) -> RBoxErr<Self::T> {
        let mut bswapped_slices: [Slice; 64] = self.slices;

        for (i, slice) in self.slices.iter().enumerate() {
            bswapped_slices[i] = slice.swap_bytes()?;
        }

        let bswapped = Self {
            header: SAMPLES_HEADER,
            datatype_version: SAMPLES_FILE_VERSION,
            unknown: self.unknown,
            tempo: self.tempo.swap_bytes(),
            trim_len: self.trim_len.swap_bytes(),
            loop_len: self.loop_len.swap_bytes(),
            stretch: self.stretch.swap_bytes(),
            loop_mode: self.loop_mode.swap_bytes(),
            gain: self.gain.swap_bytes(),
            quantization: self.quantization.swap_bytes(),
            trim_start: self.trim_start.swap_bytes(),
            trim_end: self.trim_end.swap_bytes(),
            loop_start: self.loop_start.swap_bytes(),
            slices: bswapped_slices,
            slices_len: self.slices_len.swap_bytes(),
            checksum: self.checksum.swap_bytes(),
        };

        Ok(bswapped)
    }
}

impl SampleAttributes {
    /// Create a new `SampleAttributesFile` struct.
    /// 'Human-readable' `f32` values for `gain` and `tempo` are converted to proper `u8` values in this method.
    /// ```rust
    /// # use std::array::from_fn;
    /// # use ot_tools_io::samples::SampleAttributes;
    /// # use ot_tools_io::samples::options::{
    /// #    SampleAttributeTimestrechMode,
    /// #    SampleAttributeTrigQuantizationMode,
    /// #    SampleAttributeLoopMode,
    /// # };
    /// # use ot_tools_io::samples::configs::{
    /// #    SampleLoopConfig,
    /// #    SampleTrimConfig,
    /// # };
    /// # use ot_tools_io::samples::slices::{Slices, Slice};
    /// # let slice_arr: [Slice; 64] = from_fn(|_| Slice::default());
    /// # let slices: Slices = Slices { slices: slice_arr, count: 0 };
    /// let x = SampleAttributes::new(
    ///     &120.0,
    ///     // ...
    ///     # &SampleAttributeTimestrechMode::default(),
    ///     # &SampleAttributeTrigQuantizationMode::default(),
    ///     &0.0,
    ///     // ...
    ///     # &SampleTrimConfig { start: 0, end: 100, length: 25 },
    ///     # &SampleLoopConfig { start: 0, length: 100, mode: SampleAttributeLoopMode::Off },
    ///     # &slices,
    /// ).unwrap();
    /// assert_eq!(x.tempo, 2880);
    /// assert_eq!(x.gain, 48);
    /// ```
    pub fn new(
        tempo: &f32,
        stretch: &SampleAttributeTimestrechMode,
        quantization: &SampleAttributeTrigQuantizationMode,
        gain: &f32,
        trim_config: &SampleTrimConfig,
        loop_config: &SampleLoopConfig,
        slices: &Slices,
    ) -> RBoxErr<Self> {
        Ok(Self {
            header: SAMPLES_HEADER,
            datatype_version: SAMPLES_FILE_VERSION,
            unknown: 0,
            gain: bin_gain_from_human(gain)?,
            stretch: stretch.value()?,
            tempo: bin_tempo_from_human(tempo)?,
            quantization: quantization.value()? as u8,
            trim_start: trim_config.start,
            trim_end: trim_config.end,
            trim_len: trim_config.length, // bin lengths are multiplied by 100?
            loop_start: loop_config.start,
            loop_len: loop_config.length, // bin lengths are multiplied by 100?
            loop_mode: loop_config.mode.value()?,
            slices: slices.slices,
            slices_len: slices.count,
            checksum: 0,
        })
    }
}

// For samples, need to run special decode method as need to flip bytes depending on endianness
impl Decode for SampleAttributes {
    /// Decode raw bytes of a `.ot` data file into a new struct,
    /// swap byte values if system is little-endian then do some minor
    /// post-processing to get user-friendly settings values.
    fn decode(bytes: &[u8]) -> RBoxErr<Self> {
        let decoded: Self = bincode::deserialize(bytes)?;
        let mut bswapd = decoded.clone();

        // swapping bytes is one required when running on little-endian systems
        if cfg!(target_endian = "little") {
            bswapd = decoded.swap_bytes()?;
        }

        Ok(bswapd)
    }
}

// For sample data, need swap bytes depending on endianness and calculate a checksum
impl Encode for SampleAttributes {
    /// Encodes struct data to binary representation, after some pre-processing.
    ///
    /// Before serializing, will:
    /// 1. modify tempo and gain values to machine ranges
    /// 2. swaps bytes of values (when current system is little-endian)
    /// 3. generate checksum value
    fn encode(&self) -> RBoxErr<Vec<u8>> {
        Ok(bincode::serialize(self)?)
    }
}

impl CalculateChecksum for SampleAttributes {
    fn calculate_checksum(&self) -> RBoxErr<u16> {
        let bytes = self.encode()?;

        // skip header and checksum byte values
        let checksum_bytes = &bytes[16..bytes.len() - 2];

        let chk: u32 = checksum_bytes
            .iter()
            .map(|x| *x as u32)
            .sum::<u32>()
            .rem_euclid(u16::MAX as u32 + 1);

        Ok(chk as u16)
    }
}

impl CheckHeader for SampleAttributes {
    fn check_header(&self) -> bool {
        self.header == SAMPLES_HEADER
    }
}

impl CheckChecksum for SampleAttributes {
    fn check_checksum(&self) -> RBoxErr<bool> {
        Ok(self.checksum == self.calculate_checksum()?)
    }
}

impl CheckIntegrity for SampleAttributes {}

/// Only really useful for debugging and / or reverse engineering purposes.
#[derive(Debug, Serialize, Deserialize, Decodeable)]
pub struct SampleAttributesRawBytes {
    #[serde(with = "BigArray")]
    pub data: [u8; 832],
}

#[cfg(test)]
mod test {
    use crate::samples::configs::{SampleLoopConfig, SampleTrimConfig};
    use crate::samples::options::SampleAttributeLoopMode;
    use crate::samples::slices::{Slice, Slices};

    fn create_mock_configs_blank() -> (SampleTrimConfig, SampleLoopConfig, Slices) {
        let trim_config = SampleTrimConfig {
            start: 0,
            end: 0,
            length: 0,
        };

        let loop_config = SampleLoopConfig {
            start: 0,
            length: 0,
            mode: SampleAttributeLoopMode::Normal,
        };

        let default_slice = Slice {
            trim_start: 0,
            trim_end: 0,
            loop_start: 0xFFFFFFFF,
        };

        let slices: [Slice; 64] = [default_slice; 64];

        let slice_conf = Slices { slices, count: 0 };

        (trim_config, loop_config, slice_conf)
    }

    mod checksum {
        /*
        mod array_based {
            use crate::CalculateChecksum;
            use std::array::from_fn;

            #[test]
            #[ignore]
            fn ok_no_overflow_all_255() {
                let bytes: [u8; 832] = from_fn(|_| 255);
                assert_eq!(
                    get_checksum(&bytes).unwrap(),
                    10962,
                    "overflows should wrap"
                );
            }
            #[test]
            #[ignore]
            fn ok_no_overflow() {
                let bytes: [u8; 832] = from_fn(|_| 78);

                assert_eq!(
                    get_checksum(&bytes).unwrap(),
                    63492,
                    "random value that shouldn't overflow at all"
                );
            }

            #[test]
            #[ignore]
            fn ok_64_slice_len() {
                let bytes: [u8; 832] = from_fn(|_| 64);
                assert_eq!(get_checksum(&bytes).unwrap(), 52096,);
            }

            #[test]
            #[ignore]
            fn ok_one_bytes() {
                let bytes: [u8; 832] = from_fn(|_| 1);
                assert_eq!(
                    get_checksum(&bytes).unwrap(),
                    814,
                    "low values definitely don't overflow"
                );
            }

            #[test]
            #[ignore]
            fn ok_zeroed() {
                let bytes: [u8; 832] = from_fn(|_| 0);
                assert_eq!(
                    get_checksum(&bytes).unwrap(),
                    0,
                    "unknown if this is correct behaviour"
                );
            }
        }
        */

        mod file_based {
            use crate::read_type_from_bin_file;
            use crate::samples::{CalculateChecksum, SampleAttributes};
            use crate::test_utils::get_samples_dirpath;

            #[test]
            fn zero_slices_trig_quant_one_step() {
                let path = get_samples_dirpath()
                    .join("checksum")
                    .join("0slices-tq1step.ot");
                let data = read_type_from_bin_file::<SampleAttributes>(&path).unwrap();
                assert_eq!(data.calculate_checksum().unwrap(), data.checksum);
            }

            #[test]
            fn zero_slices() {
                let path = get_samples_dirpath().join("checksum").join("0slices.ot");
                let data = read_type_from_bin_file::<SampleAttributes>(&path).unwrap();
                assert_eq!(data.calculate_checksum().unwrap(), data.checksum);
            }

            #[test]
            fn one_slice() {
                let path = get_samples_dirpath().join("checksum").join("1slices.ot");
                let data = read_type_from_bin_file::<SampleAttributes>(&path).unwrap();
                assert_eq!(data.calculate_checksum().unwrap(), data.checksum);
            }
            #[test]
            fn two_slices() {
                let path = get_samples_dirpath().join("checksum").join("2slices.ot");
                let data = read_type_from_bin_file::<SampleAttributes>(&path).unwrap();
                assert_eq!(data.calculate_checksum().unwrap(), data.checksum);
            }
            #[test]
            fn four_slices() {
                let path = get_samples_dirpath().join("checksum").join("4slices.ot");
                let data = read_type_from_bin_file::<SampleAttributes>(&path).unwrap();
                assert_eq!(data.calculate_checksum().unwrap(), data.checksum);
            }
            #[test]
            fn eight_slices() {
                let path = get_samples_dirpath().join("checksum").join("8slices.ot");
                let data = read_type_from_bin_file::<SampleAttributes>(&path).unwrap();
                assert_eq!(data.calculate_checksum().unwrap(), data.checksum);
            }
            #[test]
            fn sixteen_slices() {
                let path = get_samples_dirpath().join("checksum").join("16slices.ot");
                let data = read_type_from_bin_file::<SampleAttributes>(&path).unwrap();
                assert_eq!(data.calculate_checksum().unwrap(), data.checksum);
            }
            #[test]
            fn thirty_two_slices() {
                let path = get_samples_dirpath().join("checksum").join("32slices.ot");
                let data = read_type_from_bin_file::<SampleAttributes>(&path).unwrap();
                assert_eq!(data.calculate_checksum().unwrap(), data.checksum);
            }
            #[test]
            fn forty_eight_slices() {
                let path = get_samples_dirpath().join("checksum").join("48slices.ot");
                let data = read_type_from_bin_file::<SampleAttributes>(&path).unwrap();
                assert_eq!(data.calculate_checksum().unwrap(), data.checksum);
            }
            #[test]
            fn sixty_two_slices() {
                let path = get_samples_dirpath().join("checksum").join("62slices.ot");
                let data = read_type_from_bin_file::<SampleAttributes>(&path).unwrap();
                assert_eq!(data.calculate_checksum().unwrap(), data.checksum);
            }
            #[test]
            fn sixty_three_slices() {
                let path = get_samples_dirpath().join("checksum").join("63slices.ot");
                let data = read_type_from_bin_file::<SampleAttributes>(&path).unwrap();
                assert_eq!(data.calculate_checksum().unwrap(), data.checksum);
            }
            #[test]
            fn sixty_four_slices_correct() {
                let path = get_samples_dirpath().join("checksum").join("64slices.ot");
                let data = read_type_from_bin_file::<SampleAttributes>(&path).unwrap();
                assert_eq!(data.calculate_checksum().unwrap(), data.checksum);
            }
        }
    }

    mod bin_tempo_from_human {
        use crate::samples::bin_tempo_from_human;

        #[test]
        fn err_oob_too_low() {
            assert!(bin_tempo_from_human(&29.9).is_err());
        }
        #[test]
        fn err_oob_too_high() {
            assert!(bin_tempo_from_human(&300.1).is_err());
        }

        #[test]
        fn ok_30() {
            assert_eq!(bin_tempo_from_human(&30.0).unwrap(), 720);
        }
        #[test]
        fn ok_300() {
            assert_eq!(bin_tempo_from_human(&300.0).unwrap(), 7200);
        }

        #[test]
        fn ok_120() {
            assert_eq!(bin_tempo_from_human(&120.0).unwrap(), 2880);
        }

        #[test]
        fn ok_100() {
            assert_eq!(bin_tempo_from_human(&100.0).unwrap(), 2400);
        }
    }

    mod bin_gain_from_human {
        use crate::samples::bin_gain_from_human;

        #[test]
        fn err_oob_too_low() {
            assert!(bin_gain_from_human(&-24.1).is_err());
        }
        #[test]
        fn err_oob_too_high() {
            assert!(bin_gain_from_human(&24.1).is_err());
        }

        #[test]
        fn ok_negative_24() {
            assert_eq!(bin_gain_from_human(&-24.0).unwrap(), 0);
        }
        #[test]
        fn ok_positive_24() {
            assert_eq!(bin_gain_from_human(&24.0).unwrap(), 96);
        }

        #[test]
        fn ok_positive_23_half() {
            assert_eq!(bin_gain_from_human(&23.5).unwrap(), 95);
        }

        #[test]
        fn ok_negative_23_half() {
            assert_eq!(bin_gain_from_human(&-23.5).unwrap(), 1);
        }

        #[test]
        fn ok_zero() {
            assert_eq!(bin_gain_from_human(&0.0).unwrap(), 48);
        }

        #[test]
        fn ok_zero_half() {
            assert_eq!(bin_gain_from_human(&0.5).unwrap(), 49);
        }

        #[test]
        fn ok_zero_minus_half() {
            assert_eq!(bin_gain_from_human(&-0.5).unwrap(), 47);
        }
    }

    mod create_new {

        use super::create_mock_configs_blank;
        use crate::samples::options::{
            SampleAttributeTimestrechMode, SampleAttributeTrigQuantizationMode,
        };
        use crate::samples::SampleAttributes;

        #[test]
        fn err_oob_tempo() {
            let (trim_conf, loop_conf, slices) = create_mock_configs_blank();

            let composed_chain = SampleAttributes::new(
                &10000.0,
                &SampleAttributeTimestrechMode::Off,
                &SampleAttributeTrigQuantizationMode::PatternLength,
                &0.0,
                &trim_conf,
                &loop_conf,
                &slices,
            );

            assert!(composed_chain.is_err());
        }

        #[test]
        fn err_invalid_gain() {
            let (trim_conf, loop_conf, slices) = create_mock_configs_blank();

            let composed_chain = SampleAttributes::new(
                &125.0,
                &SampleAttributeTimestrechMode::Off,
                &SampleAttributeTrigQuantizationMode::PatternLength,
                &300.0,
                &trim_conf,
                &loop_conf,
                &slices,
            );

            assert!(composed_chain.is_err());
        }
    }

    mod integrity {
        use super::create_mock_configs_blank;
        use crate::samples::options::{
            SampleAttributeTimestrechMode, SampleAttributeTrigQuantizationMode,
        };
        use crate::samples::SampleAttributes;
        use crate::CheckHeader;
        #[test]
        fn true_valid_header() {
            let (trim_conf, loop_conf, slices) = create_mock_configs_blank();
            let new = SampleAttributes::new(
                &120.0,
                &SampleAttributeTimestrechMode::Off,
                &SampleAttributeTrigQuantizationMode::PatternLength,
                &0.0,
                &trim_conf,
                &loop_conf,
                &slices,
            );
            assert!(new.unwrap().check_header());
        }

        #[test]
        fn false_invalid_header() {
            let (trim_conf, loop_conf, slices) = create_mock_configs_blank();
            let new = SampleAttributes::new(
                &120.0,
                &SampleAttributeTimestrechMode::Off,
                &SampleAttributeTrigQuantizationMode::PatternLength,
                &0.0,
                &trim_conf,
                &loop_conf,
                &slices,
            );
            let mut mutated = new.unwrap();
            mutated.header[0] = 0x00;
            mutated.header[20] = 111;
            assert!(!mutated.check_header());
        }
    }
}