audio-mixer-engine 0.3.4 → 0.4.0

package/src/lib/audio-engine.js

@@ -1,579 +1,579 @@
-import stick4csUrl from '../assets/stick-4cs.mp3';
-import stick4dUrl from '../assets/stick-4d.mp3';
-
-/**
- * Abstract AudioEngine - Part-centric audio synthesis for audio mixers
- * This class provides the contract for creating and managing musical parts
- */
-export default class AudioEngine {
-  /**
-   * Create a new AudioEngine instance
-   * @param {AudioContext} audioContext - Web Audio API context
-   * @param {Object} options - Engine-specific options
-   */
-  constructor(audioContext, options = {}) {
-    if (new.target === AudioEngine) {
-      throw new Error('AudioEngine is abstract and cannot be instantiated directly');
-    }
-    
-    this.audioContext = audioContext;
-    this.options = options;
-    this.isInitialized = false;
-    this.channels = new WeakMap(); // ChannelHandle -> internal channel data
-    this.activeChannels = new Set(); // Track active channels for cleanup
-  }
-
-  /**
-   * Initialize the audio engine - load soundfont and set up synthesis
-   * @param {string|ArrayBuffer} soundfontData - Path to soundfont or binary data
-   * @returns {Promise<void>}
-   */
-  async initialize(soundfontData) {
-    throw new Error('initialize() must be implemented by subclass');
-  }
-
-  /**
-   * Create a new channel for a musical part
-   * @param {string} partId - Unique identifier for this part (e.g., 'soprano', 'piano')
-   * @param {Object} options - Channel configuration
-   * @param {string|number} [options.instrument] - Initial instrument
-   * @param {number} [options.initialVolume=1.0] - Initial volume (0.0-1.0)
-   * @returns {ChannelHandle} Handle object for controlling this channel
-   */
-  createChannel(partId, options = {}) {
-    throw new Error('createChannel() must be implemented by subclass');
-  }
-
-
-  /**
-   * Stop all notes on all channels
-   */
-  allSoundsOff() {
-    throw new Error('allSoundsOff() must be implemented by subclass');
-  }
-
-  /**
-   * Play a metronome tick sound using audio buffers (default implementation)
-   * @param {number} audioTime - Absolute audio context time for the tick
-   * @param {boolean} isAccent - Whether this is an accent beat (downbeat)
-   * @param {number} volume - Volume level (0.0-1.0)
-   * @returns {Promise<void>}
-   */
-  async playMetronomeTick(audioTime, isAccent, volume) {
-    try {
-      // Ensure metronome buffers are loaded
-      await this._ensureMetronomeBuffersLoaded();
-
-      const buffer = isAccent ? this.accentTickBuffer : this.regularTickBuffer;
-      if (!buffer) {
-        console.warn('Metronome buffer not available');
-        return;
-      }
-
-      // Create buffer source
-      const source = this.audioContext.createBufferSource();
-      source.buffer = buffer;
-
-      // Create gain node for volume control
-      const gainNode = this.audioContext.createGain();
-      gainNode.gain.value = volume;
-
-      // Connect: source -> gain -> metronome output
-      source.connect(gainNode);
-      const metronomeOutput = this.getMetronomeOutput();
-      if (metronomeOutput) {
-        gainNode.connect(metronomeOutput);
-      } else {
-        // Fallback to main destination if no metronome output
-        gainNode.connect(this.audioContext.destination);
-      }
-
-      // Start playback at specified time
-      const startTime = Math.max(audioTime, this.audioContext.currentTime);
-      source.start(startTime);
-
-    } catch (error) {
-      console.warn('Buffer metronome playback failed:', error);
-      // Silently continue - metronome failure shouldn't break playback
-    }
-  }
-
-  /**
-   * Get the audio output node for metronome sounds (default implementation)
-   * This allows the mixer to route metronome audio separately
-   * @returns {AudioNode|null} Metronome output node or null if not available
-   */
-  getMetronomeOutput() {
-    // Initialize metronome output if not already created
-    if (!this._metronomeOutput) {
-      this._metronomeOutput = this.audioContext.createGain();
-      this._metronomeOutput.gain.value = 1.0;
-      this._metronomeOutput.connect(this.audioContext.destination);
-    }
-    return this._metronomeOutput;
-  }
-
-  /**
-   * Ensure metronome audio buffers are loaded
-   * @private
-   */
-  async _ensureMetronomeBuffersLoaded() {
-    // Skip loading if buffers already exist
-    if (this.regularTickBuffer && this.accentTickBuffer) {
-      return;
-    }
-
-    try {
-      // Try to load tick sound files if available
-      if (typeof fetch !== 'undefined') {
-        const [regularResponse, accentResponse] = await Promise.all([
-          fetch(stick4csUrl),
-          fetch(stick4dUrl)
-        ]);
-
-        const [regularBuffer, accentBuffer] = await Promise.all([
-          regularResponse.arrayBuffer(),
-          accentResponse.arrayBuffer()
-        ]);
-
-        const [regularAudioBuffer, accentAudioBuffer] = await Promise.all([
-          this.audioContext.decodeAudioData(regularBuffer),
-          this.audioContext.decodeAudioData(accentBuffer)
-        ]);
-
-        this.regularTickBuffer = regularAudioBuffer;
-        this.accentTickBuffer = accentAudioBuffer;
-        return;
-      }
-    } catch (error) {
-      console.warn('Failed to load metronome sounds:', error);
-    }
-
-    // Create silent fallback buffers (useful for testing or when files are missing)
-    this.regularTickBuffer = this.audioContext.createBuffer(2, 1024, this.audioContext.sampleRate);
-    this.accentTickBuffer = this.audioContext.createBuffer(2, 1024, this.audioContext.sampleRate);
-  }
-
-  /**
-   * Get list of all active channel handles
-   * @returns {Array<ChannelHandle>} Array of active channel handles
-   */
-  getActiveChannels() {
-    return Array.from(this.activeChannels);
-  }
-
-  /**
-   * Clean up all resources and disconnect audio nodes
-   */
-  destroy() {
-    // Stop all sounds
-    this.allSoundsOff();
-
-    // Clean up metronome resources
-    if (this._metronomeOutput) {
-      this._metronomeOutput.disconnect();
-      this._metronomeOutput = null;
-    }
-    this.regularTickBuffer = null;
-    this.accentTickBuffer = null;
-
-    // Clear tracking collections
-    this.activeChannels.clear();
-
-    this.isInitialized = false;
-  }
-
-  /**
-   * Validate that the engine is initialized
-   * @protected
-   */
-  _validateInitialized() {
-    if (!this.isInitialized) {
-      throw new Error('AudioEngine not initialized. Call initialize() first.');
-    }
-  }
-
-  /**
-   * Register a new channel handle (called by subclasses)
-   * @param {ChannelHandle} handle - Channel handle to register
-   * @protected
-   */
-  _registerChannel(handle) {
-    this.activeChannels.add(handle);
-  }
-
-  /**
-   * Unregister a channel handle (called when channel is destroyed)
-   * @param {ChannelHandle} handle - Channel handle to unregister
-   * @protected
-   */
-  _unregisterChannel(handle) {
-    this.activeChannels.delete(handle);
-    this.channels.delete(handle);
-  }
-}
-
-/**
- * ChannelHandle - Interface for controlling one musical part
- * Each instance represents one musical part (soprano, piano, etc.)
- */
-export class ChannelHandle {
-  constructor(engine, partId, options = {}) {
-    if (new.target === ChannelHandle) {
-      throw new Error('ChannelHandle is abstract and cannot be instantiated directly');
-    }
-    
-    this.engine = engine;
-    this.partId = partId;
-    this.options = { initialVolume: 1.0, ...options };
-    this.isDestroyed = false;
-    
-    // Reference counting for overlapping notes
-    this.noteRefCounts = new Map(); // pitch -> count
-    this.scheduledEvents = new Map(); // eventId -> timeoutId
-    this.activeNotes = new Set(); // Set of currently playing pitches
-  }
-
-  /**
-   * Get the output audio node for this channel
-   * This node can be connected to gain controls, analyzers, etc.
-   * @returns {AudioNode} Output node (typically a GainNode)
-   */
-  getOutputNode() {
-    throw new Error('getOutputNode() must be implemented by subclass');
-  }
-
-  /**
-   * Start a note with reference counting (handles overlaps automatically)
-   * @param {number} pitch - MIDI pitch (0-127)
-   * @param {number} velocity - Note velocity (0-127)
-   */
-  noteOn(pitch, velocity) {
-    this._validateActive();
-    
-    const currentCount = this.noteRefCounts.get(pitch) || 0;
-    
-    // Always increment reference count and start the note
-    this.noteRefCounts.set(pitch, currentCount + 1);
-    this._actualNoteOn(pitch, velocity);
-
-    // Add to active notes if not already playing
-    if (currentCount === 0) {
-      this.activeNotes.add(pitch);
-    }
-  }
-
-  /**
-   * Stop a note with reference counting (only stops when count reaches 0)
-   * @param {number} pitch - MIDI pitch (0-127)
-   */
-  noteOff(pitch) {
-    this._validateActive();
-    
-    const currentCount = this.noteRefCounts.get(pitch) || 0;
-    
-    if (currentCount <= 0) {
-      return; // No notes to stop
-    }
-    
-    const newCount = currentCount - 1;
-    this.noteRefCounts.set(pitch, newCount);
-    
-    // Only actually stop the note when reference count reaches 0
-    if (newCount === 0) {
-      this._actualNoteOff(pitch);
-      this.activeNotes.delete(pitch);
-      this.noteRefCounts.delete(pitch);
-    }
-  }
-
-  /**
-   * Schedule a note with automatic timing adjustment
-   * @param {number} startTime - Absolute audio context time when note should start
-   * @param {number} pitch - MIDI pitch (0-127)
-   * @param {number} velocity - Note velocity (0-127)
-   * @param {number} duration - Note duration in seconds
-   * @returns {string} Event ID for cancellation
-   */
-  playNote(startTime, pitch, velocity, duration) {
-    this._validateActive();
-    
-    const currentTime = this.engine.audioContext.currentTime;
-    const eventId = `${this.partId}_${startTime}_${pitch}_${Date.now()}`;
-    
-    // Adjust timing if start time is in the past
-    let adjustedStartTime = startTime;
-    let adjustedDuration = duration;
-    
-    if (startTime < currentTime) {
-      const timePassed = currentTime - startTime;
-      adjustedStartTime = currentTime;
-      adjustedDuration = Math.max(0, duration - timePassed);
-    }
-    
-    // If duration is too short after adjustment, skip this note
-    if (adjustedDuration <= 0) {
-      return eventId;
-    }
-    
-    // Schedule note on
-    const noteOnDelay = Math.max(0, (adjustedStartTime - currentTime) * 1000);
-    const noteOnTimeoutId = setTimeout(() => {
-      this.noteOn(pitch, velocity);
-      this.scheduledEvents.delete(`${eventId}_on`);
-    }, noteOnDelay);
-    
-    // Schedule note off
-    const noteOffDelay = noteOnDelay + (adjustedDuration * 1000);
-    const noteOffTimeoutId = setTimeout(() => {
-      this.noteOff(pitch);
-      this.scheduledEvents.delete(`${eventId}_off`);
-    }, noteOffDelay);
-    
-    // Track both events for cancellation
-    this.scheduledEvents.set(`${eventId}_on`, noteOnTimeoutId);
-    this.scheduledEvents.set(`${eventId}_off`, noteOffTimeoutId);
-    
-    return eventId;
-  }
-
-  /**
-   * Stop all notes on this channel
-   */
-  allNotesOff() {
-    this._validateActive();
-    
-    // Cancel all scheduled events
-    this.scheduledEvents.forEach(timeoutId => {
-      clearTimeout(timeoutId);
-    });
-    this.scheduledEvents.clear();
-    
-    // Stop all actively playing notes
-    this.activeNotes.forEach(pitch => {
-      this._actualNoteOff(pitch);
-    });
-    
-    // Reset all state
-    this.noteRefCounts.clear();
-    this.activeNotes.clear();
-  }
-
-  /**
-   * Actually start a note (implemented by subclass)
-   * @param {number} pitch - MIDI pitch (0-127)
-   * @param {number} velocity - Note velocity (0-127)
-   * @protected
-   */
-  _actualNoteOn(pitch, velocity) {
-    throw new Error('_actualNoteOn() must be implemented by subclass');
-  }
-
-  /**
-   * Actually stop a note (implemented by subclass)
-   * @param {number} pitch - MIDI pitch (0-127)
-   * @protected
-   */
-  _actualNoteOff(pitch) {
-    throw new Error('_actualNoteOff() must be implemented by subclass');
-  }
-
-  /**
-   * Change the instrument for this channel
-   * @param {string|number} instrument - Instrument name or program number
-   * @returns {Promise<void>}
-   */
-  async setInstrument(instrument) {
-    throw new Error('setInstrument() must be implemented by subclass');
-  }
-
-  /**
-   * Get current instrument for this channel
-   * @returns {string|number} Current instrument
-   */
-  getInstrument() {
-    throw new Error('getInstrument() must be implemented by subclass');
-  }
-
-  /**
-   * Set volume for this channel (affects the internal channel volume)
-   * Note: External volume control should use the output node from getOutputNode()
-   * @param {number} volume - Volume level (0.0-1.0)
-   */
-  setVolume(volume) {
-    throw new Error('setVolume() must be implemented by subclass');
-  }
-
-  /**
-   * Get current volume for this channel
-   * @returns {number} Current volume (0.0-1.0)
-   */
-  getVolume() {
-    throw new Error('getVolume() must be implemented by subclass');
-  }
-
-  /**
-   * Get the part ID for this channel
-   * @returns {string} Part identifier
-   */
-  getPartId() {
-    return this.partId;
-  }
-
-  /**
-   * Check if this channel is still active
-   * @returns {boolean} True if channel is active
-   */
-  isActive() {
-    return !this.isDestroyed && this.engine.isInitialized && this.engine.activeChannels.has(this);
-  }
-
-  /**
-   * Destroy this channel and clean up resources
-   */
-  destroy() {
-    if (!this.isDestroyed) {
-      this.allNotesOff();
-      
-      const outputNode = this.getOutputNode();
-      if (outputNode) {
-        outputNode.disconnect();
-      }
-      
-      // Clear reference counting state
-      this.noteRefCounts.clear();
-      this.scheduledEvents.clear();
-      this.activeNotes.clear();
-      
-      this.engine._unregisterChannel(this);
-      this.isDestroyed = true;
-    }
-  }
-
-  /**
-   * Validate that this channel is still active
-   * @protected
-   */
-  _validateActive() {
-    if (this.isDestroyed) {
-      throw new Error('Channel has been destroyed');
-    }
-    if (!this.engine.isInitialized) {
-      throw new Error('AudioEngine is not initialized');
-    }
-  }
-}
-
-const MidiInstrumentNumbers = {
-  // Piano family (0-7)
-  'piano': 0, 'bright_piano': 1, 'electric_grand': 2, 'honky_tonk': 3,
-  'electric_piano_1': 4, 'electric_piano_2': 5, 'harpsichord': 6, 'clavinet': 7,
-
-  // Chromatic percussion (8-15)
-  'celesta': 8, 'glockenspiel': 9, 'music_box': 10, 'vibraphone': 11,
-  'marimba': 12, 'xylophone': 13, 'tubular_bells': 14, 'dulcimer': 15,
-
-  // Organ (16-23)
-  'drawbar_organ': 16, 'percussive_organ': 17, 'rock_organ': 18, 'church_organ': 19,
-  'reed_organ': 20, 'accordion': 21, 'harmonica': 22, 'tango_accordion': 23,
-  'organ': 19,
-
-  // Guitar (24-31)
-  'nylon_guitar': 24, 'steel_guitar': 25, 'electric_guitar_jazz': 26, 'electric_guitar_clean': 27,
-  'electric_guitar_muted': 28, 'overdriven_guitar': 29, 'distortion_guitar': 30, 'guitar_harmonics': 31,
-  'guitar': 24,
-
-  // Bass (32-39)
-  'acoustic_bass': 32, 'electric_bass_finger': 33, 'electric_bass_pick': 34, 'fretless_bass': 35,
-  'slap_bass_1': 36, 'slap_bass_2': 37, 'synth_bass_1': 38, 'synth_bass_2': 39,
-  'bass': 32,
-
-  // Strings (40-47)
-  'violin': 40, 'viola': 41, 'cello': 42, 'contrabass': 43,
-  'tremolo_strings': 44, 'pizzicato_strings': 45, 'orchestral_harp': 46, 'timpani': 47,
-  'strings': 48, 'strings_ensemble': 48,
-
-  // Ensemble (48-55)
-  'slow_strings': 49, 'synth_strings_1': 50, 'synth_strings_2': 51,
-  'choir_aahs': 52, 'voice_oohs': 53, 'synth_voice': 54, 'orchestra_hit': 55,
-
-  // Brass (56-63)
-  'trumpet': 56, 'trombone': 57, 'tuba': 58, 'muted_trumpet': 59,
-  'french_horn': 60, 'brass_section': 61, 'synth_brass_1': 62, 'synth_brass_2': 63,
-
-  // Reed (64-71)
-  'soprano_sax': 64, 'alto_sax': 65, 'tenor_sax': 66, 'baritone_sax': 67,
-  'oboe': 68, 'english_horn': 69, 'bassoon': 70, 'clarinet': 71,
-  'saxophone': 64,
-
-  // Pipe (72-79)
-  'piccolo': 72, 'flute': 73, 'recorder': 74, 'pan_flute': 75,
-  'blown_bottle': 76, 'shakuhachi': 77, 'whistle': 78, 'ocarina': 79,
-
-  // Synth lead (80-87)
-  'lead_1_square': 80, 'lead_2_sawtooth': 81, 'lead_3_calliope': 82, 'lead_4_chiff': 83,
-  'lead_5_charang': 84, 'lead_6_voice': 85, 'lead_7_fifths': 86, 'lead_8_bass': 87,
-
-  // Synth pad (88-95)
-  'pad_1_new_age': 88, 'pad_2_warm': 89, 'pad_3_polysynth': 90, 'pad_4_choir': 91,
-  'pad_5_bowed': 92, 'pad_6_metallic': 93, 'pad_7_halo': 94, 'pad_8_sweep': 95,
-
-  // Synth effects (96-103)
-  'fx_1_rain': 96, 'fx_2_soundtrack': 97, 'fx_3_crystal': 98, 'fx_4_atmosphere': 99,
-  'fx_5_brightness': 100, 'fx_6_goblins': 101, 'fx_7_echoes': 102, 'fx_8_sci_fi': 103,
-
-  // Ethnic (104-111)
-  'sitar': 104, 'banjo': 105, 'shamisen': 106, 'koto': 107,
-  'kalimba': 108, 'bag_pipe': 109, 'fiddle': 110, 'shanai': 111,
-
-  // Percussive (112-119)
-  'tinkle_bell': 112, 'agogo': 113, 'steel_drums': 114, 'woodblock': 115,
-  'taiko_drum': 116, 'melodic_tom': 117, 'synth_drum': 118, 'reverse_cymbal': 119,
-
-  // Sound effects (120-127)
-  'guitar_fret_noise': 120, 'breath_noise': 121, 'seashore': 122, 'bird_tweet': 123,
-  'telephone_ring': 124, 'helicopter': 125, 'applause': 126, 'gunshot': 127
-};
-
-const MidiInstrumentNames = Object.entries(MidiInstrumentNumbers)
-  .reduce((o,[k,v])=>{
-    o[v]=k;
-    return o;
-  },{})
-
-/**
- * Utility class for common audio engine operations
- */
-export class AudioEngineUtils {
-  /**
-   * Map common instrument names to MIDI program numbers
-   * @param {string|number} instrument - Instrument name or program number
-   * @returns {number} MIDI program number
-   */
-  static getInstrumentProgram(instrument) {
-    if (typeof instrument === 'number') return instrument;
-    const program = MidiInstrumentNumbers[instrument.toLowerCase()];
-    return program !== undefined ? program : 0; // Default to Piano
-  }
-
-  /**
-   * Get instrument name from MIDI program number (for display purposes)
-   * @param {number} programNumber - MIDI program number (0-127)
-   * @returns {string} Instrument name or fallback
-   */
-  static getProgramName(programNumber) {
-
-    return MidiInstrumentNames[programNumber] || `Program ${programNumber}`;
-  }
-
-  /**
-   * Generate a unique note ID
-   * @param {number} channel - MIDI channel
-   * @param {number} pitch - MIDI pitch
-   * @param {number} startTime - Start time
-   * @returns {string} Unique note ID
-   */
-  static generateNoteId(channel, pitch, startTime) {
-    return `${channel}_${pitch}_${Math.round(startTime)}`;
-  }
+import stick4csUrl from '../assets/stick-4cs.mp3';
+import stick4dUrl from '../assets/stick-4d.mp3';
+
+/**
+ * Abstract AudioEngine - Part-centric audio synthesis for audio mixers
+ * This class provides the contract for creating and managing musical parts
+ */
+export default class AudioEngine {
+  /**
+   * Create a new AudioEngine instance
+   * @param {AudioContext} audioContext - Web Audio API context
+   * @param {Object} options - Engine-specific options
+   */
+  constructor(audioContext, options = {}) {
+    if (new.target === AudioEngine) {
+      throw new Error('AudioEngine is abstract and cannot be instantiated directly');
+    }
+    
+    this.audioContext = audioContext;
+    this.options = options;
+    this.isInitialized = false;
+    this.channels = new WeakMap(); // ChannelHandle -> internal channel data
+    this.activeChannels = new Set(); // Track active channels for cleanup
+  }
+
+  /**
+   * Initialize the audio engine - load soundfont and set up synthesis
+   * @param {string|ArrayBuffer} soundfontData - Path to soundfont or binary data
+   * @returns {Promise<void>}
+   */
+  async initialize(soundfontData) {
+    throw new Error('initialize() must be implemented by subclass');
+  }
+
+  /**
+   * Create a new channel for a musical part
+   * @param {string} partId - Unique identifier for this part (e.g., 'soprano', 'piano')
+   * @param {Object} options - Channel configuration
+   * @param {string|number} [options.instrument] - Initial instrument
+   * @param {number} [options.initialVolume=1.0] - Initial volume (0.0-1.0)
+   * @returns {ChannelHandle} Handle object for controlling this channel
+   */
+  createChannel(partId, options = {}) {
+    throw new Error('createChannel() must be implemented by subclass');
+  }
+
+
+  /**
+   * Stop all notes on all channels
+   */
+  allSoundsOff() {
+    throw new Error('allSoundsOff() must be implemented by subclass');
+  }
+
+  /**
+   * Play a metronome tick sound using audio buffers (default implementation)
+   * @param {number} audioTime - Absolute audio context time for the tick
+   * @param {boolean} isAccent - Whether this is an accent beat (downbeat)
+   * @param {number} volume - Volume level (0.0-1.0)
+   * @returns {Promise<void>}
+   */
+  async playMetronomeTick(audioTime, isAccent, volume) {
+    try {
+      // Ensure metronome buffers are loaded
+      await this._ensureMetronomeBuffersLoaded();
+
+      const buffer = isAccent ? this.accentTickBuffer : this.regularTickBuffer;
+      if (!buffer) {
+        console.warn('Metronome buffer not available');
+        return;
+      }
+
+      // Create buffer source
+      const source = this.audioContext.createBufferSource();
+      source.buffer = buffer;
+
+      // Create gain node for volume control
+      const gainNode = this.audioContext.createGain();
+      gainNode.gain.value = volume;
+
+      // Connect: source -> gain -> metronome output
+      source.connect(gainNode);
+      const metronomeOutput = this.getMetronomeOutput();
+      if (metronomeOutput) {
+        gainNode.connect(metronomeOutput);
+      } else {
+        // Fallback to main destination if no metronome output
+        gainNode.connect(this.audioContext.destination);
+      }
+
+      // Start playback at specified time
+      const startTime = Math.max(audioTime, this.audioContext.currentTime);
+      source.start(startTime);
+
+    } catch (error) {
+      console.warn('Buffer metronome playback failed:', error);
+      // Silently continue - metronome failure shouldn't break playback
+    }
+  }
+
+  /**
+   * Get the audio output node for metronome sounds (default implementation)
+   * This allows the mixer to route metronome audio separately
+   * @returns {AudioNode|null} Metronome output node or null if not available
+   */
+  getMetronomeOutput() {
+    // Initialize metronome output if not already created
+    if (!this._metronomeOutput) {
+      this._metronomeOutput = this.audioContext.createGain();
+      this._metronomeOutput.gain.value = 1.0;
+      this._metronomeOutput.connect(this.audioContext.destination);
+    }
+    return this._metronomeOutput;
+  }
+
+  /**
+   * Ensure metronome audio buffers are loaded
+   * @private
+   */
+  async _ensureMetronomeBuffersLoaded() {
+    // Skip loading if buffers already exist
+    if (this.regularTickBuffer && this.accentTickBuffer) {
+      return;
+    }
+
+    try {
+      // Try to load tick sound files if available
+      if (typeof fetch !== 'undefined') {
+        const [regularResponse, accentResponse] = await Promise.all([
+          fetch(stick4csUrl),
+          fetch(stick4dUrl)
+        ]);
+
+        const [regularBuffer, accentBuffer] = await Promise.all([
+          regularResponse.arrayBuffer(),
+          accentResponse.arrayBuffer()
+        ]);
+
+        const [regularAudioBuffer, accentAudioBuffer] = await Promise.all([
+          this.audioContext.decodeAudioData(regularBuffer),
+          this.audioContext.decodeAudioData(accentBuffer)
+        ]);
+
+        this.regularTickBuffer = regularAudioBuffer;
+        this.accentTickBuffer = accentAudioBuffer;
+        return;
+      }
+    } catch (error) {
+      console.warn('Failed to load metronome sounds:', error);
+    }
+
+    // Create silent fallback buffers (useful for testing or when files are missing)
+    this.regularTickBuffer = this.audioContext.createBuffer(2, 1024, this.audioContext.sampleRate);
+    this.accentTickBuffer = this.audioContext.createBuffer(2, 1024, this.audioContext.sampleRate);
+  }
+
+  /**
+   * Get list of all active channel handles
+   * @returns {Array<ChannelHandle>} Array of active channel handles
+   */
+  getActiveChannels() {
+    return Array.from(this.activeChannels);
+  }
+
+  /**
+   * Clean up all resources and disconnect audio nodes
+   */
+  destroy() {
+    // Stop all sounds
+    this.allSoundsOff();
+
+    // Clean up metronome resources
+    if (this._metronomeOutput) {
+      this._metronomeOutput.disconnect();
+      this._metronomeOutput = null;
+    }
+    this.regularTickBuffer = null;
+    this.accentTickBuffer = null;
+
+    // Clear tracking collections
+    this.activeChannels.clear();
+
+    this.isInitialized = false;
+  }
+
+  /**
+   * Validate that the engine is initialized
+   * @protected
+   */
+  _validateInitialized() {
+    if (!this.isInitialized) {
+      throw new Error('AudioEngine not initialized. Call initialize() first.');
+    }
+  }
+
+  /**
+   * Register a new channel handle (called by subclasses)
+   * @param {ChannelHandle} handle - Channel handle to register
+   * @protected
+   */
+  _registerChannel(handle) {
+    this.activeChannels.add(handle);
+  }
+
+  /**
+   * Unregister a channel handle (called when channel is destroyed)
+   * @param {ChannelHandle} handle - Channel handle to unregister
+   * @protected
+   */
+  _unregisterChannel(handle) {
+    this.activeChannels.delete(handle);
+    this.channels.delete(handle);
+  }
+}
+
+/**
+ * ChannelHandle - Interface for controlling one musical part
+ * Each instance represents one musical part (soprano, piano, etc.)
+ */
+export class ChannelHandle {
+  constructor(engine, partId, options = {}) {
+    if (new.target === ChannelHandle) {
+      throw new Error('ChannelHandle is abstract and cannot be instantiated directly');
+    }
+    
+    this.engine = engine;
+    this.partId = partId;
+    this.options = { initialVolume: 1.0, ...options };
+    this.isDestroyed = false;
+    
+    // Reference counting for overlapping notes
+    this.noteRefCounts = new Map(); // pitch -> count
+    this.scheduledEvents = new Map(); // eventId -> timeoutId
+    this.activeNotes = new Set(); // Set of currently playing pitches
+  }
+
+  /**
+   * Get the output audio node for this channel
+   * This node can be connected to gain controls, analyzers, etc.
+   * @returns {AudioNode} Output node (typically a GainNode)
+   */
+  getOutputNode() {
+    throw new Error('getOutputNode() must be implemented by subclass');
+  }
+
+  /**
+   * Start a note with reference counting (handles overlaps automatically)
+   * @param {number} pitch - MIDI pitch (0-127)
+   * @param {number} velocity - Note velocity (0-127)
+   */
+  noteOn(pitch, velocity) {
+    this._validateActive();
+    
+    const currentCount = this.noteRefCounts.get(pitch) || 0;
+    
+    // Always increment reference count and start the note
+    this.noteRefCounts.set(pitch, currentCount + 1);
+    this._actualNoteOn(pitch, velocity);
+
+    // Add to active notes if not already playing
+    if (currentCount === 0) {
+      this.activeNotes.add(pitch);
+    }
+  }
+
+  /**
+   * Stop a note with reference counting (only stops when count reaches 0)
+   * @param {number} pitch - MIDI pitch (0-127)
+   */
+  noteOff(pitch) {
+    this._validateActive();
+    
+    const currentCount = this.noteRefCounts.get(pitch) || 0;
+    
+    if (currentCount <= 0) {
+      return; // No notes to stop
+    }
+    
+    const newCount = currentCount - 1;
+    this.noteRefCounts.set(pitch, newCount);
+    
+    // Only actually stop the note when reference count reaches 0
+    if (newCount === 0) {
+      this._actualNoteOff(pitch);
+      this.activeNotes.delete(pitch);
+      this.noteRefCounts.delete(pitch);
+    }
+  }
+
+  /**
+   * Schedule a note with automatic timing adjustment
+   * @param {number} startTime - Absolute audio context time when note should start
+   * @param {number} pitch - MIDI pitch (0-127)
+   * @param {number} velocity - Note velocity (0-127)
+   * @param {number} duration - Note duration in seconds
+   * @returns {string} Event ID for cancellation
+   */
+  playNote(startTime, pitch, velocity, duration) {
+    this._validateActive();
+    
+    const currentTime = this.engine.audioContext.currentTime;
+    const eventId = `${this.partId}_${startTime}_${pitch}_${Date.now()}`;
+    
+    // Adjust timing if start time is in the past
+    let adjustedStartTime = startTime;
+    let adjustedDuration = duration;
+    
+    if (startTime < currentTime) {
+      const timePassed = currentTime - startTime;
+      adjustedStartTime = currentTime;
+      adjustedDuration = Math.max(0, duration - timePassed);
+    }
+    
+    // If duration is too short after adjustment, skip this note
+    if (adjustedDuration <= 0) {
+      return eventId;
+    }
+    
+    // Schedule note on
+    const noteOnDelay = Math.max(0, (adjustedStartTime - currentTime) * 1000);
+    const noteOnTimeoutId = setTimeout(() => {
+      this.noteOn(pitch, velocity);
+      this.scheduledEvents.delete(`${eventId}_on`);
+    }, noteOnDelay);
+    
+    // Schedule note off
+    const noteOffDelay = noteOnDelay + (adjustedDuration * 1000);
+    const noteOffTimeoutId = setTimeout(() => {
+      this.noteOff(pitch);
+      this.scheduledEvents.delete(`${eventId}_off`);
+    }, noteOffDelay);
+    
+    // Track both events for cancellation
+    this.scheduledEvents.set(`${eventId}_on`, noteOnTimeoutId);
+    this.scheduledEvents.set(`${eventId}_off`, noteOffTimeoutId);
+    
+    return eventId;
+  }
+
+  /**
+   * Stop all notes on this channel
+   */
+  allNotesOff() {
+    this._validateActive();
+    
+    // Cancel all scheduled events
+    this.scheduledEvents.forEach(timeoutId => {
+      clearTimeout(timeoutId);
+    });
+    this.scheduledEvents.clear();
+    
+    // Stop all actively playing notes
+    this.activeNotes.forEach(pitch => {
+      this._actualNoteOff(pitch);
+    });
+    
+    // Reset all state
+    this.noteRefCounts.clear();
+    this.activeNotes.clear();
+  }
+
+  /**
+   * Actually start a note (implemented by subclass)
+   * @param {number} pitch - MIDI pitch (0-127)
+   * @param {number} velocity - Note velocity (0-127)
+   * @protected
+   */
+  _actualNoteOn(pitch, velocity) {
+    throw new Error('_actualNoteOn() must be implemented by subclass');
+  }
+
+  /**
+   * Actually stop a note (implemented by subclass)
+   * @param {number} pitch - MIDI pitch (0-127)
+   * @protected
+   */
+  _actualNoteOff(pitch) {
+    throw new Error('_actualNoteOff() must be implemented by subclass');
+  }
+
+  /**
+   * Change the instrument for this channel
+   * @param {string|number} instrument - Instrument name or program number
+   * @returns {Promise<void>}
+   */
+  async setInstrument(instrument) {
+    throw new Error('setInstrument() must be implemented by subclass');
+  }
+
+  /**
+   * Get current instrument for this channel
+   * @returns {string|number} Current instrument
+   */
+  getInstrument() {
+    throw new Error('getInstrument() must be implemented by subclass');
+  }
+
+  /**
+   * Set volume for this channel (affects the internal channel volume)
+   * Note: External volume control should use the output node from getOutputNode()
+   * @param {number} volume - Volume level (0.0-1.0)
+   */
+  setVolume(volume) {
+    throw new Error('setVolume() must be implemented by subclass');
+  }
+
+  /**
+   * Get current volume for this channel
+   * @returns {number} Current volume (0.0-1.0)
+   */
+  getVolume() {
+    throw new Error('getVolume() must be implemented by subclass');
+  }
+
+  /**
+   * Get the part ID for this channel
+   * @returns {string} Part identifier
+   */
+  getPartId() {
+    return this.partId;
+  }
+
+  /**
+   * Check if this channel is still active
+   * @returns {boolean} True if channel is active
+   */
+  isActive() {
+    return !this.isDestroyed && this.engine.isInitialized && this.engine.activeChannels.has(this);
+  }
+
+  /**
+   * Destroy this channel and clean up resources
+   */
+  destroy() {
+    if (!this.isDestroyed) {
+      this.allNotesOff();
+      
+      const outputNode = this.getOutputNode();
+      if (outputNode) {
+        outputNode.disconnect();
+      }
+      
+      // Clear reference counting state
+      this.noteRefCounts.clear();
+      this.scheduledEvents.clear();
+      this.activeNotes.clear();
+      
+      this.engine._unregisterChannel(this);
+      this.isDestroyed = true;
+    }
+  }
+
+  /**
+   * Validate that this channel is still active
+   * @protected
+   */
+  _validateActive() {
+    if (this.isDestroyed) {
+      throw new Error('Channel has been destroyed');
+    }
+    if (!this.engine.isInitialized) {
+      throw new Error('AudioEngine is not initialized');
+    }
+  }
+}
+
+const MidiInstrumentNumbers = {
+  // Piano family (0-7)
+  'piano': 0, 'bright_piano': 1, 'electric_grand': 2, 'honky_tonk': 3,
+  'electric_piano_1': 4, 'electric_piano_2': 5, 'harpsichord': 6, 'clavinet': 7,
+
+  // Chromatic percussion (8-15)
+  'celesta': 8, 'glockenspiel': 9, 'music_box': 10, 'vibraphone': 11,
+  'marimba': 12, 'xylophone': 13, 'tubular_bells': 14, 'dulcimer': 15,
+
+  // Organ (16-23)
+  'drawbar_organ': 16, 'percussive_organ': 17, 'rock_organ': 18, 'church_organ': 19,
+  'reed_organ': 20, 'accordion': 21, 'harmonica': 22, 'tango_accordion': 23,
+  'organ': 19,
+
+  // Guitar (24-31)
+  'nylon_guitar': 24, 'steel_guitar': 25, 'electric_guitar_jazz': 26, 'electric_guitar_clean': 27,
+  'electric_guitar_muted': 28, 'overdriven_guitar': 29, 'distortion_guitar': 30, 'guitar_harmonics': 31,
+  'guitar': 24,
+
+  // Bass (32-39)
+  'acoustic_bass': 32, 'electric_bass_finger': 33, 'electric_bass_pick': 34, 'fretless_bass': 35,
+  'slap_bass_1': 36, 'slap_bass_2': 37, 'synth_bass_1': 38, 'synth_bass_2': 39,
+  'bass': 32,
+
+  // Strings (40-47)
+  'violin': 40, 'viola': 41, 'cello': 42, 'contrabass': 43,
+  'tremolo_strings': 44, 'pizzicato_strings': 45, 'orchestral_harp': 46, 'timpani': 47,
+  'strings': 48, 'strings_ensemble': 48,
+
+  // Ensemble (48-55)
+  'slow_strings': 49, 'synth_strings_1': 50, 'synth_strings_2': 51,
+  'choir_aahs': 52, 'voice_oohs': 53, 'synth_voice': 54, 'orchestra_hit': 55,
+
+  // Brass (56-63)
+  'trumpet': 56, 'trombone': 57, 'tuba': 58, 'muted_trumpet': 59,
+  'french_horn': 60, 'brass_section': 61, 'synth_brass_1': 62, 'synth_brass_2': 63,
+
+  // Reed (64-71)
+  'soprano_sax': 64, 'alto_sax': 65, 'tenor_sax': 66, 'baritone_sax': 67,
+  'oboe': 68, 'english_horn': 69, 'bassoon': 70, 'clarinet': 71,
+  'saxophone': 64,
+
+  // Pipe (72-79)
+  'piccolo': 72, 'flute': 73, 'recorder': 74, 'pan_flute': 75,
+  'blown_bottle': 76, 'shakuhachi': 77, 'whistle': 78, 'ocarina': 79,
+
+  // Synth lead (80-87)
+  'lead_1_square': 80, 'lead_2_sawtooth': 81, 'lead_3_calliope': 82, 'lead_4_chiff': 83,
+  'lead_5_charang': 84, 'lead_6_voice': 85, 'lead_7_fifths': 86, 'lead_8_bass': 87,
+
+  // Synth pad (88-95)
+  'pad_1_new_age': 88, 'pad_2_warm': 89, 'pad_3_polysynth': 90, 'pad_4_choir': 91,
+  'pad_5_bowed': 92, 'pad_6_metallic': 93, 'pad_7_halo': 94, 'pad_8_sweep': 95,
+
+  // Synth effects (96-103)
+  'fx_1_rain': 96, 'fx_2_soundtrack': 97, 'fx_3_crystal': 98, 'fx_4_atmosphere': 99,
+  'fx_5_brightness': 100, 'fx_6_goblins': 101, 'fx_7_echoes': 102, 'fx_8_sci_fi': 103,
+
+  // Ethnic (104-111)
+  'sitar': 104, 'banjo': 105, 'shamisen': 106, 'koto': 107,
+  'kalimba': 108, 'bag_pipe': 109, 'fiddle': 110, 'shanai': 111,
+
+  // Percussive (112-119)
+  'tinkle_bell': 112, 'agogo': 113, 'steel_drums': 114, 'woodblock': 115,
+  'taiko_drum': 116, 'melodic_tom': 117, 'synth_drum': 118, 'reverse_cymbal': 119,
+
+  // Sound effects (120-127)
+  'guitar_fret_noise': 120, 'breath_noise': 121, 'seashore': 122, 'bird_tweet': 123,
+  'telephone_ring': 124, 'helicopter': 125, 'applause': 126, 'gunshot': 127
+};
+
+const MidiInstrumentNames = Object.entries(MidiInstrumentNumbers)
+  .reduce((o,[k,v])=>{
+    o[v]=k;
+    return o;
+  },{})
+
+/**
+ * Utility class for common audio engine operations
+ */
+export class AudioEngineUtils {
+  /**
+   * Map common instrument names to MIDI program numbers
+   * @param {string|number} instrument - Instrument name or program number
+   * @returns {number} MIDI program number
+   */
+  static getInstrumentProgram(instrument) {
+    if (typeof instrument === 'number') return instrument;
+    const program = MidiInstrumentNumbers[instrument.toLowerCase()];
+    return program !== undefined ? program : 0; // Default to Piano
+  }
+
+  /**
+   * Get instrument name from MIDI program number (for display purposes)
+   * @param {number} programNumber - MIDI program number (0-127)
+   * @returns {string} Instrument name or fallback
+   */
+  static getProgramName(programNumber) {
+
+    return MidiInstrumentNames[programNumber] || `Program ${programNumber}`;
+  }
+
+  /**
+   * Generate a unique note ID
+   * @param {number} channel - MIDI channel
+   * @param {number} pitch - MIDI pitch
+   * @param {number} startTime - Start time
+   * @returns {string} Unique note ID
+   */
+  static generateNoteId(channel, pitch, startTime) {
+    return `${channel}_${pitch}_${Math.round(startTime)}`;
+  }
 }