Crate ot_tools_io 

Library crate for creating, reading, and updating data files for the Elektron Octatrack.

Important types

Only the following types implement the OctatrackFileIO trait, meaning only these types can be read from / written to the filesystem using this create.

Read the relevant modules in this library for more detailed information on the data contained in each file.

Type	Filename Pattern	Description
ArrangementFile	arr??.*	data for arrangements
BankFile	bank??.*	data for parts and patterns
MarkersFile	markers.*	start trim/end trim/slices/loop points for sample slots
ProjectFile	project.*	project level settings; state; sample slots
SampleSettingsFile	*.ot	saved sample settings data, loops slices etc.

How do different Octatrack data files relate to each other?

• ArrangementFiles store a u8 which references a BankFile’s Pattern, indicating the Pattern should be played when the specific row in an arrangement is triggered. The field is zero-indexed, with the full range used for Pattern references 0 (A01) -> 256 (P16).
• A BankFile’s Patterns and Parts store zero-indexed sample slot IDs as flex and static slot references (machine data in a Part and track p-lock trigs in a Pattern).
• Changing the sample loaded into a sample slot updates both the ProjectFile file (trig quantization settings, file path etc) and the MarkersFile file (trim settings, or any data in a relevant SampleSettingsFile sample settings file).
• Data from ProjectFiles and MarkersFiles is written to an SampleSettingsFile file when saving sample attributes data from the Octatrack’s audio editing menu.
• Loading a sample into a project sample slot (ProjectFiles and MarkersFiles) reads any data in an SampleSettingsFile files and configures the sample slot accordingly.

When do *.work and *.strd files get modified by the Octatrack?

• *.work files are created when creating a new project PROJECT MENU -> CHANGE PROJECT -> CREATE NEW.
• *.work files are updated by using the PROJECT MENU -> SYNC TO CARD operation.
• *.work files are updated when the user performs a PROJECT MENU -> SAVE PROJECT operation.
• *.strd files are created/updated when the user performs a PROJECT MENU -> SAVE PROJECT operation.
• *.strd files are not changed by the PROJECT -> SYNC TO CARD operation.
• arr??.strd files can also be saved via the ARRANGER MENU -> SAVE ARRANGEMENT operation.

Notable ’gotcha’s

• Project sample slots (ProjectFile files) are one-indexed, but their references everywhere else are zero-indexed (BankFile and MarkersFile files).
• A ‘Disabled’ loop point in either a MarkersFile or a SampleSettingsFile is a 0xFFFFFFFF value, but the default loop point when creating new MarkersFile is always 0_u32. The ‘Disabled’ value setting is only set when a sample is loaded into a sample slot, and a SampleSettingsFile is generated from that sample slot data.

Example code

/*
reading, mutating and writing a bank file
*/

use std::path::PathBuf;
use ot_tools_io::{OctatrackFileIO, BankFile};

let path = PathBuf::from("test-data")
    .join("blank-project")
    .join("bank01.work");

// read an editable version of the bank file
let mut bank = BankFile::from_data_file(&path).unwrap();

// change active scenes on the working copy of Part 4
bank.parts.unsaved[3].active_scenes.scene_a = 2;
bank.parts.unsaved[3].active_scenes.scene_b = 6;

// write to a new bank file
let outfpath = std::env::temp_dir()
    .join("ot-tools-io")
    .join("doctest")
    .join("main_example_1");


&bank.to_data_file(&outfpath).unwrap();

Re-exports

pub use crate::arrangements::ArrangementFile;

pub use crate::banks::BankFile;

pub use crate::markers::MarkersFile;

pub use crate::projects::ProjectFile;

pub use crate::samples::SampleSettingsFile;

Modules

arrangements

Types and ser/de for arr??.* binary data files.

banks

Types for bank??.* binary data files.

markers

Types and ser/de of markers.* binary data files.

parts

Model for part data within a bank.

patterns

Models for pattern data within a bank.

projects

Types and ser/de of project.* data files.

samples

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

slices

Slice data structs for sample files (.ot files).

Enums

LoopMode

Sample attributes Loop mode options. See Octatrack Manual section 13.2.4 ATTRIBUTES

OtToolsIoErrors

Global error variants

TimeStretchMode

Sample Time Stretch options. See Octatrack Manual section 13.2.4 ATTRIBUTES

TrigQuantizationMode

Sample attributes Trig Quantization options (quantization when manually triggering samples via track buttons). See Octatrack Manual section 13.2.4 ATTRIBUTES

Traits

CalculateChecksum

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

CheckChecksum

Adds a method to verify if checksum is valid in some data type. See this thread.

CheckFileVersion

Adds a method to verify if the data file version field is valid for the given type.

CheckHeader

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

CheckIntegrity

Adds a single method using the CheckHeader::check_header, CheckChecksum::check_checksum and CheckFileVersion::check_file_version methods to run a full integrity check.

Decode

Adds deserialisation via bincode and serde to a type. Must be present on all major file types.

DefaultsArray

Used when we need a collection of default type instances e.g. when creating a default bank we need 16 default patterns.

DefaultsArrayBoxed

Same as DefaultsArray, but using a boxed Array container type

Encode

Adds serialization via bincode and serde to a type. Must be present on all major file types.

IsDefault

Adds a method to check the current data structure matches the default for the type

OctatrackFileIO

Convenience trait for types which directly correspond to Elektron Octatrack binary data files. Associated functions and methods etc. for File I/O, plus a repr method for debugging.

OptionEnumValueConvert

Trait to convert between Enum option instances and their corresponding value.

SwapBytes

Trait for adding a method which swaps the bytes on all fields of a struct.