Crate ot_tools_io

Expand description

Serialization and Deserialization library for Elektron Octatrack data files.

§Important types

rust type	octatrack filename pattern	description
crate::arrangements::ArrangementFile	`arr??.*`	data for arrangements
crate::banks::BankFile	`bank??.*`	data for parts and patterns
crate::markers::MarkersFile	`markers.*`	start trim/end trim/slices/loop points for sample slots
crate::projects::ProjectFile	`project.*`	project level settings; state; sample slots
crate::samples::SampleAttributes	`*.ot`	saved sample settings data, loops slices etc.

Only the above types implement the crate::Encode and crate::Decode traits, which means only these types can be read from / written to the filesystem using 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?

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.

§Example code

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

use std::path::PathBuf;
use ot_tools_io::{read_type_from_bin_file, write_type_to_bin_file, banks::BankFile};

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

// read an editable version of the bank file
let mut bank: BankFile = read_type_from_bin_file(&binfpath).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");
write_type_to_bin_file::<BankFile>(&bank, &outfpath).unwrap();

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.
projects: Types and ser/de of project.* data files.
samples: Types and ser/de of *.ot binary data files.

Enums§

OtToolsIoErrors: Global error variants

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 to understand why this is useful: https://www.elektronauts.com/t/bank-unavailable-octatrack/190647/27
CheckHeader: Adds a method to verify if header(s) are valid in some data. See this thread to understand why this is useful: https://www.elektronauts.com/t/bank-unavailable-octatrack/190647/27
CheckIntegrity: Adds a single method using the crate::CheckHeader and crate::CheckChecksum 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

Functions§

bin_file_to_json_file: Read data of type <T> from a binary data file and write it to a JSON file
bin_file_to_yaml_file: Read data of type <T> from a binary data file and write it to a YAML file
default_type_to_bin_file: Create a new type with default settings, and write the data to a file.
deserialize_bin_to_type: Deserialize a bytes to a data structure of type T
deserialize_json_to_type: Deserialize a JSON string to a data structure of type T
deserialize_yaml_to_type: Deserialize a YAML string to a data structure of type T
json_file_to_bin_file: Read a JSON file then write the data to a new <T> type file
json_file_to_type: Read a JSON file into a data structure of type <T>
read_bin_file: Read bytes from a file at path.
read_str_file: Read a file at path as a string.
read_type_from_bin_file: Read a data structure of type <T> from a binary data file.
serialize_bin_from_type: Serialize to bytes from a data structure of type T
serialize_json_from_type: Serialize a JSON string from a data structure of type T
serialize_yaml_from_type: Serialize a YAML string from a data structure of type T
show_type: Show deserialized representation of a binary data file of type T at path
type_to_json_file: Write a data structure of type <T> into a JSON file
type_to_yaml_file: Write a data structure of type <T> into a YAML file
write_bin_file: Write bytes to a file at path.
write_str_file: Write a string to a file at path.
write_type_to_bin_file: Write a data structue of type <T> to a binary data file.
yaml_file_to_bin_file: Read a YAML file then write the data to a new <T> type file
yaml_file_to_type: Read a YAML file into a data structure of type <T>

Crate ot_tools_ioCopy item path