plainscore 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Innei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# plainscore
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A plain-text score format that a musician can read without docs and an AI can edit line by line. One file holds the music; plainscore turns it into timed note events, MIDI and ABC notation.
+
+```
+score 0.1
+
+title   Small Waltz in 4
+by      You
+
+instruments
+  piano  piano
+  cello  cello
+
+piece waltz  Small Waltz
+  tempo  q = 72
+  key    G major
+
+  chords verse  — bass | voicing
+    G      G2 | B3 D4 G4
+    D/F#   F#2 | A3 D4 F#4
+    Em     E2 | B3 E4 G4
+    C      C3 | C4 E4 G4
+
+  part tune  piano  mf  overlap e  lead
+    | B4 h   A4 q   G4 q | A4 w | G4 h   B4 h | C5 w |
+
+  part comp  piano
+    1    bass   w   >
+    2    upper  q   soft
+    3&   upper  e   softer
+
+  part pad  cello  mp
+    1    bass+8va  w
+
+  part pedal
+    1    Ped.
+
+  form  loop
+    A  verse
+      tune, comp p, pad 80%, pedal
+```
+
+## What it can say
+
+- **Pitches as written**, durations `w h q e s` with dots and ties, bars separated by `|`.
+- **Chord-relative patterns**: write a figure once with `bass`, `t1`–`t4`, `top`, `upper`, and it follows the chords.
+- **Form as an orchestration table**: each section row names the parts that play and how loud (`85%`, `92%-75%`, `bars 3-4`, `on 1 and 3`, `8va`, `in E`).
+- **Loop**: `form loop`, or `form loop from A1` for an intro that plays once.
+- **Variants**: versions of one piece that share a timeline (`drop P`, `Q for P`, `P <options>`).
+- **Doubles**: `part strings violins doubles tune 8vb` plays another part's notes on its own instrument.
+- **Pedal, rolls, staggered entries, ad lib.** (seeded random notes), and a **mix** block for playback balance that notation and MIDI ignore.
+
+The full reference is [docs/grammar.md](docs/grammar.md). Every score can carry the standard legend (`plainscore legend`) so a reader never needs this README.
+
+## Use
+
+```bash
+pnpm add -D plainscore
+```
+
+```bash
+plainscore check song.score
+plainscore abc song.score --piece waltz > song.abc
+plainscore midi song.score --piece waltz -o song.mid
+plainscore events song.score --variant quiet --seed 7 --passes 2
+plainscore legend
+```
+
+```ts
+import { parseScore, render } from 'plainscore'
+import { toAbc } from 'plainscore/abc'
+import { toMidi } from 'plainscore/midi'
+
+const score = parseScore(text, 'song.score')
+const rendering = render(score, 'waltz', { variant: null, seed: 1 })
+const abc = toAbc(rendering)
+const midi = toMidi(rendering)
+```
+
+`render` returns plain data: metadata, sections, key changes, every note with its onset in eighths, offset, length, level and velocity, pedal changes, and the ad lib. rules. A player only needs that.
+
+## Notation and MIDI
+
+Staves come from the declared instruments, in declaration order:
+
+- each instrument gets a staff, and `pizz.` parts get their own staff right after it;
+- a `lead` part on a piano gets a Melody staff on top;
+- pianos get a grand staff with pedal marks, and an `inner` part becomes a voice of its own;
+- clefs, MIDI programs and pedal come from the instrument's family (`piano harp violins violas cello bass flute oboe clarinet bassoon horn trumpet voice synth`).
+
+The ABC targets [abcjs](https://www.abcjs.net/) 6.x. plainscore has no runtime dependencies and does not render; pass the ABC to abcjs, or to any ABC tool.
+
+## Limits of 0.1
+
+4/4 only; the smallest grid is the eighth (with `late s` for sixteenth offsets); no tuplets, ties across barlines, tempo changes, hairpins, articulations beyond `pizz.`/`arco`, repeats with endings, imports or percussion.
+
+## Develop
+
+```bash
+pnpm install
+pnpm test
+pnpm typecheck
+pnpm build
+```
+
+`fixtures/` holds the expected ABC, MIDI and events for `examples/`. After an intended output change, run `pnpm test -u` and review the fixture diff.
+
+## License
+
+MIT

package/dist/abc/index.d.ts

@@ -0,0 +1,4 @@
+import type { Rendering } from '../render.ts';
+export declare const credits: (r: Pick<Rendering, "by" | "after">) => string[];
+export declare const movement: (r: Pick<Rendering, "piece" | "variant">) => string;
+export declare const toAbc: (r: Rendering) => string;

package/dist/abc/index.js

@@ -0,0 +1,111 @@
+import { layout } from "../staves.js";
+import { DYNAMICS } from "../words.js";
+import { keyName } from "./spell.js";
+import { pedalVoice, writeVoice } from "./voice.js";
+const NAMES = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'];
+const ROMAN = ['I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII', 'IX', 'X'];
+const leftHand = (e) => e.role === 'bass' || e.role === 'fifth' || (e.role === null && e.midi < 60);
+const innerGroups = (events) => {
+    const pitches = new Map();
+    for (const e of events)
+        if (!leftHand(e))
+            pitches.set(Number(e.inner), [...(pitches.get(Number(e.inner)) ?? []), e.midi]);
+    if (!pitches.size)
+        return new Set();
+    const mean = (g) => pitches.get(g).reduce((a, b) => a + b, 0) / pitches.get(g).length;
+    const upper = [...pitches.keys()].reduce((a, b) => (mean(b) > mean(a) ? b : a), [...pitches.keys()][0]);
+    return new Set([...pitches.keys()].filter((g) => g !== upper));
+};
+const noteName = (midi) => `${NAMES[midi % 12]}${Math.floor(midi / 12) - 1}`;
+const dynamicName = (value) => Object.entries(DYNAMICS).find(([, v]) => v === value)?.[0] ?? String(value);
+export const credits = (r) => [...(r.by ? [`Music by ${r.by}`] : []), ...(r.after ? [`After ${r.after}`] : [])];
+export const movement = (r) => r.piece.count > 1 ? `${ROMAN[r.piece.index] ?? r.piece.index + 1}. ${r.piece.title}${r.variant ? ` · ${r.variant}` : ''}` : '';
+const remarks = (r, staves) => {
+    const out = new Map();
+    for (const staff of staves)
+        if (staff.pedal && !staff.melody && !r.pedals.some((p) => p.inst === staff.inst))
+            out.set(staff.id, 'con Ped.');
+    for (const rule of r.adlibs) {
+        const articulation = rule.articulation === 'arco' ? null : rule.articulation;
+        const staff = staves.find((s) => !s.melody && s.inst === rule.inst && s.articulation === articulation);
+        if (!staff)
+            continue;
+        const range = `${noteName(rule.notes[0])}–${noteName(rule.notes[rule.notes.length - 1])}`;
+        out.set(staff.id, `ad lib. on ${Math.round(rule.chance * 100)}% of free eighths: ${NAMES[r.tonic]} ${r.mode} ${range}, 8va ${Math.round(rule.octave * 100)}%, ${dynamicName(rule.dynamic[0])}–${dynamicName(rule.dynamic[1])}`);
+    }
+    return out;
+};
+export const toAbc = (r) => {
+    const { staves, staffOf } = layout(r);
+    const inner = new Map(staves.filter((s) => s.grand).map((s) => [s.id, innerGroups(r.events.filter((e) => staffOf(e) === s.id))]));
+    const voiceOf = (e) => {
+        const staff = staves.find((s) => s.id === staffOf(e));
+        if (!staff.grand)
+            return staff.id;
+        if (leftHand(e))
+            return `${staff.id}L`;
+        return inner.get(staff.id).has(Number(e.inner)) ? `${staff.id}Inner` : `${staff.id}R`;
+    };
+    const present = new Set(r.events.map(voiceOf));
+    const grandUsed = (staff) => present.has(`${staff.id}R`) || present.has(`${staff.id}L`);
+    const voices = staves.flatMap((staff) => {
+        if (!staff.grand)
+            return present.has(staff.id) ? [{ id: staff.id, staff, hand: null, clef: staff.clef }] : [];
+        const hands = [
+            { id: `${staff.id}R`, staff, hand: 'R', clef: 'treble' },
+            { id: `${staff.id}Inner`, staff, hand: 'Inner', clef: 'treble' },
+            { id: `${staff.id}L`, staff, hand: 'L', clef: 'bass' },
+        ];
+        return hands.filter((v) => (v.hand === 'Inner' ? present.has(v.id) : grandUsed(staff)));
+    });
+    const split = (staff) => present.has(`${staff.id}Inner`);
+    const pedals = new Map(staves
+        .filter((s) => s.grand && s.pedal && grandUsed(s))
+        .map((s) => [s.id, r.pedals.filter((p) => p.inst === s.inst)])
+        .filter(([, list]) => list.length));
+    const notes = remarks(r, staves);
+    const labels = r.sections.length > 1 ? r.sections.map((s) => ({ bar: s.bar, label: s.label === s.mark ? s.mark : `${s.mark} ${s.label}` })) : [];
+    const sheet = { keys: r.keys, mode: r.mode, tonic: r.tonic, bars: r.bars, labels };
+    const group = voices
+        .map((v) => {
+        if (v.hand === 'R')
+            return `{(${v.id}${split(v.staff) ? ` ${v.staff.id}Inner` : ''}) (${v.staff.id}L${pedals.has(v.staff.id) ? ` ${v.staff.id}Pedal` : ''})}`;
+        return v.hand ? '' : `(${v.id})`;
+    })
+        .filter(Boolean)
+        .join(' ');
+    const name = (v) => (v.hand === 'R' || !v.hand ? ` name="${v.staff.name}"` : '');
+    const stem = (v) => (!split(v.staff) ? '' : v.hand === 'R' ? ' stem=up' : v.hand === 'Inner' ? ' stem=down' : '');
+    const title = movement(r);
+    const header = [
+        'X:1',
+        `T:${r.title}`,
+        ...(title ? [`T:${title}`] : []),
+        ...credits(r).map((c) => `C:${c}`),
+        'M:4/4',
+        'L:1/16',
+        `Q:1/4=${r.tempo}`,
+        `%%score ${group}`,
+        ...voices.map((v) => `V:${v.id} clef=${v.clef}${name(v)}${stem(v)}`),
+        ...[...pedals.keys()].map((id) => `V:${id}Pedal clef=bass`),
+        `K:${keyName(r.tonic, r.mode)}`,
+    ];
+    const said = new Map();
+    const written = voices.map((v, i) => {
+        if (!said.has(v.staff.id))
+            said.set(v.staff.id, new Map());
+        const style = { inner: v.hand === 'Inner', rings: v.staff.rings, clef: v.clef };
+        const remark = v.hand === 'Inner' || v.hand === 'L' ? undefined : notes.get(v.staff.id);
+        return writeVoice(sheet, style, r.events.filter((e) => voiceOf(e) === v.id), i === 0, said.get(v.staff.id), remark);
+    });
+    const pedalLines = new Map([...pedals].map(([id, list]) => [id, pedalVoice(list, r.bars)]));
+    const body = [];
+    for (let bar = 0; bar < r.bars; bar += 4)
+        voices.forEach((v, i) => {
+            body.push(`[V:${v.id}] ${written[i].slice(bar, bar + 4).join(' | ')} |`);
+            const pedal = v.hand === 'L' ? pedalLines.get(v.staff.id) : undefined;
+            if (pedal)
+                body.push(`[V:${v.staff.id}Pedal] ${pedal.slice(bar, bar + 4).join(' | ')} |`);
+        });
+    return [...header, ...body].join('\n');
+};

package/dist/abc/spell.d.ts

@@ -0,0 +1,13 @@
+export declare const BAR = 16;
+export declare const BEAT = 4;
+export declare const NOTE_LENGTHS: number[];
+export declare const REST_LENGTHS: number[];
+export declare const split: (at: number, span: number, values: number[]) => number[];
+export declare const speller: (tonic: number, mode: string) => {
+    bar: () => Map<string, number>;
+    note(midi: number, bar: Map<string, number>): string;
+};
+export declare const nearestDynamic: (velocity: number) => string;
+export declare const median: (values: number[]) => number;
+export declare const onGrid: (offset: number) => boolean;
+export declare const keyName: (tonic: number, mode: string) => string;

package/dist/abc/spell.js

@@ -0,0 +1,57 @@
+import { DYNAMICS, MODES } from "../words.js";
+export const BAR = 16;
+export const BEAT = 4;
+export const NOTE_LENGTHS = [16, 12, 8, 6, 4, 3, 2, 1];
+export const REST_LENGTHS = [16, 8, 4, 2, 1];
+const LETTERS = 'CDEFGAB';
+const NATURAL = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+const MODE_NAMES = { major: '', minor: 'm', dorian: 'Dor', lydian: 'Lyd', mixolydian: 'Mix' };
+export const split = (at, span, values) => {
+    const out = [];
+    while (span > 0) {
+        const room = at % BEAT ? BEAT - (at % BEAT) : at === 0 ? BAR : BAR / 2 - (at % (BAR / 2));
+        const l = values.find((x) => x <= Math.min(span, room));
+        out.push(l);
+        at += l;
+        span -= l;
+    }
+    return out;
+};
+const tonicLetter = (tonic) => LETTERS.indexOf([...LETTERS].find((l) => NATURAL[l] === tonic) ?? [...LETTERS].find((l) => (NATURAL[l] + 1) % 12 === tonic));
+export const speller = (tonic, mode) => {
+    const scale = MODES[mode].map((step) => (step + tonic) % 12);
+    const first = tonicLetter(tonic);
+    const degrees = scale.map((pc, i) => {
+        const letter = LETTERS[(first + i) % 7];
+        return { pc, letter, acc: ((pc - NATURAL[letter] + 18) % 12) - 6 };
+    });
+    const sig = Object.fromEntries(degrees.map((d) => [d.letter, d.acc]));
+    const spell = (pc) => {
+        const degree = degrees.find((d) => d.pc === pc);
+        if (degree)
+            return degree;
+        const natural = [...LETTERS].find((l) => NATURAL[l] === pc);
+        if (natural)
+            return { letter: natural, acc: 0 };
+        return { letter: [...LETTERS].find((l) => (NATURAL[l] + 1) % 12 === pc), acc: 1 };
+    };
+    return {
+        bar: () => new Map(),
+        note(midi, bar) {
+            const { letter, acc } = spell(midi % 12);
+            const octave = Math.floor((midi - acc) / 12) - 1;
+            const key = `${letter}${octave}`;
+            const current = bar.get(key) ?? sig[letter];
+            bar.set(key, acc);
+            const mark = acc === current ? '' : acc === 1 ? '^' : acc === -1 ? '_' : '=';
+            return mark + (octave >= 5 ? letter.toLowerCase() + "'".repeat(octave - 5) : letter + ','.repeat(4 - octave));
+        },
+    };
+};
+export const nearestDynamic = (velocity) => Object.entries(DYNAMICS).reduce((best, entry) => (Math.abs(entry[1] - velocity) < Math.abs(best[1] - velocity) ? entry : best))[0];
+export const median = (values) => [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)];
+export const onGrid = (offset) => Math.abs(offset * 2 - Math.round(offset * 2)) < 1e-6;
+export const keyName = (tonic, mode) => {
+    const letter = LETTERS[tonicLetter(tonic)];
+    return letter + (NATURAL[letter] === tonic ? '' : '#') + MODE_NAMES[mode];
+};

package/dist/abc/voice.d.ts

@@ -0,0 +1,17 @@
+import type { ScoreEvent } from '../expand.ts';
+import type { Clef } from '../families.ts';
+import type { Rendering } from '../render.ts';
+import type { Pedal } from '../words.ts';
+export interface Sheet extends Pick<Rendering, 'keys' | 'mode' | 'tonic' | 'bars'> {
+    labels: {
+        bar: number;
+        label: string;
+    }[];
+}
+export interface VoiceStyle {
+    inner: boolean;
+    rings: boolean;
+    clef: Clef;
+}
+export declare const pedalVoice: (pedals: Pedal[], bars: number) => string[];
+export declare const writeVoice: (sheet: Sheet, style: VoiceStyle, events: ScoreEvent[], top: boolean, said: Map<number, string>, remark?: string) => string[];

package/dist/abc/voice.js

@@ -0,0 +1,164 @@
+import { BAR, BEAT, NOTE_LENGTHS, REST_LENGTHS, keyName, median, nearestDynamic, onGrid, speller, split } from "./spell.js";
+const OTTAVA_TOP = 88;
+const OTTAVA_FLOOR = 72;
+const SIMILE_AFTER = 2;
+const onsets = (events) => {
+    const byPos = new Map();
+    for (const e of events) {
+        const grid = onGrid(e.offset);
+        const pos = e.step * 2 + (grid ? e.offset * 2 : 0);
+        const onset = byPos.get(pos) ?? { pos, midis: new Set(), end: pos, arpeggio: false, accent: false, levels: [], shift: 0 };
+        onset.midis.add(e.midi);
+        onset.end = Math.max(onset.end, pos + e.written * 2);
+        onset.arpeggio ||= e.rolled && !grid;
+        onset.accent ||= e.velocity > e.level + 0.04;
+        onset.levels.push(e.level);
+        byPos.set(pos, onset);
+    }
+    return [...byPos.values()].sort((a, b) => a.pos - b.pos);
+};
+const ottava = (list) => {
+    let high = false;
+    const marks = [];
+    for (const o of list) {
+        const lo = Math.min(...o.midis);
+        const hi = Math.max(...o.midis);
+        if (!high && hi >= OTTAVA_TOP && lo >= OTTAVA_FLOOR)
+            marks.push([o.pos, '"^8va"']);
+        else if (high && lo < OTTAVA_FLOOR)
+            marks.push([o.pos, '"^loco"']);
+        high = lo >= OTTAVA_FLOOR && (high || hi >= OTTAVA_TOP);
+        o.shift = high ? 12 : 0;
+    }
+    return marks;
+};
+const pedalMarks = (pedals, bars) => {
+    const marks = new Map();
+    let down = false;
+    for (const p of pedals) {
+        const pos = Math.round(p.at * 2);
+        const text = p.down ? (down ? '✱ Ped.' : 'Ped.') : down ? '✱' : '';
+        down = p.down;
+        if (!text || pos >= bars * BAR)
+            continue;
+        marks.set(pos, marks.get(pos) === '✱' && text === 'Ped.' ? '✱ Ped.' : text);
+    }
+    const routine = (bar) => {
+        const inBar = [...marks].filter(([pos]) => Math.floor(pos / BAR) === bar);
+        return inBar.length === 1 && inBar[0][0] === bar * BAR && inBar[0][1] === '✱ Ped.';
+    };
+    let shown = 0;
+    for (let bar = 0; bar < bars; bar++) {
+        if (!routine(bar))
+            continue;
+        shown++;
+        if (shown === SIMILE_AFTER + 1)
+            marks.set(bar * BAR, 'sim.');
+        else if (shown > SIMILE_AFTER + 1)
+            marks.delete(bar * BAR);
+    }
+    return marks;
+};
+export const pedalVoice = (pedals, bars) => {
+    const marks = pedalMarks(pedals, bars);
+    return Array.from({ length: bars }, (_, bar) => {
+        const start = bar * BAR;
+        const stops = [...new Set([0, ...[...marks.keys()].filter((pos) => Math.floor(pos / BAR) === bar).map((pos) => pos - start), BAR])].sort((a, b) => a - b);
+        return stops
+            .slice(0, -1)
+            .flatMap((at, i) => split(at, stops[i + 1] - at, REST_LENGTHS).map((len, j) => {
+            const text = j === 0 ? marks.get(start + at) : undefined;
+            return `${text ? `"_${text}"` : ''}x${len === 1 ? '' : len}`;
+        }))
+            .join(' ');
+    });
+};
+export const writeVoice = (sheet, style, events, top, said, remark) => {
+    const spellers = new Map(sheet.keys.map((k) => [k.bar, speller(k.tonic, sheet.mode)]));
+    let s = spellers.get(0) ?? speller(sheet.tonic, sheet.mode);
+    const total = sheet.bars * BAR;
+    const list = onsets(events);
+    const octaves = style.clef === 'treble' ? ottava(list) : [];
+    const bars = Array.from({ length: sheet.bars }, () => []);
+    const prefixes = new Map();
+    const prefix = (pos, text) => prefixes.set(pos, [...(prefixes.get(pos) ?? []), text]);
+    if (remark)
+        prefix(0, `"^${remark.replaceAll('%', '\\%')}"`);
+    if (top)
+        for (const section of sheet.labels)
+            prefix(section.bar * BAR, `"^${section.label}"`);
+    for (const [pos, mark] of octaves)
+        prefix(pos, mark);
+    let dynamic = '';
+    for (let bar = 0; bar < sheet.bars && !style.inner; bar++) {
+        const inBar = list.filter((o) => Math.floor(o.pos / BAR) === bar);
+        if (!inBar.length)
+            continue;
+        const mark = nearestDynamic(median(inBar.flatMap((o) => o.levels)));
+        if (mark !== dynamic && said.get(bar) !== mark)
+            prefix(inBar[0].pos, `!${mark}!`);
+        if (mark !== dynamic)
+            said.set(bar, mark);
+        dynamic = mark;
+    }
+    const pieces = [];
+    const push = (pos, len, midis, arpeggio = false, accent = false) => {
+        let at = pos;
+        while (at < pos + len) {
+            const start = Math.floor(at / BAR) * BAR;
+            const span = Math.min(pos + len, start + BAR) - at;
+            for (const l of split(at - start, span, midis ? NOTE_LENGTHS : REST_LENGTHS)) {
+                pieces.push({ pos: at, len: l, midis, tie: midis !== null && at + l < pos + len, arpeggio: arpeggio && at === pos, accent: accent && at === pos });
+                at += l;
+            }
+        }
+    };
+    let t = 0;
+    list.forEach((o, i) => {
+        if (o.pos >= total)
+            return;
+        if (o.pos > t)
+            push(t, o.pos - t, null);
+        const barEnd = (Math.floor(o.pos / BAR) + 1) * BAR;
+        let end = Math.min(o.end, list[i + 1]?.pos ?? total, total);
+        // A spill of less than an eighth past the barline is a legato overlap in the source, not a written tie.
+        if (end > barEnd && end % BAR < 2)
+            end -= end % BAR;
+        if (style.rings)
+            end = o.pos + split(o.pos % BAR, Math.min(end, barEnd) - o.pos, NOTE_LENGTHS)[0];
+        push(o.pos, end - o.pos, [...o.midis].map((m) => m - o.shift).sort((a, b) => a - b), o.arpeggio && o.midis.size > 1, o.accent);
+        t = end;
+    });
+    if (t < total)
+        push(t, total - t, null);
+    let accidentals = s.bar();
+    let current = -1;
+    let last = null;
+    for (const p of pieces) {
+        const bar = Math.floor(p.pos / BAR);
+        if (bar !== current) {
+            const key = sheet.keys.find((k) => k.bar === bar && bar > 0);
+            // abcjs crashes on an inline key in the second voice of a staff, which follows the staff's key anyway; and without a clef the key resets the staff to treble.
+            if (key && !style.inner)
+                bars[bar].push(`[K:${keyName(key.tonic, sheet.mode)} clef=${style.clef}]`);
+            s = spellers.get(bar) ?? s;
+            accidentals = s.bar();
+            current = bar;
+            last = null;
+        }
+        const len = p.len === 1 ? '' : String(p.len);
+        const marks = [...(prefixes.get(p.pos) ?? [])].filter((m) => p.midis || m.startsWith('"'));
+        prefixes.delete(p.pos);
+        if (p.midis && p.accent)
+            marks.push('!>!');
+        if (p.midis && p.arpeggio)
+            marks.push('!arpeggio!');
+        const names = p.midis?.map((m) => s.note(m, accidentals));
+        const body = !names ? `${style.inner ? 'x' : 'z'}${len}` : names.length === 1 ? `${names[0]}${len}` : `[${names.join('')}]${len}`;
+        const token = { beat: Math.floor(p.pos / BEAT), beamable: p.midis !== null && p.len < BEAT };
+        const glue = last && last.beamable && token.beamable && last.beat === token.beat ? '' : ' ';
+        bars[bar].push((bars[bar].length ? glue : '') + marks.join('') + body + (p.tie ? '-' : ''));
+        last = token;
+    }
+    return bars.map((tokens) => tokens.join(''));
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { parseArgs } from 'node:util';
+import { toAbc } from "./abc/index.js";
+import { checkScore } from "./expand.js";
+import { LEGEND } from "./legend.js";
+import { toMidi } from "./midi.js";
+import { DEFAULT_SEED, render } from "./render.js";
+const USAGE = `usage:
+  plainscore check <file>
+  plainscore events <file> [--piece id] [--variant v] [--seed n] [--passes n]
+  plainscore abc <file> [--piece id] [--variant v]
+  plainscore midi <file> [--piece id] [--variant v] [--seed n] [--passes n] -o out.mid
+  plainscore legend`;
+const main = () => {
+    const { positionals, values } = parseArgs({
+        allowPositionals: true,
+        options: {
+            piece: { type: 'string' },
+            variant: { type: 'string' },
+            seed: { type: 'string' },
+            passes: { type: 'string' },
+            output: { type: 'string', short: 'o' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    const [command, file] = positionals;
+    if (values.help || !command)
+        return void console.log(USAGE);
+    if (command === 'legend')
+        return void process.stdout.write(LEGEND);
+    if (!['check', 'events', 'abc', 'midi'].includes(command))
+        throw new Error(`unknown command "${command}"\n${USAGE}`);
+    if (!file)
+        throw new Error(`${command} needs a score file\n${USAGE}`);
+    const score = checkScore(readFileSync(file, 'utf8'), basename(file));
+    if (command === 'check')
+        return void console.log(`${file}: ok, ${score.pieces.map((p) => p.id).join(', ')}`);
+    const number = (value, name) => {
+        if (value === undefined)
+            return undefined;
+        if (!/^\d+$/.test(value))
+            throw new Error(`--${name} takes a whole number`);
+        return Number(value);
+    };
+    const piece = values.piece ?? score.pieces[0].id;
+    const passes = number(values.passes, 'passes');
+    if (command === 'abc')
+        return void process.stdout.write(`${toAbc(render(score, piece, { variant: values.variant }))}\n`);
+    const seed = number(values.seed, 'seed') ?? DEFAULT_SEED;
+    const rendering = render(score, piece, { variant: values.variant, seed, passes });
+    if (command === 'events')
+        return void process.stdout.write(`${JSON.stringify(rendering, null, 2)}\n`);
+    if (!values.output)
+        throw new Error('midi needs -o <file.mid>');
+    writeFileSync(values.output, toMidi(rendering));
+};
+try {
+    main();
+}
+catch (error) {
+    console.error(error.message);
+    process.exit(1);
+}

package/dist/expand.d.ts

@@ -0,0 +1,61 @@
+import { type AdLib, type Articulation, type ScoreFile } from './parse.ts';
+import { type Chord, type Pedal, type Ref } from './words.ts';
+export interface ScoreEvent {
+    step: number;
+    offset: number;
+    inst: string;
+    articulation: Articulation | null;
+    part: string;
+    role: Ref['ref'] | null;
+    midi: number;
+    length: number;
+    written: number;
+    held?: number;
+    level: number;
+    velocity: number;
+    rolled: boolean;
+    lead: boolean;
+    inner: boolean;
+    gain: number;
+    attack?: number;
+}
+export interface Voice {
+    inst: string;
+    articulation: Articulation | null;
+}
+export interface ExpandedSection {
+    mark: string;
+    label: string;
+    bar: number;
+    bars: number;
+    tonic: number;
+    voices: Voice[];
+}
+export interface AdLibRule extends Omit<AdLib, 'avoid'>, Voice {
+    part: string;
+    gain: number;
+    free: number[];
+}
+export interface Expanded {
+    id: string;
+    title: string;
+    variant: string | null;
+    tempo: number;
+    tonic: number;
+    mode: string;
+    bars: number;
+    loop: {
+        from: number;
+        to: number;
+    } | null;
+    sections: ExpandedSection[];
+    chords: Chord[];
+    events: ScoreEvent[];
+    pedals: Pedal[];
+    adlibs: AdLibRule[];
+}
+export declare const pedalUntil: (pedals: Pedal[], onset: number, loop: Expanded["loop"]) => number;
+export declare const wrap: (piece: Pick<Expanded, "bars" | "loop">, step: number) => number;
+export declare const expand: (score: ScoreFile, id: string, variant?: string | null) => Expanded;
+export declare const adlibAt: (rule: AdLibRule, step: number, random: () => number) => ScoreEvent | null;
+export declare const checkScore: (text: string, file: string) => ScoreFile;