Struct SampleSettingsFile 

pub struct SampleSettingsFile {

    pub header: [u8; 21],
    pub datatype_version: u8,
    pub unknown: u8,
    pub tempo: u32,
    pub trim_bar_len: u32,
    pub loop_bar_len: u32,
    pub stretch: u32,
    pub loop_mode: u32,
    pub gain: u16,
    pub quantization: u8,
    pub trim_start: u32,
    pub trim_end: u32,
    pub loop_start: u32,
    pub slices: Slices<Slice>,
    pub slices_len: u32,
    pub checksum: u16,
}

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

SampleSettingsFiles 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 SampleSettingsFiles 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.

Fields

header: [u8; 21]

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.

datatype_version: u8

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.

unknown: u8

Unknown data – can sometimes be 1, usually 0.

tempo: u32

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.

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:

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.

loop_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.

stretch: 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.

loop_mode: 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.

gain: u16

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.

quantization: u8

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.

trim_start: u32

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

trim_end: 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

loop_start: 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.

slices: Slices<Slice>

64 length array containing Slices. 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

slices_len: u32

Number of usable Slices in this sample. Used by the Octatrack to ignore zero-valued Slices in the slices array when loading the sample.

checksum: u16

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

use ot_tools_io::types::{SampleSettingsFile, SlotMarkers};
use ot_tools_io::HasChecksumField;

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;

Validation

Use the SampleSettingsFile::check_checksum method to check the validity of the current checksum value.

Implementations

impl SampleSettingsFile

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>

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 for more information.

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,
};

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

Examples found in repository

examples/create_sample_settings_file.rs (line 25)

fn main() -> Result<(), OtToolsIoError> {
    let outpath = std::env::temp_dir()
        .join("ot-tools-io")
        .join("examples")
        .join("create_sample_settings_file");

    let marks = SlotMarkers {
        trim_offset: 0,
        trim_end: 50000,
        loop_point: 0,
        slices: Slices::<Slice>::default(),
        slice_count: 0,
    };

    let ss_f = SampleSettingsFile::new(marks, None, None, None, None, None, None, None)?;

    create_dir_all(&outpath)?;
    ss_f.to_data_file(&outpath.join("sample.ot"))?;

    println!("created new settings file at: {outpath:?}");

    Ok(())
}

pub fn validate(&self) -> Result<(), OtToolsIoError>

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;

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(),
);

Invalid Tempo Example

use ot_tools_io::OtToolsIoError;
use ot_tools_io::types::{SampleSettingsFile, SlotMarkers};
use ot_tools_io::errors::SampleSettingsError;

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(),
);

pub fn to_slot_attr( &self, slot_type: SlotType, slot_id: u8, slot_path: Option<PathBuf>, ) -> Result<SlotAttributes, OtToolsIoError>

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::types::{SlotMarkers, SampleSettingsFile, SlotAttributes, SlotType};
use std::path::PathBuf;

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,
    }
);

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;

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()
);

pub fn timestretch_mode_into_setting( &self, ) -> Result<TimeStretchMode, OtToolsIoError>

Returns the stretch field as a variant of TimeStretchMode.

Essentially calls TimeStretchMode::try_from

pub fn loop_mode_into_setting(&self) -> Result<LoopMode, OtToolsIoError>

Returns the loop_mode field as a variant of LoopMode

Essentially calls LoopMode::try_from

pub fn trig_quantization_into_setting( &self, ) -> Result<TrigQuantizationMode, OtToolsIoError>

Returns the quantization field as a variant of TrigQuantizationMode

Essentially calls TrigQuantizationMode::try_from

Trait Implementations

impl AsMut<SampleSettingsFile> for SampleSettingsFile

fn as_mut(&mut self) -> &mut SampleSettingsFile

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<SampleSettingsFile> for SampleSettingsFile

fn as_ref(&self) -> &SampleSettingsFile

Converts this type into a shared reference of the (usually inferred) input type.

impl CheckFileIntegrity for SampleSettingsFile

fn check_integrity(&self) -> Result<bool, OtToolsIoError>

impl Clone for SampleSettingsFile

fn clone(&self) -> SampleSettingsFile

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for SampleSettingsFile

impl Debug for SampleSettingsFile

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SampleSettingsFile

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for SampleSettingsFile

impl<A, M> From<(A, M)> for SampleSettingsFile

where A: AsRef<SlotAttributes>, M: AsRef<SlotMarkers>,

fn from(value: (A, M)) -> Self

Converts to this type from the input type.

impl<A, M> From<ActiveSlot<A, M>> for SampleSettingsFile

where A: AsRef<SlotAttributes>, M: AsRef<SlotMarkers>,

fn from(value: ActiveSlot<A, M>) -> Self

Converts to this type from the input type.

impl HasChecksumField for SampleSettingsFile

fn calculate_checksum(&self) -> Result<u16, OtToolsIoError>

Method for calculating the checksum value for types that have a checksum field

fn update_checksum(&mut self) -> Result<(), OtToolsIoError>

Method for updating the checksum value for types that have a checksum field

fn check_checksum(&self) -> Result<bool, OtToolsIoError>

Method to verify if checksum is valid in some data type. See this thread.

impl HasFileVersionField for SampleSettingsFile

fn check_file_version(&self) -> Result<bool, OtToolsIoError>

Method to verify if the data file version field is valid for the given type.

impl HasHeaderField for SampleSettingsFile

fn check_header(&self) -> Result<bool, OtToolsIoError>

Method to verify if header(s) are valid in some data. See this thread.

impl Hash for SampleSettingsFile

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl OctatrackFileIO for SampleSettingsFile

fn to_bytes(&self) -> Result<Vec<u8>, OtToolsIoError>

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 from_bytes(bytes: &[u8]) -> Result<Self, OtToolsIoError>

Decode raw bytes of a .ot data file into a new struct, swapping byte values if system is little-endian.

fn repr(&self, newlines: Option<bool>)

where Self: Debug,

Read type from an Octatrack data file at path

fn from_data_file(path: &Path) -> Result<Self, OtToolsIoError>

Read type from an Octatrack data file at path

fn to_data_file(&self, path: &Path) -> Result<(), OtToolsIoError>

Write type to an Octatrack data file at path

fn from_yaml_file(path: &Path) -> Result<Self, OtToolsIoError>

Read type from a YAML file at path

fn from_yaml_str(yaml: &str) -> Result<Self, OtToolsIoError>

Read type from YAML string

fn to_yaml_file(&self, path: &Path) -> Result<(), OtToolsIoError>

Write type to a YAML file at path

fn to_yaml_string(&self) -> Result<String, OtToolsIoError>

Create YAML string from type

fn from_json_file(path: &Path) -> Result<Self, OtToolsIoError>

Read type from a JSON file at path

fn from_json_str(json: &str) -> Result<Self, OtToolsIoError>

Create type from JSON string

fn to_json_file(&self, path: &Path) -> Result<(), OtToolsIoError>

Write type to a JSON file at path

fn to_json_string(&self) -> Result<String, OtToolsIoError>

Create JSON string from type

impl Ord for SampleSettingsFile

fn cmp(&self, other: &SampleSettingsFile) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for SampleSettingsFile

fn eq(&self, other: &SampleSettingsFile) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for SampleSettingsFile

fn partial_cmp(&self, other: &SampleSettingsFile) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for SampleSettingsFile

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for SampleSettingsFile

impl<A, M> TryFrom<Option<ActiveSlot<A, M>>> for SampleSettingsFile

where A: AsRef<SlotAttributes>, M: AsRef<SlotMarkers>,

type Error = OtToolsIoError

The type returned in the event of a conversion error.

fn try_from(value: Option<ActiveSlot<A, M>>) -> Result<Self, Self::Error>

Performs the conversion.