Instruction libraries

An instruction library is stored as a single .ins file. It has, for every possible instruction, the waveform its channel produces and that waveform's spectrum. It is the catalog the reconstruction search draws its candidates from. For what a library is and how it is built, see Instruction library. This page documents the file.

Libraries are generated from the Instructions tab (or with sampletones library) and stored in the documents folder.

A library is keyed by the configuration that produces it and has one entry per instruction.

Per-instruction data

Each entry contains:

• metadata — the generator class (PulseGenerator / TriangleGenerator / NoiseGenerator) and the instruction values below;
• instruction values — the channel command:
  • on (0–1) — whether the channel sounds;
  • pitch (33–119) for pulse and triangle, or period (0–15) for noise;
  • volume (0–15) for pulse and noise;
  • duty_cycle (0–3) for pulse, or the short (0–1) flag for noise;
• waveform — one full period of the rendered wave. The longest noise samples are trimmed to two seconds, which holds the whole stretch a constant-Q spectrum is read over;
• spectrum — the waveform's precomputed frequency content.

Configuration key

Each library corresponds to one configuration. The parameters that change the rendered waveforms or their spectra form its key: sample rate, NES frequency, FFT window size, transformation gamma and spectrum method. Changing any of them selects, or generates, a different library. Reconstruction algorithms explains gamma and the spectrum method.

A file holds a deflated MessagePack payload, with the framing described in Reconstructions, and has its configuration in the file name:

sr_44100_nf_60_ws_27157_tg_0_sm_cqt_ch_384e710987cb958adf2b214df1267d10.ins

Each file records the library data version it was written with, in the metadata that leads the file, so the version reads from the first bytes without loading the entries. A library is derived data: its settings and the generators determine it wholly. A library written at the version this build writes is used as it stands. Any other is rebuilt from its settings the first time it is needed. A conversion rebuilds it without asking, and opening one from the Instructions tab asks first. See Data compatibility.

The version names what generation produces. A change to the generators or to feature extraction bumps it, and every stored library is then rebuilt. Installs of different versions that share one library folder rebuild each other's libraries as each needs them.

The current data version is 2.1.