add initial version of tab-downloader

songsterr/instrument-map.ts

@@ -0,0 +1,41 @@
+/**
+ * Represents the MIDI playback configuration for an instrument track.
+ */
+export interface InstrumentMapping {
+  program: number; // General MIDI (GM) program number (0-127)
+  isPercussion: boolean; // Flag identifying if this is a percussion/drum track
+  primaryChannel?: number; // Primary MIDI channel for audio playback
+  secondaryChannel?: number; // Secondary MIDI channel for secondary articulations
+}
+
+/**
+ * Maps a Songsterr instrument ID to a playback mapping configuration compatible with General MIDI.
+ * 
+ * @param instrumentId The raw instrument ID provided by the Songsterr metadata payload.
+ * @returns An InstrumentMapping structure indicating MIDI program and channel attributes.
+ */
+export function mapSongsterrInstrumentToPlayback(
+  instrumentId: number | undefined
+): InstrumentMapping {
+  // In Songsterr's schema, instrument ID 1024 is reserved for Drums/Percussion.
+  if (instrumentId === 1024) {
+    return {
+      program: 0, // General MIDI standard uses program 0 on Channel 9 for percussion
+      isPercussion: true,
+      primaryChannel: 9, // Channel 9 (0-indexed, corresponding to physical channel 10) is the standard percussion channel
+      secondaryChannel: 9
+    };
+  }
+
+  // Fallback program defaults to Acoustic Guitar (24) if undefined, or clamps raw IDs between standard GM limits (0-127).
+  const normalizedProgram =
+    typeof instrumentId === 'number'
+      ? Math.min(Math.max(instrumentId, 0), 127)
+      : 24;
+
+  return {
+    program: normalizedProgram,
+    isPercussion: false
+  };
+}
+