@ac-kit/format-midi 0.0.0-stage → 0.1.1

package/dist/message/midi-message.d.ts

@@ -0,0 +1,111 @@
+/**
+ * A MIDI 1.0 Channel Voice message, addressed to one of the 16 channels.
+ *
+ * Channel Mode messages (All Sound Off, Reset All Controllers, Local Control,
+ * All Notes Off, Omni and Mono/Poly modes) share the Control Change status and
+ * are represented as `controlChange` with `controller` 120–127, as on the
+ * wire.
+ *
+ * A `noteOn` with `velocity` 0 is kept as a note-on: that is what was sent, and
+ * it is what lets running status cover a whole phrase. Receivers treat it as a
+ * note-off; {@link isMidiNoteRelease} answers that question for both forms.
+ */
+export type MidiChannelMessage = {
+    type: "noteOff";
+    /** 0–15, shown to users as channels 1–16. */
+    channel: number;
+    /** 0–127; 60 is middle C. */
+    note: number;
+    /** Release velocity, 0–127. */
+    velocity: number;
+} | {
+    type: "noteOn";
+    /** 0–15. */
+    channel: number;
+    /** 0–127. */
+    note: number;
+    /** 0–127; 0 means note-off to a receiver. */
+    velocity: number;
+} | {
+    type: "polyphonicKeyPressure";
+    /** 0–15. */
+    channel: number;
+    /** 0–127. */
+    note: number;
+    /** 0–127. */
+    pressure: number;
+} | {
+    type: "controlChange";
+    /** 0–15. */
+    channel: number;
+    /** 0–127; 120–127 are the Channel Mode messages. */
+    controller: number;
+    /** 0–127. */
+    value: number;
+} | {
+    type: "programChange";
+    /** 0–15. */
+    channel: number;
+    /** 0–127, shown to users as programs 1–128. */
+    program: number;
+} | {
+    type: "channelPressure";
+    /** 0–15. */
+    channel: number;
+    /** 0–127. */
+    pressure: number;
+} | {
+    type: "pitchBend";
+    /** 0–15. */
+    channel: number;
+    /**
+     * -8192–8191, 0 being the centre. On the wire this is the 14-bit value
+     * plus 8192, least significant 7 bits first.
+     */
+    value: number;
+};
+/** A MIDI 1.0 System Common message, including System Exclusive. */
+export type MidiSystemCommonMessage = {
+    type: "sysEx";
+    /**
+     * The payload between F0 and F7, both excluded: the manufacturer ID
+     * first, every byte 0–127.
+     */
+    data: Uint8Array;
+} | {
+    type: "timeCodeQuarterFrame";
+    /** Which of the eight quarter-frame pieces this is, 0–7. */
+    piece: number;
+    /** The 4-bit value of that piece, 0–15. */
+    value: number;
+} | {
+    type: "songPositionPointer";
+    /** Position in MIDI beats (sixteenth notes) from the start, 0–16383. */
+    position: number;
+} | {
+    type: "songSelect";
+    /** 0–127. */
+    song: number;
+} | {
+    type: "tuneRequest";
+};
+/** A MIDI 1.0 System Real-Time message: one status byte, no data. */
+export type MidiSystemRealTimeMessage = {
+    type: "timingClock";
+} | {
+    type: "start";
+} | {
+    type: "continue";
+} | {
+    type: "stop";
+} | {
+    type: "activeSensing";
+} | {
+    type: "systemReset";
+};
+/**
+ * One MIDI 1.0 message, as defined by the _MIDI 1.0 Detailed Specification_.
+ * Discriminated by `type`.
+ */
+export type MidiMessage = MidiChannelMessage | MidiSystemCommonMessage | MidiSystemRealTimeMessage;
+//# sourceMappingURL=midi-message.d.ts.map

package/dist/message/midi-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"midi-message.d.ts","sourceRoot":"","sources":["../../src/message/midi-message.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAC3B;IACA,IAAI,EAAE,SAAS,CAAC;IAChB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAChB,GACD;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,YAAY;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;CAChB,GACD;IACA,IAAI,EAAE,uBAAuB,CAAC;IAC9B,YAAY;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa;IACb,QAAQ,EAAE,MAAM,CAAC;CAChB,GACD;IACA,IAAI,EAAE,eAAe,CAAC;IACtB,YAAY;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa;IACb,KAAK,EAAE,MAAM,CAAC;CACb,GACD;IACA,IAAI,EAAE,eAAe,CAAC;IACtB,YAAY;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;CACf,GACD;IACA,IAAI,EAAE,iBAAiB,CAAC;IACxB,YAAY;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa;IACb,QAAQ,EAAE,MAAM,CAAC;CAChB,GACD;IACA,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;CACb,CAAC;AAEL,oEAAoE;AACpE,MAAM,MAAM,uBAAuB,GAChC;IACA,IAAI,EAAE,OAAO,CAAC;IACd;;;OAGG;IACH,IAAI,EAAE,UAAU,CAAC;CAChB,GACD;IACA,IAAI,EAAE,sBAAsB,CAAC;IAC7B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;CACb,GACD;IACA,IAAI,EAAE,qBAAqB,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;CAChB,GACD;IACA,IAAI,EAAE,YAAY,CAAC;IACnB,aAAa;IACb,IAAI,EAAE,MAAM,CAAC;CACZ,GACD;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAE3B,qEAAqE;AACrE,MAAM,MAAM,yBAAyB,GAClC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,WAAW,GACpB,kBAAkB,GAClB,uBAAuB,GACvB,yBAAyB,CAAC"}

package/dist/message/midi-message.js

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

package/dist/message/midi-message.js.map

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

package/dist/timeline/compose-midi-timeline.d.ts

@@ -0,0 +1,42 @@
+import type { MidiFile, MidiFileEvent } from "../file/midi-file.js";
+/** One event of a {@link MidiFile}, placed on the file's time axis. */
+export type MidiTimelineEvent = {
+    /** Index of the track the event came from. */
+    trackIndex: number;
+    /**
+     * Ticks from the start of the track: the sum of the delta times up to the
+     * event.
+     */
+    tick: number;
+    /** Seconds from the start of the track. */
+    seconds: number;
+    event: MidiFileEvent;
+};
+/**
+ * Places every event of a Standard MIDI File on one time axis, in ticks and in
+ * seconds — what a player or an exporter iterates over.
+ *
+ * - **Formats 0 and 1**: the tracks play together, so the result is every event
+ *   of every track sorted by tick, ties kept in track order then event order.
+ *   Tempo starts at 120 bpm (500 000 µs per quarter note) and Set Tempo events
+ *   are honoured in whichever track they appear, although format 1 files
+ *   conventionally keep the tempo map in track 0.
+ * - **Format 2**: each track is an independent sequence, so each starts at 0
+ *   seconds under its own Set Tempo events only, and the result is the tracks
+ *   one after another in track order, not interleaved.
+ * - **Timecode division**: ticks have a fixed length, `1 / (framesPerSecond ×
+ *   ticksPerFrame)` seconds with 29 meaning 30000/1001 frames per second, and
+ *   Set Tempo events do not change it.
+ *
+ * Time complexity: O(n log n) in the total event count, for the sort; O(n) for
+ * format 2. Memory: O(n). The events are shared with `file`, not copied.
+ *
+ * @example
+ * 	// RP-001's format 0 example, 96 ticks per quarter note at 120 bpm:
+ * 	composeMidiTimeline(file).at(-1); // { trackIndex: 0, tick: 384, seconds: 2, … }
+ *
+ * @param file - A file, typically from {@link parseMidiFile}.
+ * @returns One entry per event, in playing order.
+ */
+export declare function composeMidiTimeline(file: MidiFile): MidiTimelineEvent[];
+//# sourceMappingURL=compose-midi-timeline.d.ts.map

package/dist/timeline/compose-midi-timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-midi-timeline.d.ts","sourceRoot":"","sources":["../../src/timeline/compose-midi-timeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,QAAQ,EACR,aAAa,EAEb,MAAM,sBAAsB,CAAC;AAE9B,uEAAuE;AACvE,MAAM,MAAM,iBAAiB,GAAG;IAC/B,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,aAAa,CAAC;CACrB,CAAC;AA2DF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,iBAAiB,EAAE,CAqBvE"}

package/dist/timeline/compose-midi-timeline.js

@@ -0,0 +1,87 @@
+/** RP-001: a file with no Set Tempo event before a tick plays at 120 bpm. */
+const DEFAULT_TEMPO_ = 500000;
+function appendTrackEvents_(target, file, trackIndex) {
+    let tick = 0;
+    for (const { deltaTime, event } of file.tracks[trackIndex].events) {
+        tick += deltaTime;
+        target.push({ trackIndex, tick, seconds: 0, event });
+    }
+}
+/**
+ * Sets `seconds` on `events[from…]`, sorted by tick, under the tempo changes
+ * they contain. Seconds are measured from the last tempo change, not
+ * accumulated per event, so rounding does not drift over a long file.
+ */
+function assignSeconds_(events, from, division) {
+    if (division.type === "timecode") {
+        const framesPerSecond = division.framesPerSecond === 29
+            ? 30000 / 1001
+            : division.framesPerSecond;
+        const ticksPerSecond = framesPerSecond * division.ticksPerFrame;
+        for (let index = from; index < events.length; index++) {
+            events[index].seconds = events[index].tick / ticksPerSecond;
+        }
+        return;
+    }
+    const microsecondsPerTick = 1000000 * division.ticksPerQuarterNote;
+    let segmentTick = 0;
+    let segmentSeconds = 0;
+    let secondsPerTick = DEFAULT_TEMPO_ / microsecondsPerTick;
+    for (let index = from; index < events.length; index++) {
+        const timelineEvent = events[index];
+        timelineEvent.seconds =
+            segmentSeconds + (timelineEvent.tick - segmentTick) * secondsPerTick;
+        const { event } = timelineEvent;
+        if (event.kind === "meta" && event.meta.type === "setTempo") {
+            segmentTick = timelineEvent.tick;
+            segmentSeconds = timelineEvent.seconds;
+            secondsPerTick =
+                event.meta.microsecondsPerQuarterNote / microsecondsPerTick;
+        }
+    }
+}
+/**
+ * Places every event of a Standard MIDI File on one time axis, in ticks and in
+ * seconds — what a player or an exporter iterates over.
+ *
+ * - **Formats 0 and 1**: the tracks play together, so the result is every event
+ *   of every track sorted by tick, ties kept in track order then event order.
+ *   Tempo starts at 120 bpm (500 000 µs per quarter note) and Set Tempo events
+ *   are honoured in whichever track they appear, although format 1 files
+ *   conventionally keep the tempo map in track 0.
+ * - **Format 2**: each track is an independent sequence, so each starts at 0
+ *   seconds under its own Set Tempo events only, and the result is the tracks
+ *   one after another in track order, not interleaved.
+ * - **Timecode division**: ticks have a fixed length, `1 / (framesPerSecond ×
+ *   ticksPerFrame)` seconds with 29 meaning 30000/1001 frames per second, and
+ *   Set Tempo events do not change it.
+ *
+ * Time complexity: O(n log n) in the total event count, for the sort; O(n) for
+ * format 2. Memory: O(n). The events are shared with `file`, not copied.
+ *
+ * @example
+ * 	// RP-001's format 0 example, 96 ticks per quarter note at 120 bpm:
+ * 	composeMidiTimeline(file).at(-1); // { trackIndex: 0, tick: 384, seconds: 2, … }
+ *
+ * @param file - A file, typically from {@link parseMidiFile}.
+ * @returns One entry per event, in playing order.
+ */
+export function composeMidiTimeline(file) {
+    const events = [];
+    if (file.format === 2) {
+        for (const trackIndex of file.tracks.keys()) {
+            const from = events.length;
+            appendTrackEvents_(events, file, trackIndex);
+            assignSeconds_(events, from, file.timeDivision);
+        }
+        return events;
+    }
+    for (const trackIndex of file.tracks.keys()) {
+        appendTrackEvents_(events, file, trackIndex);
+    }
+    // Array.prototype.sort is stable, so equal ticks stay in track then event order.
+    events.sort((left, right) => left.tick - right.tick);
+    assignSeconds_(events, 0, file.timeDivision);
+    return events;
+}
+//# sourceMappingURL=compose-midi-timeline.js.map

package/dist/timeline/compose-midi-timeline.js.map

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

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@ac-kit/format-midi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "MIDI 1.0: the message model with a live byte-stream Decoder/Encoder, Standard MIDI File parse/print, and tick-to-seconds timelines.",
+  "keywords": [
+    "midi",
+    "midi-file",
+    "smf",
+    "standard-midi-file",
+    "sysex"
+  ],
+  "homepage": "https://anthochamp.github.io/node-essentials/api/format-midi/",
+  "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/format-midi"
+  },
+  "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/core": "^0.3.0",
+    "@ac-kit/format-core": "^0.1.3",
+    "@ac-kit/format-varint": "^0.1.2",
+    "@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"
+  }
 }