/**
 * 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
  };
}