@jeffy-g/live-midi-types 0.11.0 → 0.11.1

package/README.md

@@ -32,7 +32,7 @@ npm install @jeffy-g/live-midi-types
 
 ## Ableton MIDI clip data
 
-`TMidiClipData` stores beat-based source data. MIDI CC events are grouped by controller in `ccMap`; `knownCCEvents` determines which controller buckets are present and their traversal order.
+`TMidiClipData` stores beat-based source data and the clip's Program Change number. MIDI CC events are grouped by controller in `ccMap`; `knownCCEvents` determines which controller buckets are present and their traversal order.
 
 ```ts
 import {
@@ -60,6 +60,7 @@ const clip: TMidiClipData = {
   clipStartInBeats: 8,
   clipLength: 4,
   adjustTimeOftempee: 0,
+  programChange: 0,
   knownCCEvents: [64],
   notes: [note],
   ccMap: {
@@ -80,6 +81,18 @@ const controlChanges = flattenCCEventMap(
 );
 ```
 
+Pass a raw-data type to `TMidiClipData` when an application also needs source-specific clip data. Omitting the generic parameter leaves the `raw` property out of the contract.
+
+```ts
+type TRawClipData = {
+  currentStart: number;
+  currentEnd: number;
+};
+
+declare const clipWithRawData: TMidiClipData<TRawClipData>;
+clipWithRawData.raw.currentStart;
+```
+
 ### Event value contracts
 
 All event `time` values are floating point quarter-note beats relative to the start of the clip.
@@ -110,14 +123,14 @@ The root entry point also exports `TimeSignatureEvent` and `KeySignatureEvent` f
 
 ## Project summaries
 
-The project types add application IDs and display metadata to clip data. `TTrackInfo.clips` is a map keyed by each `TClipSummary.id`.
+The project types add application IDs and display metadata to clip data. `TTrackInfo.clips` is a map keyed by each `TClipSummary.id`. `TMidiTrackInfo` adds the MIDI output channel, while `TGeneralTrack` represents the track types that may appear in a parsed project.
 
 ```ts
 import type {
   TMidiClipData,
   TClipSummary,
+  TMidiTrackInfo,
   TParsedAbletonLiveSet,
-  TTrackInfo,
 } from "@jeffy-g/live-midi-types";
 
 declare const clip: TMidiClipData;
@@ -133,12 +146,13 @@ const clipSummary: TClipSummary<TMidiClipData> = {
   ...clip,
 };
 
-const track: TTrackInfo<TMidiClipData> = {
+const track: TMidiTrackInfo<TMidiClipData> = {
   originId: "12",
   id: "track-91d2",
   name: "Track 1",
   color: "0",
   annotation: "",
+  channel: 0,
   clips: {
     [clipSummary.id]: clipSummary,
   },
@@ -150,6 +164,15 @@ const project: TParsedAbletonLiveSet<TMidiClipData> = {
   tracks: [track],
   tempoAutomation: [{ time: 0, bpm: 120 }],
 };
+
+const tracks = project.tracks;
+for (let idx = 0, tracksLen = tracks.length; idx < tracksLen;) {
+  const currentTrack = tracks[idx++];
+  if ("channel" in currentTrack) {
+    // currentTrack.channel is number
+    currentTrack.channel;
+  }
+}
 ```
 
 `color` is the Ableton palette index stored as a string. Convert it to a CSS color with `getColorFromIndex()`.

package/dist/index.d.ts

@@ -12,4 +12,4 @@ export * from "./midi-event.js";
 export * from "./midi-clip.js";
 export * from "./project.js";
 export * from "./ableton-colors.js";
-export declare const version = "v0.11.0";
+export declare const version = "v0.11.1";

package/dist/index.js

@@ -12,4 +12,4 @@ export * from "./midi-event.js";
 export * from "./midi-clip.js";
 export * from "./project.js";
 export * from "./ableton-colors.js";
-export const version = "v0.11.0";
+export const version = "v0.11.1";

package/dist/midi-clip.d.ts

@@ -21,7 +21,7 @@ import type { NoteEvent, MetaTextEvent, PitchBendEvent, ControlChangeEvent, Chan
  * const data: TMidiClipData = ...;
  * ```
  */
-export type TMidiClipData = {
+export type TMidiClipData<GRawData = never> = {
   /**
    * Start position of the clip on the Live MidiTrack (in beats).
    */
@@ -46,6 +46,7 @@ export type TMidiClipData = {
    * Time adjustment for tempo mapping (in beats).
    */
   adjustTimeOftempee: number;
+  programChange: number;
   /**
    * CC numbers known to this clip, sorted in ascending order.
    *
@@ -82,7 +83,9 @@ export type TMidiClipData = {
    * @since v0.10.0
    */
   meta?: MetaTextEvent[];
-};
+} & (
+  [GRawData] extends [never] ? {} : { raw: GRawData }
+);
 /**
  * @param {Record<string, ControlChangeEvent[]>} ccEventMap
  * @param {number[]} knownCCEvents

package/dist/project.d.ts

@@ -144,6 +144,17 @@ export type TTrackInfo<T extends Record<string, any>> = {
    */
   meta?: MetaTextEvent[];
 };
+export type TMidiTrackInfo<T extends Record<string, any>> = TTrackInfo<T> & {
+  /**
+   * Midi Track output channel
+   * @since v0.11.1
+   */
+  channel: number;
+};
+/**
+ * @since v0.11.1
+ */
+export type TGeneralTrack<T extends Record<string, any>> = TTrackInfo<T> | TMidiTrackInfo<T>;
 /**
  * Parsed data required by the Ableton Live project UI.
  */
@@ -164,8 +175,23 @@ export type TParsedAbletonLiveSet<T extends Record<string, any>> = {
    * Tracks in the project.
    *
    * + Currently contains only MIDI tracks.
+   *
+   * + Future versions may also include other track types, such as audio tracks.
+   *
+   * ```ts
+   * declare const als: TParsedAbletonLiveSet<Record<string, never>>;
+   * const tracks = als.tracks;
+   *
+   * for (let idx = 0, tracksLen = tracks.length; idx < tracksLen;) {
+   *   const track = tracks[idx++];
+   *   if ("channel" in track) {
+   *     // track.channel is number
+   *     track.channel;
+   *   }
+   * }
+   * ```
    */
-  tracks: Array<TTrackInfo<T>>;
+  tracks: Array<TGeneralTrack<T>>;
   /**
    * Tempo automation events extracted from the master track.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffy-g/live-midi-types",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Common TypeScript types for Ableton Live MIDI clip and event data.",
   "type": "module",
   "main": "dist/index.js",