Crate ot_tools_io

Expand description

Serialization and Deserialization library for Elektron Octatrack data files.

§Important types

rust type	octatrack 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.

Only the above types implement the OctatrackFileIO super trait, meaning only these types can be read from / written to the filesystem using the functions in this library.

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

§How do different Octatrack data files relate to each other?

Arrangements store a u8 which references a Bank’s Pattern, indicating it should play for that Arrange row. Zero indexed, where 0 (A01) -> 256 (P16).
A Bank stores zero-indexed sample slot IDs to indicate which sample should be played when on a given track (part machine data and/or track p-lock trigs).
Changing the sample loaded into a sample slot updates both the project.* file (change the trig quantization settings, file path etc) and the markers.* file (change the trim settings based on either initial load, or any data in a relevant *.ot sample settings file).
Data from project.*and markers.* is written to an *.ot file when saving sample attributes data from the Octatrack’s audio editing menu.
Loading a sample into a project sample slot (project.* and markers.* files) reads any data in an *.ot 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 (project.* files) are one-indexed, but their references everywhere else are zero-indexed (bank??.* and markers.* files).
A ‘Disabled’ loop point in either markers.* or *.ot files is a 0xFFFFFFFF value, but the default loop point when creating new markers.* file is always 0_u32. The ‘Disabled’ value setting is only set when a sample is loaded into a sample slot, and an .ot file 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 Manaul section 13.2.4 ATTRIBUTES
OtToolsIoErrors: Global error variants
TimestrechMode: Sample Timestrech options. See Octatrack Manaul section 13.2.4 ATTRIBUTES
TrigQuantizationMode: Sample attributes Trig Quantization options (quantization when manually triggering samples via track buttons). See Octatrack Manaul 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 serde_big_array::Array container type
Encode: Adds serialisation 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.

Crate ot_tools_ioCopy item path