@xromdev/notation 0.0.0-stage → 0.1.0

package/dist/score.d.ts

@@ -0,0 +1,475 @@
+/**
+ * A track as a SCORE: each pitched channel on a grand staff, the noise channel
+ * on a percussion staff, and the dynamics its volumes imply.
+ *
+ * Built on `./notation`, so a bar here is spelled exactly the way a single
+ * scrolling staff spells it — same bar line, same phase, same
+ * note values. What this file adds is the part a page of music needs and a
+ * single strip does not: which of two staves a note goes on, and what the
+ * volume column says in the words a player reads.
+ */
+import { type BarGrid, type OddBar, type StaffItem, type TickNote } from './notation.js';
+/**
+ * Middle C: in a beam group kept on the bass, the heads from here up still go
+ * onto the treble and the beam crosses to them — see `crossStaffVoice`.
+ */
+export declare const GRAND_STAFF_SPLIT = 60;
+export declare function splitGrandStaff<T extends {
+    midi: number;
+}>(notes: readonly T[], split?: number): {
+    treble: T[];
+    bass: T[];
+};
+/** A beam group that never goes below E3 — three ledger lines under the treble — is written on the treble. */
+export declare const TREBLE_FLOOR = 52;
+/**
+ * A grand-staff part as ONE voice, each item saying which of the two staves it
+ * stands on.
+ *
+ * Decided per BEAM GROUP — the beamed notes of one beat, or a note on its own —
+ * because a beam is what a reader follows:
+ *
+ *  - a group that never goes below E3 (`TREBLE_FLOOR`) is on the treble, E3
+ *    included. Ragnarok's canyon, pulse 1, bar 29, the third beat: A3 G3 C4 A3
+ *    E4 C4 G4 E4 — a reader wanted it all on the treble.
+ *  - a group that does go below E3 stays on the bass, E3s and all — bar 29's
+ *    second beat, E3 G3 C3 E3…, which "would be ugly otherwise". Only its heads
+ *    from middle C up cross to the treble, and the beam crosses with them — the
+ *    piano's cross-staff writing, drawn as one beam between the
+ *    staves with no rest on either side. Bar 30's lone G5 among B2s is that case.
+ *
+ * Every rule tried per BAR before this failed on a bar of this music: a bar
+ * that starts low and climbs three octaves has a bass half and a treble half,
+ * and the only choices a whole bar has are to tear its beams with rests or put
+ * half of it on four ledger lines.
+ *
+ * A piece tied on from the head before it stays where that head stood; a rest
+ * stands where the head before it in the bar did (else the first head after
+ * it), and a bar with no heads at all is the treble's, so the bass shows its
+ * own bar rest rather than a second one.
+ */
+export declare function crossStaffVoice(bars: readonly (readonly ScoreItem[])[]): ScoreItem[][];
+/** The highest a part may reach and still be written on the bass staff alone: E4, two ledger lines up. */
+export declare const BASS_ONLY_MAX = 64;
+/** The lowest a part may reach and still be written on the treble staff alone: G3, two ledger lines down. */
+export declare const TREBLE_ONLY_MIN = 55;
+/**
+ * The staves a part needs: one when every note it plays sits within two ledger
+ * lines of a single staff, both otherwise.
+ *
+ * A grand staff whose other half is a whole track of rests is furniture: the
+ * triangle carries the bass in every one of the twenty tracks, and in
+ * Ragnarok's canyon it reaches D#4 at most — a ledger line and a half above the
+ * bass staff. Where both single staves would do, the part's middle decides.
+ */
+export declare function partStaves(notes: readonly {
+    midi: number;
+}[]): ('treble' | 'bass')[];
+export type Dynamic = 'pp' | 'p' | 'mp' | 'mf' | 'f' | 'ff';
+/**
+ * The APU's 0..15 volume in six steps.
+ *
+ * A READING, not a fact: the nibble is linear in output level and a dynamic is
+ * a word about loudness, so the steps are even in the nibble and nothing more
+ * is claimed for them.
+ */
+export declare function dynamicOf(volume: number): Dynamic;
+/** A change of level closer than this, in ticks, is folded into the mark before it. A quarter note. */
+export declare const DYNAMIC_HOLD = 16;
+/** The words a mark can carry after its level: a figure's shape, or "the same again". */
+export type DynamicWords = 'dim.' | 'cresc.' | 'sim.';
+export interface DynamicMark {
+    tick: number;
+    dynamic: Dynamic;
+    /**
+     * How the figure goes from here: `dim.` and `cresc.` are a hairpin after the
+     * level, `sim.` is the word alone — the level is the figure's own — with a
+     * dashed line for as long as it holds.
+     */
+    words?: DynamicWords;
+    /** With `words`: the tick of the last note the hairpin or the `sim.` covers. */
+    until?: number; /**
+     * A hairpin from a level the reader is already at: the hairpin alone, no
+     * letter — ragnarok's 7 7 4 2, an mp going on from the mp before it.
+     */
+    bare?: boolean;
+}
+/** Onset to onset, notes closer than this can make one shaped figure. An eighth note. */
+export declare const FIGURE_GAP = 8;
+/**
+ * And no closer than this, a sixteenth. Faster is one note's envelope struck
+ * again and again — Arctic Caverns' 8 4 2 1 in thirty-seconds on one pitch, an
+ * echo — not a figure a player shapes.
+ */
+export declare const FIGURE_STEP = 4;
+/** A run of notes whose level only falls, or only rises: `[from, to]` are indices, inclusive. */
+export interface ShapedFigure {
+    from: number;
+    to: number;
+    words: 'dim.' | 'cresc.';
+}
+/**
+ * Runs of at least three notes, each `FIGURE_STEP` to `FIGURE_GAP` after the one before, whose
+ * level moves one way every step and by two or more in all — the 4 3 2 1 under
+ * every beat of a fading figure. The six steps of `dynamicOf` cannot show that:
+ * 4 and 3 are both p, and the hold folds the pp of 2 and 1 back into it.
+ *
+ * `notes` must be in order of start.
+ */
+export declare function shapedFigures(notes: readonly {
+    start: number;
+    volume: number;
+}[], gap?: number): ShapedFigure[];
+/**
+ * Where a voice's level changes, as the marks a score prints.
+ *
+ * Only at a change, and never two within `DYNAMIC_HOLD`: the driver can move a
+ * volume on every note, and a mark under every head is noise. Inside the hold
+ * the LOUDER level stands — the accent is what a reader has to see — and a
+ * change that comes straight back to the level before it is dropped.
+ *
+ * A shaped figure (`shapedFigures`) is written as its level and a hairpin under
+ * the first, `sim.` under the next one just like it, its dashes running on over
+ * the ones after that, until some other mark is printed. A figure that turns straight
+ * into one going the other way — wookie hole's 6 4 2 1 2 4 6 8 on one held
+ * note — is a level swaying, not a figure, and is read note by note as before.
+ * After a hairpin the reader is where it ends, so going back to where it began
+ * is written — ragnarok's mp over the 7 after 7 4 2 1 — unless a `sim.` that
+ * goes on already says the figure comes round again.
+ */
+export declare function dynamicMarks(notes: readonly {
+    start: number;
+    volume: number;
+}[], hold?: number): DynamicMark[];
+/** A noise period as a VexFlow key on the percussion staff. Only the low nibble is the period. */
+export declare function noiseKey(period: number): string;
+/** A pitched note, with the volume it starts at when the channel has one. */
+export interface ScoreNote extends TickNote {
+    volume?: number;
+    /** The note's pitch curve — `[position 0..1, semitones]` — as a piano roll draws it. */
+    bend?: readonly (readonly [number, number])[];
+    /** Grace notes in front of it, as MIDI numbers in the order they are played. */
+    grace?: readonly number[];
+    /** A repeat of the note before, quieter — an echo, written in brackets (`echoNotes`). */
+    echo?: boolean;
+    /**
+     * Played short: its `ticks` are the value it is WRITTEN as, and it sounds for
+     * less — a staccato dot over the head instead of a rest after it.
+     */
+    staccato?: boolean;
+}
+/** What a pitch curve is written as. `ticks` is the whole note's length, over which it moves. */
+export type PitchEffect = {
+    kind: 'slide';
+    /** Where it arrives, in semitones from the written pitch; to a tenth. */
+    semitones: number;
+    /** Where along the note the movement begins, 0..1. */
+    from: number;
+    ticks: number;
+    /**
+     * It lands on the next written note. When it does not — a sweep too wide to be a bend that
+     * ends on no note (ragnarok's canyon, triangle, bar 15: E3 down to B2, then a D3) — the
+     * staff draws where it lands as a small note in brackets. Set by `effectsOf`.
+     */
+    arrives?: boolean;
+} | {
+    /** The pitch moves on the note it started on — a guitarist's bend, or its release downwards. */
+    kind: 'bend';
+    semitones: number;
+    from: number;
+    ticks: number;
+} | {
+    kind: 'vibrato';
+    depth: number;
+    ticks: number;
+    /**
+     * The curve itself, `[position 0..1, semitones]`, kept for a vibrato wider than a semitone:
+     * a wave glyph says nothing of a swing like Turbo Tunnel Race's, bar 31, a D6 going up four
+     * semitones and down two and a half, so the staff draws the curve itself.
+     */
+    curve?: readonly (readonly [number, number])[];
+};
+/** A vibrato swinging further than this, in semitones, is drawn as its curve rather than a wave. */
+export declare const WIDE_VIBRATO = 1;
+/**
+ * A movement smaller than this, in semitones, is not written at all.
+ *
+ * 261 of the cartridge's 304 curves are a drift of a fifth of a semitone at the
+ * end of a note. The roll draws them as a hairline, which is right for a picture
+ * of the sound; on a staff a mark on every one of them would be noise over a
+ * third of the notes of some tracks.
+ */
+export declare const DRIFT_LIMIT = 0.5;
+/**
+ * A note's pitch curve read as notation: a slide to where it arrives, a
+ * vibrato, or nothing.
+ *
+ * Over the twenty tracks that is 33 slides (one to four semitones), 10 vibratos,
+ * and the drifts left out — the same split the Battletoads music tooling
+ * makes between a slide and a vibrato.
+ */
+/** How far into a note a strike may reach and still be read as its attack, 0..1. */
+/**
+ * Alien 3's kick takes three frames of a seventeen-frame bass note — 18% — and at 15% the
+ * vibrato after it was still read with the kick in it.
+ */
+export declare const STRIKE_SHARE = 0.25;
+export declare function pitchEffect(whole: readonly (readonly [number, number])[], ticks: number): PitchEffect | null;
+/** The most a note's pitch may move on its own and still be a bend: a tone and a half. */
+export declare const BEND_MAX = 3;
+/**
+ * Each note's effect, read against the note AFTER it in the part.
+ *
+ * A curve does not say whether the pitch is sliding somewhere or bending on the
+ * spot; the music around it does. A slide that ends on the pitch the very next
+ * note is written at arrives in that note — a glissando, as in the title music's
+ * G4 up to A4. One that goes nowhere written is the note itself bending:
+ * ragnarok's canyon, pulse 1, bar 5, a D#4 pulled up 1.3 semitones and then left
+ * for an A3 — a guitarist's bend, which a reader said at once, where "gliss." had
+ * been printed. Past `BEND_MAX` nothing bends that far, and the sweeps of fifteen
+ * to twenty-eight semitones that open a few tracks stay lines.
+ *
+ * Except when the note after it comes straight back to the pitch the curve left:
+ * that is a bend and its release, however far it went. Clinger Winger, pulse 1,
+ * an E2 pushed up six and a half semitones over four bars and then struck again
+ * as E2 — a reader heard a bend where a line marked "gliss." had been drawn.
+ * Across the whole ROM this reads that one note differently and no other.
+ */
+export declare function effectsOf(notes: readonly ScoreNote[]): Map<number, PitchEffect>;
+/**
+ * A bend's size, in semitones, to one decimal — the arrow says which way.
+ *
+ * Always the number. The guitar's words (½ for a semitone, "full" for a tone)
+ * were printed for sizes near a step and the number for the rest, so one page
+ * said "½" over a bend of 0.9 semitones and "1.3" over the next: two systems
+ * side by side, and a "½" read as half a semitone.
+ */
+export declare function bendLabel(semitones: number): string;
+/** The pitch movement a tied piece carries on from the head of its note. */
+export interface EffectCarry {
+    /** Where the note starts, and the pitch it is written at. */
+    start: number;
+    midi: number;
+    effect: PitchEffect;
+}
+/** A staff item, with the pitch effect of the note it is the head of. */
+export type ScoreItem = StaffItem & {
+    effect?: PitchEffect;
+    /**
+     * On a piece tied on after the head: the movement it is part of, when that movement is drawn
+     * along the note — a glissando or a bend held a bar or more — so a line that runs onto the next
+     * system can be carried on there and land where the note ends.
+     */
+    carry?: EffectCarry;
+    /** On a grand staff's voice: the stave the item stands on — see `crossStaffVoice`. */
+    staff?: 'treble' | 'bass';
+    /** The grace notes of the note this is the head of — see `ScoreNote.grace`. */
+    grace?: readonly number[];
+    /** The note is leaned on — see `accentedStarts`. */
+    accent?: boolean;
+    /** The note is an echo — see `ScoreNote.echo`. Its head is written in brackets. */
+    echo?: boolean;
+    /** The note is played short — see `ScoreNote.staccato`. A dot over its head. */
+    staccato?: boolean;
+    /**
+     * The other heads on this one's stem, struck at the same moment: on a percussion staff, drums by
+     * period — a cartridge plays its noise channel and its DMC samples at once, a hat over a kick; on
+     * a pitched staff, notes by MIDI number — a violin's double and triple stops.
+     */
+    chord?: readonly number[];
+    /**
+     * The APU level the note STARTS at, 0..15, as the ROM holds it — for a renderer to print under
+     * the head when asked. The dynamics are a reading of these numbers in six steps, which is what a
+     * player needs; the number itself is what the cartridge says, and the two answer different
+     * questions. Only on a head, and only where the channel has a volume at all: the triangle has
+     * none, so its notes carry nothing.
+     */
+    volume?: number;
+    /** Its beam runs across the bar line — see `crossBarRuns`. */
+    across?: 'start' | 'join';
+    /** Beams are grouped by this number rather than by the beat — see `accentBeamGroups`. */
+    beamGroup?: number;
+};
+/**
+ * How much louder than BOTH its neighbours a note has to start to be written as
+ * accented, in nibble steps.
+ *
+ * Three is the step the tracks themselves use: the driver holds a level and
+ * drops or lifts the next note by 3 — ragnarok's canyon, bar 25, alternates 4
+ * and 7 through the bar, and 7 against 4 is what the ear hears as the accent.
+ */
+export declare const ACCENT_STEP = 3;
+/**
+ * The notes a voice leans on: louder than the note before it by `ACCENT_STEP`,
+ * no quieter than the note after it, and NOT on a beat.
+ *
+ * Off the beat is the whole point. The driver moves the volume constantly, and
+ * a mark on every rise would put one under a third of the heads of some tracks
+ * while saying nothing a reader cannot see from the dynamics. What a reader
+ * cannot see is a voice that leans between the beats: ragnarok's canyon, bar 25,
+ * plays sixteenths at 9 9 7 7 4 7 4 7 4 2 7 7 4 7 4 9 — every beat of the bar
+ * but the first is a 4, and the 7s fall in the gaps. On paper that is an even
+ * run of sixteenths; in the ears it is a syncopation, and accents are what make
+ * the two agree.
+ *
+ * Read on the notes as the staff has them — after `voicePhase` has taken out a
+ * channel's authored delay — or a voice written a tick late would count as
+ * off the beat throughout.
+ */
+export declare function accentedStarts(notes: readonly ScoreNote[], beat?: number, step?: number): Set<number>;
+/**
+ * Beam groups that follow the ACCENTS rather than the beat, for a passage that
+ * is written in one pulse and played in another.
+ *
+ * Ragnarok's canyon from bar 25 is the case, and it is a case, not a rule:
+ * beats 2, 3 and 4 of every bar sit at volume 4 while the notes between them
+ * are at 7, so beaming by the quarter draws four even groups over a bar whose
+ * weight lands in five uneven ones — 3 2 3 3 2, each beginning on a note the
+ * ROM leans on. Tried as a general rule over the cartridge it made beams of 14,
+ * 16 and 32 heads elsewhere (wookie hole, Arctic Caverns), which is why the
+ * passage asks for it by tick.
+ *
+ * Numbers a group per head from `from` on: a new one at every accent, and one
+ * after the bar's LOUDEST head when what follows is quieter — the figure's own
+ * peak, which ends a group rather than joining the run under it. Bar 25 is the
+ * one that needs the second rule: bars 26 to 28 open on the two heads a beam
+ * has already carried over the bar line, while 25 opens on the same pair with
+ * nothing to carry them, and without it they were swallowed by the five heads
+ * up to the first accent.
+ */
+export declare function accentBeamGroups(bars: ScoreItem[][], 
+/** The passage the rule covers, in the staff's ticks: `[from, to)`. */
+{ from, to }: {
+    from: number;
+    to: number;
+}, 
+/** Each head's volume by its start tick — the levels the groups are read from. */
+levels: ReadonlyMap<number, number>): ScoreItem[][];
+/** The most notes a beam is carried across a bar line onto — the figure, and no more. */
+export declare const CROSS_BAR_RUN = 4;
+/**
+ * Figures a bar line cuts in half: a run that starts on the bar's last note and
+ * carries the same level into the next bar.
+ *
+ * Beams do not cross bar lines, and for good reason — the bar line is what a
+ * reader counts from. The exception earns itself when the figure is plainly one
+ * gesture and the bar line falls inside it: ragnarok's canyon, bars 25 to 28,
+ * ends each bar on an accented E3 and opens the next with D3 E3 at the same
+ * level 9, the run around it sitting at 7 and 4. Three heads, one gesture, and
+ * written bar by bar it reads as a stray sixteenth and a pair.
+ *
+ * Narrow on purpose: the last note must be ACCENTED (see `accentedStarts`), the
+ * run must be unbroken, every note must hold the same volume, and it stops after
+ * `CROSS_BAR_RUN` heads. Over the whole cartridge that is three places, all of
+ * them this figure. Loosened to "the level holds" alone it caught 148, some of
+ * them 240 notes long — a beam over half a track.
+ *
+ * Returns the start tick of each note in a crossing run, mapped to its part in
+ * it: the `start` is the note the beam leaves the bar on, the `join`s are the
+ * heads it reaches on the other side.
+ */
+export declare function crossBarRuns(notes: readonly ScoreNote[], grid: BarGrid, accents?: ReadonlySet<number>): Map<number, 'start' | 'join'>;
+/** Whether an effect is drawn along its note — and so has to carry on where the note does. */
+export declare function drawnAlong(effect: PitchEffect, measureTicks?: number): boolean;
+/** A noise hit: when, for how long, and which `$400E` period. */
+export interface ScoreHit {
+    start: number;
+    ticks: number;
+    period: number;
+    /** The APU level the hit starts at, 0..15 — see `ScoreItem.volume`. */
+    volume?: number;
+}
+export type ScoreStaveKind = 'treble' | 'bass' | 'percussion';
+export interface ScoreStave {
+    partId: string;
+    kind: ScoreStaveKind;
+    /**
+     * One list of items per bar. Filled to the bar line — except on a grand
+     * staff, where it is only what stands on THIS stave, for the layout.
+     */
+    bars: ScoreItem[][];
+    /** On a grand staff's upper stave: the part's whole voice, filled to the bar line, drawn across both. */
+    voiceBars?: ScoreItem[][];
+    /** On a grand staff's lower stave: its notes belong to the voice of the stave above. */
+    follows?: boolean;
+}
+export interface ScoreModel {
+    /** Ticks added to the piece's clock to get the score's — see `staffShift`. */
+    shift: number;
+    /** Where the bar lines fall: the metre, and the opening bar's own length. */
+    grid: BarGrid;
+    barCount: number;
+    staves: ScoreStave[];
+    /** Each part's marks, in the SCORE's ticks. */
+    dynamics: Record<string, DynamicMark[]>;
+    /**
+     * Each part's own delay taken out (`voicePhase`), in ticks: its notes sit
+     * this much EARLIER on the staff than on the piece's clock. Anything that
+     * compares a staff tick with the piece's — hiding what has not been read
+     * yet — has to take it out too.
+     */
+    phases: Record<string, number>;
+}
+/** Where a piece changes key: the tick the new key starts on, and its VexFlow name. */
+export interface KeyChange {
+    /** In the PIECE's ticks, as the ROM holds them. */
+    tick: number;
+    key: string;
+}
+/**
+ * The key each bar of a score is written in.
+ *
+ * A change takes effect from the bar its tick falls in — the tick is moved onto
+ * the staff's clock by `shift` first — so it stays with the music when the bar
+ * line or the metre is read differently. Volkmire's Inferno Race turns from D
+ * minor to D major on tick 870, which is bar 29 of its 2/4 score.
+ */
+export declare function barKeys(barCount: number, shift: number, grid: BarGrid, opening: string, changes?: readonly KeyChange[]): string[];
+/** The part id the percussion staff carries. */
+export declare const DRUMS_PART = "drums";
+/** How a score is barred and read — everything `buildScore` takes beyond the notes. */
+export interface ScoreOptions {
+    /** The tick the bar lines are counted from. Default 0. */
+    offset?: number;
+    /** Ticks in a bar: 64 is 4/4, 32 is 2/4. Default `MEASURE_TICKS`. */
+    measureTicks?: number;
+    /**
+     * Write the pickup as part of the opening bar rather than in a bar of its own.
+     *
+     * The music then starts on the score's first tick, and the opening bar is as
+     * much longer than the metre as the pickup is — one bar of 19/32 in front of
+     * Volkmire's Inferno Race's 2/4, instead of a bar of rests with the run in it.
+     */
+    mergePickup?: boolean;
+    /**
+     * The passage read by its accents: the only place accents are marked (`accentedStarts`), and
+     * where the beams follow them rather than the beat (`accentBeamGroups`). None given, no accents.
+     * In the PIECE's ticks, like everything a caller gives; `shift` moves it onto the staff's clock.
+     */
+    accentBeams?: {
+        from: number;
+        to: number;
+    };
+    /** Bars later in the piece with a length of their own — see `BarGrid`. */
+    oddBars?: readonly OddBar[];
+    /**
+     * Take a part's own delay of up to `MAX_PHASE` ticks out (`voicePhase`). Default true: a sound
+     * driver delays a channel a tick or two on purpose, and the staff writes it on the beat. Music
+     * that is already on its beat — a MIDI file — wants it off, or a voice is moved off the beat it
+     * keeps.
+     */
+    alignVoices?: boolean;
+}
+/**
+ * The whole score, worked out once.
+ *
+ * `options.offset` is the tick the bar lines are counted from and
+ * `options.measureTicks` the length of a bar; any other notation view of the
+ * same piece should use the same two, so they all bar the music the same way.
+ */
+export declare function buildScore(parts: readonly {
+    id: string;
+    notes: readonly ScoreNote[];
+    /** Which staves, when the caller decides rather than the notes (`partStaves`). */
+    staves?: readonly ('treble' | 'bass')[];
+}[], drums: readonly ScoreHit[], totalTicks: number, { offset, measureTicks, mergePickup, accentBeams, oddBars, alignVoices, }?: ScoreOptions): ScoreModel;