@sudobility/music_types 0.11.17 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudobility/music_types",
-  "version": "0.11.17",
+  "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",