ot_tools_io/

markers.rs

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

//! Types and ser/de of `markers.*` binary data files.
//!
//! A "Markers" file contains data related to the playback settings of loaded
//! sample slots
//! - Trim Start
//! - Trim End
//! - Loop Point
//! - Slices (Start / End / Loop Point)
//!
//! The Markers file is dependent on a Project's Sample Slots. Switching out a
//! sample slot updates playback settings in the markers file.
//!
//! TODO: Figure out exactly WHEN update occurs (when adding a file to the slot?)

use crate::samples::slices::{Slice, SLICE_LOOP_POINT_DEFAULT};
use crate::samples::SwapBytes;
use crate::{
    CalculateChecksum, CheckChecksum, CheckHeader, CheckIntegrity, Decode, Encode, IsDefault,
    OtToolsIoErrors, RBoxErr,
};
use ot_tools_io_derive::Decodeable;
use serde::{Deserialize, Serialize};
use serde_big_array::{Array, BigArray};
use std::array::from_fn;

/*
# ===== DEFAULT DATA FILE ===== #
00000000  46 4f 52 4d 00 00 00 00  44 50 53 31 53 41 4d 50  |FORM....DPS1SAMP|
00000010  00 00 00 00 00 04 00 00  00 00 00 00 00 00 00 00  |................|
00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
# ***** REPEATS *****
00032890  00 00 00 00 00 00 00 04                           |........|
00032898
*/

/// Header data for the markers file
pub const MARKERS_HEADER: [u8; 21] = [
    0x46, 0x4f, 0x52, 0x4d, 0x00, 0x00, 0x00, 0x00, 0x44, 0x50, 0x53, 0x31, 0x53, 0x41, 0x4d, 0x50,
    0x00, 0x00, 0x00, 0x00, 0x00,
];

/// Current/supported version of markers files.
pub const MARKERS_FILE_VERSION: u8 = 4;

/// The model for a 'slot' within a [MarkersFile].
/// Slot settings like quantization are stored in the [crate::projects::slots::ProjectSampleSlot] type
#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize, Decodeable)]
pub struct SlotPlayback {
    /// main sample trim offset (start)
    pub trim_offset: u32,

    /// main sample trim end
    pub trim_end: u32,

    /// main sample loop point
    pub loop_point: u32,

    /// slices array for slice position editing
    #[serde(with = "BigArray")]
    pub slices: [Slice; 64],

    /// number of slices
    pub slice_count: u32,
}

impl SlotPlayback {
    fn validate(&self) -> RBoxErr<bool> {
        for slice in self.slices.iter() {
            slice.validate()?;
        }
        let trim_ok = self.trim_offset < self.trim_end;
        let slice_count_ok = self.slice_count == self.slices.len() as u32;
        let loop_start_ok = self.loop_point >= self.trim_offset;
        let loop_end_ok =
            self.loop_point <= self.trim_end || self.loop_point == SLICE_LOOP_POINT_DEFAULT;

        if !(trim_ok && slice_count_ok && loop_start_ok && loop_end_ok) {
            return Err(OtToolsIoErrors::TodoError.into());
        }

        Ok(true)
    }
}

impl SwapBytes for SlotPlayback {
    type T = SlotPlayback;
    fn swap_bytes(self) -> RBoxErr<Self::T> {
        let mut slices: [Slice; 64] = self.slices;

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

        let bswapped = Self {
            trim_offset: self.trim_offset.swap_bytes(),
            trim_end: self.trim_end.swap_bytes(),
            loop_point: self.loop_point.swap_bytes(),
            slices,
            slice_count: self.slice_count.swap_bytes(),
        };

        Ok(bswapped)
    }
}

impl Default for SlotPlayback {
    fn default() -> Self {
        Self {
            trim_offset: 0,
            trim_end: 0,
            loop_point: 0,
            slices: from_fn(|_| Slice::default()),
            slice_count: 0,
        }
    }
}

/// The 'markers' file. Contains sample editor data for all slots in a project.
#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
pub struct MarkersFile {
    #[serde(with = "BigArray")]
    pub header: [u8; 21],

    /// version of data file. used in OS upgrades for patching files (and checks
    /// performed on files during loading of a project).
    ///
    /// ### background / context
    ///
    /// Got this error on the device when i messed up the default markers file
    /// when i didn't include the `4` (current value for 1.40B).
    /// ```text
    /// >>> 2025-04-24 22:06:00 ERROR Couldn't read from markers file ...
    /// >>> '/test-set-bankcopy/PROJECT-BLANK/markers.work' ('INVALID FILESIZE')
    /// ```
    ///
    /// Additionally, Banks for projects created with 1.40X have a 'version'
    /// number of 23, while the LESSSELF/V1 project started with 1.25E has a
    /// version of 15.
    ///
    /// So yep. These weird numbers are version numbers for the data types /
    /// structures / files.
    pub datatype_version: u8,

    /// audio editor slots for flex slots
    pub flex_slots: Box<Array<SlotPlayback, 128>>,

    /// 8x dedicated flex recording tracks
    pub recorder_slots: Box<Array<SlotPlayback, 8>>,

    /// audio editor slots for static slots
    pub static_slots: Box<Array<SlotPlayback, 128>>,

    // i'm assuming a u16 checksum here as well?
    pub checksum: u16,
}

impl MarkersFile {
    #[allow(dead_code)]
    fn validate(&self) -> RBoxErr<bool> {
        for slot in self.flex_slots.iter() {
            slot.validate()?;
        }
        for slot in self.recorder_slots.iter() {
            slot.validate()?;
        }
        for slot in self.static_slots.iter() {
            slot.validate()?;
        }

        Ok(true)
    }
}

impl SwapBytes for MarkersFile {
    type T = MarkersFile;
    fn swap_bytes(self) -> RBoxErr<Self::T> {
        let mut flex_slots = self.flex_slots.clone();
        for (i, slot) in self.flex_slots.iter().enumerate() {
            flex_slots[i] = slot.clone().swap_bytes()?;
        }

        let mut recorder_slots = self.recorder_slots.clone();
        for (i, slot) in self.recorder_slots.iter().enumerate() {
            recorder_slots[i] = slot.clone().swap_bytes()?;
        }

        let mut static_slots = self.static_slots.clone();
        for (i, slot) in self.static_slots.iter().enumerate() {
            static_slots[i] = slot.clone().swap_bytes()?;
        }

        let bswapped = Self {
            header: self.header,
            datatype_version: self.datatype_version,
            flex_slots,
            recorder_slots,
            static_slots,
            checksum: self.checksum.swap_bytes(),
        };

        Ok(bswapped)
    }
}

impl Decode for MarkersFile {
    fn decode(bytes: &[u8]) -> RBoxErr<Self>
    where
        Self: Sized,
        Self: for<'a> Deserialize<'a>,
    {
        let mut x: Self = bincode::deserialize(bytes)?;
        #[cfg(target_endian = "little")]
        {
            x = x.swap_bytes()?;
        }

        Ok(x)
    }
}

impl Encode for MarkersFile {
    fn encode(&self) -> RBoxErr<Vec<u8>> {
        let bytes = bincode::serialize(self)?;
        Ok(bytes)
    }
}

impl MarkersFile {
    fn new(
        flex_slots: [SlotPlayback; 128],
        recorder_slots: [SlotPlayback; 8],
        static_slots: [SlotPlayback; 128],
    ) -> RBoxErr<Self> {
        let mut init = Self {
            header: MARKERS_HEADER,
            datatype_version: MARKERS_FILE_VERSION,
            flex_slots: Array(flex_slots).into(),
            recorder_slots: Array(recorder_slots).into(),
            static_slots: Array(static_slots).into(),
            checksum: 0,
        };

        init.checksum = init.calculate_checksum()?;
        Ok(init)
    }
}

impl Default for MarkersFile {
    fn default() -> Self {
        Self::new(
            from_fn(|_| SlotPlayback::default()),
            from_fn(|_| SlotPlayback::default()),
            from_fn(|_| SlotPlayback::default()),
        )
        .unwrap()
    }
}

impl IsDefault for MarkersFile {
    fn is_default(&self) -> bool {
        let default = &mut MarkersFile::default();
        default == self
    }
}

impl CalculateChecksum for MarkersFile {
    fn calculate_checksum(&self) -> RBoxErr<u16> {
        let bytes = self.encode()?;
        let mut chk: u16 = 0;
        for byte in &bytes[16..bytes.len() - 2] {
            chk = chk.wrapping_add(*byte as u16);
        }
        Ok(chk)
    }
}

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

impl CheckChecksum for MarkersFile {
    fn check_checksum(&self) -> RBoxErr<bool> {
        let calculated = self.calculate_checksum()?;
        if self.checksum != calculated {
            eprintln!(
                "Markers file: Invalid checksum: current={} calcuated={}",
                self.checksum, calculated,
            );
            Err(OtToolsIoErrors::TodoError.into())
        } else {
            Ok(true)
        }
    }
}

impl CheckIntegrity for MarkersFile {}

#[derive(Debug, Serialize, Deserialize, Decodeable)]
pub struct MarkersRawBytes {
    pub data: Box<Array<u8, 0x00032898>>,
}

#[cfg(test)]
mod tests {
    mod can_read_generated_files {
        use crate::markers::MarkersFile;
        use crate::samples::slices::Slice;
        use crate::test_utils::get_markers_dirpath;
        use crate::{read_type_from_bin_file, CalculateChecksum};

        const SAMPLE_LEN: u32 = 2679;

        fn test_helper(fname: &str) -> MarkersFile {
            let fpath = get_markers_dirpath().join(fname);
            let r = read_type_from_bin_file::<MarkersFile>(&fpath);

            println!("result: {r:?}");
            assert!(r.is_ok());
            r.unwrap()
        }

        fn assert_helper(m: MarkersFile, mut v: MarkersFile) {
            v.checksum = v.calculate_checksum().unwrap();
            println!("header");
            assert_eq!(m.header, v.header);
            println!("datatype version");
            assert_eq!(m.datatype_version, v.datatype_version);
            println!("recorder slots");
            assert_eq!(m.recorder_slots, v.recorder_slots);
            println!("flex slots");
            assert_eq!(m.flex_slots, v.flex_slots);
            println!("static slots");
            assert_eq!(m.static_slots, v.static_slots);
            println!("checksum slots");
            assert_eq!(m.checksum, v.checksum);
        }

        #[test]
        fn flex_slot_1_noedit() {
            let m = test_helper("flex-slot-1-noedit.work");
            let mut valid = MarkersFile::default();
            valid.flex_slots[0].trim_end = SAMPLE_LEN;
            assert_helper(m, valid);
        }

        #[test]
        fn flex_slot_128_noedit() {
            let m = test_helper("flex-slot-128-noedit.work");
            let mut valid = MarkersFile::default();
            valid.flex_slots[127].trim_end = SAMPLE_LEN;
            assert_helper(m, valid);
        }

        #[test]
        fn static_slot_1_noedit() {
            let m = test_helper("static-slot-1-noedit.work");
            let mut valid = MarkersFile::default();
            // FIXME: I edited the recorder slot, then cleared the sample association
            //        and moved onto statics... but this didn't ACTUALLY CLEAR the
            //        recording slot data -- recording slots persist!
            valid.recorder_slots[0].trim_end = SAMPLE_LEN;
            valid.static_slots[0].trim_end = SAMPLE_LEN;
            assert_helper(m, valid);
        }

        #[test]
        fn static_slot_128_noedit() {
            let m = test_helper("static-slot-128-noedit.work");
            let mut valid = MarkersFile::default();
            // FIXME: I edited the recorder slot, then cleared the sample association
            //        and moved onto statics... but this didn't ACTUALLY CLEAR the
            //        recording slot data -- recording slots persist!
            valid.recorder_slots[0].trim_end = SAMPLE_LEN;
            valid.static_slots[127].trim_end = SAMPLE_LEN;
            assert_helper(m, valid);
        }

        #[test]
        fn recorder_slot_1_noedit() {
            let m = test_helper("recorder-slot-1-noedit.work");
            let mut valid = MarkersFile::default();
            valid.recorder_slots[0].trim_end = SAMPLE_LEN;
            assert_helper(m, valid);
        }

        #[test]
        fn flex_slot_1_loop_edit() {
            let m = test_helper("flex-slot-1-loop-edit.work");
            let mut valid = MarkersFile::default();
            valid.flex_slots[0].trim_end = SAMPLE_LEN;
            valid.flex_slots[0].loop_point = 1456;
            assert_helper(m, valid);
        }

        #[test]
        fn flex_slot_1_start_edit() {
            let m = test_helper("flex-slot-1-start-edit.work");
            let mut valid = MarkersFile::default();
            valid.flex_slots[0].trim_end = SAMPLE_LEN;
            valid.flex_slots[0].trim_offset = 1456;
            // TODO: Huh?
            valid.flex_slots[0].loop_point = 1456;
            assert_helper(m, valid);
        }

        // didn't get this one?
        #[ignore]
        #[test]
        fn flex_slot_1_end_edit() {
            let m = test_helper("flex-slot-1-start-edit.work");
            let mut valid = MarkersFile::default();
            valid.flex_slots[0].trim_end = SAMPLE_LEN;
            assert_helper(m, valid);
        }

        #[test]
        fn flex_slot_1_slice_1_noloop() {
            let m = test_helper("flex-slot-1-slice-1-noloop.work");
            let mut valid = MarkersFile::default();
            valid.flex_slots[0].trim_end = SAMPLE_LEN;
            valid.flex_slots[0].slice_count = 1;
            valid.flex_slots[0].slices[0] = Slice {
                trim_start: 0,
                trim_end: 416,
                loop_start: 0xFFFFFFFF,
            };
            assert_helper(m, valid);
        }

        #[test]
        fn flex_slot_1_slice_1_looped() {
            let m = test_helper("flex-slot-1-slice-1-looped.work");
            let mut valid = MarkersFile::default();
            valid.flex_slots[0].trim_end = SAMPLE_LEN;
            valid.flex_slots[0].slice_count = 1;
            valid.flex_slots[0].slices[0] = Slice {
                trim_start: 0,
                trim_end: 416,
                loop_start: 202,
            };
            assert_helper(m, valid);
        }

        // initial linear slice grid
        #[test]
        fn flex_slot_1_slice_4_noloop() {
            let m = test_helper("flex-slot-1-slice-4-noloop.work");
            let mut valid = MarkersFile::default();
            valid.flex_slots[0].trim_end = SAMPLE_LEN;
            valid.flex_slots[0].slice_count = 4;
            valid.flex_slots[0].slices[0] = Slice {
                trim_start: 0,
                trim_end: 668,
                loop_start: 0xFFFFFFFF,
            };
            valid.flex_slots[0].slices[1] = Slice {
                trim_start: 668,
                trim_end: 1338,
                loop_start: 0xFFFFFFFF,
            };
            valid.flex_slots[0].slices[2] = Slice {
                trim_start: 1338,
                trim_end: 2008,
                loop_start: 0xFFFFFFFF,
            };
            valid.flex_slots[0].slices[3] = Slice {
                trim_start: 2008,
                trim_end: SAMPLE_LEN,
                loop_start: 0xFFFFFFFF,
            };
            assert_helper(m, valid);
        }
    }
}