@typeonce/ritmo-tools 0.17.0 → 0.19.0

package/dist/music/core/check.d.ts

@@ -0,0 +1,51 @@
+import { type NoteCache } from "./render.ts";
+import { type Song } from "./song.ts";
+export type Severity = "error" | "warning";
+export interface Issue {
+    readonly rule: string;
+    readonly severity: Severity;
+    /** The track it is about, by name; none for the whole song. */
+    readonly track?: string | undefined;
+    readonly message: string;
+}
+export interface TrackReport {
+    readonly name: string;
+    readonly instrument: string;
+    readonly notes: number;
+    /** RMS in dBFS of the track alone, at its volume. */
+    readonly loudness: number;
+    readonly range: readonly [string, string] | undefined;
+}
+export interface Follow {
+    /** The track whose notes follow the reference most closely. */
+    readonly track: string;
+    /** Share of the reference's notes this track also plays at that moment (same note, any octave), 0 to 1. */
+    readonly share: number;
+}
+export type Verdict = "clean" | "warnings" | "errors";
+export interface SongReport {
+    readonly verdict: Verdict;
+    readonly seconds: number;
+    readonly bars: number;
+    readonly tempo: number;
+    readonly key: string;
+    readonly peak: number;
+    readonly loudness: number;
+    readonly tracks: ReadonlyArray<TrackReport>;
+    readonly follows?: Follow | undefined;
+    readonly issues: ReadonlyArray<Issue>;
+}
+export declare const limits: {
+    /** Past full scale, samples are clipped (dBFS). */
+    readonly clipping: -0.1;
+    /** Game music this quiet gets lost under the sounds (RMS dBFS). */
+    readonly quiet: -30;
+    /** A track this much quieter than the loudest one is barely heard (dB). */
+    readonly buried: 18;
+    /** A melody following less than this share of the reference has wandered off it. */
+    readonly follows: 0.5;
+};
+/** How closely each melodic track follows the reference's notes; the closest one. */
+export declare const followOf: (song: Song) => Follow | undefined;
+export declare const checkSong: (song: Song, cache?: NoteCache) => SongReport;
+//# sourceMappingURL=check.d.ts.map

package/dist/music/core/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/music/core/check.ts"],"names":[],"mappings":"AASA,OAAO,EAAkC,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,EAA2E,KAAK,IAAI,EAAE,MAAM,WAAW,CAAA;AAE9G,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAA;AAE1C,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;CACtD;AAED,MAAM,WAAW,MAAM;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,2GAA2G;IAC3G,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAA;AAErD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;CACtC;AAED,eAAO,MAAM,MAAM;IACjB,mDAAmD;aACnD,QAAQ,EAAE,CAAC,GAAG;IACd,mEAAmE;aACnE,KAAK,EAAE,CAAC,EAAE;IACV,2EAA2E;aAC3E,MAAM,EAAE,EAAE;IACV,oFAAoF;aACpF,OAAO,EAAE,GAAG;CACJ,CAAA;AAIV,qFAAqF;AACrF,eAAO,MAAM,QAAQ,SAAU,IAAI,KAAG,MAAM,GAAG,SAiB9C,CAAA;AAED,eAAO,MAAM,SAAS,SAAU,IAAI,UAAU,SAAS,KAAG,UAuDzD,CAAA"}

package/dist/music/core/check.js

@@ -0,0 +1,113 @@
+/**
+ * Checking a song: what the agent can know about it without hearing it.
+ * It renders the song and measures it (length, peak, loudness, each track's
+ * loudness), and reads its notes for what usually sounds wrong: notes out of
+ * the key, notes an instrument cannot play well, a track drowned by the
+ * others, the same note struck twice at once. With a reference, it says how
+ * closely the song's melody follows it.
+ */
+import { instruments } from "./instruments.js";
+import { loudnessOf, peakOf, renderSong } from "./render.js";
+import { barsOf, inKey, lengthInBeats, lengthInSeconds, midiOf, nameOf, parseKey } from "./song.js";
+export const limits = {
+    /** Past full scale, samples are clipped (dBFS). */
+    clipping: -0.1,
+    /** Game music this quiet gets lost under the sounds (RMS dBFS). */
+    quiet: -30,
+    /** A track this much quieter than the loudest one is barely heard (dB). */
+    buried: 18,
+    /** A melody following less than this share of the reference has wandered off it. */
+    follows: 0.5
+};
+const round = (value) => Math.round(value * 10) / 10;
+/** How closely each melodic track follows the reference's notes; the closest one. */
+export const followOf = (song) => {
+    const reference = song.reference;
+    if (reference === undefined || reference.notes.length === 0)
+        return undefined;
+    let best;
+    for (const track of song.tracks) {
+        if (instruments[track.instrument].kind === "drums")
+            continue;
+        let matched = 0;
+        for (const heard of reference.notes) {
+            const pitch = midiOf(heard.pitch);
+            const at = heard.at + reference.offset + Math.min(heard.length, 0.25) / 2;
+            const hit = track.notes.some((note) => note.at <= at && at < note.at + note.length && (((midiOf(note.pitch) ?? -1) - (pitch ?? 0)) % 12 + 12) % 12 === 0);
+            if (hit)
+                matched++;
+        }
+        const share = Math.round((matched / reference.notes.length) * 100) / 100;
+        if (best === undefined || share > best.share)
+            best = { track: track.name, share };
+    }
+    return best;
+};
+export const checkSong = (song, cache) => {
+    const issues = [];
+    const key = parseKey(song.key);
+    const end = lengthInBeats(song);
+    const mix = renderSong(song, { cache });
+    const peak = peakOf(mix);
+    const loudness = loudnessOf(mix);
+    const tracks = song.tracks.map((track, index) => {
+        const instrument = instruments[track.instrument];
+        const melodic = instrument.kind === "melodic";
+        const midis = melodic ? track.notes.flatMap((note) => midiOf(note.pitch) ?? []) : [];
+        if (track.notes.length === 0)
+            issues.push({ rule: "empty-track", severity: "warning", track: track.name, message: "Has no notes." });
+        if (melodic && key !== undefined) {
+            const outside = track.notes.filter((note) => !inKey(key, midiOf(note.pitch) ?? 0));
+            if (outside.length > 0) {
+                const listed = outside.slice(0, 6).map((note) => `${note.pitch} (${barsOf(song, note.at, note.at + note.length)})`);
+                issues.push({ rule: "out-of-key", severity: "warning", track: track.name, message: `${outside.length} note${outside.length === 1 ? " is" : "s are"} outside ${song.key}: ${listed.join(", ")}${outside.length > 6 ? ", …" : ""}. Fine for a passing color; otherwise move ${outside.length === 1 ? "it" : "them"} to a note of the key.` });
+            }
+        }
+        if (melodic) {
+            const [low, high] = instrument.range;
+            const outOfRange = midis.filter((midi) => midi < low || midi > high);
+            if (outOfRange.length > 0)
+                issues.push({ rule: "range", severity: "warning", track: track.name, message: `${outOfRange.length} note${outOfRange.length === 1 ? "" : "s"} outside what the ${instrument.label.toLowerCase()} plays well (${nameOf(low)} to ${nameOf(high)}): ${[...new Set(outOfRange.map(nameOf))].slice(0, 6).join(", ")}.` });
+        }
+        const late = track.notes.filter((note) => note.at >= end);
+        if (late.length > 0)
+            issues.push({ rule: "past-the-end", severity: "warning", track: track.name, message: `${late.length} note${late.length === 1 ? " starts" : "s start"} after the song's last bar (${song.bars}) and ${late.length === 1 ? "is" : "are"} never heard. Add bars or move ${late.length === 1 ? "it" : "them"}.` });
+        // The same note struck again while it still sounds: two copies at once, or a note cut short.
+        let doubled = 0;
+        const sorted = [...track.notes].sort((a, b) => a.at - b.at);
+        for (let i = 0; i < sorted.length; i++) {
+            for (let j = i + 1; j < sorted.length && sorted[j].at < sorted[i].at + sorted[i].length - 1e-6; j++)
+                if (sorted[j].pitch === sorted[i].pitch)
+                    doubled++;
+        }
+        if (doubled > 0)
+            issues.push({ rule: "overlap", severity: "warning", track: track.name, message: `${doubled} note${doubled === 1 ? " starts" : "s start"} while the same note is still held. Shorten the first, or remove one.` });
+        // Each track alone, uncompressed: the compressor would lift a buried track and hide it.
+        const alone = loudnessOf(renderSong({ ...song, compressor: false }, { tracks: [index], cache }));
+        return {
+            name: track.name,
+            instrument: track.instrument,
+            notes: track.notes.length,
+            loudness: alone,
+            range: midis.length === 0 ? undefined : [nameOf(Math.min(...midis)), nameOf(Math.max(...midis))]
+        };
+    });
+    if (song.tracks.every((track) => track.notes.length === 0))
+        issues.push({ rule: "silent", severity: "error", message: "No track has notes: the song is silent." });
+    else if (peak > limits.clipping)
+        issues.push({ rule: "clipping", severity: "error", message: `Peaks at +${round(Math.max(0, peak))} dBFS: it clips and distorts. Lower master by about ${Math.ceil(peak + 1)} dB (master × ${round(Math.pow(10, -(peak + 1) / 20))}).` });
+    else if (loudness < limits.quiet)
+        issues.push({ rule: "quiet", severity: "warning", message: `${loudness} dBFS overall: quiet for game music (about -18 to -24 sits well under sound effects). Raise master.` });
+    const heard = tracks.filter((track, i) => track.notes > 0 && song.tracks[i].mute !== true);
+    const loudest = Math.max(...heard.map((track) => track.loudness));
+    for (const track of heard) {
+        if (loudest - track.loudness > limits.buried)
+            issues.push({ rule: "buried", severity: "warning", track: track.name, message: `${round(loudest - track.loudness)} dB under the loudest track: barely heard. Raise its volume, or drop it.` });
+    }
+    const follows = followOf(song);
+    if (follows !== undefined && follows.share < limits.follows)
+        issues.push({ rule: "off-reference", severity: "warning", message: `The closest track (${follows.track}) plays ${Math.round(follows.share * 100)}% of the reference's notes: the melody has wandered from the hum. Keep its notes, or say why not.` });
+    const verdict = issues.some((issue) => issue.severity === "error") ? "errors" : issues.length > 0 ? "warnings" : "clean";
+    return { verdict, seconds: round(lengthInSeconds(song)), bars: song.bars, tempo: song.tempo, key: song.key, peak, loudness, tracks, follows, issues };
+};
+//# sourceMappingURL=check.js.map

package/dist/music/core/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../../src/music/core/check.ts"],"names":[],"mappings":"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"}

package/dist/music/core/instruments.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The instruments a song can use: each one is synthesized from a small
+ * model of how the real instrument makes its sound (a plucked string for
+ * the guitar, struck strings for the piano, a breath and a tube for the
+ * flute), so they need no sample files and play the same bits everywhere.
+ *
+ * Each instrument turns one note (a pitch, how long it is held, how hard it
+ * is played) into mono samples; the renderer places, pans, and mixes them.
+ */
+export type InstrumentKind = "melodic" | "drums";
+export interface Instrument {
+    readonly label: string;
+    readonly kind: InstrumentKind;
+    /** What it sounds like and what it is good for, for the agent and the person. */
+    readonly about: string;
+    /** The lowest and highest notes it plays well, as MIDI numbers. */
+    readonly range: readonly [number, number];
+    /** The General MIDI program a MIDI export names for it (drums use channel 10). */
+    readonly program: number;
+    /** The page draws its notes in this color. */
+    readonly color: string;
+}
+export declare const instruments: {
+    readonly piano: {
+        readonly label: "Piano";
+        readonly kind: "melodic";
+        readonly about: "A grand piano: chords, melodies, bass. Warm and full; notes ring and fade.";
+        readonly range: readonly [21, 108];
+        readonly program: 0;
+        readonly color: "#7aa2f7";
+    };
+    readonly epiano: {
+        readonly label: "Electric piano";
+        readonly kind: "melodic";
+        readonly about: "A soft electric piano (Rhodes): mellow chords, lo-fi and cozy tunes.";
+        readonly range: readonly [28, 103];
+        readonly program: 4;
+        readonly color: "#9d8cf7";
+    };
+    readonly guitar: {
+        readonly label: "Acoustic guitar";
+        readonly kind: "melodic";
+        readonly about: "A plucked steel-string guitar: strummed chords, picked patterns (arpeggios), folk melodies.";
+        readonly range: readonly [40, 88];
+        readonly program: 25;
+        readonly color: "#f0a843";
+    };
+    readonly bass: {
+        readonly label: "Bass guitar";
+        readonly kind: "melodic";
+        readonly about: "A plucked electric bass: the low line under the chords, one note at a time.";
+        readonly range: readonly [28, 60];
+        readonly program: 33;
+        readonly color: "#e06c75";
+    };
+    readonly strings: {
+        readonly label: "Strings";
+        readonly kind: "melodic";
+        readonly about: "A string section: long held chords that swell in, sweeping melodies. Slow to start, so give it long notes.";
+        readonly range: readonly [28, 96];
+        readonly program: 48;
+        readonly color: "#56b6c2";
+    };
+    readonly flute: {
+        readonly label: "Flute";
+        readonly kind: "melodic";
+        readonly about: "A breathy wooden flute: gentle melodies, one note at a time, best in its middle and high notes.";
+        readonly range: readonly [60, 96];
+        readonly program: 73;
+        readonly color: "#98c379";
+    };
+    readonly marimba: {
+        readonly label: "Marimba";
+        readonly kind: "melodic";
+        readonly about: "Wooden bars struck by mallets: short bright notes, playful patterns.";
+        readonly range: readonly [45, 96];
+        readonly program: 12;
+        readonly color: "#d19a66";
+    };
+    readonly bells: {
+        readonly label: "Bells";
+        readonly kind: "melodic";
+        readonly about: "Glassy bells: sparkle, magic, a few long high notes over the rest.";
+        readonly range: readonly [60, 108];
+        readonly program: 9;
+        readonly color: "#e5c07b";
+    };
+    readonly pad: {
+        readonly label: "Warm pad";
+        readonly kind: "melodic";
+        readonly about: "A soft synth pad: a cushion of held chords behind everything; slow to swell.";
+        readonly range: readonly [36, 96];
+        readonly program: 89;
+        readonly color: "#c678dd";
+    };
+    readonly chipLead: {
+        readonly label: "Chip lead";
+        readonly kind: "melodic";
+        readonly about: "A retro game-console square wave: chiptune melodies, one note at a time.";
+        readonly range: readonly [48, 96];
+        readonly program: 80;
+        readonly color: "#4cc38a";
+    };
+    readonly chipBass: {
+        readonly label: "Chip bass";
+        readonly kind: "melodic";
+        readonly about: "A retro game-console triangle wave: chiptune bass lines.";
+        readonly range: readonly [28, 72];
+        readonly program: 38;
+        readonly color: "#2fb3a3";
+    };
+    readonly rockGuitar: {
+        readonly label: "Distorted guitar";
+        readonly kind: "melodic";
+        readonly about: "An electric guitar through an overdriven amp: rock riffs, power chords (a note and the one seven semitones up), crunchy rhythm parts.";
+        readonly range: readonly [40, 88];
+        readonly program: 30;
+        readonly color: "#ff7b54";
+    };
+    readonly reese: {
+        readonly label: "Reese bass";
+        readonly kind: "melodic";
+        readonly about: "Detuned saws, a sub, and grit, slowly moving: the drum & bass bass, also for dark electronic lines. One note at a time; hold notes long.";
+        readonly range: readonly [28, 60];
+        readonly program: 38;
+        readonly color: "#b4475a";
+    };
+    readonly synthLead: {
+        readonly label: "Synth lead";
+        readonly kind: "melodic";
+        readonly about: "A wide stack of detuned saws (a supersaw): modern electronic leads and riffs, bright and big. One note at a time.";
+        readonly range: readonly [48, 96];
+        readonly program: 81;
+        readonly color: "#3fb6f2";
+    };
+    readonly drums: {
+        readonly label: "Drum kit";
+        readonly kind: "drums";
+        readonly about: "A clean drum kit. Its notes are drums, not pitches: kick, snare, hat, openHat, clap, tomLow, tomHigh, crash, rim, shaker.";
+        readonly range: readonly [0, 127];
+        readonly program: 0;
+        readonly color: "#bdbab3";
+    };
+    readonly breaks: {
+        readonly label: "Punchy kit";
+        readonly kind: "drums";
+        readonly about: "A hard-hitting kit for rock, drum & bass, and electronic music: a clicky, driven kick, a cracking snare, crisp hats. The same drums as the drum kit.";
+        readonly range: readonly [0, 127];
+        readonly program: 0;
+        readonly color: "#e8e3d5";
+    };
+};
+export type InstrumentId = keyof typeof instruments;
+export declare const instrumentIds: ReadonlyArray<InstrumentId>;
+/** The instruments whose notes are drums. */
+export type KitId = "drums" | "breaks";
+export declare const isKit: (id: InstrumentId) => id is KitId;
+export type DrumName = "kick" | "snare" | "hat" | "openHat" | "clap" | "tomLow" | "tomHigh" | "crash" | "rim" | "shaker";
+/** The drums, top to bottom as the page lists them, with their General MIDI numbers. */
+export declare const drums: ReadonlyArray<{
+    readonly name: DrumName;
+    readonly label: string;
+    readonly gm: number;
+}>;
+export declare const drumNames: ReadonlyArray<string>;
+export declare const isDrum: (name: string) => name is DrumName;
+export interface NoteInput {
+    readonly midi: number;
+    /** How long the note is held, in seconds. */
+    readonly held: number;
+    readonly velocity: number;
+    readonly rate: number;
+    readonly random: () => number;
+}
+/** One note of a melodic instrument (`midi` a MIDI number), as mono samples from the note's start. */
+export declare const playVoice: (instrument: Exclude<InstrumentId, KitId>, midi: number, held: number, velocity: number, rate: number, random: () => number) => Float32Array;
+/** One hit of a drum kit, as mono samples from the hit. */
+export declare const playDrum: (kit: KitId, name: DrumName, velocity: number, rate: number, random: () => number) => Float32Array;
+//# sourceMappingURL=instruments.d.ts.map

package/dist/music/core/instruments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruments.d.ts","sourceRoot":"","sources":["../../../src/music/core/instruments.ts"],"names":[],"mappings":"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"}