audio-mixer-engine 0.1.0

package/src/lib/midi-player.js

@@ -0,0 +1,700 @@
+import mitt from 'mitt';
+import BeatMapper from './beat-mapper.js';
+
+/**
+ * Modern MidiPlayer - Part-centric MIDI player
+ * 
+ * IMPORTANT: This class provides MIDI playback and individual part outputs.
+ * For volume/mute/solo controls, you MUST set up external audio routing:
+ * 
+ * @example
+ * // 1. Create player
+ * const player = new MidiPlayer(engine, instrumentMap, midiData);
+ * 
+ * // 2. Set up external routing for each part (REQUIRED for audio output)
+ * const partOutput = player.getPartOutput('soprano');
+ * const externalGain = audioContext.createGain();
+ * const masterGain = audioContext.createGain();
+ * 
+ * partOutput.connect(externalGain);
+ * externalGain.connect(masterGain);
+ * masterGain.connect(audioContext.destination);
+ * 
+ * // 3. Control volume via external gain node
+ * externalGain.gain.value = 0.5; // 50% volume
+ * 
+ * Uses AudioEngine abstraction for synthesis
+ */
+export default class MidiPlayer {
+  /**
+   * Create a new MidiPlayer instance
+   * @param {AudioEngine} audioEngine - Initialized audio engine instance
+   * @param {Object} instrumentMap - Mapping of part names to instrument configurations  
+   * @param {Object} parsedMidiData - Output from MidiParser
+   * @param {Object} [structureMetadata] - Optional score structure for beat mapping
+   */
+  constructor(audioEngine, instrumentMap, parsedMidiData, structureMetadata = null) {
+    // Validate required parameters
+    if (!audioEngine || !audioEngine.isInitialized) {
+      throw new Error('Initialized AudioEngine is required');
+    }
+    if (!parsedMidiData) {
+      throw new Error('Parsed MIDI data is required');
+    }
+
+    // Core dependencies
+    this.audioEngine = audioEngine;
+    this.instrumentMap = instrumentMap || {};
+    this.parsedData = parsedMidiData;
+
+    // Initialize state
+    this._isPlaying = false;
+    this._currentTime = 0;
+    this._totalDuration = 0;
+    this.playbackSpeed = 1.0;
+    
+    // Channel management - part-centric approach
+    this.partChannels = new Map(); // partName -> ChannelHandle
+    this.partOutputs = new Map();  // partName -> GainNode (for external control)
+    
+    // Scheduling and timing
+    this.playbackStartTime = 0;
+    this.lookAheadTime = 0.05; // 50ms lookahead for scheduling
+    this.scheduleInterval = null;
+    this.partNotePointers = new Map(); // partName -> next note index to consider
+    this.partProgramPointers = new Map(); // partName -> next program change index to consider
+    
+    // Event handling with mitt
+    this.eventBus = mitt();
+    
+    // Beat mapping
+    this.beatMapper = new BeatMapper();
+    this.beats = []; // Will be populated from structure metadata or fallback
+
+    // Set up audio routing and calculate duration
+    this._setupPartChannels();
+    this._calculateTotalDuration();
+    
+    // Initialize note and program change pointers
+    this._resetNotePointers();
+    this._resetProgramPointers();
+    
+    // Generate beat mapping if structure provided
+    if (structureMetadata) {
+      this.beats = this.beatMapper.mapBeats(parsedMidiData, structureMetadata);
+    } else {
+      // Generate simple beat mapping from parsed data tempo changes
+      this.beats = this._generateSimpleBeatMapping();
+    }
+  }
+
+  // ========================================
+  // PUBLIC API METHODS (unchanged interface)
+  // ========================================
+
+  /**
+   * Start playback from current position
+   */
+  play() {
+    if (this._isPlaying) return;
+
+    this._isPlaying = true;
+    this.playbackStartTime = this.audioEngine.audioContext.currentTime - (this._currentTime / this.playbackSpeed);
+    
+    // Reset note and program change pointers based on current time
+    this._resetNotePointers();
+    this._resetProgramPointers();
+    
+    this._schedulePlayback();
+    this._startTimeUpdateLoop();
+  }
+
+  /**
+   * Start playback at a specific audio context time
+   * @param {number} startTime - Audio context time when playback should begin
+   */
+  playAt(startTime) {
+    if (this._isPlaying) return;
+
+    this._isPlaying = true;
+    this.playbackStartTime = startTime - (this._currentTime / this.playbackSpeed);
+    
+    // Reset note and program change pointers based on current time
+    this._resetNotePointers();
+    this._resetProgramPointers();
+    
+    this._schedulePlayback();
+    this._startTimeUpdateLoop();
+  }
+
+  /**
+   * Pause playback (resumable)
+   */
+  pause() {
+    if (!this._isPlaying) return;
+    
+    this._isPlaying = false;
+    this._stopScheduling();
+    this._stopTimeUpdateLoop();
+  }
+
+  /**
+   * Stop playback and reset to beginning
+   */
+  stop() {
+    this._isPlaying = false;
+    this._currentTime = 0;
+    this._stopScheduling();
+    this._stopTimeUpdateLoop();
+    this._resetNotePointers();
+    this._resetProgramPointers();
+  }
+
+  /**
+   * Skip to a specific time in seconds
+   * @param {number} seconds - Time to skip to
+   */
+  skipToTime(seconds) {
+    seconds = Math.max(0, Math.min(seconds, this._totalDuration));
+    
+    const wasPlaying = this._isPlaying;
+    if (wasPlaying) {
+      this.pause();
+    }
+    
+    this._currentTime = seconds;
+    this._resetNotePointers();
+    this._resetProgramPointers();
+    
+    if (wasPlaying) {
+      this.play();
+    }
+  }
+
+  /**
+   * Set playback speed
+   * @param {number} speed - Speed multiplier (1.0 = normal)
+   */
+  setPlaybackSpeed(speed) {
+    if (speed <= 0) {
+      throw new Error('Playback speed must be greater than 0');
+    }
+
+    const wasPlaying = this._isPlaying;
+    
+    if (wasPlaying) {
+      this.pause();
+    }
+    
+    this.playbackSpeed = speed;
+    
+    if (wasPlaying) {
+      this.play();
+    }
+  }
+
+  /**
+   * Navigate to a specific bar position
+   * @param {number} barNumber - Bar number (1-based)
+   * @param {number} repeat - Repeat section number (0-based)
+   */
+  setBar(barNumber, repeat = 0) {
+    const time = this.getTimeFromBar(barNumber, repeat);
+    if (time !== null) {
+      this.skipToTime(time);
+      this._emitEvent('barChanged', { bar: barNumber, beat: 1, repeat, time });
+    }
+  }
+  
+  /**
+   * Get time position for a specific bar
+   * @param {number} barNumber - Bar number (1-based)
+   * @param {number} repeat - Repeat section number (0-based)
+   * @returns {number|null} Time in seconds or null if not found
+   */
+  getTimeFromBar(barNumber, repeat = 0) {
+    const beat = this.beats.find(b => 
+      b.bar === barNumber && b.beat === 1 && b.repeat === repeat
+    );
+    return beat ? beat.time : null;
+  }
+  
+  /**
+   * Get bar information for a specific time position
+   * @param {number} time - Time in seconds
+   * @returns {Object|null} Bar info object or null
+   */
+  getBarFromTime(time) {
+    if (!this.beats.length) return null;
+    
+    let currentBeat = null;
+    for (let i = this.beats.length - 1; i >= 0; i--) {
+      if (this.beats[i].time <= time) {
+        currentBeat = this.beats[i];
+        break;
+      }
+    }
+    return currentBeat;
+  }
+
+  
+  /**
+   * Stop all sounds immediately
+   */
+  allSoundsOff() {
+    this.audioEngine.allSoundsOff();
+  }
+
+  /**
+   * Get the output node for a specific part for external mixer routing
+   * 
+   * IMPORTANT: You MUST connect this output to external gain/analyzer nodes:
+   * 
+   * @example
+   * const partOutput = player.getPartOutput('soprano');
+   * const externalGain = audioContext.createGain();
+   * const analyzer = audioContext.createAnalyser();
+   * 
+   * partOutput.connect(externalGain);
+   * externalGain.connect(analyzer);
+   * analyzer.connect(masterGain); // External master gain
+   * 
+   * // Now control volume via external gain:
+   * externalGain.gain.value = 0.5; // 50% volume
+   * 
+   * @param {string} partName - Name of the part (e.g., 'soprano', 'alto')
+   * @returns {AudioNode|null} Output gain node for this part
+   */
+  getPartOutput(partName) {
+    return this.partOutputs.get(partName) || null;
+  }
+
+  /**
+   * Get the channel handle for a specific part (for direct note control)
+   * @param {string} partName - Name of the part
+   * @returns {ChannelHandle|null} Channel handle for this part
+   */
+  getPartChannel(partName) {
+    return this.partChannels.get(partName) || null;
+  }
+
+
+  // ========================================
+  // STATE ACCESS METHODS (unchanged)
+  // ========================================
+
+  getCurrentTime() {
+    if (this._isPlaying) {
+      const elapsed = (this.audioEngine.audioContext.currentTime - this.playbackStartTime) * this.playbackSpeed;
+      this._currentTime = Math.min(elapsed, this._totalDuration);
+    }
+    return this._currentTime;
+  }
+
+  getTotalDuration() {
+    return this._totalDuration;
+  }
+
+  isPlaying() {
+    return this._isPlaying;
+  }
+
+  // ========================================
+  // EVENT HANDLING (mitt-based)
+  // ========================================
+
+  on(event, callback) {
+    this.eventBus.on(event, callback);
+  }
+
+  off(event, callback) {
+    this.eventBus.off(event, callback);
+  }
+
+  // ========================================
+  // PART-CENTRIC IMPLEMENTATION METHODS
+  // ========================================
+
+  /**
+   * Set up channel handles for each musical part
+   * @private
+   */
+  _setupPartChannels() {
+    Object.keys(this.parsedData.parts).forEach(partName => {
+      // Get instrument configuration for this part
+      const partData = this.parsedData.parts[partName];
+      const instrumentConfig = this.instrumentMap[partName] || {};
+      
+      // Use MIDI program change if available, otherwise fall back to instrumentConfig or default
+      const instrument = instrumentConfig.instrument !== undefined 
+        ? instrumentConfig.instrument 
+        : (partData.defaultInstrument !== undefined ? partData.defaultInstrument : 0);
+      
+      try {
+        // Create channel handle through audio engine
+        const channelHandle = this.audioEngine.createChannel(partName, {
+          instrument: instrument,
+          initialVolume: instrumentConfig.volume || 1.0
+        });
+        
+        this.partChannels.set(partName, channelHandle);
+        
+        // Create external gain node for mixer control
+        const partGain = this.audioEngine.audioContext.createGain();
+        partGain.gain.value = 1.0;
+        
+        // Connect: ChannelHandle -> PartGain
+        // Note: The actual audio routing depends on the specific AudioEngine implementation
+        // This provides the interface for external volume control, solo/mute, and analysis
+        const channelOutput = channelHandle.getOutputNode();
+        if (channelOutput) {
+          channelOutput.connect(partGain);
+        }
+        
+        this.partOutputs.set(partName, partGain);
+        
+      } catch (error) {
+        console.error(`Failed to create channel for part '${partName}':`, error);
+        this._emitEvent('error', error);
+      }
+    });
+  }
+
+  /**
+   * Calculate total duration from parsed MIDI data
+   * @private
+   */
+  _calculateTotalDuration() {
+    let maxEndTime = 0;
+    
+    Object.values(this.parsedData.parts).forEach(part => {
+      part.notes.forEach(note => {
+        if (note.endTime > maxEndTime) {
+          maxEndTime = note.endTime;
+        }
+      });
+    });
+    
+    this._totalDuration = maxEndTime;
+  }
+
+  /**
+   * Schedule all notes for playback using simplified approach
+   * @private
+   */
+  _schedulePlayback() {
+    // Stop any existing scheduling
+    this._stopScheduling();
+
+    // Start the simplified scheduling loop
+    this._startScheduleLoop();
+  }
+
+  /**
+   * Start the simplified scheduling loop
+   * @private
+   */
+  _startScheduleLoop() {
+    if (this.scheduleInterval) return;
+
+    this.scheduleInterval = setInterval(() => {
+      if (!this._isPlaying) return;
+
+      const currentTime = this.audioEngine.audioContext.currentTime;
+      const playbackTime = (currentTime - this.playbackStartTime) * this.playbackSpeed;
+      const scheduleAheadTime = playbackTime + this.lookAheadTime;
+
+      // Simple scheduling: advance pointers and schedule upcoming events
+      for (const [partName, channelHandle] of this.partChannels) {
+        const partData = this.parsedData.parts[partName];
+        if (!partData) continue;
+
+        // Handle program changes
+        if (partData.programChanges && partData.programChanges.length > 0) {
+          let programIndex = this.partProgramPointers.get(partName) || 0;
+          const programChanges = partData.programChanges;
+
+          // Skip program changes that have already passed
+          while (programIndex < programChanges.length && programChanges[programIndex].time < playbackTime) {
+            programIndex++;
+          }
+
+          // Apply program changes that should happen within the lookahead window
+          while (programIndex < programChanges.length && programChanges[programIndex].time <= scheduleAheadTime) {
+            const programChange = programChanges[programIndex];
+            channelHandle.setInstrument(programChange.programNumber);
+            programIndex++;
+          }
+
+          // Update pointer for this part
+          this.partProgramPointers.set(partName, programIndex);
+        }
+
+        // Handle notes
+        if (partData.notes) {
+          let noteIndex = this.partNotePointers.get(partName) || 0;
+          const notes = partData.notes;
+
+          // Skip notes that have already ended
+          while (noteIndex < notes.length && notes[noteIndex].endTime < playbackTime) {
+            noteIndex++;
+          }
+
+          // Schedule notes that should start within the lookahead window
+          while (noteIndex < notes.length && notes[noteIndex].startTime <= scheduleAheadTime) {
+            const note = notes[noteIndex];
+            
+            // Skip zero-duration notes
+            if (note.endTime - note.startTime >= 0.01) {
+              const audioStartTime = this.playbackStartTime + (note.startTime / this.playbackSpeed);
+              const audioDuration = (note.endTime - note.startTime) / this.playbackSpeed;
+              
+              channelHandle.playNote(audioStartTime, note.pitch, note.velocity, audioDuration);
+            }
+            
+            noteIndex++;
+          }
+
+          // Update pointer for this part
+          this.partNotePointers.set(partName, noteIndex);
+        }
+      }
+    }, 50); // Schedule every 50ms - less frequent since we're doing less work
+  }
+
+  /**
+   * Reset note pointers for all parts based on current playback time
+   * @private
+   */
+  _resetNotePointers() {
+    const currentTime = this._currentTime;
+    
+    for (const [partName] of this.partChannels) {
+      const partData = this.parsedData.parts[partName];
+      if (!partData || !partData.notes) continue;
+      
+      // Find the first note that hasn't ended yet
+      let noteIndex = 0;
+      while (noteIndex < partData.notes.length && partData.notes[noteIndex].endTime < currentTime) {
+        noteIndex++;
+      }
+      
+      this.partNotePointers.set(partName, noteIndex);
+    }
+  }
+
+  /**
+   * Reset program change pointers for all parts based on current playback time
+   * @private
+   */
+  _resetProgramPointers() {
+    const currentTime = this._currentTime;
+    
+    for (const [partName, channelHandle] of this.partChannels) {
+      const partData = this.parsedData.parts[partName];
+      if (!partData || !partData.programChanges) {
+        this.partProgramPointers.set(partName, 0);
+        continue;
+      }
+      
+      // Find the most recent program change before current time
+      let programIndex = 0;
+      let lastActiveProgram = partData.defaultInstrument;
+      
+      while (programIndex < partData.programChanges.length && 
+             partData.programChanges[programIndex].time <= currentTime) {
+        lastActiveProgram = partData.programChanges[programIndex].programNumber;
+        programIndex++;
+      }
+      
+      // Set the current instrument to the most recent program
+      channelHandle.setInstrument(lastActiveProgram);
+      
+      this.partProgramPointers.set(partName, programIndex);
+    }
+  }
+
+  /**
+   * Stop scheduling and all channel notes
+   * @private
+   */
+  _stopScheduling() {
+    // Stop the scheduling loop
+    if (this.scheduleInterval) {
+      clearInterval(this.scheduleInterval);
+      this.scheduleInterval = null;
+    }
+
+    // Stop all notes on all channels (channels handle their own cleanup)
+    this.partChannels.forEach(channelHandle => {
+      if (channelHandle.isActive()) {
+        channelHandle.allNotesOff();
+      }
+    });
+  }
+
+  /**
+   * Start the time update loop for firing timeupdate events
+   * @private
+   */
+  _startTimeUpdateLoop() {
+    this.timeUpdateInterval = setInterval(() => {
+      const currentTime = this.getCurrentTime();
+      
+      // Emit timeupdate event
+      this._emitEvent('timeupdate', { currentTime });
+      
+      // Emit barChanged event if beat mapping is available
+      const barInfo = this.getBarFromTime(currentTime);
+      if (barInfo) {
+        this._emitEvent('barChanged', barInfo);
+      }
+      
+      // Check for end of playback
+      if (currentTime >= this._totalDuration) {
+        this.stop();
+        this._emitEvent('ended', { finalTime: currentTime });
+      }
+    }, 100); // Update every 100ms
+  }
+
+  /**
+   * Stop the time update loop
+   * @private
+   */
+  _stopTimeUpdateLoop() {
+    if (this.timeUpdateInterval) {
+      clearInterval(this.timeUpdateInterval);
+      this.timeUpdateInterval = null;
+    }
+  }
+
+  /**
+   * Emit an event to all registered listeners
+   * @param {string} eventType - Type of event
+   * @param {any} data - Data to pass to listeners
+   * @private
+   */
+  _emitEvent(eventType, data) {
+    // Get all listeners for this event type and call them individually
+    // to ensure one failing listener doesn't prevent others from being called
+    const listeners = this.eventBus.all.get(eventType) || [];
+    listeners.forEach(listener => {
+      try {
+        listener(data);
+      } catch (error) {
+        console.error(`Error in ${eventType} event listener:`, error);
+      }
+    });
+  }
+
+  /**
+   * Generate simple beat mapping from MIDI tempo changes when no structure metadata provided
+   * @returns {Array} Array of beat mapping objects
+   * @private
+   */
+  _generateSimpleBeatMapping() {
+    // Generate basic beat mapping from MIDI tempo changes
+    const beats = [];
+    const tempoChanges = this.parsedData.tempoChanges || [];
+    const defaultTempo = 120;
+    
+    // Use actual time signature from barStructure instead of hardcoding 4
+    const barStructure = this.parsedData.barStructure || [];
+    const firstBarData = barStructure[0] || { sig: [4, 4], bpm: defaultTempo };
+    const beatsPerBar = firstBarData.sig[0];
+    const tempo = Array.isArray(firstBarData.bpm) ? firstBarData.bpm[0] : firstBarData.bpm;
+    const secondsPerBeat = 60 / tempo;
+    const secondsPerBar = secondsPerBeat * beatsPerBar;
+    
+    if (tempoChanges.length === 0) {
+      // No tempo data, create mapping based on total duration and barStructure
+      const numBars = Math.max(1, Math.ceil(this._totalDuration / secondsPerBar));
+      let currentTime = 0;
+      
+      for (let bar = 1; bar <= numBars; bar++) {
+        // Get time signature for this specific bar (not just the first bar)
+        const barIndex = Math.max(0, bar - 1);
+        const currentBarData = barStructure[barIndex] || firstBarData;
+        const currentBeatsPerBar = currentBarData.sig[0];
+        const currentTempo = Array.isArray(currentBarData.bpm) ? currentBarData.bpm[0] : currentBarData.bpm;
+        const currentSecondsPerBeat = 60 / currentTempo;
+        
+        for (let beat = 1; beat <= currentBeatsPerBar; beat++) {
+          beats.push({
+            bar,
+            beat,
+            repeat: 0,
+            tempo: currentTempo,
+            time: currentTime,
+            timeSig: currentBeatsPerBar
+          });
+          
+          currentTime += currentSecondsPerBeat;
+        }
+      }
+      
+      return beats;
+    }
+    
+    // Convert tempo changes to beat array with all beats
+    // This is a simplified implementation - full beat mapping requires BeatMapper
+    let currentTime = 0;
+    let currentBar = 1;
+    
+    for (let i = 0; i < tempoChanges.length; i++) {
+      const change = tempoChanges[i];
+      const nextChange = tempoChanges[i + 1];
+      const endTime = nextChange ? nextChange.time : this._totalDuration;
+      const currentBpm = change.tempo || defaultTempo;
+      const currentSecondsPerBeat = 60 / currentBpm;
+      
+      // Generate beats from this tempo change to the next
+      while (currentTime < endTime) {
+        for (let beat = 1; beat <= beatsPerBar && currentTime < endTime; beat++) {
+          beats.push({
+            bar: currentBar,
+            beat,
+            repeat: 0,
+            tempo: currentBpm,
+            time: currentTime,
+            timeSig: beatsPerBar
+          });
+          
+          currentTime += currentSecondsPerBeat;
+        }
+        currentBar++;
+      }
+    }
+    
+    return beats;
+  }
+
+  /**
+   * Clean up resources and destroy the player
+   */
+  destroy() {
+    this.stop();
+    
+    // Destroy all channel handles
+    this.partChannels.forEach(channelHandle => {
+      channelHandle.destroy();
+    });
+    this.partChannels.clear();
+    
+    // Disconnect part outputs
+    this.partOutputs.forEach(gainNode => {
+      gainNode.disconnect();
+    });
+    this.partOutputs.clear();
+    
+    // Clear note and program change pointers
+    this.partNotePointers.clear();
+    this.partProgramPointers.clear();
+    
+    // Clear event bus
+    this.eventBus.all.clear();
+    
+    // Note: We don't destroy the audioEngine as it might be shared
+  }
+}