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

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# @ac-kit/format-midi
+
+## 0.1.0
+
+### Minor Changes
+
+- 992cbbb: New package: MIDI 1.0, from the bytes on a live port to the time in seconds of
+  every event in a Standard MIDI File.
+  
+  - `MidiMessage` models every MIDI 1.0 message — the seven Channel Voice
+    messages (Channel Mode as `controlChange` 120–127), System Common including
+    `sysEx`, and System Real-Time — with `MidiChannelMessage`,
+    `MidiSystemCommonMessage` and `MidiSystemRealTimeMessage` naming the groups.
+    `encodeMidiMessage` writes one with every field range-checked, and
+    `isMidiNoteRelease` treats a note-on with velocity 0 as the note-off
+    receivers take it for.
+  - `MidiMessageDecoder` reads a live byte stream the way a MIDI receiver does:
+    running status, real-time bytes returned the moment they arrive even inside
+    another message or a SysEx, SysEx ended by F7 or by any other status, and
+    every violation — stray data, a message cut short, an undefined status, a
+    lone F7, a SysEx over `maxSysExLength` (1 MiB by default) — a recoverable
+    `MidiStreamError` after which it resynchronises. `MidiMessageEncoder` writes
+    messages back, optionally with running status.
+  - `parseMidiFile` reads a Standard MIDI File (RP-001) into its format, time
+    division (metrical or SMPTE) and tracks of channel, SysEx (F0 and F7 forms)
+    and meta events, every RP-001 meta type by name and text kept as bytes. It
+    skips unknown chunks and extra header bytes, accepts a track without End of
+    Track as it is, and throws `MidiFileError` with the byte offset on malformed
+    input. `printMidiFile` writes the file back byte for byte, with or without
+    running status.
+  - `composeMidiTimeline` places every event on one axis with its tick and
+    seconds: format 0 and 1 tracks merged by tick under every Set Tempo event,
+    format 2 tracks timed independently, SMPTE divisions at a fixed tick length.
+
+### Patch Changes
+
+- Updated dependencies [6254a3f]
+  - @ac-kit/format-core@0.1.3

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,104 @@
-# Temporary Holding Version
+# @ac-kit/format-midi
 
-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.
+MIDI 1.0 in plain data: the messages a device sends and receives, decoded from
+and encoded to a live byte stream; Standard MIDI Files, parsed and written back
+byte for byte; and the time, in seconds, of every event in a file.
+
+```ts
+import { ByteAccumulator } from "@ac-kit/core";
+import { DecodeStream } from "@ac-kit/format-core";
+import {
+  MidiMessageDecoder,
+  composeMidiTimeline,
+  parseMidiFile,
+} from "@ac-kit/format-midi";
+
+// A live port: running status, real-time bytes anywhere, SysEx of any length.
+const messages = port.readable.pipeThrough(
+  new DecodeStream(new MidiMessageDecoder(), {
+    buffer: new ByteAccumulator(65_536),
+    onError: (error) => console.warn(error),
+  }),
+);
+
+// A file: every event with its tick and its time in seconds.
+for (const { tick, seconds, event } of composeMidiTimeline(parseMidiFile(bytes))) {
+  // …
+}
+```
+
+It opens no device: read bytes from wherever the platform exposes MIDI — an
+ALSA raw MIDI node, a serial port, a USB-MIDI endpoint, Web MIDI — and write
+bytes back the same way.
+
+## Messages
+
+`MidiMessage` is a union discriminated by `type`, following the _MIDI 1.0
+Detailed Specification_: the seven Channel Voice messages, System Common
+(`sysEx`, `timeCodeQuarterFrame`, `songPositionPointer`, `songSelect`,
+`tuneRequest`) and System Real-Time (`timingClock`, `start`, `continue`, `stop`,
+`activeSensing`, `systemReset`). `MidiChannelMessage`,
+`MidiSystemCommonMessage` and `MidiSystemRealTimeMessage` name the three groups.
+
+Values are the ones on the wire, with two exceptions: `pitchBend` is -8192–8191
+with 0 at the centre, and a `sysEx` holds its payload without the F0 and F7
+around it. Channel Mode messages are `controlChange` with controller 120–127, as
+on the wire. A note-on with velocity 0 stays a `noteOn`; `isMidiNoteRelease`
+answers whether a message releases a note in either form.
+
+`encodeMidiMessage` writes one message, checking every field's range.
+
+## Streams
+
+`MidiMessageDecoder` is a `Decoder` from `@ac-kit/format-core`, so it runs under
+`DecodeStream`, `decodeAll` or any other driver. It reads a stream the way a
+MIDI receiver does:
+
+- data bytes after a channel message reuse its status (running status), until
+  a System Common message or a SysEx cancels it;
+- a real-time byte is returned the moment it arrives, even in the middle of
+  another message or of a SysEx, which then carries on;
+- a SysEx ends at F7 or at any other status byte;
+- stray data bytes, a message cut short, an undefined status (F4, F5, F9, FD),
+  a lone F7 and a SysEx over `maxSysExLength` (1 MiB by default) are
+  recoverable `error` resu rather than the driver's buffer, so the buffer only
+ever holds a few bytes beyond the chunk just received. One instance serves
+exactly one stream; `reset`   decoding resumes at the next status byte.
+
+The decoder keeps a message interrupted by a real-time byte, and a SysEx in
+progress, in its own state, so one instance serves exactly one stream; `reset`
+clears it.
+
+`MidiMessageEncoder` is the matching `Encoder`, with an optional
+`runningStatus`.
+
+## Standard MIDI Files
+
+`parseMidiFile` reads a Standard MIDI File (RP-001) into a `MidiFile`: its
+`format` (0, 1 or 2), its `timeDivision` (ticks per quarter note, or SMPTE
+frames and ticks per frame) and its tracks of `{ deltaTime, event }`. An event
+is a channel message, an F0 or F7 SysEx event with its bytes as stored, or a
+`MidiMetaEvent` — every meta type of RP-001 by name, the others as `unknown`.
+Text meta events keep their bytes, because the standard does not say which
+encoding they use.
+
+It skips chunks of unknown type and extra header bytes, and accepts a track
+that does not end with End of Track, without adding one. A malformed file throws
+`MidiFileError`, a `SyntaxError` carrying the byte `offset` it gave up at.
+
+`printMidiFile` writes a `MidiFile` back, with `runningStatus` as an option. The
+events are written as given and none is added, so a track built by hand needs
+its own End of Track. A field out of range is a `RangeError`.
+
+## Timeline
+
+`composeMidiTimeline` lists every event of a file with its `trackIndex`, `tick`
+and `seconds`, in playing order. Tracks of a format 0 or 1 file are merged by
+tick, under every Set Tempo event in any track. Tracks of a format 2 file are
+independent sequences: each is timed on its own and they follow one another.
+An SMPTE division gives each tick a fixed length, with frame rate 29 meaning
+29.97.
+
+See the
+[generated API docs](https://anthochamp.github.io/node-essentials/api/format-midi/)
+for the full reference.

package/dist/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What a {@link MidiStreamError} reports:
+ *
+ * - `strayData` — data bytes with no status to give them meaning: nothing was
+ *   received yet, or a System Common or SysEx message cancelled running
+ *   status.
+ * - `incompleteMessage` — a status byte arrived before the data bytes of the
+ *   previous message were all received; the partial message is dropped.
+ * - `undefinedStatus` — one of the status bytes MIDI 1.0 leaves undefined: F4 and
+ *   F5 (System Common) or F9 and FD (System Real-Time).
+ * - `unexpectedEndOfExclusive` — an F7 (End of Exclusive) with no SysEx open.
+ * - `sysExTooLong` — a SysEx payload exceeded the decoder's `maxSysExLength`; the
+ *   rest of it, up to its end, is discarded.
+ */
+export type MidiStreamErrorReason = "strayData" | "incompleteMessage" | "undefinedStatus" | "unexpectedEndOfExclusive" | "sysExTooLong";
+/**
+ * A recoverable violation in a live MIDI byte stream, reported by
+ * {@link MidiMessageDecoder} as an `error` decode result. The offending bytes
+ * are consumed and decoding resumes at the next status byte, the way a MIDI
+ * receiver resynchronises.
+ */
+export declare class MidiStreamError extends SyntaxError {
+    /** What kind of violation was found. */
+    readonly reason: MidiStreamErrorReason;
+    constructor(message: string, 
+    /** What kind of violation was found. */
+    reason: MidiStreamErrorReason);
+}
+/**
+ * A Standard MIDI File is malformed: a chunk or event is truncated, a
+ * variable-length quantity is invalid, a data byte has no running status to
+ * apply to, or a meta event's length does not match its type.
+ *
+ * Thrown by {@link parseMidiFile}. A model built by the caller that
+ * {@link printMidiFile} cannot write — a field out of range, a message that is
+ * not a channel message — is a `RangeError` instead.
+ */
+export declare class MidiFileError extends SyntaxError {
+    /** Byte offset in the file of the structure the parser gave up at. */
+    readonly offset: number;
+    constructor(message: string, 
+    /** Byte offset in the file of the structure the parser gave up at. */
+    offset: number, options?: ErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,qBAAqB,GAC9B,WAAW,GACX,mBAAmB,GACnB,iBAAiB,GACjB,0BAA0B,GAC1B,cAAc,CAAC;AAElB;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,WAAW;IAG9C,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAHvC,YACC,OAAO,EAAE,MAAM;IACf,wCAAwC;IAC/B,MAAM,EAAE,qBAAqB,EAItC;CACD;AAED;;;;;;;;GAQG;AACH,qBAAa,aAAc,SAAQ,WAAW;IAG5C,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM;IAHxB,YACC,OAAO,EAAE,MAAM;IACf,sEAAsE;IAC7D,MAAM,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE,YAAY,EAItB;CACD"}

package/dist/errors.js

@@ -0,0 +1,36 @@
+/**
+ * A recoverable violation in a live MIDI byte stream, reported by
+ * {@link MidiMessageDecoder} as an `error` decode result. The offending bytes
+ * are consumed and decoding resumes at the next status byte, the way a MIDI
+ * receiver resynchronises.
+ */
+export class MidiStreamError extends SyntaxError {
+    reason;
+    constructor(message, 
+    /** What kind of violation was found. */
+    reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "MidiStreamError";
+    }
+}
+/**
+ * A Standard MIDI File is malformed: a chunk or event is truncated, a
+ * variable-length quantity is invalid, a data byte has no running status to
+ * apply to, or a meta event's length does not match its type.
+ *
+ * Thrown by {@link parseMidiFile}. A model built by the caller that
+ * {@link printMidiFile} cannot write — a field out of range, a message that is
+ * not a channel message — is a `RangeError` instead.
+ */
+export class MidiFileError extends SyntaxError {
+    offset;
+    constructor(message, 
+    /** Byte offset in the file of the structure the parser gave up at. */
+    offset, options) {
+        super(`${message} (at byte ${offset})`, options);
+        this.offset = offset;
+        this.name = "MidiFileError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAqBA;;;;;GAKG;AACH,MAAM,OAAO,eAAgB,SAAQ,WAAW;IAIrC,MAAM;IAHhB,YACC,OAAe;IACf,wCAAwC;IAC/B,MAA6B;QAEtC,KAAK,CAAC,OAAO,CAAC,CAAC;sBAFN,MAAM;QAGf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAC/B,CAAC;CACD;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAc,SAAQ,WAAW;IAInC,MAAM;IAHhB,YACC,OAAe;IACf,sEAAsE;IAC7D,MAAc,EACvB,OAAsB;QAEtB,KAAK,CAAC,GAAG,OAAO,aAAa,MAAM,GAAG,EAAE,OAAO,CAAC,CAAC;sBAHxC,MAAM;QAIf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC7B,CAAC;CACD"}

package/dist/file/_meta-types.d.ts

@@ -0,0 +1,33 @@
+import type { MidiMetaEvent } from "./midi-meta-event.js";
+export type TextMetaType_ = Exclude<Extract<MidiMetaEvent, {
+    data: Uint8Array;
+}>["type"], "sequencerSpecific" | "unknown">;
+export declare const META_SEQUENCE_NUMBER_ = 0;
+export declare const META_CHANNEL_PREFIX_ = 32;
+export declare const META_MIDI_PORT_ = 33;
+export declare const META_END_OF_TRACK_ = 47;
+export declare const META_SET_TEMPO_ = 81;
+export declare const META_SMPTE_OFFSET_ = 84;
+export declare const META_TIME_SIGNATURE_ = 88;
+export declare const META_KEY_SIGNATURE_ = 89;
+export declare const META_SEQUENCER_SPECIFIC_ = 127;
+export declare const TEXT_META_TYPES_: Readonly<Record<number, TextMetaType_>>;
+export declare const TEXT_META_CODES_: {
+    readonly text: 1;
+    readonly copyright: 2;
+    readonly trackName: 3;
+    readonly instrumentName: 4;
+    readonly lyric: 5;
+    readonly marker: 6;
+    readonly cuePoint: 7;
+    readonly programName: 8;
+    readonly deviceName: 9;
+};
+/** Every meta type a member other than `unknown` spells. */
+export declare const KNOWN_META_TYPES_: ReadonlySet<number>;
+/**
+ * SMPTE frame rates by the 2-bit code in bits 5–6 of an SMPTE Offset's hour
+ * byte.
+ */
+export declare const SMPTE_FRAME_RATES_: readonly [24, 25, 29, 30];
+//# sourceMappingURL=_meta-types.d.ts.map

package/dist/file/_meta-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_meta-types.d.ts","sourceRoot":"","sources":["../../src/file/_meta-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,MAAM,aAAa,GAAG,OAAO,CAClC,OAAO,CAAC,aAAa,EAAE;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,CAAC,MAAM,CAAC,EACpD,mBAAmB,GAAG,SAAS,CAC/B,CAAC;AAIF,eAAO,MAAM,qBAAqB,IAAO,CAAC;AAC1C,eAAO,MAAM,oBAAoB,KAAO,CAAC;AACzC,eAAO,MAAM,eAAe,KAAO,CAAC;AACpC,eAAO,MAAM,kBAAkB,KAAO,CAAC;AACvC,eAAO,MAAM,eAAe,KAAO,CAAC;AACpC,eAAO,MAAM,kBAAkB,KAAO,CAAC;AACvC,eAAO,MAAM,oBAAoB,KAAO,CAAC;AACzC,eAAO,MAAM,mBAAmB,KAAO,CAAC;AACxC,eAAO,MAAM,wBAAwB,MAAO,CAAC;AAE7C,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAUpE,CAAC;AAEF,eAAO,MAAM,gBAAgB;mBACtB,CAAI;wBACC,CAAI;wBACJ,CAAI;6BACC,CAAI;oBACb,CAAI;qBACH,CAAI;uBACF,CAAI;0BACD,CAAI;yBACL,CAAI;CACiC,CAAC;AAEnD,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAWhD,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,YAAI,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAU,CAAC"}

package/dist/file/_meta-types.js

@@ -0,0 +1,52 @@
+// Meta event types of RP-001, with 0x08 and 0x09 from RP-019 and 0x21 from the
+// MMA's later addition (Program Name, Device Name, MIDI Port).
+export const META_SEQUENCE_NUMBER_ = 0x00;
+export const META_CHANNEL_PREFIX_ = 0x20;
+export const META_MIDI_PORT_ = 0x21;
+export const META_END_OF_TRACK_ = 0x2f;
+export const META_SET_TEMPO_ = 0x51;
+export const META_SMPTE_OFFSET_ = 0x54;
+export const META_TIME_SIGNATURE_ = 0x58;
+export const META_KEY_SIGNATURE_ = 0x59;
+export const META_SEQUENCER_SPECIFIC_ = 0x7f;
+export const TEXT_META_TYPES_ = {
+    0x01: "text",
+    0x02: "copyright",
+    0x03: "trackName",
+    0x04: "instrumentName",
+    0x05: "lyric",
+    0x06: "marker",
+    0x07: "cuePoint",
+    0x08: "programName",
+    0x09: "deviceName",
+};
+export const TEXT_META_CODES_ = {
+    text: 0x01,
+    copyright: 0x02,
+    trackName: 0x03,
+    instrumentName: 0x04,
+    lyric: 0x05,
+    marker: 0x06,
+    cuePoint: 0x07,
+    programName: 0x08,
+    deviceName: 0x09,
+};
+/** Every meta type a member other than `unknown` spells. */
+export const KNOWN_META_TYPES_ = new Set([
+    META_SEQUENCE_NUMBER_,
+    ...Object.values(TEXT_META_CODES_),
+    META_CHANNEL_PREFIX_,
+    META_MIDI_PORT_,
+    META_END_OF_TRACK_,
+    META_SET_TEMPO_,
+    META_SMPTE_OFFSET_,
+    META_TIME_SIGNATURE_,
+    META_KEY_SIGNATURE_,
+    META_SEQUENCER_SPECIFIC_,
+]);
+/**
+ * SMPTE frame rates by the 2-bit code in bits 5–6 of an SMPTE Offset's hour
+ * byte.
+ */
+export const SMPTE_FRAME_RATES_ = [24, 25, 29, 30];
+//# sourceMappingURL=_meta-types.js.map

package/dist/file/_meta-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_meta-types.js","sourceRoot":"","sources":["../../src/file/_meta-types.ts"],"names":[],"mappings":"AAOA,+EAA+E;AAC/E,+DAA+D;AAC/D,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAC1C,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AACzC,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AACpC,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AACpC,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AACvC,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AACzC,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AACxC,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAE7C,MAAM,CAAC,MAAM,gBAAgB,GAA4C;IACxE,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,gBAAgB;IACtB,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,YAAY;CAClB,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC/B,IAAI,EAAE,IAAI;IACV,SAAS,EAAE,IAAI;IACf,SAAS,EAAE,IAAI;IACf,cAAc,EAAE,IAAI;IACpB,KAAK,EAAE,IAAI;IACX,MAAM,EAAE,IAAI;IACZ,QAAQ,EAAE,IAAI;IACd,WAAW,EAAE,IAAI;IACjB,UAAU,EAAE,IAAI;CACiC,CAAC;AAEnD,4DAA4D;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC;IAC7D,qBAAqB;IACrB,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC;IAClC,oBAAoB;IACpB,eAAe;IACf,kBAAkB;IAClB,eAAe;IACf,kBAAkB;IAClB,oBAAoB;IACpB,mBAAmB;IACnB,wBAAwB;CACxB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAU,CAAC"}

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

@@ -0,0 +1,68 @@
+import type { MidiChannelMessage } from "../message/midi-message.js";
+import type { MidiMetaEvent } from "./midi-meta-event.js";
+/**
+ * How a Standard MIDI File counts time in its delta times.
+ *
+ * - `metrical` — ticks per quarter note, so a tick's length follows the tempo.
+ * - `timecode` — ticks per SMPTE frame, independent of tempo. A `framesPerSecond`
+ *   of 29 means 30 drop-frame, 29.97 frames per second.
+ */
+export type MidiTimeDivision = {
+    type: "metrical";
+    /** 1–32767. */
+    ticksPerQuarterNote: number;
+} | {
+    type: "timecode";
+    framesPerSecond: 24 | 25 | 29 | 30;
+    /** 1–255. */
+    ticksPerFrame: number;
+};
+/**
+ * One event of a track, with the bytes it was stored as.
+ *
+ * - `channel` — a channel message, stored without running status or with it.
+ * - `sysEx` — an F0 event: `data` is the stored bytes after the length, which
+ *   normally end with F7. A SysEx split over several events has its first part
+ *   here and the rest in `sysExEscape` events.
+ * - `sysExEscape` — an F7 event: `data` is sent as is, which carries a SysEx
+ *   continuation or any bytes not otherwise expressible, real-time ones
+ *   included.
+ * - `meta` — a meta event (FF), never sent to a device.
+ */
+export type MidiFileEvent = {
+    kind: "channel";
+    message: MidiChannelMessage;
+} | {
+    kind: "sysEx";
+    data: Uint8Array;
+} | {
+    kind: "sysExEscape";
+    data: Uint8Array;
+} | {
+    kind: "meta";
+    meta: MidiMetaEvent;
+};
+/** An event and the ticks elapsed since the previous one in its track. */
+export type MidiTrackEvent = {
+    /** 0–268 435 455 (0x0FFFFFFF), the most a 4-byte quantity holds. */
+    deltaTime: number;
+    event: MidiFileEvent;
+};
+/** One `MTrk` chunk. */
+export type MidiTrack = {
+    /** In file order. A well-formed track ends with an `endOfTrack` meta event. */
+    events: MidiTrackEvent[];
+};
+/**
+ * A Standard MIDI File (RP-001).
+ *
+ * `format` says how the tracks relate: 0 is a single track holding every
+ * channel, 1 is simultaneous tracks played together, 2 is independent
+ * single-track sequences.
+ */
+export type MidiFile = {
+    format: 0 | 1 | 2;
+    timeDivision: MidiTimeDivision;
+    tracks: MidiTrack[];
+};
+//# sourceMappingURL=midi-file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"midi-file.d.ts","sourceRoot":"","sources":["../../src/file/midi-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACzB;IACA,IAAI,EAAE,UAAU,CAAC;IACjB,eAAe;IACf,mBAAmB,EAAE,MAAM,CAAC;CAC3B,GACD;IACA,IAAI,EAAE,UAAU,CAAC;IACjB,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IACnC,aAAa;IACb,aAAa,EAAE,MAAM,CAAC;CACrB,CAAC;AAEL;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GACtB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAEzC,0EAA0E;AAC1E,MAAM,MAAM,cAAc,GAAG;IAC5B,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;CACrB,CAAC;AAEF,wBAAwB;AACxB,MAAM,MAAM,SAAS,GAAG;IACvB,+EAA+E;IAC/E,MAAM,EAAE,cAAc,EAAE,CAAC;CACzB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IACtB,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClB,YAAY,EAAE,gBAAgB,CAAC;IAC/B,MAAM,EAAE,SAAS,EAAE,CAAC;CACpB,CAAC"}

package/dist/file/midi-file.js

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

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

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

package/dist/file/midi-meta-event.d.ts

@@ -0,0 +1,74 @@
+/**
+ * A meta event of a Standard MIDI File track (RP-001), discriminated by `type`.
+ *
+ * The text events keep their bytes: the standard does not say which character
+ * encoding they use, and files in the wild use ASCII, Latin-1, Shift JIS and
+ * UTF-8 alike. Decode them with the encoding the file is known to use.
+ */
+export type MidiMetaEvent = {
+    type: "sequenceNumber";
+    /**
+     * 0–65535, or `undefined` for the zero-length form, which numbers the
+     * sequence by its position in the file.
+     */
+    number: number | undefined;
+} | {
+    type: "text" | "copyright" | "trackName" | "instrumentName" | "lyric" | "marker" | "cuePoint" | "programName" | "deviceName";
+    /** The text, in an unspecified encoding. */
+    data: Uint8Array;
+} | {
+    type: "channelPrefix";
+    /** 0–15: the channel the following SysEx and meta events relate to. */
+    channel: number;
+} | {
+    type: "midiPort";
+    /** 0–255: the output port the track's events go to. */
+    port: number;
+} | {
+    type: "endOfTrack";
+} | {
+    type: "setTempo";
+    /** Length of a quarter note, 0–16 777 215 µs; 500 000 is 120 bpm. */
+    microsecondsPerQuarterNote: number;
+} | {
+    type: "smpteOffset";
+    /** Frame rate, encoded in the hour byte; 29 means 30 drop-frame (29.97). */
+    frameRate: 24 | 25 | 29 | 30;
+    /** 0–23 in practice; 0–31 fits the hour byte. */
+    hours: number;
+    /** 0–59 in practice; 0–255 fits the byte. */
+    minutes: number;
+    /** 0–59 in practice; 0–255 fits the byte. */
+    seconds: number;
+    /** Below the frame rate in practice; 0–255 fits the byte. */
+    frames: number;
+    /** Hundredths of a frame, 0–99 in practice; 0–255 fits the byte. */
+    fractionalFrames: number;
+} | {
+    type: "timeSignature";
+    /** Beats per bar, 0–255. */
+    numerator: number;
+    /** The beat's note value as a power of two: 2 is a quarter note. */
+    denominatorPower: number;
+    /** MIDI clocks (24 per quarter note) per metronome click, 0–255. */
+    clocksPerClick: number;
+    /** Notated 32nd notes per MIDI quarter note, normally 8. */
+    thirtySecondNotesPerQuarter: number;
+} | {
+    type: "keySignature";
+    /** Sharps when positive, flats when negative, -7–7. */
+    sharpsFlats: number;
+    /** Whether the key is minor rather than major. */
+    minor: boolean;
+} | {
+    type: "sequencerSpecific";
+    /** The payload, manufacturer ID first. */
+    data: Uint8Array;
+} | {
+    type: "unknown";
+    /** A meta type, 0–127, that none of the other members spells. */
+    metaType: number;
+    /** The payload, as stored. */
+    data: Uint8Array;
+};
+//# sourceMappingURL=midi-meta-event.d.ts.map

package/dist/file/midi-meta-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"midi-meta-event.d.ts","sourceRoot":"","sources":["../../src/file/midi-meta-event.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACtB;IACA,IAAI,EAAE,gBAAgB,CAAC;IACvB;;;OAGG;IACH,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B,GACD;IACA,IAAI,EACD,MAAM,GACN,WAAW,GACX,WAAW,GACX,gBAAgB,GAChB,OAAO,GACP,QAAQ,GACR,UAAU,GACV,aAAa,GACb,YAAY,CAAC;IAChB,4CAA4C;IAC5C,IAAI,EAAE,UAAU,CAAC;CAChB,GACD;IACA,IAAI,EAAE,eAAe,CAAC;IACtB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;CACf,GACD;IACA,IAAI,EAAE,UAAU,CAAC;IACjB,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;CACZ,GACD;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IACA,IAAI,EAAE,UAAU,CAAC;IACjB,qEAAqE;IACrE,0BAA0B,EAAE,MAAM,CAAC;CAClC,GACD;IACA,IAAI,EAAE,aAAa,CAAC;IACpB,4EAA4E;IAC5E,SAAS,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IAC7B,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,gBAAgB,EAAE,MAAM,CAAC;CACxB,GACD;IACA,IAAI,EAAE,eAAe,CAAC;IACtB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,gBAAgB,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,2BAA2B,EAAE,MAAM,CAAC;CACnC,GACD;IACA,IAAI,EAAE,cAAc,CAAC;IACrB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,KAAK,EAAE,OAAO,CAAC;CACd,GACD;IACA,IAAI,EAAE,mBAAmB,CAAC;IAC1B,0CAA0C;IAC1C,IAAI,EAAE,UAAU,CAAC;CAChB,GACD;IACA,IAAI,EAAE,SAAS,CAAC;IAChB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,IAAI,EAAE,UAAU,CAAC;CAChB,CAAC"}

package/dist/file/midi-meta-event.js

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

package/dist/file/midi-meta-event.js.map

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

package/dist/file/parse-midi-file.d.ts

@@ -0,0 +1,29 @@
+import type { MidiFile } from "./midi-file.js";
+/**
+ * Parses a Standard MIDI File (RP-001) into its header and tracks, every event
+ * kept with the bytes it was stored as.
+ *
+ * Tolerates what RP-001 asks readers to tolerate: an `MThd` chunk longer than 6
+ * bytes (the extra bytes are skipped) and chunks of an unknown type (skipped
+ * whole). Running status is applied within a track and cancelled by SysEx and
+ * meta events.
+ *
+ * Reads the tracks as they are, without repair: the track count in the header
+ * is not checked against the `MTrk` chunks present, every `MTrk` chunk becomes
+ * a track, and a track that does not end with End of Track — common in files
+ * written by hand-rolled tools — is accepted with nothing appended, so
+ * {@link printMidiFile} writes it back unchanged.
+ *
+ * Time complexity: O(n) in `bytes.length`. Memory: O(n); every payload is
+ * copied, so the result does not alias `bytes`.
+ *
+ * @param bytes - The whole file.
+ * @returns The file's format, time division and tracks.
+ * @throws {MidiFileError} When the file has no `MThd` header, a chunk or event
+ *   is truncated, a variable-length quantity is overlong or longer than 4
+ *   bytes, a data byte has no running status, a status byte other than a
+ *   channel, SysEx or meta one appears in a track, or a known meta event has
+ *   the wrong length or an out-of-range field.
+ */
+export declare function parseMidiFile(bytes: Uint8Array): MidiFile;
+//# sourceMappingURL=parse-midi-file.d.ts.map

package/dist/file/parse-midi-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-midi-file.d.ts","sourceRoot":"","sources":["../../src/file/parse-midi-file.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACX,QAAQ,EAKR,MAAM,gBAAgB,CAAC;AA6RxB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,QAAQ,CAuCzD"}