@ac-kit/model-music 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @ac-kit/model-music
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [235ec3c]
+  - @ac-kit/core@0.5.0
+  - @ac-kit/algo@0.2.2
+
+## 0.1.0
+
+### Minor Changes
+
+- eb2aa3d: First release: `Song`, a piece of music as notes timed in ticks and seconds,
+  with its parts, `TempoMap` (`composeTempoMap`, `tempoMapSeconds`,
+  `tempoMapTick`), time and key signatures, measures (`composeMeasures`), pedals,
+  markers and lyrics.
+
+### Patch Changes
+
+- Updated dependencies [aca1cb1]
+  - @ac-kit/core@0.4.0
+  - @ac-kit/algo@0.2.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-2026 Anthony Champagne and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @ac-kit/model-music
 
-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.
+Music as plain data: a `Song` lists the notes to play with the time each one is
+played at, in ticks and in seconds, together with the parts, tempo map, meter,
+key, measures, pedals, markers and lyrics around them.
+
+```ts
+import {
+  composeMeasures,
+  composeTempoMap,
+  tempoMapSeconds,
+} from "@ac-kit/model-music";
+
+const tempoMap = composeTempoMap(480, [
+  { tick: 0, microsecondsPerQuarterNote: 600_000 },
+  { tick: 7680, microsecondsPerQuarterNote: 500_000 },
+]);
+
+tempoMapSeconds(tempoMap, 1920); // 2.4
+composeMeasures([{ tick: 0, numerator: 3, denominator: 4 }], tempoMap, 7680);
+```
+
+## What it is for
+
+One description of a piece, several sources and several readers. A Standard
+MIDI File and a MusicXML score both convert to a `Song`; a practice tool, a
+falling-notes view and a player read it without knowing where it came from.
+`@ac-kit/format-midi` provides the MIDI conversion.
+
+## Contents
+
+- `Song`, `SongPart`, `SongNote`, `Spelling`, `SongPedal`, `SongMarker`,
+  `SongLyric` — the description. A note carries its part, staff, voice, MIDI
+  pitch, velocity and its start and end, plus the written spelling, fingering
+  and grace flag a score provides and a MIDI file cannot.
+- `TempoMap`, `composeTempoMap`, `tempoMapSeconds`, `tempoMapTick` — ticks to
+  seconds and back, under every tempo change.
+- `TimeSignature`, `KeySignature`, `Measure`, `composeMeasures` — the meter,
+  and measures built from it when the source has none of its own.
+
+See the
+[generated API docs](https://anthochamp.github.io/node-essentials/api/model-music/)
+for the full reference.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./song/song.js";
+export * from "./time/meter.js";
+export * from "./time/tempo-map.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./song/song.js";
+export * from "./time/meter.js";
+export * from "./time/tempo-map.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,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}

package/dist/song/song.d.ts

@@ -0,0 +1,96 @@
+import type { KeySignature, Measure, TimeSignature } from "../time/meter.js";
+import type { TempoMap } from "../time/tempo-map.js";
+/**
+ * A piece of music as the notes to play and the time each is played at, with
+ * what a score or a player needs around them.
+ *
+ * Every `tick` counts in `tempoMap.ticksPerQuarterNote`, and every `seconds` is
+ * the time from the start of the song under that tempo map. Every list is
+ * sorted by tick; `notes` by start tick, then by pitch.
+ */
+export type Song = {
+    title: string | undefined;
+    tempoMap: TempoMap;
+    /** Where the song ends: its last event, or the end of its last note. */
+    endTick: number;
+    endSeconds: number;
+    parts: SongPart[];
+    notes: SongNote[];
+    timeSignatures: TimeSignature[];
+    keySignatures: KeySignature[];
+    measures: Measure[];
+    markers: SongMarker[];
+    pedals: SongPedal[];
+    lyrics: SongLyric[];
+};
+/** One instrument's part, which notes and pedals refer to by index. */
+export type SongPart = {
+    name: string | undefined;
+    /** General MIDI program, 0–127, when the source names one. */
+    program: number | undefined;
+    /** Unpitched percussion: `pitch` then names a drum, not a pitch. */
+    percussion: boolean;
+    /** Staves the part is written on: 2 for a piano's grand staff. */
+    staves: number;
+};
+/** A pitch as written: letter, alteration and octave. */
+export type Spelling = {
+    step: "A" | "B" | "C" | "D" | "E" | "F" | "G";
+    /** Semitones: -1 flat, 1 sharp; fractions for microtones. */
+    alter: number;
+    /** Scientific pitch notation: middle C is C4. */
+    octave: number;
+};
+/** One sounding note. Tied notes are one note. */
+export type SongNote = {
+    /** Index into `Song.parts`. */
+    part: number;
+    /** 1-based staff of the part, when the source says. */
+    staff: number | undefined;
+    /** Voice within the part, when the source says. */
+    voice: number | undefined;
+    /** MIDI note number, 0–127; 60 is middle C. */
+    pitch: number;
+    /** On the MIDI velocity scale, 1–127. */
+    velocity: number;
+    startTick: number;
+    endTick: number;
+    startSeconds: number;
+    endSeconds: number;
+    /** The written pitch, which the MIDI number alone cannot tell (C♯ or D♭). */
+    spelling?: Spelling;
+    /** Finger number, 1 (thumb) to 5. */
+    fingering?: number;
+    /** A grace note, played in no time of its own as written. */
+    grace?: boolean;
+};
+/** A named point in the song. */
+export type SongMarker = {
+    tick: number;
+    seconds: number;
+    text: string;
+    /** `rehearsal` is a score's rehearsal mark; `cue` a cue point for a performer. */
+    kind: "marker" | "cue" | "rehearsal";
+};
+/** A pedal position from `tick` on, until the next change of the same pedal. */
+export type SongPedal = {
+    /** Index into `Song.parts`. */
+    part: number;
+    tick: number;
+    seconds: number;
+    pedal: "sustain" | "sostenuto" | "soft";
+    /** 0 is released, 1 fully pressed; values between are half-pedalling. */
+    value: number;
+};
+/** One sung syllable. */
+export type SongLyric = {
+    /** Index into `Song.parts`, when the lyrics belong to one. */
+    part: number | undefined;
+    tick: number;
+    seconds: number;
+    /** The syllable, with the spaces between words. */
+    text: string;
+    /** A break before the syllable: a new line, or a new paragraph or screen. */
+    break: "none" | "line" | "paragraph";
+};
+//# sourceMappingURL=song.d.ts.map

package/dist/song/song.d.ts.map

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

package/dist/song/song.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=song.js.map

package/dist/song/song.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"song.js","sourceRoot":"","sources":["../../src/song/song.ts"],"names":[],"mappings":""}

package/dist/time/meter.d.ts

@@ -0,0 +1,64 @@
+import { type TempoMap } from "./tempo-map.js";
+/**
+ * A time signature in force from `tick` on: `numerator` beats of
+ * `1/denominator` notes per measure.
+ */
+export type TimeSignature = {
+    tick: number;
+    /** Beats per measure, 1 or more. */
+    numerator: number;
+    /** The beat's note value: 4 is a quarter note, 8 an eighth. A power of two. */
+    denominator: number;
+};
+/** The mode of a key signature, as MusicXML names them. */
+export type KeyMode = "major" | "minor" | "ionian" | "dorian" | "phrygian" | "lydian" | "mixolydian" | "aeolian" | "locrian" | "none";
+/** A key signature in force from `tick` on. */
+export type KeySignature = {
+    tick: number;
+    /** Sharps when positive, flats when negative, -7–7. */
+    fifths: number;
+    mode: KeyMode;
+};
+/** One measure: where it starts and ends, and the meter it is in. */
+export type Measure = {
+    /** The measure number as printed: `"1"`, `"12a"`, `"0"` for a pickup. */
+    label: string;
+    startTick: number;
+    endTick: number;
+    startSeconds: number;
+    endSeconds: number;
+    numerator: number;
+    denominator: number;
+};
+/** 4/4, the meter of a song before any time signature (MIDI RP-001). */
+export declare const DEFAULT_TIME_SIGNATURE: Omit<TimeSignature, "tick">;
+/**
+ * Divides a song into measures from its time signatures, numbering them from 1,
+ * when nothing gives the measures themselves — a MIDI file, unlike a score.
+ *
+ * - Before the first time signature, or with none, the meter is
+ *   {@link DEFAULT_TIME_SIGNATURE}, 4/4.
+ * - A time signature falling inside a measure cuts that measure short, and the
+ *   next one starts at the change.
+ * - Measures cover `[0, endTick)`, with at least one; the last one keeps its full
+ *   length past `endTick`.
+ *
+ * Time complexity: O(m + s) in the number of measures and of time signatures,
+ * plus O(m log t) in the tempo changes for the times. Memory: O(m).
+ *
+ * @example
+ * 	composeMeasures([], composeTempoMap(96, []), 400).map(
+ * 		({ startTick }) => startTick,
+ * 	);
+ * 	// [0, 384]
+ *
+ * @param timeSignatures - Sorted by tick.
+ * @param tempoMap - The song's tempo map, for the times and the tick
+ *   resolution.
+ * @param endTick - Where the song ends.
+ * @returns The measures, in order.
+ * @throws {RangeError} When a time signature has a numerator below 1 or a
+ *   denominator that is not a power of two, or when they are not sorted.
+ */
+export declare function composeMeasures(timeSignatures: readonly TimeSignature[], tempoMap: TempoMap, endTick: number): Measure[];
+//# sourceMappingURL=meter.d.ts.map

package/dist/time/meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.d.ts","sourceRoot":"","sources":["../../src/time/meter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,QAAQ,EAAmB,MAAM,gBAAgB,CAAC;AAEhE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,OAAO,GAChB,OAAO,GACP,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,SAAS,GACT,SAAS,GACT,MAAM,CAAC;AAEV,+CAA+C;AAC/C,MAAM,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACd,CAAC;AAEF,qEAAqE;AACrE,MAAM,MAAM,OAAO,GAAG;IACrB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,CAG9D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAC9B,cAAc,EAAE,SAAS,aAAa,EAAE,EACxC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,GACb,OAAO,EAAE,CAkDX"}

package/dist/time/meter.js

@@ -0,0 +1,79 @@
+import { isPowerOfTwo } from "@ac-kit/core";
+import { tempoMapSeconds } from "./tempo-map.js";
+/** 4/4, the meter of a song before any time signature (MIDI RP-001). */
+export const DEFAULT_TIME_SIGNATURE = {
+    numerator: 4,
+    denominator: 4,
+};
+/**
+ * Divides a song into measures from its time signatures, numbering them from 1,
+ * when nothing gives the measures themselves — a MIDI file, unlike a score.
+ *
+ * - Before the first time signature, or with none, the meter is
+ *   {@link DEFAULT_TIME_SIGNATURE}, 4/4.
+ * - A time signature falling inside a measure cuts that measure short, and the
+ *   next one starts at the change.
+ * - Measures cover `[0, endTick)`, with at least one; the last one keeps its full
+ *   length past `endTick`.
+ *
+ * Time complexity: O(m + s) in the number of measures and of time signatures,
+ * plus O(m log t) in the tempo changes for the times. Memory: O(m).
+ *
+ * @example
+ * 	composeMeasures([], composeTempoMap(96, []), 400).map(
+ * 		({ startTick }) => startTick,
+ * 	);
+ * 	// [0, 384]
+ *
+ * @param timeSignatures - Sorted by tick.
+ * @param tempoMap - The song's tempo map, for the times and the tick
+ *   resolution.
+ * @param endTick - Where the song ends.
+ * @returns The measures, in order.
+ * @throws {RangeError} When a time signature has a numerator below 1 or a
+ *   denominator that is not a power of two, or when they are not sorted.
+ */
+export function composeMeasures(timeSignatures, tempoMap, endTick) {
+    let previousTick = 0;
+    for (const { tick, numerator, denominator } of timeSignatures) {
+        if (!(numerator >= 1 && Number.isInteger(numerator))) {
+            throw new RangeError(`time signature numerator ${numerator} is below 1`);
+        }
+        if (!(denominator >= 1) || isPowerOfTwo(denominator) !== true) {
+            throw new RangeError(`time signature denominator ${denominator} is not a power of two`);
+        }
+        if (!(tick >= previousTick)) {
+            throw new RangeError(`time signature at tick ${tick} is out of order`);
+        }
+        previousTick = tick;
+    }
+    const measures = [];
+    let meter = DEFAULT_TIME_SIGNATURE;
+    let nextIndex = 0;
+    let startTick = 0;
+    let startSeconds = 0;
+    while (startTick < endTick || measures.length === 0) {
+        while (nextIndex < timeSignatures.length &&
+            timeSignatures[nextIndex].tick <= startTick) {
+            meter = timeSignatures[nextIndex];
+            nextIndex++;
+        }
+        const fullLength = (tempoMap.ticksPerQuarterNote * 4 * meter.numerator) / meter.denominator;
+        const nextChangeTick = timeSignatures[nextIndex]?.tick ?? Infinity;
+        const endOfMeasure = Math.min(startTick + fullLength, nextChangeTick);
+        const endSeconds = tempoMapSeconds(tempoMap, endOfMeasure);
+        measures.push({
+            label: String(measures.length + 1),
+            startTick,
+            endTick: endOfMeasure,
+            startSeconds,
+            endSeconds,
+            numerator: meter.numerator,
+            denominator: meter.denominator,
+        });
+        startTick = endOfMeasure;
+        startSeconds = endSeconds;
+    }
+    return measures;
+}
+//# sourceMappingURL=meter.js.map

package/dist/time/meter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.js","sourceRoot":"","sources":["../../src/time/meter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAiB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AA+ChE,wEAAwE;AACxE,MAAM,CAAC,MAAM,sBAAsB,GAAgC;IAClE,SAAS,EAAE,CAAC;IACZ,WAAW,EAAE,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,eAAe,CAC9B,cAAwC,EACxC,QAAkB,EAClB,OAAe;IAEf,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,KAAK,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,cAAc,EAAE,CAAC;QAC/D,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,IAAI,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,UAAU,CAAC,4BAA4B,SAAS,aAAa,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,IAAI,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE,CAAC;YAC/D,MAAM,IAAI,UAAU,CACnB,8BAA8B,WAAW,wBAAwB,CACjE,CAAC;QACH,CAAC;QACD,IAAI,CAAC,CAAC,IAAI,IAAI,YAAY,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,UAAU,CAAC,0BAA0B,IAAI,kBAAkB,CAAC,CAAC;QACxE,CAAC;QACD,YAAY,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,IAAI,KAAK,GAAG,sBAAsB,CAAC;IACnC,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,OAAO,SAAS,GAAG,OAAO,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,OACC,SAAS,GAAG,cAAc,CAAC,MAAM;YACjC,cAAc,CAAC,SAAS,CAAE,CAAC,IAAI,IAAI,SAAS,EAC3C,CAAC;YACF,KAAK,GAAG,cAAc,CAAC,SAAS,CAAE,CAAC;YACnC,SAAS,EAAE,CAAC;QACb,CAAC;QAED,MAAM,UAAU,GACf,CAAC,QAAQ,CAAC,mBAAmB,GAAG,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC;QAC1E,MAAM,cAAc,GAAG,cAAc,CAAC,SAAS,CAAC,EAAE,IAAI,IAAI,QAAQ,CAAC;QACnE,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,UAAU,EAAE,cAAc,CAAC,CAAC;QACtE,MAAM,UAAU,GAAG,eAAe,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QAC3D,QAAQ,CAAC,IAAI,CAAC;YACb,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;YAClC,SAAS;YACT,OAAO,EAAE,YAAY;YACrB,YAAY;YACZ,UAAU;YACV,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;SAC9B,CAAC,CAAC;QACH,SAAS,GAAG,YAAY,CAAC;QACzB,YAAY,GAAG,UAAU,CAAC;IAC3B,CAAC;IAED,OAAO,QAAQ,CAAC;AACjB,CAAC"}

package/dist/time/tempo-map.d.ts

@@ -0,0 +1,81 @@
+/** A tempo in force from `tick` on, until the next change. */
+export type TempoChange = {
+    tick: number;
+    /** The time of `tick`, from the start of the song. */
+    seconds: number;
+    /**
+     * Length of a quarter note, in microseconds; 500 000 is 120 bpm. A real
+     * number, not limited to what a MIDI Set Tempo event can store.
+     */
+    microsecondsPerQuarterNote: number;
+};
+/**
+ * How ticks map to seconds over a whole song: the tick resolution and every
+ * tempo change, in tick order, the first one at tick 0.
+ *
+ * Build one with {@link composeTempoMap}, which keeps that invariant and fills
+ * in each change's `seconds`.
+ */
+export type TempoMap = {
+    /** Ticks per quarter note, the resolution every `tick` of a song uses. */
+    ticksPerQuarterNote: number;
+    changes: TempoChange[];
+};
+/** A tempo change before its time in seconds is known. */
+export type TempoMark = Omit<TempoChange, "seconds">;
+/** 120 bpm, the tempo of a song before any tempo mark (MIDI RP-001). */
+export declare const DEFAULT_MICROSECONDS_PER_QUARTER_NOTE = 500000;
+/**
+ * Builds the tempo map of a song from its tempo marks, computing the time of
+ * each.
+ *
+ * - A song with no mark at tick 0 starts at
+ *   {@link DEFAULT_MICROSECONDS_PER_QUARTER_NOTE}, 120 bpm.
+ * - Of several marks at one tick, the last one given wins.
+ * - A mark equal to the tempo already in force is kept out of the map.
+ *
+ * Time complexity: O(n) in `marks.length`. Memory: O(n).
+ *
+ * @example
+ * 	composeTempoMap(96, [
+ * 		{ tick: 192, microsecondsPerQuarterNote: 1_000_000 },
+ * 	]);
+ * 	// { ticksPerQuarterNote: 96, changes: [
+ * 	//   { tick: 0, seconds: 0, microsecondsPerQuarterNote: 500_000 },
+ * 	//   { tick: 192, seconds: 1, microsecondsPerQuarterNote: 1_000_000 } ] }
+ *
+ * @param ticksPerQuarterNote - The song's tick resolution, above 0.
+ * @param marks - The tempo marks, sorted by tick, none below 0.
+ * @returns The tempo map.
+ * @throws {RangeError} When `ticksPerQuarterNote` or a tempo is not above 0, or
+ *   when the marks are not sorted from tick 0 on.
+ */
+export declare function composeTempoMap(ticksPerQuarterNote: number, marks: readonly TempoMark[]): TempoMap;
+/**
+ * The time of a tick, in seconds from the start of the song.
+ *
+ * Ticks need not be integers. A tick below 0 extrapolates the first tempo.
+ *
+ * Time complexity: O(log n) in the number of tempo changes. Memory: O(1).
+ *
+ * @example
+ * 	tempoMapSeconds(composeTempoMap(96, []), 96); // 0.5
+ *
+ * @see {@link tempoMapTick} for the converse.
+ */
+export declare function tempoMapSeconds(tempoMap: TempoMap, tick: number): number;
+/**
+ * The tick at a time in seconds from the start of the song, as a real number:
+ * round it where a whole tick is needed.
+ *
+ * A time below 0 extrapolates the first tempo.
+ *
+ * Time complexity: O(log n) in the number of tempo changes. Memory: O(1).
+ *
+ * @example
+ * 	tempoMapTick(composeTempoMap(96, []), 0.5); // 96
+ *
+ * @see {@link tempoMapSeconds} for the converse.
+ */
+export declare function tempoMapTick(tempoMap: TempoMap, seconds: number): number;
+//# sourceMappingURL=tempo-map.d.ts.map

package/dist/time/tempo-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tempo-map.d.ts","sourceRoot":"","sources":["../../src/time/tempo-map.ts"],"names":[],"mappings":"AAEA,8DAA8D;AAC9D,MAAM,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,0BAA0B,EAAE,MAAM,CAAC;CACnC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IACtB,0EAA0E;IAC1E,mBAAmB,EAAE,MAAM,CAAC;IAC5B,OAAO,EAAE,WAAW,EAAE,CAAC;CACvB,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AAErD,wEAAwE;AACxE,eAAO,MAAM,qCAAqC,SAAU,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAC9B,mBAAmB,EAAE,MAAM,EAC3B,KAAK,EAAE,SAAS,SAAS,EAAE,GACzB,QAAQ,CA8CV;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAcxE"}

package/dist/time/tempo-map.js

@@ -0,0 +1,114 @@
+import { bisectRight } from "@ac-kit/algo";
+/** 120 bpm, the tempo of a song before any tempo mark (MIDI RP-001). */
+export const DEFAULT_MICROSECONDS_PER_QUARTER_NOTE = 500000;
+/**
+ * Builds the tempo map of a song from its tempo marks, computing the time of
+ * each.
+ *
+ * - A song with no mark at tick 0 starts at
+ *   {@link DEFAULT_MICROSECONDS_PER_QUARTER_NOTE}, 120 bpm.
+ * - Of several marks at one tick, the last one given wins.
+ * - A mark equal to the tempo already in force is kept out of the map.
+ *
+ * Time complexity: O(n) in `marks.length`. Memory: O(n).
+ *
+ * @example
+ * 	composeTempoMap(96, [
+ * 		{ tick: 192, microsecondsPerQuarterNote: 1_000_000 },
+ * 	]);
+ * 	// { ticksPerQuarterNote: 96, changes: [
+ * 	//   { tick: 0, seconds: 0, microsecondsPerQuarterNote: 500_000 },
+ * 	//   { tick: 192, seconds: 1, microsecondsPerQuarterNote: 1_000_000 } ] }
+ *
+ * @param ticksPerQuarterNote - The song's tick resolution, above 0.
+ * @param marks - The tempo marks, sorted by tick, none below 0.
+ * @returns The tempo map.
+ * @throws {RangeError} When `ticksPerQuarterNote` or a tempo is not above 0, or
+ *   when the marks are not sorted from tick 0 on.
+ */
+export function composeTempoMap(ticksPerQuarterNote, marks) {
+    if (!(ticksPerQuarterNote > 0)) {
+        throw new RangeError(`ticks per quarter note ${ticksPerQuarterNote} is not above 0`);
+    }
+    const changes = [
+        {
+            tick: 0,
+            seconds: 0,
+            microsecondsPerQuarterNote: DEFAULT_MICROSECONDS_PER_QUARTER_NOTE,
+        },
+    ];
+    for (const { tick, microsecondsPerQuarterNote } of marks) {
+        if (!(microsecondsPerQuarterNote > 0)) {
+            throw new RangeError(`tempo ${microsecondsPerQuarterNote} µs per quarter note is not above 0`);
+        }
+        const last = changes.at(-1);
+        if (!(tick >= last.tick)) {
+            throw new RangeError(`tempo mark at tick ${tick} is out of order`);
+        }
+        if (tick === last.tick) {
+            const previous = changes.at(-2);
+            if (previous?.microsecondsPerQuarterNote === microsecondsPerQuarterNote) {
+                changes.pop();
+            }
+            else {
+                last.microsecondsPerQuarterNote = microsecondsPerQuarterNote;
+            }
+            continue;
+        }
+        if (last.microsecondsPerQuarterNote === microsecondsPerQuarterNote) {
+            continue;
+        }
+        changes.push({
+            tick,
+            seconds: secondsAfter_(last, tick, ticksPerQuarterNote),
+            microsecondsPerQuarterNote,
+        });
+    }
+    return { ticksPerQuarterNote, changes };
+}
+/**
+ * The time of a tick, in seconds from the start of the song.
+ *
+ * Ticks need not be integers. A tick below 0 extrapolates the first tempo.
+ *
+ * Time complexity: O(log n) in the number of tempo changes. Memory: O(1).
+ *
+ * @example
+ * 	tempoMapSeconds(composeTempoMap(96, []), 96); // 0.5
+ *
+ * @see {@link tempoMapTick} for the converse.
+ */
+export function tempoMapSeconds(tempoMap, tick) {
+    const { changes, ticksPerQuarterNote } = tempoMap;
+    const index = Math.max(0, bisectRight(changes, tick, (change, value) => change.tick - value) - 1);
+    return secondsAfter_(changes[index], tick, ticksPerQuarterNote);
+}
+/**
+ * The tick at a time in seconds from the start of the song, as a real number:
+ * round it where a whole tick is needed.
+ *
+ * A time below 0 extrapolates the first tempo.
+ *
+ * Time complexity: O(log n) in the number of tempo changes. Memory: O(1).
+ *
+ * @example
+ * 	tempoMapTick(composeTempoMap(96, []), 0.5); // 96
+ *
+ * @see {@link tempoMapSeconds} for the converse.
+ */
+export function tempoMapTick(tempoMap, seconds) {
+    const { changes, ticksPerQuarterNote } = tempoMap;
+    const index = Math.max(0, bisectRight(changes, seconds, (change, value) => change.seconds - value) -
+        1);
+    const change = changes[index];
+    return (change.tick +
+        ((seconds - change.seconds) * 1000000 * ticksPerQuarterNote) /
+            change.microsecondsPerQuarterNote);
+}
+// Measured from the change rather than accumulated, so a long song does not drift.
+function secondsAfter_(change, tick, ticksPerQuarterNote) {
+    return (change.seconds +
+        ((tick - change.tick) * change.microsecondsPerQuarterNote) /
+            (1000000 * ticksPerQuarterNote));
+}
+//# sourceMappingURL=tempo-map.js.map

package/dist/time/tempo-map.js.map

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

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@ac-kit/model-music",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Music as plain data: the notes of a song with their times in ticks and seconds, its parts, tempo map, meter, measures, pedals, markers and lyrics.",
+  "keywords": [
+    "measures",
+    "music",
+    "notes",
+    "song",
+    "tempo-map"
+  ],
+  "homepage": "https://anthochamp.github.io/node-essentials/api/model-music/",
+  "bugs": {
+    "url": "https://git.grenadine.io/anthochamp/node-essentials/issues"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Anthony Champagne <dev@anthonychampagne.fr>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.grenadine.io/anthochamp/node-essentials.git",
+    "directory": "packages/model-music"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "exports": {
+      ".": "./dist/index.js"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "compile": "tsc -p ./tsconfig.build.json -outDir dist",
+    "compile:check": "tsc -noEmit -p ./tsconfig.json",
+    "clean": "rimraf dist",
+    "build": "yarn clean && yarn compile",
+    "test": "yarn run -T vitest run",
+    "prepack": "yarn build"
+  },
+  "dependencies": {
+    "@ac-kit/algo": "^0.2.2",
+    "@ac-kit/core": "^0.5.0",
+    "@types/web": "^0.0.359"
+  },
+  "devDependencies": {
+    "@ac-kit/tsconfig": "0.1.0",
+    "@ac-kit/typedoc-config": "0.1.0",
+    "@ac-kit/vitest-config": "0.1.1",
+    "@typescript/native": "typescript@7.0.2",
+    "rimraf": "6.1.3",
+    "typedoc": "0.28.20",
+    "typescript": "@typescript/typescript6@6.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  }
 }