midiwire 0.1.0

package/src/core/MIDIController.js

@@ -0,0 +1,756 @@
+import { clamp, normalize14BitValue, normalizeValue } from "../utils/midi.js"
+import { EventEmitter } from "./EventEmitter.js"
+import { MIDIValidationError } from "./errors.js"
+import { MIDIConnection } from "./MIDIConnection.js"
+
+/**
+ * @typedef {Object} PatchData
+ * @property {string} name - Patch name
+ * @property {string|null} device - Output device name
+ * @property {string} timestamp - ISO timestamp
+ * @property {string} version - Patch format version
+ * @property {Object.<number, ChannelData>} channels - Channel data indexed by channel number
+ * @property {Object.<string, SettingData>} settings - Control settings indexed by setting key
+ */
+
+/**
+ * @typedef {Object} ChannelData
+ * @property {Object.<number, number>} ccs - CC values indexed by CC number
+ * @property {Object.<number, number>} notes - Note velocities indexed by note number
+ */
+
+/**
+ * @typedef {Object} SettingData
+ * @property {number} min - Minimum value
+ * @property {number} max - Maximum value
+ * @property {boolean} invert - Invert flag
+ * @property {boolean} is14Bit - 14-bit CC flag
+ * @property {string|null} label - Optional label
+ * @property {string|null} elementId - Element ID if available
+ * @property {Function|null} onInput - Optional callback for value updates
+ */
+
+/**
+ * Controller event constants
+ */
+export const CONTROLLER_EVENTS = {
+  READY: "ready",
+  ERROR: "error",
+  CC_SEND: "cc-send",
+  CC_RECV: "cc-recv",
+  NOTE_ON_SEND: "note-on-send",
+  NOTE_ON_RECV: "note-on-recv",
+  NOTE_OFF_SEND: "note-off-send",
+  NOTE_OFF_RECV: "note-off-recv",
+  SYSEX_SEND: "sysex-send",
+  SYSEX_RECV: "sysex-recv",
+  OUTPUT_CHANGED: "output-changed",
+  INPUT_CONNECTED: "input-connected",
+  DESTROYED: "destroyed",
+  MIDI_MSG: "midi-msg",
+  PATCH_SAVED: "patch-saved",
+  PATCH_LOADED: "patch-loaded",
+  PATCH_DELETED: "patch-deleted",
+}
+
+/**
+ * Main controller for browser-based MIDI operations. Provides APIs for:
+ * - Device management (connect/disconnect, enumerate devices)
+ * - Control binding (DOM elements ↔ MIDI CC)
+ * - MIDI messaging (send/receive CC, Note, SysEx)
+ * - Patch management (save/load presets)
+ * - Event handling (MIDI messages, connection changes, errors)
+ * @extends EventEmitter
+ */
+export class MIDIController extends EventEmitter {
+  /**
+   * @param {Object} options
+   * @param {number} [options.channel=1] - Default MIDI channel (1-16)
+   * @param {string|number} [options.output] - MIDI output device
+   * @param {string|number} [options.input] - MIDI input device
+   * @param {boolean} [options.sysex=false] - Request SysEx access
+   * @param {boolean} [options.autoConnect=true] - Auto-connect to first available output
+   * @param {Function} [options.onReady] - Callback when MIDI is ready
+   * @param {Function} [options.onError] - Error handler
+   */
+  constructor(options = {}) {
+    super()
+
+    this.options = {
+      channel: 1,
+      autoConnect: true,
+      sysex: false,
+      ...options,
+    }
+
+    this.connection = null
+    this.bindings = new Map()
+    this.state = new Map() // Track all CC values
+    this.initialized = false
+  }
+
+  /**
+   * Initialize MIDI access
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    if (this.initialized) {
+      console.warn("MIDI Controller already initialized")
+      return
+    }
+
+    try {
+      this.connection = new MIDIConnection({
+        sysex: this.options.sysex,
+      })
+
+      await this.connection.requestAccess()
+
+      if (this.options.autoConnect) {
+        await this.connection.connect(this.options.output)
+      }
+
+      // Connect input if specified
+      if (this.options.input !== undefined) {
+        await this.connectInput(this.options.input)
+      }
+
+      this.initialized = true
+      this.emit(CONTROLLER_EVENTS.READY, this)
+      this.options.onReady?.(this)
+    } catch (err) {
+      this.emit(CONTROLLER_EVENTS.ERROR, err)
+      this.options.onError?.(err)
+      throw err
+    }
+  }
+
+  /**
+   * Connect to a MIDI input device for receiving messages
+   * @param {string|number} device - Device name, ID, or index
+   * @returns {Promise<void>}
+   */
+  async connectInput(device) {
+    await this.connection.connectInput(device, (event) => {
+      this._handleMIDIMessage(event)
+    })
+    this.emit(CONTROLLER_EVENTS.INPUT_CONNECTED, this.connection.getCurrentInput())
+  }
+
+  /**
+   * Send a control change message
+   * @param {number} cc - CC number (0-127)
+   * @param {number} value - CC value (0-127)
+   * @param {number} [channel] - MIDI channel (defaults to controller channel)
+   */
+  sendCC(cc, value, channel = this.options.channel) {
+    if (!this.initialized) {
+      console.warn("MIDI not initialized. Call initialize() first.")
+      return
+    }
+
+    // Validate inputs
+    cc = clamp(Math.round(cc), 0, 127)
+    value = clamp(Math.round(value), 0, 127)
+    channel = clamp(Math.round(channel), 1, 16)
+
+    const status = 0xb0 + (channel - 1) // Control Change status
+    this.connection.send([status, cc, value])
+
+    // Update state
+    const key = `${channel}:${cc}`
+    this.state.set(key, value)
+
+    this.emit(CONTROLLER_EVENTS.CC_SEND, { cc, value, channel })
+  }
+
+  /**
+   * Send a SysEx message
+   * @param {Array<number>} data - SysEx data bytes (without F0/F7 wrapper)
+   * @param {boolean} [includeWrapper=false] - If true, data already includes F0/F7
+   *
+   * @example
+   * // Send with wrapper included
+   * midi.sendSysEx([0xF0, 0x42, 0x30, 0x00, 0x01, 0x2F, 0x12, 0xF7], true)
+   */
+  sendSysEx(data, includeWrapper = false) {
+    if (!this.initialized) {
+      console.warn("MIDI not initialized. Call initialize() first.")
+      return
+    }
+
+    if (!this.options.sysex) {
+      console.warn("SysEx not enabled. Initialize with sysex: true")
+      return
+    }
+
+    this.connection.sendSysEx(data, includeWrapper)
+    this.emit(CONTROLLER_EVENTS.SYSEX_SEND, { data, includeWrapper })
+  }
+
+  /**
+   * Send a note on message
+   * @param {number} note - Note number (0-127)
+   * @param {number} [velocity=64] - Note velocity (0-127)
+   * @param {number} [channel] - MIDI channel
+   */
+  sendNoteOn(note, velocity = 64, channel = this.options.channel) {
+    if (!this.initialized) return
+
+    note = clamp(Math.round(note), 0, 127)
+    velocity = clamp(Math.round(velocity), 0, 127)
+    channel = clamp(Math.round(channel), 1, 16)
+
+    const status = 0x90 + (channel - 1)
+    this.connection.send([status, note, velocity])
+
+    this.emit(CONTROLLER_EVENTS.NOTE_ON_SEND, { note, velocity, channel })
+  }
+
+  /**
+   * Send a note off message
+   * @param {number} note - Note number (0-127)
+   * @param {number} [channel] - MIDI channel
+   * @param {number} [velocity=0] - Release velocity (0-127)
+   */
+  sendNoteOff(note, channel = this.options.channel, velocity = 0) {
+    if (!this.initialized) return
+
+    note = clamp(Math.round(note), 0, 127)
+    velocity = clamp(Math.round(velocity), 0, 127)
+    channel = clamp(Math.round(channel), 1, 16)
+
+    // Use Note On with velocity 0 for better compatibility with some synths
+    const status = 0x90 + (channel - 1)
+    this.connection.send([status, note, velocity])
+
+    this.emit(CONTROLLER_EVENTS.NOTE_OFF_SEND, { note, channel, velocity })
+  }
+
+  /**
+   * Bind a control programmatically
+   * @param {HTMLElement} element - DOM element
+   * @param {Object} config - Binding configuration
+   * @param {number} config.cc - CC number
+   * @param {number} [config.min=0] - Minimum input value
+   * @param {number} [config.max=127] - Maximum input value
+   * @param {number} [config.channel] - Override channel
+   * @param {boolean} [config.invert=false] - Invert the value
+   * @param {Function} [config.onInput] - Optional callback for value updates (receives normalized element value)
+   * @param {Object} [options={}] - Additional options
+   * @param {number} [options.debounce=0] - Debounce delay in ms for high-frequency updates
+   * @returns {Function} Unbind function
+   */
+  bind(element, config, options = {}) {
+    if (!element) {
+      console.warn("Cannot bind: element is null or undefined")
+      return () => {}
+    }
+
+    const binding = this._createBinding(element, config, options)
+    this.bindings.set(element, binding)
+
+    // Send initial value
+    if (this.initialized && this.connection?.isConnected()) {
+      binding.handler({ target: element })
+    }
+
+    return () => this.unbind(element)
+  }
+
+  /**
+   * Unbind a control
+   * @param {HTMLElement} element
+   */
+  unbind(element) {
+    const binding = this.bindings.get(element)
+    if (binding) {
+      binding.destroy()
+      this.bindings.delete(element)
+    }
+  }
+
+  /**
+   * Get current value of a CC
+   * @param {number} cc - CC number
+   * @param {number} [channel] - MIDI channel
+   * @returns {number|undefined}
+   */
+  getCC(cc, channel = this.options.channel) {
+    const key = `${channel}:${cc}`
+    return this.state.get(key)
+  }
+
+  /**
+   * Get all available MIDI outputs
+   * @returns {Array<{id: string, name: string, manufacturer: string}>}
+   */
+  getOutputs() {
+    return this.connection?.getOutputs() || []
+  }
+
+  /**
+   * Get all available MIDI inputs
+   * @returns {Array<{id: string, name: string, manufacturer: string}>}
+   */
+  getInputs() {
+    return this.connection?.getInputs() || []
+  }
+
+  /**
+   * Switch to a different output device
+   * @param {string|number} output - Device name, ID, or index
+   * @returns {Promise<void>}
+   */
+  async setOutput(output) {
+    await this.connection.connect(output)
+    this.emit(CONTROLLER_EVENTS.OUTPUT_CHANGED, this.connection.getCurrentOutput())
+  }
+
+  /**
+   * Get current output device
+   * @returns {Object|null}
+   */
+  getCurrentOutput() {
+    return this.connection?.getCurrentOutput() || null
+  }
+
+  /**
+   * Get current input device
+   * @returns {Object|null}
+   */
+  getCurrentInput() {
+    return this.connection?.getCurrentInput() || null
+  }
+
+  /**
+   * Clean up resources
+   */
+  destroy() {
+    for (const binding of this.bindings.values()) {
+      binding.destroy()
+    }
+    this.bindings.clear()
+    this.state.clear()
+    this.connection?.disconnect()
+    this.initialized = false
+    this.emit(CONTROLLER_EVENTS.DESTROYED)
+    this.removeAllListeners()
+  }
+
+  /**
+   * Handle incoming MIDI messages
+   * @private
+   */
+  _handleMIDIMessage(event) {
+    const [status, data1, data2] = event.data
+    const messageType = status & 0xf0
+    const channel = (status & 0x0f) + 1
+
+    // SysEx message
+    if (status === 0xf0) {
+      this.emit(CONTROLLER_EVENTS.SYSEX_RECV, {
+        data: Array.from(event.data),
+        timestamp: event.midiwire,
+      })
+      return
+    }
+
+    // Control Change
+    if (messageType === 0xb0) {
+      const key = `${channel}:${data1}`
+      this.state.set(key, data2)
+
+      this.emit(CONTROLLER_EVENTS.CC_RECV, {
+        cc: data1,
+        value: data2,
+        channel,
+      })
+      return
+    }
+
+    // Note On
+    if (messageType === 0x90 && data2 > 0) {
+      this.emit(CONTROLLER_EVENTS.NOTE_ON_RECV, {
+        note: data1,
+        velocity: data2,
+        channel,
+      })
+      return
+    }
+
+    // Note Off (either 0x80 or 0x90 with velocity 0)
+    if (messageType === 0x80 || (messageType === 0x90 && data2 === 0)) {
+      this.emit(CONTROLLER_EVENTS.NOTE_OFF_RECV, {
+        note: data1,
+        channel,
+      })
+      return
+    }
+
+    // Other messages
+    this.emit(CONTROLLER_EVENTS.MIDI_MSG, {
+      status,
+      data: [data1, data2],
+      channel,
+      timestamp: event.midiwire,
+    })
+  }
+
+  /**
+   * Create a binding between an element and MIDI CC
+   * @private
+   */
+  _createBinding(element, config, options = {}) {
+    const {
+      min = parseFloat(element.getAttribute("min")) || 0,
+      max = parseFloat(element.getAttribute("max")) || 127,
+      channel,
+      invert = false,
+      onInput = undefined,
+    } = config
+    const { debounce = 0 } = options
+
+    // Store resolved values back to config for patch saving
+    // Don't store channel if not explicitly provided - use dynamic midi.options.channel
+    const resolvedConfig = {
+      ...config,
+      min,
+      max,
+      invert,
+      onInput,
+    }
+    if (channel !== undefined) {
+      resolvedConfig.channel = channel
+    }
+
+    // Handle 14-bit CC (MSB + LSB)
+    if (config.is14Bit) {
+      const { msb, lsb } = config
+
+      const handler = (event) => {
+        const value = parseFloat(event.target.value)
+
+        if (Number.isNaN(value)) return
+
+        // Normalize to 14-bit range (0-16383)
+        const { msb: msbValue, lsb: lsbValue } = normalize14BitValue(value, min, max, invert)
+
+        // Send MSB and LSB using dynamic channel
+        const channelToUse = channel || this.options.channel
+        this.sendCC(msb, msbValue, channelToUse)
+        this.sendCC(lsb, lsbValue, channelToUse)
+      }
+
+      // Add debouncing if specified
+      let timeoutId = null
+      const debouncedHandler =
+        debounce > 0
+          ? (event) => {
+              if (timeoutId) clearTimeout(timeoutId)
+              timeoutId = setTimeout(() => {
+                handler(event)
+                timeoutId = null
+              }, debounce)
+            }
+          : handler
+
+      element.addEventListener("input", debouncedHandler)
+      element.addEventListener("change", debouncedHandler)
+
+      return {
+        element,
+        config: resolvedConfig,
+        handler,
+        destroy: () => {
+          if (timeoutId) clearTimeout(timeoutId)
+          element.removeEventListener("input", debouncedHandler)
+          element.removeEventListener("change", debouncedHandler)
+        },
+      }
+    }
+
+    // Handle 7-bit CC
+    const { cc } = config
+
+    const handler = (event) => {
+      const value = parseFloat(event.target.value)
+
+      if (Number.isNaN(value)) return
+
+      // Normalize to 0-127 MIDI range
+      const midiValue = normalizeValue(value, min, max, invert)
+
+      // Use dynamic channel from midi.options.channel
+      const channelToUse = channel === undefined ? this.options.channel : channel
+      this.sendCC(cc, midiValue, channelToUse)
+    }
+
+    // Add debouncing if specified
+    let timeoutId = null
+    const debouncedHandler =
+      debounce > 0
+        ? (event) => {
+            if (timeoutId) clearTimeout(timeoutId)
+            timeoutId = setTimeout(() => {
+              handler(event)
+              timeoutId = null
+            }, debounce)
+          }
+        : handler
+
+    element.addEventListener("input", debouncedHandler)
+    element.addEventListener("change", debouncedHandler)
+
+    return {
+      element,
+      config: resolvedConfig,
+      handler,
+      destroy: () => {
+        if (timeoutId) clearTimeout(timeoutId)
+        element.removeEventListener("input", debouncedHandler)
+        element.removeEventListener("change", debouncedHandler)
+      },
+    }
+  }
+
+  /**
+   * Get current state as a patch object
+   * @param {string} [name] - Optional patch name
+   * @returns {Object} Patch object
+   */
+  getPatch(name = "Unnamed Patch") {
+    const patch = {
+      name,
+      device: this.getCurrentOutput()?.name || null,
+      timestamp: new Date().toISOString(),
+      version: "1.0",
+      channels: {},
+      settings: {},
+    }
+
+    // Collect CC values by channel
+    for (const [key, value] of this.state.entries()) {
+      const [channel, cc] = key.split(":").map(Number)
+      if (!patch.channels[channel]) {
+        patch.channels[channel] = { ccs: {}, notes: {} }
+      }
+      patch.channels[channel].ccs[cc] = value
+    }
+
+    // Collect control settings
+    for (const [element, binding] of this.bindings.entries()) {
+      const { config } = binding
+      if (config.cc) {
+        const settingKey = `cc${config.cc}`
+        patch.settings[settingKey] = {
+          min: config.min,
+          max: config.max,
+          invert: config.invert || false,
+          is14Bit: config.is14Bit || false,
+          label: element.getAttribute?.("data-midi-label") || null,
+          elementId: element.id || null,
+        }
+      }
+    }
+
+    return patch
+  }
+
+  /**
+   * Apply a patch to the controller
+   * @param {PatchData} patch - Patch object
+   * @returns {Promise<void>}
+   */
+  async setPatch(patch) {
+    if (!patch || !patch.channels) {
+      throw new MIDIValidationError("Invalid patch format", "patch")
+    }
+
+    // Handle different patch versions
+    const version = patch.version || "1.0"
+
+    if (version === "1.0") {
+      await this._applyPatchV1(patch)
+    } else {
+      console.warn(`Unknown patch version: ${version}. Attempting to apply as v1.0`)
+      await this._applyPatchV1(patch)
+    }
+
+    this.emit(CONTROLLER_EVENTS.PATCH_LOADED, { patch })
+  }
+
+  /**
+   * Apply v1.0 patch format
+   * @private
+   * @param {PatchData} patch
+   */
+  async _applyPatchV1(patch) {
+    // Apply CC values
+    for (const [channelStr, channelData] of Object.entries(patch.channels)) {
+      const channel = parseInt(channelStr, 10)
+
+      // Apply CC values
+      if (channelData.ccs) {
+        for (const [ccStr, value] of Object.entries(channelData.ccs)) {
+          const cc = parseInt(ccStr, 10)
+          this.sendCC(cc, value, channel)
+        }
+      }
+
+      // Apply note states if present
+      if (channelData.notes) {
+        for (const [noteStr, velocity] of Object.entries(channelData.notes)) {
+          const note = parseInt(noteStr, 10)
+          if (velocity > 0) {
+            this.sendNoteOn(note, velocity, channel)
+          } else {
+            this.sendNoteOff(note, channel)
+          }
+        }
+      }
+    }
+
+    // Apply settings to controls (if they exist)
+    if (patch.settings) {
+      for (const [bindingKey, setting] of Object.entries(patch.settings)) {
+        // Find controls by CC number and update their settings
+        for (const [element, binding] of this.bindings.entries()) {
+          if (binding.config.cc?.toString() === bindingKey.replace("cc", "")) {
+            // Update element attributes if they exist
+            if (element.min !== undefined && setting.min !== undefined) {
+              element.min = String(setting.min)
+            }
+            if (element.max !== undefined && setting.max !== undefined) {
+              element.max = String(setting.max)
+            }
+          }
+        }
+      }
+    }
+
+    // Update element values from channel data for all bound elements
+    for (const [element, binding] of this.bindings.entries()) {
+      const { config } = binding
+      if (config.cc !== undefined) {
+        const channel = config.channel || this.options.channel
+        const channelData = patch.channels[channel]
+        if (channelData?.ccs) {
+          const ccValue = channelData.ccs[config.cc]
+          if (ccValue !== undefined) {
+            // Convert MIDI value (0-127) back to element value
+            const min =
+              config.min !== undefined ? config.min : parseFloat(element.getAttribute?.("min")) || 0
+            const max =
+              config.max !== undefined
+                ? config.max
+                : parseFloat(element.getAttribute?.("max")) || 127
+            const invert = config.invert || false
+
+            let elementValue
+            if (invert) {
+              elementValue = max - (ccValue / 127) * (max - min)
+            } else {
+              elementValue = min + (ccValue / 127) * (max - min)
+            }
+
+            // Use onInput callback if provided, otherwise fall back to direct element update
+            if (config.onInput && typeof config.onInput === "function") {
+              config.onInput(elementValue)
+            } else {
+              element.value = elementValue
+              // Dispatch input event to trigger any display updates
+              element.dispatchEvent(new Event("input", { bubbles: true }))
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Save a patch to localStorage
+   * @param {string} name - Patch name
+   * @param {Object} [patch] - Optional patch object (will use getPatch() if not provided)
+   * @returns {string} Storage key used
+   */
+  savePatch(name, patch = null) {
+    const patchToSave = patch || this.getPatch(name)
+    const key = `midiwire_patch_${name}`
+
+    try {
+      localStorage.setItem(key, JSON.stringify(patchToSave))
+      this.emit(CONTROLLER_EVENTS.PATCH_SAVED, { name, patch: patchToSave })
+      return key
+    } catch (err) {
+      console.error("Failed to save patch:", err)
+      throw err
+    }
+  }
+
+  /**
+   * Load a patch from localStorage
+   * @param {string} name - Patch name
+   * @returns {Object|null} Patch object or null if not found
+   */
+  loadPatch(name) {
+    const key = `midiwire_patch_${name}`
+
+    try {
+      const stored = localStorage.getItem(key)
+      if (!stored) {
+        return null
+      }
+
+      const patch = JSON.parse(stored)
+      this.emit(CONTROLLER_EVENTS.PATCH_LOADED, { name, patch })
+      return patch
+    } catch (err) {
+      console.error("Failed to load patch:", err)
+      return null
+    }
+  }
+
+  /**
+   * Delete a patch from localStorage
+   * @param {string} name - Patch name
+   * @returns {boolean} Success
+   */
+  deletePatch(name) {
+    const key = `midiwire_patch_${name}`
+
+    try {
+      localStorage.removeItem(key)
+      this.emit(CONTROLLER_EVENTS.PATCH_DELETED, { name })
+      return true
+    } catch (err) {
+      console.error("Failed to delete patch:", err)
+      return false
+    }
+  }
+
+  /**
+   * List all saved patches
+   * @returns {Array<Object>} Array of { name, patch }
+   */
+  listPatches() {
+    const patches = []
+
+    try {
+      for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i)
+        if (key?.startsWith("midiwire_patch_")) {
+          const name = key.replace("midiwire_patch_", "")
+          const patch = this.loadPatch(name)
+          if (patch) {
+            patches.push({ name, patch })
+          }
+        }
+      }
+    } catch (err) {
+      console.error("Failed to list patches:", err)
+    }
+
+    return patches.sort((a, b) => a.name.localeCompare(b.name))
+  }
+}