@xromdev/notation 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksandr Maksymov
+
+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,160 @@
-# Temporary Holding Version
+# @xromdev/notation
 
-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.
+Notes in ticks, read as a score — **note values, ties, tuplets, bar lines, key
+spelling, clefs, the grand staff and dynamics, with no DOM and no renderer.**
+
+Give it notes as integers — where each starts and how long it lasts, in
+sixty-fourth notes — and it tells you how to write them:
+
+- **Note values:** each length is written with the fewest heads. A note that
+  crosses a bar line is tied over it, and a syncopation is one head rather
+  than a sixteenth tied into scraps. Off-grid runs of three that a sound
+  driver could only approximate (10 + 11 + 11 ticks) are written as triplets.
+- **Bar lines:** any metre, an opening bar of its own length (a 19/32 pickup
+  bar in front of 2/4), and odd bars later in the piece. A channel's own
+  delay of a tick or three is taken out, so its notes sit on the beat.
+- **Pitch spelling** in the key and through key changes. Black keys are
+  written the way the signature has them, and C♭ and F♭ appear where the key
+  flattens those letters.
+- **Clefs:** chosen per bar, by a part's worst ledger-line ladder rather than
+  its average. A bar that drops into the other register changes clef partway
+  through.
+- **A grand staff:** a part that needs two staves is split by beam group, and
+  a beam crosses between the staves the way piano music does.
+- **Percussion:** a percussion staff for the NES noise channel, its sixteen
+  rates mapped onto the drum lines.
+- **Dynamics, bends and accents:**
+  - dynamics read from volume levels;
+  - a figure whose level falls or rises note by note (4 3 2 1 in sixteenths)
+    written as its level and a hairpin, the next one like it as `sim.` with
+    dashes for as long as it holds;
+  - slides, bends and vibrato read from pitch curves;
+  - grace notes and echoes in brackets;
+  - accents and beams that follow them, in a passage you name.
+
+Every rule was made on the music of Battletoads (NES), whose sound driver
+counts in exactly these ticks, and checked by ear across its twenty tracks.
+The comments in the source name the bars that decided each one.
+
+The output is a model for whatever draws it. Durations come out as VexFlow
+codes (`w h q 8 16 32 64` plus dots) and pitches as VexFlow keys (`f#/4`), so
+[VexFlow](https://www.vexflow.com) can draw it as it stands.
+
+**See it:** the score pages at [xrom.dev](https://xrom.dev).
+
+## Install
+
+```sh
+npm install @xromdev/notation
+```
+
+## A score
+
+```ts
+import { buildScore, keyOf, staffKey, noiseKey } from '@xromdev/notation';
+
+// 16 ticks to a quarter: 16 is a quarter, 8 an eighth, 64 a bar of 4/4.
+const lead = [
+  { start: 0, ticks: 16, midi: 64, volume: 12 },
+  { start: 16, ticks: 8, midi: 66, volume: 12 },
+  { start: 24, ticks: 8, midi: 67, volume: 8 },
+  { start: 32, ticks: 32, midi: 71, volume: 12 },
+];
+const drums = [
+  { start: 0, ticks: 8, period: 15 }, // NES noise rates: 15 kick
+  { start: 16, ticks: 8, period: 7 }, //                  7 snare
+];
+
+const score = buildScore([{ id: 'lead', notes: lead }], drums, 64, {
+  measureTicks: 64, // 4/4
+});
+
+const key = keyOf('G');
+for (const stave of score.staves) {
+  for (const bar of stave.bars) {
+    for (const item of bar) {
+      const pitch =
+        item.midi === null ? 'rest'
+        : stave.kind === 'percussion' ? noiseKey(item.midi)
+        : staffKey(item.midi, key);
+      console.log(stave.kind, pitch, item.duration + '.'.repeat(item.dots));
+    }
+  }
+}
+// treble e/4 q · f#/4 8 · g/4 8 · b/4 h
+// percussion e/4 8 · rest 8 · d/5 8 · rest 8 · rest h
+console.log(score.dynamics.lead); // [{ tick: 0, dynamic: 'f' }]
+```
+
+`ScoreModel` holds:
+- `staves` — each with its bars, already filled to the bar line. A grand
+  staff also carries `voiceBars` (the part as one voice across both staves).
+- `grid` and `shift` — where the bar lines fall.
+- `barCount`.
+- `dynamics` and `phases` per part. `phases` is the delay taken out of each part.
+  A dynamic is `{ tick, dynamic }`, and on a shaped figure also `words`
+  (`'dim.'` or `'cresc.'` — a hairpin; `'sim.'` — the word and dashes, no
+  level printed), `until` (the tick of the last note the hairpin or the dashes
+  cover) and `bare` (a hairpin from a level already in force: print no letter).
+
+Each item is a head or a rest, with:
+- `start`, `ticks`, `duration`, `dots`;
+- ties (`tieStart`, `tieStop`) and `tuplet`;
+- and, where they apply: `effect`, `grace`, `accent`, `echo`, `volume`,
+  `staff` and `beamGroup`.
+
+### Options
+
+| option | default | |
+|---|---|---|
+| `offset` | 0 | The tick the bar lines are counted from. |
+| `measureTicks` | 64 | Ticks in a bar: 64 is 4/4, 32 is 2/4, 48 is 3/4. |
+| `mergePickup` | false | Put a pickup into a longer opening bar instead of a bar of rests. |
+| `oddBars` | `[]` | `{ bar, ticks }` — later bars with a length of their own. |
+| `accentBeams` | none | `{ from, to }` ticks: mark accents there, and beam by them. |
+
+A part's notes may also carry:
+- `volume` (0..15), from which the dynamics and accents are read;
+- `bend` — a pitch curve as `[position 0..1, semitones]` pairs;
+- `grace` — MIDI numbers played in front of the note;
+- `echo` — a quieter repeat, written in brackets.
+
+## One staff
+
+The pieces under `buildScore`, for a single strip of music:
+
+```ts
+import { barring, voicePhase, shiftNotes, staffItems, staffMeasures, clefPlan } from '@xromdev/notation';
+
+const { grid, shift } = barring(offset, 64);
+const phase = voicePhase(notes, offset, 64);
+const end = totalTicks + shift;
+const bars = staffMeasures(staffItems(shiftNotes(notes, shift - phase), end, grid), end, grid);
+```
+
+`clefPlan` gives each bar's clef, and `staffRoom` how far the music reaches
+above and below the staff. `decompose(position, length)` spells a single run
+of ticks. `keyOf`, `staffKey` and `barKeys` handle keys and key changes.
+
+## Speed
+
+Measured on 46 real pieces (Battletoads, Battletoads & Double Dragon,
+Alien 3, RoboCop 1 and 3, Terminator 2) on a laptop:
+
+| | per piece |
+|---|---|
+| A whole score (`buildScore`) | ~0.9 ms |
+| Each channel's single staff | ~0.6 ms |
+
+Both are computed once per piece, not per frame. About 6 KB minified and gzipped.
+
+## Development
+
+```sh
+npm install
+npm test
+```
+
+## License
+
+MIT © Oleksandr Maksymov

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @xromdev/notation — notes in ticks, read as a score.
+ */
+export * from './notation.js';
+export * from './score.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * @xromdev/notation — notes in ticks, read as a score.
+ */
+export * from './notation.js';
+export * from './score.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC","sourcesContent":["/**\n * @xromdev/notation — notes in ticks, read as a score.\n */\n\nexport * from './notation.js';\nexport * from './score.js';\n"]}

package/dist/notation.d.ts

@@ -0,0 +1,414 @@
+/**
+ * Ticks read as NOTATION: note values, dots, ties and bar lines.
+ *
+ * Nothing here quantises, because nothing has to: one tick is exactly a
+ * sixty-fourth note (a sixteenth of a quarter), so every note given already
+ * sits on the grid notation is written on. That is what makes music read out
+ * of a game cartridge writable at all — the usual failure of notation built
+ * from MIDI is a performance that lands a few milliseconds off the beat, and
+ * a sound driver gives no performance, only the integers it counts. Anything
+ * else has to be quantised to sixty-fourths before it comes here.
+ *
+ * The rules were made on Battletoads (NES), whose driver counts in exactly
+ * these ticks, and checked by ear on its twenty tracks; the examples in these
+ * comments are the bars that decided them.
+ *
+ * Durations come out as VexFlow codes (`w h q 8 16 32 64`), pitches as VexFlow
+ * keys (`c#/4`) — the shortest names there are, and what a renderer reads.
+ */
+/** Engine ticks in a quarter note. The driver's own grid, not a choice. */
+export declare const TICKS_PER_QUARTER = 16;
+export declare const BEATS_PER_MEASURE = 4;
+/**
+ * A bar of 4/4, which is what all but one track is written in and what every
+ * caller gets by default.
+ *
+ * Not a constant of the music: Volkmire's Inferno Race is in 2/4, and its
+ * sections — the change to D major among them — start on odd multiples of half
+ * a 4/4 bar, so no 64-tick bar line can hold them. So everything here takes the
+ * bar length it is barring to, and `MEASURE_TICKS` is only the default.
+ */
+export declare const MEASURE_TICKS: number;
+/** Quarters in a bar of `measureTicks` ticks. */
+export declare const beatsIn: (measureTicks: number) => number;
+/**
+ * A bar of so many ticks as a time signature.
+ *
+ * In the note value that measures it WHOLE: 64 ticks are 4/4 and 32 are 2/4,
+ * but an opening bar of 38 is no number of quarters — it is 19 thirty-seconds,
+ * and 19/32 is what a reader is shown.
+ */
+export declare function timeSignatureOf(measureTicks: number, 
+/**
+ * The note value a bar is counted in, when the reading names one: 2 writes a
+ * bar of 128 ticks as 4/2 rather than 8/4. Left out — or not dividing the bar,
+ * as an opening bar of its own length may not — it is chosen as below.
+ */
+beatValue?: number): {
+    beats: number;
+    beatValue: number;
+};
+/**
+ * Where the bar lines of a piece fall: every bar `measureTicks` long, except
+ * the first.
+ *
+ * The opening bar has its own length because a pickup written as a bar of rests
+ * is a lie about the music: Volkmire's Inferno Race opens with a run and a held
+ * note that together are six ticks longer than two of its 2/4 bars, and a
+ * reader meets that as one bar of 19/32 and then 2/4 throughout, rather than as
+ * a bar of rests, a bar line through the run, and a note tied over it.
+ *
+ * `firstBarTicks` equal to `measureTicks` is the ordinary case, and then the
+ * grid is the plain multiples every other piece uses.
+ *
+ * `oddBars` are bars later in the piece with a length of their own — a bar of
+ * 2/4 in a piece in 4/4. Arctic Caverns has one: after six bars of 4/4 the bass
+ * runs up E F# G A B C D E in 32 ticks, and everything after that run, every
+ * section and the loop's end, sits half a bar past the 4/4 grid.
+ */
+export interface BarGrid {
+    measureTicks: number;
+    firstBarTicks: number;
+    /** Bars after the first with their own length, by bar index, in order. */
+    oddBars?: readonly OddBar[];
+}
+/** A bar after the first whose length is not the metre's — see `BarGrid`. */
+export interface OddBar {
+    /** The bar's index, from 0 — never the first bar, which has `firstBarTicks`. */
+    bar: number;
+    ticks: number;
+}
+export declare const barGrid: (measureTicks?: number, firstBarTicks?: number, oddBars?: readonly OddBar[]) => BarGrid;
+/** The tick a bar begins on. */
+export declare const barStartOf: (grid: BarGrid, index: number) => number;
+/** How long a bar is: the first and any odd bar have their own length, the rest the metre's. */
+export declare const barTicksOf: (grid: BarGrid, index: number) => number;
+/** Which bar a tick falls in. Ticks before the piece belong to its first bar. */
+export declare const barAt: (grid: BarGrid, tick: number) => number;
+/** How many bars a piece of `totalTicks` takes, the last one counted however little it holds. */
+export declare const barCountOf: (grid: BarGrid, totalTicks: number) => number;
+/** One writable note value: how long it is, what it is called, how many dots. */
+export interface NoteValue {
+    ticks: number;
+    /** VexFlow duration code. */
+    duration: string;
+    dots: number;
+}
+/**
+ * A length as a sum of writable note values, from a position in the bar.
+ *
+ * The FEWEST heads, and only then the tidiest. The first version was greedy and
+ * took a value only when it started on its own grid, which reads well in a
+ * rulebook and terribly on a staff: four ticks from the second thirty-second of
+ * a beat came out as a dotted thirty-second tied to a sixty-fourth — a
+ * sixteenth written as two heads, which nobody writes. Here the head count is
+ * minimised outright (a sixteenth begun off the beat is a syncopation, and a
+ * syncopation is one head), and starting on the grid and keeping beat three
+ * visible only break ties between spellings with the same count.
+ */
+export declare function decompose(position: number, length: number, measureTicks?: number): NoteValue[];
+/** A note of one voice, in the integers the ROM holds. */
+export interface TickNote {
+    /** Ticks from the start of the piece. */
+    start: number;
+    ticks: number;
+    /** MIDI number. */
+    midi: number;
+}
+/**
+ * One head of a tuplet: three notes written in the time of two.
+ *
+ * `num` heads in the time of `occupied`, and the bracket is drawn over the run
+ * from `first` to `last` — VexFlow needs the group, not the single head.
+ */
+export interface TupletSpan {
+    num: number;
+    occupied: number;
+    first: boolean;
+    last: boolean;
+}
+/** One head or rest on the staff — already a writable value. */
+export interface StaffItem {
+    start: number;
+    ticks: number;
+    /** null is a rest. */
+    midi: number | null;
+    duration: string;
+    dots: number;
+    /** Set on each head of a tuplet — see `tupletGroups`. */
+    tuplet?: TupletSpan;
+    /**
+     * Still the same sounding note as the head before it / after it.
+     *
+     * A tie is the difference between one note and two, and one crossing a bar
+     * line is drawn as two half curves that meet at it.
+     */
+    tieStart: boolean;
+    tieStop: boolean;
+}
+export interface StaffMeasure {
+    /** Bar number from the start of the piece, counting from 0. */
+    index: number;
+    /** Tick the bar starts on. */
+    start: number;
+    items: StaffItem[];
+}
+/** One head of a tuplet, with the value it is written as. */
+interface TupletHead {
+    span: TupletSpan;
+    value: NoteValue;
+}
+/**
+ * Where the music divides a written value into THREE.
+ *
+ * One tick is a sixty-fourth, so a third of anything is not a whole number and
+ * the driver cannot hold a true triplet: it writes the nearest integers it can,
+ * and the give-away is a run of three that sums to a written value and divides
+ * as evenly as integers allow without dividing evenly. A quarter triplet is
+ * 10+11+11 of the half's 32 ticks; a sixteenth triplet is 2+3+3 of the
+ * eighth's 8. Spelt by `decompose` instead, each of those becomes two heads
+ * under a tie, and a bar of them is unreadable — which is how this was found.
+ *
+ * The rule is deliberately narrow, and it is checked against the ROM rather
+ * than reasoned about: over all twenty tracks it fires exactly twice — title
+ * music's bar 39, where pulse 1, pulse 2, the triangle and the drums all take
+ * it together, and Clinger Winger's drums, once a bar for five bars. Nothing
+ * else in the cartridge matches, so nothing else is re-spelt.
+ *
+ * Even thirds are NOT tuplets: three heads of the same written value need no
+ * bracket, and the ROM has none inside these totals anyway.
+ */
+export declare function tupletGroups(notes: readonly TickNote[], grid?: BarGrid): Map<number, TupletHead>;
+/** The notes a tuplet of `num` is written in the time of: the largest power of two below it. */
+export declare const tupletOccupied: (num: number) => number;
+export declare function staffItems(notes: readonly TickNote[], totalTicks: number, grid?: BarGrid): StaffItem[];
+/**
+ * The ribbon cut into bars, each one filled to the bar line.
+ *
+ * A bar short of its four beats is not a bar — a formatter given one spaces it
+ * as though the missing time did not exist, and the staff stops lining up with
+ * the music beside it — so whatever is left at the end is padded with rests.
+ */
+export declare function staffMeasures(items: readonly StaffItem[], totalTicks: number, grid?: BarGrid): StaffMeasure[];
+/**
+ * A MIDI number as a VexFlow key — `c#/4` for 61, `db/4` in a key that flats D.
+ *
+ * A black key is spelt the way the KEY SIGNATURE has it when the signature
+ * alters either of its letters, and as a sharp otherwise. A flat key spelt in
+ * sharps prints D-sharp against a signature that flattens E — a sign on nearly
+ * every note — which is what rat race looked like before flats could be written.
+ * Spelling EVERY black key flat in a flat key was the next mistake: Volkmire's
+ * Inferno, in E-flat, climbs F to F-sharp, and printing that as G-flat put a
+ * flat on a note a reader took for a B-flat already in the key.
+ *
+ * Two white keys have a flat spelling of their own: B is C-flat and E is F-flat. They take it only
+ * in a key that flattens that letter — six flats for C-flat. Rat race is in E-flat minor, whose
+ * sixth degree is C-flat; written as B it printed a natural against the B-flat of the signature.
+ */
+export declare function staffKey(midi: number, key?: KeySignature): string;
+/**
+ * The heads of a chord as VexFlow keys, each black key spelt so the chord reads as intervals do.
+ *
+ * `staffKey` spells one note against the key, and for a line that is right: Volkmire's Inferno, in
+ * E-flat, climbs F to F-sharp. A chord is read the other way — by the intervals between its heads.
+ * Paganini's Caprice 17, in E-flat, strikes E-flat with G-flat: written E-flat and F-sharp, that is
+ * an augmented second where a minor third sounds. So for the black keys of a chord both spellings
+ * are tried, and the one whose intervals span the letters their size asks for wins — a third across
+ * three letters, a second across two; where the intervals cannot tell, `staffKey` decides. In the
+ * order given.
+ */
+export declare function chordKeys(midis: readonly number[], key?: KeySignature): string[];
+/** What a key signature does: which letters it alters, and which way. */
+export interface KeySignature {
+    /** `#` for a sharp key, `b` for a flat one. C has neither and no letters. */
+    accidental: '#' | 'b';
+    letters: readonly string[];
+    /** Letters whose black key is written flat although the key leaves the letter alone — see `keyOf`. */
+    spelt?: readonly string[];
+}
+/**
+ * A key signature by its VexFlow name (`G` one sharp, `Eb` three flats).
+ * A name it does not know is C — written with every sign at its note rather
+ * than guessed at.
+ */
+export declare function keyOf(name?: string): KeySignature;
+/**
+ * The signature part of a key name, the one VexFlow is given — `F` of `F+Db+Ab`.
+ *
+ * What follows a `+` is spelling, not signature: black keys to write as those flats although the
+ * key does not flatten their letters. Turbo tunnel, in D minor with one flat, falls D, D-flat, C in
+ * the bass; the rule for black keys wrote the middle chord as C-sharp and G-sharp.
+ */
+export declare const signatureName: (name?: string) => string | undefined;
+/**
+ * Treble or bass for a voice, from where it actually sits.
+ *
+ * The median rather than the mean: one low pickup note must not drag a melody
+ * onto ledger lines below the bass staff. The boundary is middle C's octave —
+ * a voice whose middle is below A3 spends more of its time under the treble
+ * staff than in it.
+ */
+export declare function chooseClef(notes: readonly {
+    midi: number;
+}[]): 'treble' | 'bass';
+/**
+ * How hard a voice is to read from a given bar line: its heads, plus one for
+ * every head that starts off its own grid.
+ *
+ * The measureTicks `voicePhase` minimises. A run of ticks written as
+ * one note on the beat costs 1. The syncopation counts as much as a tie, and
+ * that is deliberate: `decompose` writes an off-beat run as ONE head, so by
+ * heads alone every bar line would look equally good, and the search would
+ * happily put the whole piece a sixteenth off the beat.
+ */
+export declare function notationCost(notes: readonly TickNote[], offset: number, measureTicks?: number): number;
+/**
+ * How many ticks one channel is written behind the beat. Never more than
+ * `MAX_PHASE`.
+ *
+ * The delay is AUTHORED, not the driver's. Nearly every track opens a channel
+ * or two with an explicit `$80` rest one sixty-fourth long, and Intruder
+ * Excluder puts a three-tick rest ahead of pulse 2's copy of pulse 1's bass
+ * line — a two-tick echo, some 60ms, and audible as one. (An earlier version of
+ * this comment called it the cost of setup commands; the stream dump says
+ * otherwise.)
+ *
+ * On a staff, though, it is the difference between a quarter note and a chain
+ * of tied scraps, so the notes are written on the beat and the delay is
+ * STATED: a staff should label every voice it moved, and not move its playhead.
+ * Longer echoes (Surf City's six ticks) are past `MAX_PHASE` and are written as
+ * they sound.
+ */
+export declare const MAX_PHASE = 3;
+export declare function voicePhase(notes: readonly TickNote[], offset: number, measureTicks?: number): number;
+/**
+ * A voice moved `by` ticks along the staff's clock, cut at tick 0.
+ *
+ * Taking a channel's delay out can carry its first sliver before the music
+ * starts: ragnarok's canyon opens the noise channel with a one-tick hit on
+ * tick 0 and then plays everything a tick late. Refusing the phase for the sake
+ * of that sliver — which is what a guard in `voicePhase` once did — left every
+ * drum on an odd tick, and each of those gave the formatter a column of
+ * its own: a gap between the first two sixteenths of pulse 1 in every bar. So
+ * the phase is taken, and what lands before tick 0 is cut off there.
+ */
+export declare function shiftNotes<T extends TickNote>(notes: readonly T[], by: number): T[];
+/**
+ * Ticks to ADD to a piece's own clock to get the staff's, for a bar line
+ * `offset` ticks in.
+ *
+ * Less than a bar, so a piece barred off its first tick gets a pickup bar
+ * rather than notes before tick zero — and nothing at all for offset 0, which
+ * is what every track uses: an empty bar in front of the music says the music
+ * starts a bar late.
+ */
+export declare function staffShift(offset: number, measureTicks?: number): number;
+/**
+ * How a piece is barred: where its bar lines fall, and what its notes are moved
+ * by to sit behind them.
+ *
+ * Two readings of the same pickup. Left alone it gets a bar of its own, padded
+ * in front with rests, and the music starts part way into bar one. `merged`
+ * instead makes the OPENING BAR longer by the pickup and moves nothing: the run
+ * and the note it lands on are one bar of 19/32, and the metre takes over after
+ * it. The second reads better whenever the pickup is not a whole phrase — a bar
+ * line through the middle of a run is worse than an irregular first bar.
+ */
+export declare function barring(offset: number, measureTicks?: number, merged?: boolean, 
+/** Bars later in the piece with a length of their own — see `BarGrid`. */
+oddBars?: readonly OddBar[]): {
+    grid: BarGrid;
+    shift: number;
+};
+export type Clef = 'treble' | 'bass';
+/**
+ * The outer LINES of each staff, as MIDI numbers: E4..F5 and G2..A3.
+ *
+ * Not the centres — what matters for room is where the ledger lines start.
+ */
+export declare const STAFF_SPAN: Record<Clef, readonly [number, number]>;
+/**
+ * The pitch each staff is centred on: B4 on the treble, D3 on the bass. Kept
+ * for callers that want the middle line; the clef is not chosen by it.
+ */
+export declare const CLEF_CENTRE: Record<Clef, number>;
+/**
+ * How much better the other clef has to be before a bar switches, in semitones
+ * of the ladder it saves.
+ *
+ * Without it a line hovering between the two staves changes clef every other
+ * bar, which is unreadable in a way that ledger lines are not.
+ */
+export declare const CLEF_HYSTERESIS = 3;
+/**
+ * How much better a clef change PART WAY through a bar has to be than the best
+ * clef for the whole bar, in semitones of the ladder it saves.
+ *
+ * Higher than `CLEF_HYSTERESIS`, because a change inside a bar is louder. At 3,
+ * a line that crosses between the staves on every beat changed clef inside
+ * bar after bar — Ragnarok's canyon went treble, bass, treble, bass through
+ * bars 5 to 9 — for ladders that were only a few rungs shorter. Measured over
+ * the twenty tracks' voices: at 3, 92 changes inside bars; at 6, the bar that
+ * drops an octave still splits and the see-saw is gone.
+ */
+export declare const CLEF_SPLIT_MARGIN = 6;
+/**
+ * A clef per bar — a real score changes clef, and for this music it has to.
+ *
+ * These channels are not instruments with a range: one voice carries the bass
+ * for eight bars and then a melody three octaves up, and on one fixed clef a
+ * TENTH of all the notes in the cartridge land more than an octave off the
+ * staff — a ladder of ledger lines, most of it clipped by the strip's edge.
+ * Chosen per bar the same figure is 1.35%, at a cost of one clef change every
+ * twelve bars. What a bar costs on each clef is `clefCost`.
+ *
+ * A bar with nothing in it keeps the running clef rather than voting: a rest is
+ * not evidence about register, and letting silence switch the clef puts the
+ * change in the wrong bar.
+ *
+ * A bar can also change clef PART WAY THROUGH, once, where the music drops or
+ * climbs into the other register. Chosen for the bar as a whole, a register
+ * change inside it is paid for by every note on the wrong side of it: bar 5 of
+ * Ragnarok's canyon is eleven E4s and then five E3s, and the whole bar went to
+ * the bass clef — eleven heads on ledger lines to spare five. A split is taken
+ * when it beats the best whole-bar clef by `CLEF_SPLIT_MARGIN`, and only from
+ * the clef the bar opens in, so a bar never carries two changes.
+ */
+export declare function clefPlan(bars: readonly (readonly BarNote[])[], start?: Clef): BarClef[];
+/** A note as the clef reads it: the tick of the bar it starts on, and its pitch. */
+export interface BarNote {
+    tick: number;
+    midi: number;
+}
+/** The clef one bar opens in, and the one change inside it, if it has one. */
+export interface BarClef {
+    clef: Clef;
+    /** From this tick of the bar on, the staff reads in `change.clef`. */
+    change?: {
+        tick: number;
+        clef: Clef;
+    };
+}
+/** The clef a note starting on `tick` of the bar is written in. */
+export declare function clefAt(bar: BarClef, tick: number): Clef;
+/** The clef a bar hands on to the next one. */
+export declare function clefAfter(bar: BarClef): Clef;
+/**
+ * How far this music reaches above and below the staff, in ledger positions.
+ *
+ * What it is FOR: a strip has a fixed amount of room around the staff, and
+ * splitting it evenly suits almost no voice. A bass line spends the whole track
+ * under the staff and a lead over it — measured across the twenty tracks, only
+ * a third of the voices fit an even split, while the same room divided in
+ * proportion to where the notes actually go fits nearly all of them. The staff
+ * is put where the music needs it rather than in the middle.
+ *
+ * Read over the WHOLE piece, not the bars on screen: a staff that slid up and
+ * down as the melody moved would be unreadable, and would take the bar lines
+ * and the pinned clef with it.
+ */
+export declare function staffRoom(bars: readonly (readonly BarNote[])[], clefs: readonly BarClef[]): {
+    above: number;
+    below: number;
+};
+export {};