Crate ot_tools_io 

Library crate for reading/writing data files for the Elektron Octatrack.

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

Brief Overview

Important types and traits are re-exported or defined in the root of the crate’s namespace for your convenience – everything you need to read and write Octatrack data files should be available with use ot_tools_io::*. Less commonly used types and traits are public within their specific modules and will require importing.

// basic / common imports
use ot_tools_io::{SampleSettingsFile, OctatrackFileIO, HasHeaderField};

// lower level / less common imports
use ot_tools_io::samples::{SAMPLES_HEADER, SAMPLES_FILE_VERSION, DEFAULT_GAIN, DEFAULT_TEMPO};
use ot_tools_io::slices::{Slice, Slices, SLICE_LOOP_POINT_DISABLED};
use ot_tools_io::parts::{Part, AudioTrackMachineParamsSetupPickup};

The OctatrackFileIO Trait

You’ll usually want to import the OctatrackFileIO trait if you’re reading or writing files. It adds the associated functions & methods for file I/O, including for file I/O for YAML and JSON files.

// write a sample settings file to yaml and json

use std::path::PathBuf;
use ot_tools_io::{SampleSettingsFile, OctatrackFileIO, HasHeaderField};

let path = PathBuf::from("test-data")
    .join("samples")
    .join("sample.ot");

let otfile = SampleSettingsFile::from_data_file(&path).unwrap();

let outdir = std::env::temp_dir()
    .join("ot-tools-io")
    .join("doctest")
    .join("write_yaml_and_json");

&otfile.to_yaml_file(&outdir.join("sample.yaml")).unwrap();
&otfile.to_json_file(&outdir.join("sample.json")).unwrap();

The HasSomeField Traits

The Has*Field traits add methods to a type to perform integrity checks: checksum calculation and validation, header validation and file patch version validation.

// check the header of sample settings file

use std::path::PathBuf;
use ot_tools_io::{SampleSettingsFile, OctatrackFileIO, HasHeaderField};

let path = PathBuf::from("test-data")
    .join("samples")
    .join("sample.ot");

let otfile = SampleSettingsFile::from_data_file(&path).unwrap();
assert!(otfile.check_header().unwrap())

The OtToolsIoError Type

The OtToolsIoError type should be used to catch any errors in normal use as it implements From for all other internal errors

// handling errors

use ot_tools_io::OtToolsIoError;
use ot_tools_io::settings::MidiChannel;

// always errors
fn try_from_err() -> Result<MidiChannel, OtToolsIoError> {
    Ok(MidiChannel::try_from(100_i8)?)
}

assert!(try_from_err().is_err());
assert_eq!(
    try_from_err().unwrap_err().to_string(),
    "invalid setting value: Invalid MIDI Channel value".to_string(),
);

SomeFile Types

Types directly related to some file used by the Octatrack are named as SomeFile, where Some is the relevant file base name (*.ot files obviously don’t have a basename we can use).

Only these *File types can be read from / written to the filesystem using this crate’s OctatrackFileIO trait methods / functions.

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.

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

Additional Details

Octatrack File Relationships

• 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, slices, loop points).

• Slot 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.

• 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). These references point to the relevant slot in both the MarkersFile and ProjectFile for a project.

• 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).

Octatrack Device File Modifications

• *.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

Sample Slot IDs

Project Sample Slots store their slots with a one-indexed slot_id field.

All other references to sample slots are zero-indexed (i.e. BankFile and MarkersFile files).

I’m using lots of italics and bold formatting here because it is super annoying but there’s not much i can do about it. Remember you will need to convert from one to zero indexed whenever you deal with Sample Slots.

Default Loop Point Values Differ Between Types

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.

Slava Ukraini

I’ve worked with Ukrainian developers. What is happening to their country is abhorrent.

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.

errors

Re-exports of all custom error types in the library. You shouldn’t need these unless you’re operating with lower level functions / methods / types (the crate::OtToolsIoError type implements From for all these types).

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.

settings

Settings enums. Mostly related to crate::SampleSettingsFile, crate::projects::SlotAttributes and crate::MarkersFile types.

slices

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

Enums

OtToolsIoError

Global error variant handling. All internally used error types and variants can cast to this type.

Traits

CheckFileIntegrity

Adds a single method using the HasHeaderField::check_header, HasChecksumField::check_checksum and HasFileVersionField::check_file_version methods to run a full integrity check.

Defaults

Create a ‘default’ container type T with N instances of Self. Used when we need a collection of default type instances e.g. when creating a default bank we need 16 default patterns.

HasChecksumField

A type has a checksum field which needs implementations to handle calculation and validation

HasFileVersionField

A type has a file patch version field which needs implementations to handle validation

HasHeaderField

A type has a header field which needs implementations to handle validation

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.