audio-mixer-engine 0.1.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "audio-mixer-engine",
+  "version": "0.1.0",
+  "description": "Audio engine library for audio mixer applications with MIDI parsing, playback, and synthesis",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:coverage": "NODE_OPTIONS=\"--max-old-space-size=4096\" vitest run --coverage",
+    "test:parser": "NODE_OPTIONS=\"--max-old-space-size=4096\" vitest run --coverage tests/unit/lib/midi-parser.test.js"
+  },
+  "keywords": [
+    "audio",
+    "midi",
+    "choir",
+    "music",
+    "synthesis",
+    "web-audio"
+  ],
+  "author": "Your Name",
+  "license": "MIT",
+  "dependencies": {
+    "@vue/test-utils": "^2.4.6",
+    "mitt": "^3.0.1",
+    "spessasynth_lib": "^3.27.8",
+    "uuid": "^11.1.0",
+    "vite-plugin-vue-devtools": "^8.0.1"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.3",
+    "@vitest/coverage-v8": "^3.2.4",
+    "jsdom": "^26.0.0",
+    "node-web-audio-api": "^1.0.4",
+    "vite": "^6.2.4",
+    "vitest": "^3.1.1"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yourusername/audio-mixer-engine.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/audio-mixer-engine/issues"
+  },
+  "homepage": "https://github.com/yourusername/audio-mixer-engine#readme"
+}

package/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * Audio Mixer Engine - Main exports
+ * 
+ * This library provides audio synthesis and MIDI playback capabilities
+ * specifically designed for audio mixer applications.
+ */
+
+// Core audio engine
+export { default as AudioEngine, ChannelHandle, AudioEngineUtils } from './lib/audio-engine.js';
+
+// SpessaSynth implementation
+export { default as SpessaSynthAudioEngine } from './lib/spessasynth-audio-engine.js';
+export { default as SpessaSynthChannelHandle } from './lib/spessasynth-channel-handle.js';
+
+// MIDI processing
+export { default as MidiParser } from './lib/midi-parser.js';
+export { default as BeatMapper } from './lib/beat-mapper.js';
+export { default as MidiPlayer } from './lib/midi-player.js';

package/src/lib/audio-engine.js

@@ -0,0 +1,526 @@
+/**
+ * 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');
+  }
+
+  /**
+   * 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();
+    
+    // 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');
+    }
+  }
+}
+
+/**
+ * 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 instrumentMap = {
+      // 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 program = instrumentMap[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) {
+    const programNames = [
+      // Piano family (0-7)
+      'Piano', 'Bright Piano', 'Electric Grand', 'Honky-tonk Piano',
+      'Electric Piano 1', 'Electric Piano 2', 'Harpsichord', 'Clavinet',
+      
+      // Chromatic percussion (8-15)
+      'Celesta', 'Glockenspiel', 'Music Box', 'Vibraphone',
+      'Marimba', 'Xylophone', 'Tubular Bells', 'Dulcimer',
+      
+      // Organ (16-23)
+      'Drawbar Organ', 'Percussive Organ', 'Rock Organ', 'Church Organ',
+      'Reed Organ', 'Accordion', 'Harmonica', 'Tango Accordion',
+      
+      // Guitar (24-31)
+      'Nylon Guitar', 'Steel Guitar', 'Electric Guitar (jazz)', 'Electric Guitar (clean)',
+      'Electric Guitar (muted)', 'Overdriven Guitar', 'Distortion Guitar', 'Guitar Harmonics',
+      
+      // Bass (32-39)
+      'Acoustic Bass', 'Electric Bass (finger)', 'Electric Bass (pick)', 'Fretless Bass',
+      'Slap Bass 1', 'Slap Bass 2', 'Synth Bass 1', 'Synth Bass 2',
+      
+      // Strings (40-47)
+      'Violin', 'Viola', 'Cello', 'Contrabass',
+      'Tremolo Strings', 'Pizzicato Strings', 'Orchestral Harp', 'Timpani',
+      
+      // Ensemble (48-55)
+      'String Ensemble 1', 'String Ensemble 2', 'Synth Strings 1', 'Synth Strings 2',
+      'Choir Aahs', 'Voice Oohs', 'Synth Voice', 'Orchestra Hit',
+      
+      // Brass (56-63)
+      'Trumpet', 'Trombone', 'Tuba', 'Muted Trumpet',
+      'French Horn', 'Brass Section', 'Synth Brass 1', 'Synth Brass 2',
+      
+      // Reed (64-71)
+      'Soprano Sax', 'Alto Sax', 'Tenor Sax', 'Baritone Sax',
+      'Oboe', 'English Horn', 'Bassoon', 'Clarinet',
+      
+      // Pipe (72-79)
+      'Piccolo', 'Flute', 'Recorder', 'Pan Flute',
+      'Blown Bottle', 'Shakuhachi', 'Whistle', 'Ocarina',
+      
+      // Synth lead (80-87)
+      'Lead 1 (square)', 'Lead 2 (sawtooth)', 'Lead 3 (calliope)', 'Lead 4 (chiff)',
+      'Lead 5 (charang)', 'Lead 6 (voice)', 'Lead 7 (fifths)', 'Lead 8 (bass + lead)',
+      
+      // Synth pad (88-95)
+      'Pad 1 (new age)', 'Pad 2 (warm)', 'Pad 3 (polysynth)', 'Pad 4 (choir)',
+      'Pad 5 (bowed)', 'Pad 6 (metallic)', 'Pad 7 (halo)', 'Pad 8 (sweep)',
+      
+      // Synth effects (96-103)
+      'FX 1 (rain)', 'FX 2 (soundtrack)', 'FX 3 (crystal)', 'FX 4 (atmosphere)',
+      'FX 5 (brightness)', 'FX 6 (goblins)', 'FX 7 (echoes)', 'FX 8 (sci-fi)',
+      
+      // Ethnic (104-111)
+      'Sitar', 'Banjo', 'Shamisen', 'Koto',
+      'Kalimba', 'Bag pipe', 'Fiddle', 'Shanai',
+      
+      // Percussive (112-119)
+      'Tinkle Bell', 'Agogo', 'Steel Drums', 'Woodblock',
+      'Taiko Drum', 'Melodic Tom', 'Synth Drum', 'Reverse Cymbal',
+      
+      // Sound effects (120-127)
+      'Guitar Fret Noise', 'Breath Noise', 'Seashore', 'Bird Tweet',
+      'Telephone Ring', 'Helicopter', 'Applause', 'Gunshot'
+    ];
+    
+    return programNames[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)}`;
+  }
+}