midiwire 0.1.0

package/src/utils/midi.js

@@ -0,0 +1,244 @@
+import { MIDIValidationError } from "../core/errors.js"
+
+/**
+ * Clamp a value between min and max
+ * @param {number} value - Value to clamp
+ * @param {number} min - Minimum value
+ * @param {number} max - Maximum value
+ * @returns {number}
+ */
+export function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value))
+}
+
+/**
+ * Normalize a value from input range to MIDI range (0-127)
+ * @param {number} value - Input value
+ * @param {number} inputMin - Input minimum
+ * @param {number} inputMax - Input maximum
+ * @param {boolean} [invert=false] - Invert the output
+ * @returns {number} MIDI value (0-127)
+ */
+export function normalizeValue(value, inputMin, inputMax, invert = false) {
+  // Normalize to 0-1
+  const normalized = (value - inputMin) / (inputMax - inputMin)
+
+  // Invert if requested
+  const final = invert ? 1 - normalized : normalized
+
+  // Scale to MIDI range (0-127)
+  const midiValue = final * 127
+
+  return clamp(Math.round(midiValue), 0, 127)
+}
+
+/**
+ * Denormalize a MIDI value (0-127) to a custom range
+ * @param {number} midiValue - MIDI value (0-127)
+ * @param {number} outputMin - Output minimum
+ * @param {number} outputMax - Output maximum
+ * @param {boolean} [invert=false] - Invert the input
+ * @returns {number}
+ */
+export function denormalizeValue(midiValue, outputMin, outputMax, invert = false) {
+  // Normalize MIDI value to 0-1
+  let normalized = clamp(midiValue, 0, 127) / 127
+
+  // Invert if requested
+  if (invert) {
+    normalized = 1 - normalized
+  }
+
+  // Scale to output range
+  return outputMin + normalized * (outputMax - outputMin)
+}
+
+/**
+ * Convert a note name to MIDI note number
+ * @param {string} noteName - Note name (e.g., "C4", "A#3", "Bb5")
+ * @returns {number} MIDI note number (0-127)
+ * @throws {MIDIValidationError} If noteName is not a valid note format
+ */
+export function noteNameToNumber(noteName) {
+  const notes = {
+    C: 0,
+    "C#": 1,
+    DB: 1,
+    D: 2,
+    "D#": 3,
+    EB: 3,
+    E: 4,
+    F: 5,
+    "F#": 6,
+    GB: 6,
+    G: 7,
+    "G#": 8,
+    AB: 8,
+    A: 9,
+    "A#": 10,
+    BB: 10,
+    B: 11,
+  }
+
+  const match = noteName.match(/^([A-G][#b]?)(-?\d+)$/i)
+  if (!match) {
+    throw new MIDIValidationError(`Invalid note name: ${noteName}`, "note", noteName)
+  }
+
+  const [, note, octave] = match
+  const noteValue = notes[note.toUpperCase()]
+
+  if (noteValue === undefined) {
+    throw new MIDIValidationError(`Invalid note: ${note}`, "note", note)
+  }
+
+  const midiNote = (parseInt(octave, 10) + 1) * 12 + noteValue
+  return clamp(midiNote, 0, 127)
+}
+
+/**
+ * Convert MIDI note number to note name
+ * @param {number} noteNumber - MIDI note number (0-127)
+ * @param {boolean} [useFlats=false] - Use flats instead of sharps
+ * @returns {string} Note name (e.g., "C4")
+ */
+export function noteNumberToName(noteNumber, useFlats = false) {
+  const sharps = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+  const flats = ["C", "Db", "D", "Eb", "E", "F", "Gb", "G", "Ab", "A", "Bb", "B"]
+
+  const notes = useFlats ? flats : sharps
+  const octave = Math.floor(noteNumber / 12) - 1
+  const note = notes[noteNumber % 12]
+
+  return `${note}${octave}`
+}
+
+/**
+ * Convert frequency (Hz) to nearest MIDI note number
+ * @param {number} frequency - Frequency in Hz
+ * @returns {number} MIDI note number
+ */
+export function frequencyToNote(frequency) {
+  const noteNumber = 69 + 12 * Math.log2(frequency / 440)
+  return clamp(Math.round(noteNumber), 0, 127)
+}
+
+/**
+ * Convert MIDI note number to frequency (Hz)
+ * @param {number} noteNumber - MIDI note number
+ * @returns {number} Frequency in Hz
+ */
+export function noteToFrequency(noteNumber) {
+  return 440 * 2 ** ((noteNumber - 69) / 12)
+}
+
+/**
+ * Get CC name for common controller numbers
+ * @param {number} cc - CC number
+ * @returns {string} CC name or "CC {number}"
+ */
+export function getCCName(cc) {
+  const names = {
+    0: "Bank Select",
+    1: "Modulation",
+    2: "Breath Controller",
+    4: "Foot Controller",
+    5: "Portamento Time",
+    7: "Volume",
+    8: "Balance",
+    10: "Pan",
+    11: "Expression",
+    64: "Sustain Pedal",
+    65: "Portamento",
+    66: "Sostenuto",
+    67: "Soft Pedal",
+    68: "Legato",
+    71: "Resonance",
+    72: "Release Time",
+    73: "Attack Time",
+    74: "Cutoff",
+    75: "Decay Time",
+    76: "Vibrato Rate",
+    77: "Vibrato Depth",
+    78: "Vibrato Delay",
+    84: "Portamento Control",
+    91: "Reverb",
+    92: "Tremolo",
+    93: "Chorus",
+    94: "Detune",
+    95: "Phaser",
+    120: "All Sound Off",
+    121: "Reset All Controllers",
+    123: "All Notes Off",
+  }
+
+  return names[cc] || `CC ${cc}`
+}
+
+/**
+ * Encode a 14-bit value into MSB and LSB (7-bit each)
+ * @param {number} value - 14-bit value (0-16383)
+ * @returns {{msb: number, lsb: number}} MSB and LSB values
+ */
+export function encode14BitValue(value) {
+  const clamped = clamp(Math.round(value), 0, 16383)
+  return {
+    msb: (clamped >> 7) & 0x7f,
+    lsb: clamped & 0x7f,
+  }
+}
+
+/**
+ * Decode MSB and LSB (7-bit each) into a 14-bit value
+ * @param {number} msb - Most significant byte (0-127)
+ * @param {number} lsb - Least significant byte (0-127)
+ * @returns {number} 14-bit value (0-16383)
+ */
+export function decode14BitValue(msb, lsb) {
+  return (clamp(msb, 0, 127) << 7) | clamp(lsb, 0, 127)
+}
+
+/**
+ * Normalize a 14-bit value from input range
+ * @param {number} value - Input value
+ * @param {number} inputMin - Input minimum
+ * @param {number} inputMax - Input maximum
+ * @param {boolean} [invert=false] - Invert the output
+ * @returns {{msb: number, lsb: number}} MSB and LSB values
+ */
+export function normalize14BitValue(value, inputMin, inputMax, invert = false) {
+  // Normalize to 0-1
+  const normalized = (value - inputMin) / (inputMax - inputMin)
+
+  // Invert if requested
+  const final = invert ? 1 - normalized : normalized
+
+  // Scale to 14-bit range (0-16383)
+  const value14Bit = final * 16383
+
+  return encode14BitValue(value14Bit)
+}
+
+/**
+ * Denormalize a 14-bit value to a custom range
+ * @param {number} msb - Most significant byte (0-127)
+ * @param {number} lsb - Least significant byte (0-127)
+ * @param {number} outputMin - Output minimum
+ * @param {number} outputMax - Output maximum
+ * @param {boolean} [invert=false] - Invert the input
+ * @returns {number} Denormalized value
+ */
+export function denormalize14BitValue(msb, lsb, outputMin, outputMax, invert = false) {
+  const value14Bit = decode14BitValue(msb, lsb)
+
+  // Normalize to 0-1
+  let normalized = value14Bit / 16383
+
+  // Invert if requested
+  if (invert) {
+    normalized = 1 - normalized
+  }
+
+  // Scale to output range
+  return outputMin + normalized * (outputMax - outputMin)
+}

package/src/utils/midi.test.js

@@ -0,0 +1,260 @@
+import { describe, expect, it } from "vitest"
+import {
+  clamp,
+  decode14BitValue,
+  denormalize14BitValue,
+  denormalizeValue,
+  encode14BitValue,
+  frequencyToNote,
+  getCCName,
+  normalize14BitValue,
+  normalizeValue,
+  noteNameToNumber,
+  noteNumberToName,
+  noteToFrequency,
+} from "./midi.js"
+
+describe("MIDI Utils - Additional Tests", () => {
+  describe("denormalizeValue", () => {
+    it("should denormalize MIDI values to custom range", () => {
+      expect(denormalizeValue(64, 0, 100, false)).toBeCloseTo(50, 0) // 50% of 100
+      expect(denormalizeValue(0, 0, 100, false)).toBe(0)
+      expect(denormalizeValue(127, 0, 100, false)).toBe(100)
+    })
+
+    it("should invert values when requested", () => {
+      expect(denormalizeValue(0, 0, 100, true)).toBe(100)
+      expect(denormalizeValue(127, 0, 100, true)).toBe(0)
+      expect(denormalizeValue(64, 0, 100, true)).toBeCloseTo(50, 0)
+    })
+
+    it("should handle negative ranges", () => {
+      expect(denormalizeValue(0, -50, 50, false)).toBe(-50)
+      expect(denormalizeValue(127, -50, 50, false)).toBe(50)
+      expect(denormalizeValue(64, -50, 50, false)).toBeCloseTo(0, 0)
+    })
+  })
+
+  describe("frequencyToNote", () => {
+    it("should convert frequencies to MIDI notes", () => {
+      expect(frequencyToNote(440)).toBe(69) // A4
+      expect(frequencyToNote(261.63)).toBe(60) // C4
+      expect(frequencyToNote(220)).toBe(57) // A3
+    })
+
+    it("should clamp to valid MIDI range", () => {
+      expect(frequencyToNote(20000)).toBe(127) // Very high frequency
+      expect(frequencyToNote(1)).toBe(0) // Very low frequency
+    })
+
+    it("should round to nearest note", () => {
+      expect(frequencyToNote(441)).toBe(69)
+      expect(frequencyToNote(439)).toBe(69)
+    })
+  })
+
+  describe("noteToFrequency", () => {
+    it("should convert MIDI notes to frequencies", () => {
+      expect(noteToFrequency(69)).toBeCloseTo(440, 2) // A4
+      expect(noteToFrequency(60)).toBeCloseTo(261.63, 2) // C4
+      expect(noteToFrequency(57)).toBeCloseTo(220, 2) // A3
+    })
+
+    it("should handle all valid notes", () => {
+      expect(noteToFrequency(0)).toBeCloseTo(8.18, 2)
+      expect(noteToFrequency(127)).toBeCloseTo(12543.85, 2)
+    })
+  })
+
+  describe("clamp - additional edge cases", () => {
+    it("should handle equal min and max", () => {
+      expect(clamp(5, 10, 10)).toBe(10)
+      expect(clamp(15, 10, 10)).toBe(10)
+    })
+
+    it("should handle NaN values", () => {
+      expect(clamp(NaN, 0, 100)).toBeNaN()
+    })
+
+    it("should handle infinity", () => {
+      expect(clamp(Infinity, 0, 100)).toBe(100)
+      expect(clamp(-Infinity, 0, 100)).toBe(0)
+    })
+  })
+
+  describe("normalizeValue - additional edge cases", () => {
+    it("should handle equal input range", () => {
+      // Division by zero case - should handle gracefully
+      const result = normalizeValue(50, 50, 50, false)
+      expect(result).toBeNaN()
+    })
+
+    it("should handle out of range values", () => {
+      expect(normalizeValue(200, 0, 100, false)).toBe(127)
+      expect(normalizeValue(-50, 0, 100, false)).toBe(0)
+    })
+  })
+
+  describe("noteNameToNumber - additional tests", () => {
+    it("should handle all valid note names", () => {
+      expect(noteNameToNumber("C0")).toBe(12)
+      expect(noteNameToNumber("C#0")).toBe(13)
+      expect(noteNameToNumber("Db0")).toBe(13)
+      expect(noteNameToNumber("G9")).toBe(127)
+    })
+
+    it("should handle case variations", () => {
+      expect(noteNameToNumber("c4")).toBe(60)
+      expect(noteNameToNumber("A#4")).toBe(70)
+      expect(noteNameToNumber("bb4")).toBe(70)
+    })
+
+    it("should throw on invalid note names", () => {
+      expect(() => noteNameToNumber("C#")).toThrow("Invalid note name")
+      expect(() => noteNameToNumber("H4")).toThrow("Invalid note")
+      // C10 is actually valid (12 * 11 = 132, which gets clamped to 127)
+      expect(() => noteNameToNumber("C10")).not.toThrow()
+      expect(noteNameToNumber("C10")).toBe(127) // Clamped to max
+    })
+  })
+
+  describe("noteNumberToName - additional tests", () => {
+    it("should handle all octaves", () => {
+      expect(noteNumberToName(0)).toBe("C-1")
+      expect(noteNumberToName(127)).toBe("G9")
+    })
+
+    it("should use flats when requested", () => {
+      expect(noteNumberToName(70, true)).toBe("Bb4")
+      expect(noteNumberToName(72, true)).toBe("C5") // No flat for C
+    })
+  })
+
+  describe("getCCName - additional tests", () => {
+    it("should return all known CC names", () => {
+      expect(getCCName(0)).toBe("Bank Select")
+      expect(getCCName(1)).toBe("Modulation")
+      expect(getCCName(7)).toBe("Volume")
+      expect(getCCName(64)).toBe("Sustain Pedal")
+      expect(getCCName(120)).toBe("All Sound Off")
+    })
+
+    it("should return generic format for unknown CCs", () => {
+      expect(getCCName(200)).toBe("CC 200")
+      expect(getCCName(-1)).toBe("CC -1")
+    })
+  })
+
+  describe("14-bit MIDI", () => {
+    describe("encode14BitValue", () => {
+      it("should encode 0 to MSB=0, LSB=0", () => {
+        expect(encode14BitValue(0)).toEqual({ msb: 0, lsb: 0 })
+      })
+
+      it("should encode 16383 to MSB=127, LSB=127", () => {
+        expect(encode14BitValue(16383)).toEqual({ msb: 127, lsb: 127 })
+      })
+
+      it("should encode middle value correctly", () => {
+        const result = encode14BitValue(8192)
+        expect(result.msb).toBe(64)
+        expect(result.lsb).toBe(0)
+      })
+
+      it("should clamp values below 0", () => {
+        expect(encode14BitValue(-100)).toEqual({ msb: 0, lsb: 0 })
+      })
+
+      it("should clamp values above 16383", () => {
+        expect(encode14BitValue(20000)).toEqual({ msb: 127, lsb: 127 })
+      })
+    })
+
+    describe("decode14BitValue", () => {
+      it("should decode MSB=0, LSB=0 to 0", () => {
+        expect(decode14BitValue(0, 0)).toBe(0)
+      })
+
+      it("should decode MSB=127, LSB=127 to 16383", () => {
+        expect(decode14BitValue(127, 127)).toBe(16383)
+      })
+
+      it("should decode middle values correctly", () => {
+        expect(decode14BitValue(64, 0)).toBe(8192)
+        expect(decode14BitValue(32, 0)).toBe(4096)
+        expect(decode14BitValue(96, 0)).toBe(12288)
+      })
+    })
+
+    describe("encode14BitValue / decode14BitValue round-trip", () => {
+      it("should round-trip all edge values", () => {
+        const testValues = [0, 1, 127, 128, 16383]
+        testValues.forEach((value) => {
+          const encoded = encode14BitValue(value)
+          const decoded = decode14BitValue(encoded.msb, encoded.lsb)
+          expect(decoded).toBe(value)
+        })
+      })
+
+      it("should round-trip random values", () => {
+        for (let i = 0; i < 100; i++) {
+          const value = Math.floor(Math.random() * 16384)
+          const encoded = encode14BitValue(value)
+          const decoded = decode14BitValue(encoded.msb, encoded.lsb)
+          expect(decoded).toBe(value)
+        }
+      })
+    })
+
+    describe("normalize14BitValue", () => {
+      it("should normalize input range to 14-bit MSB/LSB", () => {
+        const result = normalize14BitValue(50, 0, 100, false)
+        expect(result).toHaveProperty("msb")
+        expect(result).toHaveProperty("lsb")
+        expect(result.msb).toBeGreaterThanOrEqual(0)
+        expect(result.msb).toBeLessThanOrEqual(127)
+        expect(result.lsb).toBeGreaterThanOrEqual(0)
+        expect(result.lsb).toBeLessThanOrEqual(127)
+      })
+
+      it("should handle min=0, max=127", () => {
+        const result = normalize14BitValue(64, 0, 127, false)
+        const decoded = decode14BitValue(result.msb, result.lsb)
+        // 64/127 = 0.5039, so decoded should be ~8256 (0.5039 * 16383)
+        expect(decoded).toBeGreaterThan(8200)
+        expect(decoded).toBeLessThan(8300)
+      })
+
+      it("should invert values when requested", () => {
+        const result = normalize14BitValue(0, 0, 100, true)
+        expect(result.msb).toBe(127)
+        expect(result.lsb).toBe(127)
+      })
+
+      it("should handle negative ranges", () => {
+        const result = normalize14BitValue(0, -50, 50, false)
+        expect(result.msb).toBe(64)
+        expect(result.lsb).toBe(0)
+      })
+    })
+
+    describe("denormalize14BitValue", () => {
+      it("should denormalize 14-bit values to custom range", () => {
+        const msb = 64
+        const lsb = 0
+        const result = denormalize14BitValue(msb, lsb, 0, 100, false)
+        expect(result).toBeCloseTo(50, 1)
+      })
+
+      it("should handle min=0, max=16383", () => {
+        expect(denormalize14BitValue(0, 0, 0, 16383, false)).toBe(0)
+        expect(denormalize14BitValue(127, 127, 0, 16383, false)).toBe(16383)
+      })
+
+      it("should invert values when requested", () => {
+        const result = denormalize14BitValue(0, 0, 0, 100, true)
+        expect(result).toBeCloseTo(100, 0)
+      })
+    })
+  })
+})

package/src/utils/sysex.js

@@ -0,0 +1,98 @@
+/**
+ * Parse a SysEx message
+ * @param {Array<number>} data - Raw MIDI data
+ * @returns {Object|null} Parsed SysEx data or null if not SysEx
+ */
+export function parseSysEx(data) {
+  if (data[0] !== 0xf0 || data[data.length - 1] !== 0xf7) {
+    return null
+  }
+
+  return {
+    manufacturerId: data[1],
+    payload: data.slice(2, -1),
+    raw: data,
+  }
+}
+
+/**
+ * Create a SysEx message
+ * @param {number} manufacturerId - Manufacturer ID
+ * @param {Array<number>} payload - SysEx payload data
+ * @returns {Array<number>} Complete SysEx message with F0/F7
+ */
+export function createSysEx(manufacturerId, payload) {
+  return [0xf0, manufacturerId, ...payload, 0xf7]
+}
+
+/**
+ * Check if data is a SysEx message
+ * @param {Array<number>} data - MIDI data
+ * @returns {boolean}
+ */
+export function isSysEx(data) {
+  return data.length >= 2 && data[0] === 0xf0 && data[data.length - 1] === 0xf7
+}
+
+/**
+ * Encode 8-bit data to 7-bit MIDI format
+ * @param {Array<number>} data - 8-bit data array
+ * @returns {Array<number>} 7-bit encoded data
+ */
+export function encode7Bit(data) {
+  const result = []
+
+  // Process data in groups of 7 bytes
+  for (let i = 0; i < data.length; i += 7) {
+    const group = data.slice(i, i + 7)
+    let headerByte = 0
+    const dataBytes = []
+
+    // Process each byte in the group
+    for (let j = 0; j < group.length; j++) {
+      const byte = group[j]
+      // Check if MSB (bit 7) is set
+      if (byte & 0x80) {
+        headerByte |= 1 << j
+      }
+      // Add the lower 7 bits as a data byte
+      dataBytes.push(byte & 0x7f)
+    }
+
+    // Add header byte followed by the data bytes
+    // Note: result length may not be a multiple of 8
+    result.push(headerByte, ...dataBytes)
+  }
+
+  return result
+}
+
+/**
+ * Decode 7-bit MIDI format to 8-bit data
+ * @param {Array<number>} data - 7-bit encoded data
+ * @returns {Array<number>} 8-bit decoded data
+ */
+export function decode7Bit(data) {
+  const result = []
+
+  // Process data in groups of 8 bytes (1 header + 7 data bytes)
+  for (let i = 0; i < data.length; i += 8) {
+    const headerByte = data[i]
+    // Calculate how many data bytes are in this group (1-7)
+    const groupSize = Math.min(7, data.length - i - 1)
+
+    // Process the data bytes in this group
+    for (let j = 0; j < groupSize; j++) {
+      let byte = data[i + 1 + j]
+
+      // Reconstruct the 8-bit value using header bit
+      if (headerByte & (1 << j)) {
+        byte |= 0x80
+      }
+
+      result.push(byte)
+    }
+  }
+
+  return result
+}