Skip to content

Latest commit

 

History

History
220 lines (198 loc) · 12.7 KB

patch-json.md

File metadata and controls

220 lines (198 loc) · 12.7 KB

A LAB sound as text: sidou-patch/1

One LAB sound as JSON, with named fields in musical units: a wave by name, the cutoff in Hz, the envelope as the 0..15 steps LAB's cards show. It is what a language model writes from the instructions, what the site's Library reads, checks, previews and sends to the FM-1, and what it shows any of SIDOU's sixteen sounds as. The JSON Schema is patch.schema.json; the site serves both as llms.txt (with llms-fields.txt, llms-lab.txt, llms-examples.txt it links, and llms-full.txt, all of them in one) and patch.schema.json at its root, and the sixteen as sounds/patches/*.json.

{
  "format": "sidou-patch/1",
  "name": "303 BASS",
  "wave": "saw",
  "envelope": {"attack": 0, "decay": 8, "sustain": 8, "release": 8},
  "filter": {"cutoff_hz": 2077, "resonance": 12, "voices": [1], "envelope": {"depth": 40, "decay": 6, "sustain": 0}},
  "vibrato": {"rate_hz": 0}
}

A patch holds everything a LAB sound holds (sound-format.md, the 109 bytes of app/lab_sound.h) and its name; not the chip, its character or the octave, which are the instrument's. One converter, platform/web/patch_json.c, reads a patch into the 109 bytes and writes the 109 bytes as a patch: the site runs it as WebAssembly (tools/wasm-patch), the host tests through sidou-sys. A patch written from a sound reads back as exactly that sound.

Reading

  • format is required and is "sidou-patch/1". Every other field may be left out.
  • What is left out is LAB's own starting sound, SAW LEAD as the FM-1 loads it at power-on. A layer is a copy of the top-level oscillator but what it names; a table step plays its layer's wave unless it names one; an effect takes its type's settings (the FM-1's own, as its CHIP view picks a type) but what it names; an LFO is a triangle unless it names a shape. null is left out.
  • The length of layers is the number of extra oscillators, of table.steps the table's steps. A table with steps is on unless "on": false.
  • name is upper-cased; it is the instrument's name in the song and LAB's name for the sound.
  • Text before the first { and after the patch is skipped, so a model's whole answer can be pasted.
  • A number takes up to three decimals; cutoff_hz, the LFOs' rate_hz and the percentages become the nearest value the sound can hold.
  • A patch is refused, with the field, what is wrong and what is allowed, when a field is unknown, of the wrong type or out of its range; when layers meet sync_lead; when a table is on with no steps or loops past its last step; when a one-oscillator sound filters some voices but not all (each key plays on the next free voice, so the filter takes all three or none; a layered sound routes layers apart, layer n being voice n); and when it is silent. Silent is heard, not estimated: the song is played (platform/web/patch_level.c, the song player on each chip model, C2, C3 and C4 held 0.3 s each, the first as long as the attack, then let go) and a sound is heard on a chip when the eighth loudest 128-sample block, its mean taken out, has an RMS of 512 or more. Neither chip hearing it is a refusal; one chip only, a warning.

Writing

A sound is written with format, name, the wave and the envelope, then every field whose value is not what reading would fill in. Numbers are the shortest decimal that reads back as the same value.

The fields

The ranges are the converter's own (this table is generated by host/crates/sidou-patch/tests/patch_docs.rs; SIDOU_PATCH_DOC_UPDATE=1 rewrites it).

Field Allowed
format "sidou-patch/1"
name up to 12 characters: A to Z, 0 to 9, space and !"#$%&'()*+,-./:;<=>?@[]^_
wave triangle, saw, pulse and noise, one or several joined with + (like "triangle+saw"), or none
ring true or false
sync true or false
pulse_width 0 to 100 (percent of the cycle, 50 is square)
envelope.attack 0 to 15
envelope.decay 0 to 15
envelope.sustain 0 to 15
envelope.release 0 to 15
transpose -24 to 24 (semitones)
detune -99 to 99 (cents)
level 0 to 100 (percent: the layer's loudness, 100 full; on a one-oscillator sound every voice's)
fine_tune -50 to 50 (cents, the whole sound)
filter.mode low, band and high, one or several joined with + (like "low+band"), or off
filter.cutoff_hz 0 to 14298 (Hz, as an 8580 plays it)
filter.resonance 0 to 15
filter.voices a list of chip voices 1 to 3, like [1, 2, 3] (the chip voices through the filter: all three or none on a one-oscillator sound)
filter.resonance_link -8 to 8 (the resonance follows the cutoff knob)
filter.lfo_depth 0 to 32 (a cutoff wobble at the PWM rate, 0 off)
filter.envelope.depth -63 to 63 (cutoff steps of 32 at the peak, below 0 closes)
filter.envelope.attack 0 to 15
filter.envelope.decay 0 to 15
filter.envelope.sustain 0 to 15
filter.envelope.release 0 to 15
pwm.depth 0 to 50 (percent of the cycle swept)
pwm.rate_hz 0 to 12.75
pwm.link -8 to 8 (the PWM depth follows the pulse width knob)
sync_lead.on true or false (oscillator 1 hard-synced to a silent one; one note at a time)
sync_lead.ratio 0 to 15.996 (the synced pitch over the note's, 2.75 is SYNC LEAD's)
sync_lead.semitones -12 to 12 (added to the ratio)
vibrato.rate_hz 0 to 12.7
vibrato.depth 0 to 127 (127 is about a semitone each way)
vibrato.delay 0 to 127 (hundredths of a second after the note starts)
arp.on true or false
arp.rate 1fr, 2fr, 3fr, 4fr, 6fr, 8fr, 1/32, 1/16 or 1/8 (50 Hz frames a note, or a MIDI clock division)
arp.order up, down, up_down or played
arp.octaves 1 to 2
bend_range 0 to 24 (semitones)
velocity off, sustain, cutoff or pulse_width (what the key velocity moves)
mod_wheel pulse_width, vibrato or cutoff (what the wheel moves)
aftertouch off, vibrato, pulse_width or cutoff (what pressure moves)
layers a list of up to 2
layers[].wave triangle, saw, pulse and noise, one or several joined with + (like "triangle+saw"), or none
layers[].ring true or false
layers[].sync true or false
layers[].pulse_width 0 to 100
layers[].envelope.attack 0 to 15
layers[].envelope.decay 0 to 15
layers[].envelope.sustain 0 to 15
layers[].envelope.release 0 to 15
layers[].transpose -24 to 24
layers[].detune -99 to 99
layers[].level 0 to 100
table.on true or false
table.layer 1 to 3 (the layer it plays on; a one-oscillator sound plays it on every note)
table.loop 0 to 16 (0 plays once and holds the last step, n goes back to step n)
table.frames 1 to 16 (50 Hz frames a step)
table.steps a list of up to 16
table.steps[].wave triangle, saw, pulse and noise, one or several joined with + (like "triangle+saw"), or none
table.steps[].test true or false (the SID's test bit: silences and resets the oscillator)
table.steps[].ring true or false
table.steps[].sync true or false
table.steps[].note -32 to 95 semitones from the key played, a fixed note "C#0" to "B7", or "hold"
lfos a list of up to 2
lfos[].shape off, triangle, saw_up, saw_down, square or sample_hold
lfos[].to pitch, pulse_width, cutoff or volume
lfos[].rate_hz 0.05 to 12.75 (snapped to the nearest of 32 rates)
lfos[].depth -63 to 63 (below 0 inverts; 63 on pitch is an octave)
fx.distortion.type off, tape, overdrive, fuzz, crush or lofi
fx.distortion.amount 0 to 127
fx.distortion.a 0 to 127
fx.distortion.b 0 to 127
fx.distortion.mix 0 to 127
fx.modulation.type off, chorus, flanger, phaser, tremolo, autopan or wow
fx.modulation.amount 0 to 127
fx.modulation.a 0 to 127
fx.modulation.b 0 to 127
fx.modulation.mix 0 to 127
fx.effect.type off, delay, pingpong, reverb or lush
fx.effect.amount 0 to 127
fx.effect.a 0 to 127
fx.effect.b 0 to 127
fx.effect.mix 0 to 127

Banks: sidou-bank/1

Up to sixteen patches as one song, an instrument each, the way the site's sixteen sounds go (the sixteen as a bank, assets/sounds/sidou-sounds-bank.json, make sidou-sounds.sng byte for byte). Its schema is bank.schema.json.

{"format": "sidou-bank/1", "name": "ACID KIT", "patches": [{"name": "KICK", "...": "..."}, {"name": "BASS"}]}
  • format is required; name is the song's name on the FM-1, 1 to 16 characters (a store name: the font's upper case, not starting with a space), BANK when left out; patches holds 1 to 16 patches, each read as above, its format optional.
  • A refusal names the patch: patches[1].wave: "sawtooth" is not allowed. .... A bank whose sounds' tables do not fit one song's 255 rows each is refused at the patch that overflows.
  • Its link is library.html#bank=, made as a patch's; the sixteen are a 6.8 KB link, inside the page's 8 KB.

STEP patterns: sidou-step/1

One STEP lane as a song: the FM-1's NEW song (app/song_io.c's template, with its drum kit) with the lane's pattern written as STEP's keys write it (a test plays the keys and compares the pattern and its locks), so it opens on STEP and plays. Examples: assets/steps/*.json.

  • format (required), name (the song's, as a bank's, STEP when left out), voice 1 to 3 (1), role auto, drums, bass, arp, lead, none, bass+drums, acid (the SCNE chunk; auto), gate staccato (a key off after a note when the next row is empty) or legato (staccato), pages 1 to 4 (1; the pattern is 16 rows a page).
  • instrument: a patch (placed in the first free instrument, kept so ENV pulls it back exactly), "pulse" or "bass" (the NEW song's instruments 1 and 2), or "kit" (its drums, instruments 3 to 14).
  • steps: step 1 to 64 (required, once each, inside the pages), note "C0" to "G#7" ("C3"), drum (with the kit only, and then required), slide, accent (true; the locks 10 and 11) and chance 0 to 100 (lock 9; 100 keeps none).
  • Writing a song back as a pattern takes the lane's notes, the instrument (one patch, the pulse, the bass, or the kit), staccato when a key off follows a note, the locks and the role.

Whole songs: sidou-song/1

A song as sections of step-grid strings, patches as its instruments and a play order, laid out in the FM-1's NEW song as GoatTracker patterns and orderlists. Its schema is song.schema.json, its instructions for models prompt-to-patch-song.md (the site's llms-song.txt), its examples GROOVE and THREE_PARTS in sidou-patch's tests.

  • format (required), name (1 to 16 characters), bpm 60 to 250 (125; plays as the nearest tempo, 107.4, 115.7, 125.3, 136.7, 150.4 and so on up to 250.6, and the Library page and sidou-sysex song report the one that plays); swing straight (the default), light, shuffle or hard: the song's offbeats played late (its eighths when it plays eighths, else its sixteenths), written as GoatTracker's funktempo on voice 1's rows as the FM-1's SWING writes it (one a tempo cannot give is refused in words with the ones it can).
  • instruments: up to 16 patches named 1 to 8 characters, format optional; "kit", "pulse" and "bass" are the NEW song's own and need no entry (a song's instrument of that name wins).
  • sections: up to 16 named, each rows 1 to 128 and voices, up to three, each {"instrument", "notes"} or null; a voice left out or null rests for the section.
  • notes: one token a row, separated by any whitespace, as many as rows: C0 to G#7 with ! (accent) or ~ (slide) after it, - hold, . rest (a key off); with the kit k s h o c t T r dk ds dc dh, each with ! after it for an accent, no ~.
  • order: 1 to 64 section names, looped from the start.
  • A song that does not fit is refused in the FM-1's words (208 patterns, 64 KiB, 512 accents and slides, 255 rows of each table). Its link is library.html#song=, made as a patch's.

The link

library.html#patch= followed by the patch's JSON, percent-encoded (what encodeURIComponent writes), opens the patch on the Library page: it checks and previews it and shows Send to FM-1, and sends nothing by itself. A fragment never reaches a server. The longest of the sixteen sounds is a link of under 2 KB.