# nord-format
Parse and write **Clavia / Nord** keyboard binary file formats from Rust.
This is the pure format-logic crate of the drawbar toolkit: the `CBIN` container
(both header generations, each with its checksum), and per-model entity layouts
declared once with `#[bitbody]`. It depends only on [`crcxx`] (plus `zip` behind
the `bundle` feature for backup bundles) and does no USB, OS, or I/O beyond
`Read`/`Seek`/`Write` — so it's trivially testable against a specimen corpus and
reusable by higher layers (a device/USB crate, a CLI) without dragging in a
transport stack.
## What it handles
The support map lives in the rustdoc, where it sits beside the code it
describes: the [`formats`] module docs define the three support tiers —
decoded, structurally decoded, container-verified stub — and each decoded
body's struct doc opens with how far read/write goes, what a read validates,
and the provenance of its placements, followed by its generated byte map.
In brief:
- **Decoded** — the Electro 5 program, live slot, song and settings (values
named, pinned by hardware sweeps); the Stage 2, 3 and 4 programs and presets
(every documented parameter placed; values raw except where the community
maps enumerate them).
- **Structurally decoded** — sample instruments (`nsmp`, `nsmp3`, `nsmp4`:
rename, retune, remap, and the encoded audio decoded back to samples in every
generation), piano libraries (`npno`: the CNSP prefix) and
Nord Sample Editor projects (`nsmpproj`: the editor's text save file — zones,
strokes and audio files read and edited, new projects written).
- **Container-verified stubs** — every other corpus format: 60+ CBIN tags
across the whole model line, plus the Lead SysEx/MIDI banks and the `.cn3`
Electro 2 library, all carried verbatim. ZIP backup bundles parse behind the
`bundle` feature (read-only).
Everything that parses **round-trips byte-for-byte**, verified against a
change-one-knob specimen corpus. **Both `CBIN` container generations are read and
written** — type-1 (crc32 over the body) and the older type-0 (trailing crc16 over
the whole file), so factory files round-trip too — and `inspect` reports container
facts (tag, generation, version, length, checksum verdict) for *any* CBIN file in
O(1) memory, mapped body or not.
## Usage
```rust
use nord_format::{from_path, Entity, Program};
use nord_format::bank::Item; // for `.location()`
use nord_format::formats::ne5::OrganModel;
let entity = from_path("patch.ne5p")?;
if let Entity::Program(Program::Electro5(p)) = entity {
// `p` is a `Cbin<ne5::Program>`: the CBIN header plus the decoded body,
// and it derefs to the body, so the panels read as fields.
println!("location: {:?}", p.location());
println!(
"lower/upper: {:?} / {:?}",
p.center_panel.lower_part, p.center_panel.upper_part
);
// Organ state is decoded per model + selected preset:
let preset = p.organ_panel.preset(OrganModel::B3);
println!("B3 drawbars: {:?}", p.organ_panel.drawbars(OrganModel::B3, preset));
println!("B3 vibrato: {:?}", p.organ_panel.vib_type(OrganModel::B3));
}
```
`from_path` / `from_stream` sniff the container and return an [`Entity`]. Each
format lives under `formats::`, named for the four-character CBIN tag it carries —
or, where a model family shares a prefix across several tags, for that prefix. So
`formats::ne5` holds the concrete `Program`/`Song`/`Settings` layouts and the
`OrganModel` / `VibChorus` / `PercSpeed` decode types, while `formats::nsmp` and
`formats::npno` are single formats shared across the line.
## Lossless round-trip is the core invariant
Unknown regions are kept as **raw byte blocks** and decoded values are exposed as
read-only views over them, so `parse → write` is byte-identical even where the
semantics are incomplete. Every newly decoded field is a safe, incremental
refinement — never a risk to the write path.
## Features
- **`bundle`** — ZIP-based backup bundles (pulls in the `zip` stack). Off by
default so parse-only consumers stay lean; enable with `--features bundle`.
- **`corpus`** — *test-only*. Adds the private specimen corpus to the sweep;
see below. Implies `bundle`, because the corpus holds ZIP banks.
## Tests
Unit tests live inline (`#[cfg(test)] mod tests`) and run on a plain
`cargo test`, alongside `tests/dispatch.rs`, which synthesizes a file for
every registered tag in memory and checks dispatch + round-trip for both
header generations, and the **specimen sweep**, `tests/corpus`: one generated
test per file — container checksum, parse, byte-exact round trip, no
unnameable decoded values, every registry field set to a new value and read
back without moving another, and the file's oracle sidecar
(`<file>.oracle.json`) where it has one. A file joins by being readable; an
oracle by existing beside it.
The sweep always reads `tests/fixtures/` — specimens this crate's own writers
produced, with sidecars saying what was set, committed as the part of the
corpus any checkout can carry.
With `--features corpus` it also reads the private specimen corpus. Two more
suites then check corpus-backed behaviors (`tests/corpus_behaviors.rs`) and verify
that every registered bit affects its declared field (`tests/coverage.rs`).
```sh
cargo test -p nord-format # open suite: unit + dispatch + fixtures sweep
# With the corpus — point at a nord-corpus checkout:
NORD_CORPUS_ROOT=/path/to/nord-corpus \
cargo test -p nord-format --features corpus
# With nix
nix build .#nord.nord-format-corpus
```
## Disclaimer
Not affiliated with, authorized, or endorsed by Clavia DMI AB. "Nord", "Clavia",
and "Electro" are trademarks of Clavia DMI AB, used here only to identify the
hardware these formats come from. All reverse engineering is of files produced by
Nord hardware, for interoperability.
[`crcxx`]: https://docs.rs/crcxx
[`Entity`]: https://docs.rs/nord-format
[`formats`]: https://docs.rs/nord-format/latest/nord_format/formats/