@sudobility/music_types 0.11.16 → 0.11.18

package/dist/platform/mod.d.ts

@@ -1,49 +1,68 @@
 /**
- * A neutral model of an Amiga tracker module, shaped by exactly what the
- * `.MOD` importer in music_lib reads — so that music_lib carries no byte
- * handling of its own, the same split `MidiFile` uses.
+ * A format-neutral model of a tracker module.
  *
- * Decoding stops at this shape deliberately. Turning periods into pitches and
- * speed/tempo into a `TempoMap` is musical work, so it lives in music_lib;
- * only the byte reading is platform-shaped, and even that is shared by all
- * three `MusicIo` implementations rather than reimplemented per platform.
+ * Was `ModFile`, shaped by exactly what ProTracker stores. That shape does not
+ * survive contact with the rest of the family: only MOD uses Amiga periods,
+ * only MOD has fixed 64-row patterns, and only MOD lets a sample stand in for
+ * an instrument. So the model states what every format agrees on and each
+ * decoder normalises its own quirks behind it — which is what keeps
+ * `trackerToScore` free of format branches.
+ *
+ * Decoding stops here deliberately. Turning this into a score is musical work
+ * and lives in music_lib; only the byte reading is platform-shaped, and even
+ * that is shared by all three `MusicIo` implementations rather than
+ * reimplemented per platform.
  */
-/** A sampled instrument slot. Names are free text and often decorative or empty. */
-export type ModSample = {
+export type TrackerFormat = 'mod' | 's3m' | 'xm' | 'it' | 'dsm' | 'mptm';
+/** One instrument slot. In MOD/S3M/DSM a sample *is* the instrument; XM, IT and MPTM put a layer above. */
+export type TrackerInstrument = {
     index: number;
     name: string;
 };
 /**
  * One channel's cell in one row.
  *
- * `period` is the Amiga period value, not a pitch: 0 means "no note here",
- * which is why this is not an optional field. `sample` is 0 for "keep
- * whatever this channel was already playing".
+ * `note` is a MIDI note number rather than a period: MOD is the only format
+ * that stores periods, so converting in its decoder keeps the approximation
+ * that conversion involves in one place instead of leaking into shared code.
+ *
+ * `effect`/`param` are deliberately absent. Notation import reads exactly one
+ * thing from the effect column — speed and tempo — and *which* effect carries
+ * it is format knowledge (XM splits `F` at 0x20; S3M and IT use `A` and `T`).
+ * Each decoder normalises to `speed`/`bpm`, so nothing downstream branches on
+ * format.
  */
-export type ModCell = {
-    sample: number;
-    period: number;
-    effect: number;
-    param: number;
+export type TrackerCell = {
+    /** 0 means "keep whatever this channel was already playing". */
+    instrument: number;
+    /** MIDI note number, `'off'` for an explicit release or cut, `null` for an empty cell. */
+    note: number | 'off' | null;
+    /** Ticks per row, where this cell changes it. */
+    speed?: number;
+    /** Beats per minute, where this cell changes it. */
+    bpm?: number;
+    /** `Dxx` — this row ends the pattern early. */
+    patternBreak?: boolean;
 };
-export type ModFile = {
+export type TrackerModule = {
+    format: TrackerFormat;
     title: string;
     channels: number;
-    samples: ModSample[];
+    instruments: TrackerInstrument[];
     /** Pattern indices in playback order; a pattern played three times appears three times. */
     order: number[];
-    /** `patterns[pattern][row][channel]`. */
-    patterns: ModCell[][][];
+    /** `patterns[p][row][channel]`. Row count varies per pattern — MOD is always 64, IT allows 200. */
+    patterns: TrackerCell[][][];
 };
 /**
- * Reading a `.MOD` file.
+ * Reading a tracker module.
  *
  * A capability for surface consistency — the app reaches every file format
  * through `getAppServices().io` — even though nothing about parsing is
  * platform-bound. All three implementations delegate to one shared module.
  */
-export interface ModCodec {
-    /** Decode a ProTracker module. Throws on anything that is not one, rather than returning a garbage file that looks imported. */
-    decode(bytes: ArrayBuffer): ModFile;
+export interface TrackerCodec {
+    /** Sniffs the format from the bytes and decodes it. Throws on anything that is not one, rather than returning a garbage module that looks imported. */
+    decode(bytes: ArrayBuffer): TrackerModule;
 }
 //# sourceMappingURL=mod.d.ts.map

package/dist/platform/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/platform/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,oFAAoF;AACpF,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAExF,MAAM,MAAM,OAAO,GAAG;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,2FAA2F;IAC3F,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yCAAyC;IACzC,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;CACzB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,gIAAgI;IAChI,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC;CACrC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/platform/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC;AAEzE,2GAA2G;AAC3G,MAAM,MAAM,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,2FAA2F;IAC3F,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,mGAAmG;IACnG,QAAQ,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;CAC7B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,uJAAuJ;IACvJ,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,CAAC;CAC3C"}

package/dist/platform/mod.js

@@ -1,12 +1,17 @@
 /**
- * A neutral model of an Amiga tracker module, shaped by exactly what the
- * `.MOD` importer in music_lib reads — so that music_lib carries no byte
- * handling of its own, the same split `MidiFile` uses.
+ * A format-neutral model of a tracker module.
  *
- * Decoding stops at this shape deliberately. Turning periods into pitches and
- * speed/tempo into a `TempoMap` is musical work, so it lives in music_lib;
- * only the byte reading is platform-shaped, and even that is shared by all
- * three `MusicIo` implementations rather than reimplemented per platform.
+ * Was `ModFile`, shaped by exactly what ProTracker stores. That shape does not
+ * survive contact with the rest of the family: only MOD uses Amiga periods,
+ * only MOD has fixed 64-row patterns, and only MOD lets a sample stand in for
+ * an instrument. So the model states what every format agrees on and each
+ * decoder normalises its own quirks behind it — which is what keeps
+ * `trackerToScore` free of format branches.
+ *
+ * Decoding stops here deliberately. Turning this into a score is musical work
+ * and lives in music_lib; only the byte reading is platform-shaped, and even
+ * that is shared by all three `MusicIo` implementations rather than
+ * reimplemented per platform.
  */
 export {};
 //# sourceMappingURL=mod.js.map

package/dist/platform/mod.js.map

@@ -1 +1 @@
-{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../src/platform/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../src/platform/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/platform/playback.d.ts

@@ -15,9 +15,25 @@ export type TransportPlaybackState = 'stopped' | 'playing' | 'paused';
  * currently-sounding note ids changes; `onStateChange` fires on every
  * play/pause/stop transition, including ones the engine itself initiates.
  */
+export type SoundingNote = {
+    /** The `NoteEvent.id` this voice came from, for notation highlighting. */
+    noteId: string;
+    /** Which track it is on, so a consumer can filter without searching the score. */
+    trackId: string;
+    /** Its sounding MIDI pitch, so a keyboard can light a key without resolving the event. */
+    midi: number;
+};
 export type PlaybackObserver = {
     onPositionTick(tick: number): void;
-    onActiveNotes(noteIds: string[]): void;
+    /**
+     * The notes currently sounding, whenever that set changes.
+     *
+     * Resolved rather than bare ids. The scheduler already knows each note's
+     * track and pitch — it scheduled them — and emitting only the id forced every
+     * consumer to search the whole score to get it back: `playingPitchesForTrack`
+     * was an O(score) scan per sounding note, twenty times a second.
+     */
+    onActiveNotes(notes: SoundingNote[]): void;
     onStateChange(state: TransportPlaybackState): void;
     /**
      * How far along the engine is in becoming able to make a sound.

package/dist/platform/playback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playback.d.ts","sourceRoot":"","sources":["../../src/platform/playback.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACvC,aAAa,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACnD;;;;;;;;OAQG;IACH,iBAAiB,CAAC,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACpD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC9C;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GACnB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;IACb,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAAC;IACxC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACpD,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACnD;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,mCAAmC;IACnC,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACrC,kDAAkD;IAClD,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACpE,gFAAgF;IAChF,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4GAA4G;IAC5G,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAAC;IACrD,OAAO,IAAI,IAAI,CAAC;CACjB"}
+{"version":3,"file":"playback.d.ts","sourceRoot":"","sources":["../../src/platform/playback.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;;;;;OAOG;IACH,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAC3C,aAAa,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACnD;;;;;;;;OAQG;IACH,iBAAiB,CAAC,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACpD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC9C;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GACnB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;IACb,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAAC;IACxC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACpD,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACnD;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,mCAAmC;IACnC,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACrC,kDAAkD;IAClD,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACpE,gFAAgF;IAChF,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4GAA4G;IAC5G,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAAC;IACrD,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudobility/music_types",
-  "version": "0.11.16",
+  "version": "0.11.18",
   "description": "TypeScript types and Zod schemas for the ScoreSmith music API - scores, generation contracts, project payloads",
   "type": "module",
   "main": "./dist/index.js",