ot-tools-io 0.11.3

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

//! All types and trait implementations related to [`SampleSettingsFile`]s.

use crate::generics::Slices;
use crate::markers::SlotMarkers;
use crate::projects::{SlotAttributes, DEFAULT_GAIN, DEFAULT_TEMPO};
use crate::settings::{LoopMode, SlotType, TimeStretchMode, TrigQuantizationMode};
use crate::slices::Slice;
use crate::traits::SwapBytes;
use crate::{
    HasChecksumField, HasFileVersionField, HasHeaderField, OctatrackFileIO, OtToolsIoError,
};
use ot_tools_io_derive::{AsMutDerive, AsRefDerive, IntegrityChecks};
use serde::{Deserialize, Serialize};
use std::path::PathBuf;
use thiserror::Error;

#[cfg(test)]
mod test_utils {
    use super::{
        OtToolsIoError, SampleSettingsFile, SlotMarkers, SAMPLES_FILE_VERSION, SAMPLES_HEADER,
    };
    use crate::projects::DEFAULT_GAIN;
    pub(crate) fn create_mock_new_sample_settings(
        tempo: Option<u32>,
        gain: Option<u16>,
    ) -> Result<SampleSettingsFile, OtToolsIoError> {
        SampleSettingsFile::new(
            SlotMarkers::default(),
            gain,
            tempo,
            None,
            None,
            None,
            None,
            None,
        )
    }

    pub(crate) fn mock_0_slice_test_file() -> SampleSettingsFile {
        SampleSettingsFile {
            header: SAMPLES_HEADER,
            datatype_version: SAMPLES_FILE_VERSION,
            unknown: 1,
            tempo: 2281,
            trim_bar_len: 800,
            loop_bar_len: 800,
            stretch: 2,
            loop_mode: 0,
            gain: DEFAULT_GAIN as u16,
            quantization: 255,
            trim_start: 0,
            trim_end: 890839,
            loop_start: 0,
            slices: SlotMarkers::default().slices,
            slices_len: 0,
            checksum: 998,
        }
    }
}

/// Errors specific to [`SampleSettingsFile`]s.
///
/// Most of the time this will be casted into an [`OtToolsIoError`] instance in a return type.
#[derive(Debug, Error)]
pub enum SampleSettingsError {
    #[error("invalid gain, must be u16 in range 0 <= x <= 96: {value}")]
    GainOutOfBounds { value: u32 },
    #[error("invalid tempo value, must be u32 in range 720 <= x <= 7200: {value}")]
    TempoOutOfBounds { value: u32 },
    #[error("invalid slot_id value, must be 1 to 128 for Static slot type or 136 for Flex slot type: id: {id} type: {slot_type}")]
    SlotIdOutOfBounds { id: u8, slot_type: SlotType },
    #[error("invalid checksum value for sample settings file: {checksum}")]
    InvalidChecksum { checksum: u16 },
    #[error("invalid file version value for sample settings file: {version}")]
    InvalidFileVersion { version: u8 },
}

// in `hexdump -C` format:
// ```
// FORM....DPS1SMPA
// ......
// ```
/// Standard header bytes in a sample settings 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 settings file
pub const SAMPLES_FILE_VERSION: u8 = 2;

/// An Octatrack `.ot` file a.k.a. a sample settings file contains trim, slice and attribute
/// settings for a sample/slot.
/// Essentially the type is a combination of [`SlotAttributes`] and [`SlotMarkers`] data, excluding
/// the `slot_id`, `path` and `slot_type` fields from [`SlotAttributes`].
///
/// # The Type's Name
///
/// The Octatrack manual specifically refers to
/// > SAVE SAMPLE SETTINGS will save the trim, slice and attribute settings in a
/// > separate file and link it to the sample currently being edited.
/// >
/// > -- page 87.
///
/// So this is the settings file for a given sample.
///
/// # Missing [`Default`] trait
///
/// In practice, a [`SampleSettingsFile`] is usually paired with an audio file.
/// This library assumes we’re exclusively operating on Octatrack binary data files, that we have no
/// access to any audio sample files.
/// As such, there is no way to know what a "default" implementation of this type would like.
/// So there isn't one.
///
/// Instead of calling `default`, always create a new instance with [`SampleSettingsFile::new`].
///
/// # Converting to other data types
///
/// [`SampleSettingsFile`]s can be converted to/from [`SlotMarkers`] and/or [`SlotAttributes`] using
/// the information from the below table
///
/// | From | To | Via |
/// | ---- | ---- | ---- |
/// | [`SampleSettingsFile`] | [`SlotMarkers`] | [`SlotMarkers::from`] |
/// | [`SampleSettingsFile`] | [`SlotAttributes`] | [`SampleSettingsFile::to_slot_attr`] \* |
/// | `(SlotAttributes, SlotMarkers)` | [`SampleSettingsFile`] | [`SampleSettingsFile::from`] |
///
/// \* requires additional arguments
///
/// # Trim Bar Length and Loop Bar Length
///
/// These fields are not necessary to have a functional [`SampleSettingsFile`].
/// If both of these fields are set to zero, but the BPM/tempo field is populated,
/// then the Octatrack will load the sample using the BPM/tempo field.
///
/// To calculate an appropriate value for these two fields we would have to convert from number of
/// samples to number of bars.
/// This calculation requires the sample rate and length of the relevant audio sample file,
/// meaning this library would need access to such audio sample files.
///
/// This library assumes we're exclusively operating on Octatrack binary data files,
/// that we have no access to any audio files.
///
/// Therefore, these two fields are always set to zero when using any of the following methods
/// - [`SampleSettingsFile::new`]
/// - [`SampleSettingsFile::from`] \*
///
/// If you want to set these two values you have to do one of:
/// - Calculate the appropriate `tempo` value for your desired `trim_bar_len` or `loop_bar_len` and use that
///   when calling [`SampleSettingsFile::new`] or when creating a new struct from scratch
///   (leaving the `trim_bar_len` and `loop_bar_len` fields set to zero if creating a struct from scratch).
/// - Manually create the [`SampleSettingsFile`] from scratch and provide appropriate values for all
///   fields -- note that this means manually adding header etc. field values too.
///
/// Please note that the `trim_bar_len` and `loop_bar_len` fields are **NOT** set to zero during
/// deserialization.
/// A [`SampleSettingsFile`]s should be correctly represented when the file has been generated by
/// the Octatrack itself.
///
/// \* [`SampleSettingsFile::from`] will be able to convert it in the future,
/// but appropriate fields need to be added to the [`SlotAttributes`] type first.
///
/// # Little-endian systems
///
/// The bytes of this type are swapped during decoding on little-endian systems to ensure data is
/// written out correctly.
#[derive(
    Copy,
    Clone,
    Debug,
    Eq,
    Hash,
    Ord,
    PartialEq,
    PartialOrd,
    Serialize,
    Deserialize,
    AsMutDerive,
    AsRefDerive,
    IntegrityChecks,
)]
pub struct SampleSettingsFile {
    /// Header
    ///
    /// ## Validation
    ///
    /// Use the [`SampleSettingsFile::check_header`] method from the [`HasHeaderField`] trait.
    ///
    /// The [`SampleSettingsFile::validate`] method will call [`SampleSettingsFile::check_header`]
    /// to verify the current instance's header.
    pub header: [u8; 21],

    /// Datatype's version ID
    ///
    /// ## Validation
    ///
    /// Use the [`SampleSettingsFile::check_file_version`] method from the [`HasFileVersionField`] trait.
    ///
    /// The [`SampleSettingsFile::validate`] method will call [`SampleSettingsFile::check_file_version`]
    /// to verify the current instance's version.
    pub datatype_version: u8,

    /// Unknown data -- can sometimes be 1, usually 0.
    pub unknown: u8,

    /// Tempo determines the BPM of sample playback.
    /// In this field, the value is always the machine UI's BPM (human BPM) multiplied by 24.
    ///
    /// From page 86 of the Octatrack manual:
    /// > ORIGINAL TEMPO displays the calculated BPM of the sample.
    /// > If it is not correct, it can be changed using the LEVEL knob.
    /// > This setting will affect the sound of a timestretched sample.
    /// > For correct results it should be set to match the original BPM of the sample.
    /// > Altering this setting will alter the TRIM LEN (BARS) and LOOP LEN (BARS) settings.
    ///
    /// ## Validation
    ///
    /// The [`SampleSettingsFile::validate`] method checks whether the field's current value is
    /// within appropriate bounds.
    ///
    /// Validating this field against the `trim_bar_len` and/or `loop_bar_len` fields is outside the scope
    /// of this library.
    pub tempo: u32,

    /// Number of bars for determining the BPM of sample playback.
    /// Should be an appropriate value which corresponds to the `tempo` field.
    ///
    /// From page 86 of the Octatrack manual:
    /// > TRIM LEN (BARS) shows the length of the sample in bars.
    /// > Altering this setting will alter the ORIGINAL TEMPO and LOOP LEN (BARS) settings.
    ///
    /// ## Validation
    ///
    /// The [`SampleSettingsFile::validate`] method does not check this field for validity.
    ///
    /// Validating this field against the `trim_bar_len` and/or `loop_bar_len` fields is outside the scope
    /// of this library.
    pub trim_bar_len: u32,

    /// Number of bars for determining the BPM of sample playback.
    /// Should be an appropriate value which corresponds to the `tempo` field.
    ///
    /// From page 86 of the Octatrack manual:
    /// > LOOP LEN (BARS) displays the amount of bars the looped section of the sample consists of.
    /// > Altering this setting will alter the ORIGINAL TEMPO and TRIM LEN (BARS) settings.
    ///
    /// ## Validation
    ///
    /// The [`SampleSettingsFile::validate`] method does not check this field for validity.
    ///
    /// Validating this field against the `trim_bar_len` and/or `loop_bar_len` fields is outside the scope
    /// of this library.
    pub loop_bar_len: u32,

    /// Time-stretching algorithm applied to the sample.
    /// See [`TimeStretchMode`] for suitable choices.
    ///
    /// ## No enum usage?
    ///
    /// [`TimeStretchMode`] has a base representation of `u8` but a [`SampleSettingsFile`] expects a
    /// `u32` value for this field.
    /// As such, we have to convert to `u32` values for this field via [`TimeStretchMode::try_from`]
    /// instead of the relevant variant.
    /// While it may be possible to change this in a future version via a custom implementation of
    /// [`Serialize`] and [`Deserialize`], it is currently out of scope.
    ///
    /// Use the [`SampleSettingsFile::new`] method to create a new instance with the appropriate
    /// enum variant.
    ///
    /// ## Validation
    ///
    /// The [`SampleSettingsFile::validate`] method checks whether this field has an appropriate value.
    pub stretch: u32,

    /// Loop mode for the sample.
    /// See [`LoopMode`] for suitable choices.
    ///
    /// ## No enum usage?
    ///
    /// [`LoopMode`] has a base representation of `u8` but a [`SampleSettingsFile`] expects a
    /// `u32` value for this field.
    /// As such, we have to convert to `u32` values for this field via [`LoopMode::try_from`]
    /// instead of the relevant variant.
    /// While it may be possible to change this in a future version via a custom implementation of
    /// [`Serialize`] and [`Deserialize`], it is currently out of scope.
    ///
    /// Use the [`SampleSettingsFile::new`] method to create a new instance with the appropriate
    /// enum variant.
    ///
    /// ## Validation
    ///
    /// The [`SampleSettingsFile::validate`] method checks whether this field has an appropriate value.
    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.
    ///
    /// ## Validation
    ///
    /// The [`SampleSettingsFile::validate`] method checks whether this field has an appropriate
    /// value within the Octatrack's bounds for gain.
    pub gain: u16,

    /// Trig Quantization mode applied to the sample.
    /// See [`TrigQuantizationMode`] for suitable choices.
    ///
    /// ## No enum usage?
    ///
    /// [`TrigQuantizationMode`] has a base representation of `u8` but a [`SampleSettingsFile`]
    /// expects a `u32` value for this field.
    /// As such, we have to convert to `u32` values for this field via
    /// [`TrigQuantizationMode::try_from`] instead of the relevant variant.
    /// While it may be possible to change this in a future version via a custom implementation of
    /// [`Serialize`] and [`Deserialize`], it is currently out of scope.
    ///
    /// Use the [`SampleSettingsFile::new`] method to create a new instance with the appropriate
    /// enum variant.
    ///
    /// ## Validation
    ///
    /// The [`SampleSettingsFile::validate`] method checks whether this field has an appropriate value.
    pub quantization: u8,

    /// Where the trim start marker is placed for the sample, measured in bars.
    /// Default is 0 (start of sample).
    ///
    /// ## Validation
    ///
    /// The [`SampleSettingsFile::validate`] method checks whether this field is less than `trim_end`
    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.
    ///
    /// ## Validation
    ///
    /// The [`SampleSettingsFile::validate`] method checks whether this field is greater than `trim_start`
    pub trim_end: u32,

    /// Start position for any loops.
    /// Default is the same as trim start.
    ///
    /// 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
    ///
    /// ## Validation
    ///
    /// The [`SampleSettingsFile::validate`] method checks whether this field is within the bounds
    /// of `trim_start` and `trim_end` values.
    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.
    ///
    /// ## Validation
    ///
    /// The [`SampleSettingsFile::validate`] method calls [`Slice::validate`]
    pub slices: Slices<Slice>,

    /// Number of usable [`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 file.
    /// For now, this value must be calculated and added to the struct **after** the struct is created,
    /// via [`SampleSettingsFile::calculate_checksum`]
    ///
    /// # Example
    /// ```rust
    /// use ot_tools_io::types::{SampleSettingsFile, SlotMarkers};
    /// use ot_tools_io::HasChecksumField;
    ///
    /// # use ot_tools_io::OtToolsIoError;
    /// # fn main() -> Result<(), OtToolsIoError> {
    /// let mut ss_f = SampleSettingsFile::new(
    ///     SlotMarkers::default(),
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    /// )?;
    ///
    /// let checksum = ss_f.calculate_checksum()?;
    /// ss_f.checksum = checksum;
    ///
    /// # Ok(()) }
    /// ```
    /// ## Validation
    ///
    /// Use the [`SampleSettingsFile::check_checksum`] method to check the validity of the current
    /// checksum value.
    pub checksum: u16,
}

impl SampleSettingsFile {
    /// Create a new `SampleSettingsFile`
    ///
    /// Values like `tempo` and `gain` need to be normalized to relevant Octatrack range bounds
    /// when using this method.
    ///
    /// # Trim Bar Length and Loop Bar Length
    ///
    /// If the `trim_bar_len` and `loop_bar_len` arguments are not provided then the corresponding
    /// field values are set to zero.
    ///
    /// When providing these values you should ensure that you have correctly calculated both of
    /// these values **AND** the tempo value.
    /// All three are used simultaneously by the Octatrack,
    /// and I haven't spent any time figuring out which one takes priority
    /// (I think it's BPM/tempo, but I cannot confirm yet).
    ///
    /// See the relevant documentation [here][SampleSettingsFile#trim-length-and-loop-length] for
    /// more information.
    /// ```rust
    /// use std::array::from_fn;
    /// use ot_tools_io::OtToolsIoError;
    /// use ot_tools_io::types::{Slices, SlotMarkers, SampleSettingsFile};
    /// use ot_tools_io::settings::{
    ///    TrigQuantizationMode,
    ///    LoopMode,
    ///    TimeStretchMode,
    /// };
    /// # fn main() -> Result<(), OtToolsIoError> {
    ///
    /// let marks = SlotMarkers {
    ///     trim_offset: 0,
    ///     trim_end: 100,
    ///     loop_point: 0,
    ///     slices: Slices::default(),
    ///     slice_count: 0,
    /// };
    /// let x = SampleSettingsFile::new(
    ///     marks,
    ///     Some(48),    // -24.0 <-> +24.0 (0 <-> 96)
    ///     Some(2880),  // bpm x 24 (720 <-> 7200)
    ///     None,        // trim_bar_len will be zero, see documentation explainer
    ///     None,        // loop_bar_len will be zero, see documentation explainer
    ///     Some(TimeStretchMode::default()),
    ///     Some(TrigQuantizationMode::default()),
    ///     Some(LoopMode::default()),
    /// )?;
    /// assert_eq!(x.trim_start, 0);
    /// assert_eq!(x.trim_end, 100);
    /// assert_eq!(x.loop_start, 0);
    /// assert_eq!(x.trim_bar_len, 0);
    /// assert_eq!(x.loop_bar_len, 0);
    /// assert_eq!(x.tempo, 2880);
    /// assert_eq!(x.gain, 48);
    /// assert_eq!(x.stretch, 2);  // converted to u32 repr
    /// assert_eq!(x.quantization, 255);  // converted to u32 repr
    /// assert_eq!(x.loop_mode, 0);  // converted to u32 repr
    /// # Ok(()) }
    /// ```
    /*
    can't help this much unless i start creating sub-types, and i'm not too keen on that
    just now considering what happened with TrimConfig and LoopConfig.

    however, with some upcoming changes to slots, it may be worth thinking about two extra sub-types

    for settings:
    ```
    struct SlotSettings {
        stretch: TimeStretchMode,
        quantization: TrigQuantizationMode,
        loop_mode: LoopMode,
    };
    ```

    for playback stretch control:
    (trim bar len, loop bar len and bpm affect the time stretch algorithm)
    ```
    struct SlotStretchControl {
        tempo: Option<u16>,
        trim_bar_len: Option<u32>,
        loop_bar_len: Option<u32>,
    };
    ```
    */
    #[allow(clippy::too_many_arguments)]
    pub fn new<M: AsRef<SlotMarkers>>(
        markers: M,
        gain: Option<u16>,
        tempo: Option<u32>,
        trim_bar_len: Option<u32>,
        loop_bar_len: Option<u32>,
        stretch: Option<TimeStretchMode>,
        quantization: Option<TrigQuantizationMode>,
        loop_mode: Option<LoopMode>,
    ) -> Result<Self, OtToolsIoError> {
        let marks = markers.as_ref();

        let mut new = Self {
            // markers values, required
            trim_start: marks.trim_offset,
            trim_end: marks.trim_end,
            loop_start: marks.loop_point,
            slices: marks.slices,
            slices_len: marks.slice_count,
            // constant values
            header: SAMPLES_HEADER,
            datatype_version: SAMPLES_FILE_VERSION,
            unknown: 0,
            // optional values
            gain: gain.unwrap_or(DEFAULT_GAIN as u16),
            tempo: tempo.unwrap_or(DEFAULT_TEMPO as u32),
            stretch: stretch.unwrap_or_default().into(),
            quantization: quantization.unwrap_or_default().into(),
            loop_mode: loop_mode.unwrap_or_default().into(),
            trim_bar_len: trim_bar_len.unwrap_or(0), // see docs for explanation of why this is zero
            loop_bar_len: loop_bar_len.unwrap_or(0), // see docs for explanation of why this is zero
            // not set here
            checksum: 0, // set below
        };

        new.checksum = new.calculate_checksum()?;

        new.validate()?;

        Ok(new)
    }

    /// Runs a series of validation checks on the field values for an instance of the type.
    ///
    /// Will return an appropriate error if a problem is discovered with a field's value.
    ///
    /// Read through the fields on [`SampleSettingsFile`] to find out which ones are checked and how
    /// they are checked.
    ///
    /// # Invalid Gain Example
    /// ```
    /// use ot_tools_io::OtToolsIoError;
    /// use ot_tools_io::types::{SampleSettingsFile, SlotMarkers};
    /// use ot_tools_io::errors::SampleSettingsError;
    /// # fn main() -> Result<(), OtToolsIoError> {
    ///
    /// let ss_f = SampleSettingsFile::new(
    ///     SlotMarkers::default(),
    ///     Some(100),
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    ///     None
    /// );
    ///
    /// assert_eq!(
    ///     ss_f.unwrap_err().to_string(),
    ///     OtToolsIoError::SampleSettings(
    ///         SampleSettingsError::GainOutOfBounds {value: 100}
    ///     ).to_string(),
    /// );
    /// # Ok(()) }
    /// ```
    ///
    /// # Invalid Tempo Example
    /// ```
    /// use ot_tools_io::OtToolsIoError;
    /// use ot_tools_io::types::{SampleSettingsFile, SlotMarkers};
    /// use ot_tools_io::errors::SampleSettingsError;
    /// # fn main() -> Result<(), OtToolsIoError> {
    ///
    /// let ss_f = SampleSettingsFile::new(
    ///     SlotMarkers::default(),
    ///     None,
    ///     Some(120),
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    ///     None
    /// );
    ///
    /// assert_eq!(
    ///     ss_f.unwrap_err().to_string(),
    ///     OtToolsIoError::SampleSettings(
    ///         SampleSettingsError::TempoOutOfBounds {value: 120}
    ///     ).to_string(),
    /// );
    ///
    /// # Ok(()) }
    /// ```
    pub fn validate(&self) -> Result<(), OtToolsIoError> {
        #[allow(clippy::manual_range_contains)]
        if self.tempo < 720 || self.tempo > 7200 {
            return Err(SampleSettingsError::TempoOutOfBounds { value: self.tempo }.into());
        }

        if self.gain > 96 {
            return Err(SampleSettingsError::GainOutOfBounds {
                value: self.gain as u32,
            }
            .into());
        }

        SlotMarkers::from(self).validate()?;

        LoopMode::try_from(self.loop_mode)?;
        TimeStretchMode::try_from(self.stretch)?;
        TrigQuantizationMode::try_from(self.quantization)?;

        if !self.check_checksum()? {
            return Err(SampleSettingsError::InvalidChecksum {
                checksum: self.checksum,
            }
            .into());
        };

        if !self.check_header()? {
            return Err(OtToolsIoError::FileHeader);
        };

        if !self.check_file_version()? {
            return Err(SampleSettingsError::InvalidFileVersion {
                version: self.datatype_version,
            }
            .into());
        };

        if !self.check_checksum()? {
            return Err(SampleSettingsError::InvalidChecksum {
                checksum: self.checksum,
            }
            .into());
        };

        Ok(())
    }

    /// Create a new [`SlotAttributes`] instance from this [`SampleSettingsFile`].
    ///
    /// Will validate the `slot_id` argument depending on the [`SlotType`] variant provided to the
    /// `slot_type` argument.
    ///
    /// # Valid Example
    /// ```
    /// # use ot_tools_io::OtToolsIoError;
    /// use ot_tools_io::types::{SlotMarkers, SampleSettingsFile, SlotAttributes, SlotType};
    /// # use ot_tools_io::settings::{TimeStretchMode, LoopMode, TrigQuantizationMode};
    /// use std::path::PathBuf;
    /// # fn main() -> Result<(), OtToolsIoError> {
    ///
    /// let ss_f = SampleSettingsFile::new(
    ///     SlotMarkers::default(),
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    /// )?;
    ///
    /// let attrs = ss_f.to_slot_attr(
    ///     SlotType::Static,
    ///     100,
    ///     Some(PathBuf::from("some/path"))
    /// )?;
    ///
    /// assert_eq!(
    ///     attrs,
    ///     SlotAttributes {
    ///         slot_id: 100,
    ///         slot_type: SlotType::Static,
    ///         path: Some(PathBuf::from("some/path")),
    ///         timestrech_mode: TimeStretchMode::default(),
    ///         loop_mode: LoopMode::default(),
    ///         trig_quantization_mode: TrigQuantizationMode::default(),
    ///         gain: 48,
    ///         bpm: 2880,
    ///     }
    /// );
    /// # Ok(()) }
    /// ```
    ///
    /// # Error Example
    /// ```
    /// use ot_tools_io::OtToolsIoError;
    /// use ot_tools_io::errors::SampleSettingsError;
    /// use ot_tools_io::types::{SlotMarkers, SampleSettingsFile, SlotAttributes, SlotType};
    /// use std::path::PathBuf;
    /// # fn main() -> Result<(), OtToolsIoError> {
    ///
    /// let ss_f = SampleSettingsFile::new(
    ///     SlotMarkers::default(),
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    ///     None,
    /// )?;
    ///
    /// let attrs_err = ss_f.to_slot_attr(
    ///     SlotType::Static,
    ///     200,  // bad slot id!
    ///     Some(PathBuf::from("some/path"))
    /// ).unwrap_err();
    ///
    /// assert_eq!(
    ///     attrs_err.to_string(),
    ///     OtToolsIoError::SampleSettings(
    ///         SampleSettingsError::SlotIdOutOfBounds { id: 200, slot_type: SlotType::Static }
    ///     ).to_string()
    /// );
    /// # Ok(()) }
    /// ```
    pub fn to_slot_attr(
        &self,
        slot_type: SlotType,
        slot_id: u8,
        slot_path: Option<PathBuf>,
    ) -> Result<SlotAttributes, OtToolsIoError> {
        // neither static nor flex slots cannot have id = 0
        if slot_id == 0 {
            return Err(SampleSettingsError::SlotIdOutOfBounds {
                id: slot_id,
                slot_type,
            }
            .into());
        }

        // static slots cannot have id > 128
        if slot_type == SlotType::Static && slot_id > 128 {
            return Err(SampleSettingsError::SlotIdOutOfBounds {
                id: slot_id,
                slot_type,
            }
            .into());
        }

        // flex slots cannot have id > 136
        if slot_type == SlotType::Flex && slot_id > 136 {
            return Err(SampleSettingsError::SlotIdOutOfBounds {
                id: slot_id,
                slot_type,
            }
            .into());
        }

        Ok(SlotAttributes {
            slot_type,
            slot_id,
            path: slot_path,
            timestrech_mode: TimeStretchMode::try_from(self.stretch)?,
            loop_mode: LoopMode::try_from(self.loop_mode)?,
            trig_quantization_mode: TrigQuantizationMode::try_from(self.quantization)?,
            gain: self.gain as u8,
            bpm: self.tempo as u16,
        })
    }

    /// Returns the `stretch` field as a variant of [`TimeStretchMode`].
    ///
    /// Essentially calls [`TimeStretchMode::try_from`]
    pub fn timestretch_mode_into_setting(&self) -> Result<TimeStretchMode, OtToolsIoError> {
        TimeStretchMode::try_from(self.stretch).map_err(OtToolsIoError::SettingValue)
    }

    /// Returns the `loop_mode` field as a variant of [`LoopMode`]
    ///
    /// Essentially calls [`LoopMode::try_from`]
    pub fn loop_mode_into_setting(&self) -> Result<LoopMode, OtToolsIoError> {
        LoopMode::try_from(self.loop_mode).map_err(OtToolsIoError::SettingValue)
    }

    /// Returns the `quantization` field as a variant of [`TrigQuantizationMode`]
    ///
    /// Essentially calls [`TrigQuantizationMode::try_from`]
    pub fn trig_quantization_into_setting(&self) -> Result<TrigQuantizationMode, OtToolsIoError> {
        TrigQuantizationMode::try_from(self.loop_mode).map_err(OtToolsIoError::SettingValue)
    }
}

#[cfg(test)]
mod new {
    use super::test_utils::create_mock_new_sample_settings;
    use super::SampleSettingsError;
    use crate::OtToolsIoError;

    #[test]
    fn invalid_oob_temp_high() -> Result<(), OtToolsIoError> {
        assert_eq!(
            create_mock_new_sample_settings(Some(7201), None)
                .unwrap_err()
                .to_string(),
            OtToolsIoError::SampleSettings(SampleSettingsError::TempoOutOfBounds { value: 7201 })
                .to_string()
        );
        Ok(())
    }

    #[test]
    fn invalid_oob_temp_low() -> Result<(), OtToolsIoError> {
        let s_f = create_mock_new_sample_settings(Some(29), None);
        assert_eq!(
            s_f.unwrap_err().to_string(),
            OtToolsIoError::SampleSettings(SampleSettingsError::TempoOutOfBounds { value: 29 })
                .to_string()
        );
        Ok(())
    }

    #[test]
    fn invalid_oob_gain() -> Result<(), OtToolsIoError> {
        assert_eq!(
            create_mock_new_sample_settings(None, Some(97))
                .unwrap_err()
                .to_string(),
            OtToolsIoError::SampleSettings(SampleSettingsError::GainOutOfBounds { value: 97 })
                .to_string()
        );
        Ok(())
    }
}

#[cfg(test)]
mod validate {
    use super::test_utils::create_mock_new_sample_settings;
    use super::SampleSettingsError;
    use crate::settings::InvalidValueError;
    use crate::traits::HasChecksumField;
    use crate::OtToolsIoError;

    #[test]
    fn ok() -> Result<(), OtToolsIoError> {
        let s_f = create_mock_new_sample_settings(None, None)?;
        assert!(s_f.validate().is_ok());
        Ok(())
    }

    // gain and tempo are tested above

    #[test]
    fn err_stretch() -> Result<(), OtToolsIoError> {
        let mut s_f = create_mock_new_sample_settings(None, None)?;
        s_f.stretch = 255;
        s_f.checksum = s_f.calculate_checksum()?;
        assert_eq!(
            s_f.validate().unwrap_err().to_string(),
            OtToolsIoError::SettingValue(InvalidValueError::TimeStretchMode).to_string()
        );
        Ok(())
    }

    #[test]
    fn err_loop() -> Result<(), OtToolsIoError> {
        let mut s_f = create_mock_new_sample_settings(None, None)?;
        s_f.loop_mode = 255;
        s_f.checksum = s_f.calculate_checksum()?;
        assert_eq!(
            s_f.validate().unwrap_err().to_string(),
            OtToolsIoError::SettingValue(InvalidValueError::LoopMode).to_string()
        );
        Ok(())
    }

    #[test]
    fn err_quant() -> Result<(), OtToolsIoError> {
        let mut s_f = create_mock_new_sample_settings(None, None)?;
        s_f.quantization = 250; // 255 is an actual value for quantization!
        s_f.checksum = s_f.calculate_checksum()?;
        assert_eq!(
            s_f.validate().unwrap_err().to_string(),
            OtToolsIoError::SettingValue(InvalidValueError::TrigQuantizationMode).to_string()
        );
        Ok(())
    }

    #[test]
    fn err_chksum() -> Result<(), OtToolsIoError> {
        let mut s_f = create_mock_new_sample_settings(None, None)?;
        s_f.checksum = 1;
        assert_eq!(
            s_f.validate().unwrap_err().to_string(),
            OtToolsIoError::SampleSettings(SampleSettingsError::InvalidChecksum {
                checksum: s_f.checksum
            })
            .to_string(),
        );
        Ok(())
    }

    #[test]
    fn err_header() -> Result<(), OtToolsIoError> {
        let mut s_f = create_mock_new_sample_settings(None, None)?;
        s_f.header[0] = 255;
        s_f.checksum = s_f.calculate_checksum()?;
        assert_eq!(
            s_f.validate().unwrap_err().to_string(),
            OtToolsIoError::FileHeader.to_string(),
        );
        Ok(())
    }

    #[test]
    fn err_file_version() -> Result<(), OtToolsIoError> {
        let mut s_f = create_mock_new_sample_settings(None, None)?;
        s_f.datatype_version = 255;
        s_f.checksum = s_f.calculate_checksum()?;
        assert_eq!(
            s_f.validate().unwrap_err().to_string(),
            OtToolsIoError::SampleSettings(SampleSettingsError::InvalidFileVersion {
                version: s_f.datatype_version
            })
            .to_string(),
        );
        Ok(())
    }
}

#[cfg(test)]
mod to_slot_attrs {
    use super::test_utils::create_mock_new_sample_settings;
    use crate::projects::SlotAttributes;
    use crate::samples::SampleSettingsError;
    use crate::settings::SlotType;
    use crate::OtToolsIoError;
    use std::path::PathBuf;

    #[test]
    fn basic_static() -> Result<(), OtToolsIoError> {
        let settings = create_mock_new_sample_settings(None, None)?;

        let attrs = settings.to_slot_attr(
            SlotType::Static,
            1,
            Some(PathBuf::from("../AUDIO/path.wav")),
        )?;

        assert_eq!(
            attrs,
            SlotAttributes {
                slot_type: SlotType::Static,
                slot_id: 1,
                path: Some(PathBuf::from("../AUDIO/path.wav")),
                timestrech_mode: Default::default(),
                loop_mode: Default::default(),
                trig_quantization_mode: Default::default(),
                gain: 48,
                bpm: 2880,
            },
        );
        Ok(())
    }

    #[test]
    fn invalid_static_slot_id_0() -> Result<(), OtToolsIoError> {
        let settings = create_mock_new_sample_settings(None, None)?;

        let attrs = settings.to_slot_attr(
            SlotType::Static,
            0,
            Some(PathBuf::from("../AUDIO/path.wav")),
        );

        assert_eq!(
            attrs.unwrap_err().to_string(),
            OtToolsIoError::SampleSettings(SampleSettingsError::SlotIdOutOfBounds {
                id: 0,
                slot_type: SlotType::Static
            })
            .to_string(),
        );
        Ok(())
    }

    #[test]
    fn invalid_static_slot_id_129() -> Result<(), OtToolsIoError> {
        let settings = create_mock_new_sample_settings(None, None)?;

        let attrs = settings.to_slot_attr(
            SlotType::Static,
            129,
            Some(PathBuf::from("../AUDIO/path.wav")),
        );

        assert_eq!(
            attrs.unwrap_err().to_string(),
            OtToolsIoError::SampleSettings(SampleSettingsError::SlotIdOutOfBounds {
                id: 129,
                slot_type: SlotType::Static
            })
            .to_string(),
        );
        Ok(())
    }

    #[test]
    fn basic_flex() -> Result<(), OtToolsIoError> {
        let settings = create_mock_new_sample_settings(None, None)?;

        let attrs =
            settings.to_slot_attr(SlotType::Flex, 1, Some(PathBuf::from("../AUDIO/path.wav")))?;

        assert_eq!(
            attrs,
            SlotAttributes {
                slot_type: SlotType::Flex,
                slot_id: 1,
                path: Some(PathBuf::from("../AUDIO/path.wav")),
                timestrech_mode: Default::default(),
                loop_mode: Default::default(),
                trig_quantization_mode: Default::default(),
                gain: 48,
                bpm: 2880,
            },
        );
        Ok(())
    }

    #[test]
    fn invalid_flex_slot_id_0() -> Result<(), OtToolsIoError> {
        let settings = create_mock_new_sample_settings(None, None)?;

        let attrs =
            settings.to_slot_attr(SlotType::Flex, 0, Some(PathBuf::from("../AUDIO/path.wav")));

        assert_eq!(
            attrs.unwrap_err().to_string(),
            OtToolsIoError::SampleSettings(SampleSettingsError::SlotIdOutOfBounds {
                id: 0,
                slot_type: SlotType::Flex
            })
            .to_string(),
        );
        Ok(())
    }

    #[test]
    fn invalid_flex_slot_id_137() -> Result<(), OtToolsIoError> {
        let settings = create_mock_new_sample_settings(None, None)?;

        let attrs = settings.to_slot_attr(
            SlotType::Flex,
            137,
            Some(PathBuf::from("../AUDIO/path.wav")),
        );

        assert_eq!(
            attrs.unwrap_err().to_string(),
            OtToolsIoError::SampleSettings(SampleSettingsError::SlotIdOutOfBounds {
                id: 137,
                slot_type: SlotType::Flex
            })
            .to_string(),
        );
        Ok(())
    }
}

impl SwapBytes for SampleSettingsFile {
    fn swap_bytes(self) -> Self {
        let mut bswapped_slices = self.slices;

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

        Self {
            header: SAMPLES_HEADER,
            datatype_version: SAMPLES_FILE_VERSION,
            unknown: self.unknown,
            tempo: self.tempo.swap_bytes(),
            trim_bar_len: self.trim_bar_len.swap_bytes(),
            loop_bar_len: self.loop_bar_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(),
        }
    }
}

impl OctatrackFileIO for SampleSettingsFile {
    /// Encodes struct data to binary representation, after some pre-processing.
    ///
    /// Before serializing, will:
    /// 1. generate checksum value
    /// 2. swap bytes of values (when current system is little-endian)
    fn to_bytes(&self) -> Result<Vec<u8>, OtToolsIoError> {
        // todo: figure out a non-clone version of this
        #[allow(clippy::clone_on_copy)]
        let mut chkd = self.clone();
        chkd.checksum = self.calculate_checksum()?;

        let encoded = if cfg!(target_endian = "little") {
            bincode::serialize(&chkd.swap_bytes())?
        } else {
            bincode::serialize(&chkd)?
        };
        Ok(encoded)
    }

    /// Decode raw bytes of a `.ot` data file into a new struct,
    /// swapping byte values if system is little-endian.
    fn from_bytes(bytes: &[u8]) -> Result<Self, OtToolsIoError> {
        let decoded: Self = bincode::deserialize(bytes)?;

        // todo: figure out a non-clone version of this
        #[allow(clippy::clone_on_copy)]
        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)
    }
}

#[cfg(test)]
mod from_bytes {
    use crate::read_bin_file;
    use crate::samples::test_utils::mock_0_slice_test_file;
    use crate::test_utils::get_samples_dirpath;
    use crate::{OctatrackFileIO, OtToolsIoError, SampleSettingsFile};
    #[test]
    fn valid() -> Result<(), OtToolsIoError> {
        let path = get_samples_dirpath().join("checksum").join("0slices.ot");
        let bytes = read_bin_file(&path)?;
        let s = SampleSettingsFile::from_bytes(&bytes)?;
        assert_eq!(s, mock_0_slice_test_file());
        Ok(())
    }
}

#[cfg(test)]
mod to_bytes {
    use crate::read_bin_file;
    use crate::samples::test_utils::mock_0_slice_test_file;
    use crate::test_utils::get_samples_dirpath;
    use crate::{OctatrackFileIO, OtToolsIoError};
    #[test]
    fn valid() -> Result<(), OtToolsIoError> {
        let path = get_samples_dirpath().join("checksum").join("0slices.ot");
        let bytes = read_bin_file(&path)?;
        let b = mock_0_slice_test_file().to_bytes()?;
        assert_eq!(b, bytes);
        Ok(())
    }
}

impl HasChecksumField for SampleSettingsFile {
    // tests for this are in the main tests directory -- `samples_settings_files.rs`
    fn calculate_checksum(&self) -> Result<u16, OtToolsIoError> {
        let bytes = bincode::serialize(&self)?;

        // 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)
    }

    fn update_checksum(&mut self) -> Result<(), OtToolsIoError> {
        self.checksum = self.calculate_checksum()?;
        Ok(())
    }

    fn check_checksum(&self) -> Result<bool, OtToolsIoError> {
        Ok(self.checksum == self.calculate_checksum()?)
    }
}

#[cfg(test)]
mod checksum_field {
    use super::test_utils::create_mock_new_sample_settings;
    use crate::{HasChecksumField, OtToolsIoError};
    #[test]
    fn valid() -> Result<(), OtToolsIoError> {
        let mut x = create_mock_new_sample_settings(None, None)?;
        x.checksum = x.calculate_checksum()?;
        assert!(x.check_checksum()?);
        Ok(())
    }

    #[test]
    fn invalid() -> Result<(), OtToolsIoError> {
        let mut x = create_mock_new_sample_settings(None, None)?;
        x.checksum = x.calculate_checksum()?;
        x.checksum = 0;
        assert!(!x.check_checksum()?);
        Ok(())
    }

    mod files {
        use crate::test_utils::get_samples_dirpath;
        use crate::{HasChecksumField, OctatrackFileIO, OtToolsIoError, SampleSettingsFile};

        fn helper(test_name: String) -> Result<(u16, u16), OtToolsIoError> {
            let mut src_path = get_samples_dirpath().join("checksum").join(&test_name);
            src_path.set_extension("ot");

            let valid = SampleSettingsFile::from_data_file(&src_path)?;

            #[allow(clippy::clone_on_copy)] // want a full deep copy / clone
            let mut x = valid.clone();
            x.checksum = 0;

            Ok((x.calculate_checksum()?, valid.checksum))
        }

        #[test]
        fn zero_slices_trig_quant_one_step() -> Result<(), OtToolsIoError> {
            let (test, valid) = helper("0slices-tq1step".to_string())?;
            assert_eq!(test, valid);
            Ok(())
        }

        #[test]
        fn zero_slices() -> Result<(), OtToolsIoError> {
            let (test, valid) = helper("0slices".to_string())?;
            assert_eq!(test, valid);
            Ok(())
        }

        #[test]
        fn one_slice() -> Result<(), OtToolsIoError> {
            let (test, valid) = helper("1slices".to_string())?;
            assert_eq!(test, valid);
            Ok(())
        }

        #[test]
        fn two_slices() -> Result<(), OtToolsIoError> {
            let (test, valid) = helper("2slices".to_string())?;
            assert_eq!(test, valid);
            Ok(())
        }

        #[test]
        fn four_slices() -> Result<(), OtToolsIoError> {
            let (test, valid) = helper("4slices".to_string())?;
            assert_eq!(test, valid);
            Ok(())
        }

        #[test]
        fn eight_slices() -> Result<(), OtToolsIoError> {
            let (test, valid) = helper("8slices".to_string())?;
            assert_eq!(test, valid);
            Ok(())
        }

        #[test]
        fn sixteen_slices() -> Result<(), OtToolsIoError> {
            let (test, valid) = helper("16slices".to_string())?;
            assert_eq!(test, valid);
            Ok(())
        }

        #[test]
        fn thirty_two_slices() -> Result<(), OtToolsIoError> {
            let (test, valid) = helper("32slices".to_string())?;
            assert_eq!(test, valid);
            Ok(())
        }

        #[test]
        fn forty_eight_slices() -> Result<(), OtToolsIoError> {
            let (test, valid) = helper("48slices".to_string())?;
            assert_eq!(test, valid);
            Ok(())
        }

        #[test]
        fn sixty_two_slices() -> Result<(), OtToolsIoError> {
            let (test, valid) = helper("62slices".to_string())?;
            assert_eq!(test, valid);
            Ok(())
        }

        #[test]
        fn sixty_three_slices() -> Result<(), OtToolsIoError> {
            let (test, valid) = helper("63slices".to_string())?;
            assert_eq!(test, valid);
            Ok(())
        }

        #[test]
        fn sixty_four_slices_correct() -> Result<(), OtToolsIoError> {
            let (test, valid) = helper("64slices".to_string())?;
            assert_eq!(test, valid);
            Ok(())
        }
    }
}

impl HasHeaderField for SampleSettingsFile {
    fn check_header(&self) -> Result<bool, OtToolsIoError> {
        Ok(self.header == SAMPLES_HEADER)
    }
}

#[cfg(test)]
mod header_field {
    use super::test_utils::create_mock_new_sample_settings;
    use crate::{HasHeaderField, OtToolsIoError};
    #[test]
    fn valid() -> Result<(), OtToolsIoError> {
        assert!(create_mock_new_sample_settings(None, None)?.check_header()?);
        Ok(())
    }

    #[test]
    fn invalid() -> Result<(), OtToolsIoError> {
        let mut mutated = create_mock_new_sample_settings(None, None)?;
        mutated.header[0] = 0x00;
        mutated.header[20] = 111;
        assert!(!mutated.check_header()?);
        Ok(())
    }
}

impl HasFileVersionField for SampleSettingsFile {
    fn check_file_version(&self) -> Result<bool, OtToolsIoError> {
        Ok(self.datatype_version == SAMPLES_FILE_VERSION)
    }
}

#[cfg(test)]
mod file_version_field {
    use super::test_utils::create_mock_new_sample_settings;
    use crate::{HasFileVersionField, OtToolsIoError};
    #[test]
    fn valid() -> Result<(), OtToolsIoError> {
        assert!(create_mock_new_sample_settings(None, None)?.check_file_version()?);
        Ok(())
    }

    #[test]
    fn invalid() -> Result<(), OtToolsIoError> {
        let mut mutated = create_mock_new_sample_settings(None, None)?;
        mutated.datatype_version = 0;
        assert!(!mutated.check_file_version()?);
        Ok(())
    }
}

impl<A, M> From<(A, M)> for SampleSettingsFile
where
    A: AsRef<SlotAttributes>,
    M: AsRef<SlotMarkers>,
{
    fn from(value: (A, M)) -> Self {
        let attrs = value.0.as_ref();
        let markers = value.1.as_ref();

        SampleSettingsFile {
            header: SAMPLES_HEADER,
            datatype_version: SAMPLES_FILE_VERSION,
            unknown: 0,
            tempo: attrs.bpm as u32,
            // todo: does not currently exist as a field in `SlotAttributes`
            trim_bar_len: 0,
            // todo: does not currently exist as a field in `SlotAttributes`
            loop_bar_len: 0,
            stretch: attrs.timestrech_mode.into(),
            loop_mode: attrs.loop_mode.into(),
            gain: attrs.gain as u16,
            quantization: attrs.trig_quantization_mode.into(),
            trim_start: markers.trim_offset,
            trim_end: markers.trim_end,
            loop_start: markers.loop_point,
            slices: markers.slices,
            slices_len: markers.slice_count,
            checksum: 0,
        }
    }
}

#[cfg(test)]
mod sample_settings_from {
    use crate::generics::Slots;
    use crate::projects::SlotAttributes;
    use crate::MarkersFile;
    use crate::OtToolsIoError;
    use crate::SampleSettingsFile;

    #[test]
    fn from_owned_valid() -> Result<(), OtToolsIoError> {
        let slots = Slots::<Option<SlotAttributes>>::default();
        let slot = slots.recording_buffers[0].clone();
        let markers = MarkersFile::default().flex_slots[0];
        let _ = SampleSettingsFile::from((slot.unwrap(), markers));
        Ok(())
    }

    #[test]
    fn from_borrowed_valid() -> Result<(), OtToolsIoError> {
        let slots = Slots::<Option<SlotAttributes>>::default();
        let slot = slots.recording_buffers[0].clone();
        let markers = MarkersFile::default().flex_slots[0];
        let _ = SampleSettingsFile::from((&slot.unwrap(), &markers));
        Ok(())
    }
}