libadlmidi-js 2.1.0 → 2.2.0

package/dist/utils/opl3.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Get the register bank bit for a channel.
+ *
+ * @param {number} channel - Per-chip channel (0-17)
+ * @returns {number} 0x000 for channels 0-8, 0x100 for channels 9-17
+ */
+export function channelBank(channel: number): number;
+/**
+ * Get the frequency-number low register address (0xA0 series).
+ *
+ * @param {number} channel - Per-chip channel (0-17)
+ * @returns {number} Register address
+ */
+export function fnumLoReg(channel: number): number;
+/**
+ * Get the key-on / block / fnum-high register address (0xB0 series).
+ *
+ * @param {number} channel - Per-chip channel (0-17)
+ * @returns {number} Register address
+ */
+export function keyOnBlockReg(channel: number): number;
+/**
+ * Get the feedback / connection register address (0xC0 series).
+ *
+ * @param {number} channel - Per-chip channel (0-17)
+ * @returns {number} Register address
+ */
+export function feedbackConnReg(channel: number): number;
+/**
+ * Get the register address for an operator parameter.
+ *
+ * @param {number} baseReg - Register group base: 0x20 (AM/VIB/EG/KSR/MULT),
+ *   0x40 (KSL/TL), 0x60 (AR/DR), 0x80 (SL/RR), or 0xE0 (waveform)
+ * @param {number} channel - Per-chip channel (0-17)
+ * @param {number} operatorSlot - 0 for modulator, 1 for carrier
+ * @returns {number} Register address (0x000-0x1FF)
+ */
+export function operatorReg(baseReg: number, channel: number, operatorSlot: number): number;
+/**
+ * Convert a MIDI note number to OPL3 fnum and block values.
+ *
+ * Uses the standard OPL3 frequency formula:
+ *   freq = fnum * OPL3_SAMPLE_RATE / 2^(20 - block)
+ *
+ * Picks the lowest block where fnum fits in 10 bits (maximum resolution).
+ * Notes above ~6.2 kHz (above MIDI 110 or so) will saturate.
+ *
+ * @param {number} note - MIDI note number (0-127)
+ * @returns {{fnum: number, block: number}}
+ */
+export function noteToFnumBlock(note: number): {
+    fnum: number;
+    block: number;
+};
+/**
+ * Encode fnum and block into the two register byte values.
+ *
+ * @param {number} fnum - Frequency number (0-1023)
+ * @param {number} block - Block / octave (0-7)
+ * @returns {{fnumLo: number, fnumHiBlock: number}} Values for A0h and B0h
+ *   registers. The B0h value does NOT include the key-on bit.
+ */
+export function encodeFnumBlock(fnum: number, block: number): {
+    fnumLo: number;
+    fnumHiBlock: number;
+};
+/**
+ * Encode a key-on register write for a channel.
+ *
+ * @param {number} channel - Per-chip channel (0-17)
+ * @param {number} fnum - Frequency number (0-1023)
+ * @param {number} block - Block / octave (0-7)
+ * @returns {{reg: number, value: number}}
+ */
+export function keyOn(channel: number, fnum: number, block: number): {
+    reg: number;
+    value: number;
+};
+/**
+ * Encode a key-off register write for a channel.
+ *
+ * @param {number} channel - Per-chip channel (0-17)
+ * @param {number} fnum - Frequency number (0-1023)
+ * @param {number} block - Block / octave (0-7)
+ * @returns {{reg: number, value: number}}
+ */
+export function keyOff(channel: number, fnum: number, block: number): {
+    reg: number;
+    value: number;
+};
+/**
+ * Encode an Operator's properties into OPL3 register writes.
+ *
+ * @param {import('./struct.js').Operator} op
+ * @param {number} channel - Per-chip channel (0-17)
+ * @param {number} operatorSlot - 0 for modulator, 1 for carrier
+ * @returns {Array<{reg: number, value: number}>}
+ */
+export function encodeOperatorRegisters(op: import("./struct.js").Operator, channel: number, operatorSlot: number): Array<{
+    reg: number;
+    value: number;
+}>;
+/**
+ * Generate all register writes to program a 2-op channel voice.
+ *
+ * Writes both operators and the feedback/connection register. Follows
+ * the ADL_Instrument convention: operators[0] = carrier (slot 1),
+ * operators[1] = modulator (slot 0). Sets stereo output bits (L+R)
+ * on the C0h register, which is required for audible output in OPL3 mode.
+ *
+ * Only handles 2-op instruments. Throws on 4-op or pseudo-4-op
+ * instruments, which require two paired channels.
+ *
+ * @param {import('./struct.js').Instrument} instrument
+ * @param {number} channel - Per-chip channel (0-17)
+ * @returns {Array<{reg: number, value: number}>}
+ */
+export function encodeChannelVoice(instrument: import("./struct.js").Instrument, channel: number): Array<{
+    reg: number;
+    value: number;
+}>;
+/**
+ * Create a channel reservation bitmask from channel indices.
+ *
+ * @param {...number} channels - Per-chip channel indices (0-22)
+ * @returns {number} Bitmask for use with reserveChipChannels()
+ */
+export function channelMask(...channels: number[]): number;
+/**
+ * OPL3 register helpers for raw chip access.
+ *
+ * Pure-JS utilities for working with the OPL3 register layout. No WASM
+ * dependency. Use alongside AdlMidiCore.rawOPL3() or AdlMidi.rawOPL3()
+ * to program the chip directly.
+ *
+ * @module opl3
+ */
+/** Total per-chip channels including rhythm-mode percussion */
+export const CHANNELS_PER_CHIP: 23;
+/** Standard 2-op melodic channels per chip */
+export const CHANNELS_STANDARD: 18;
+/** Rhythm-mode percussion channels (indices 18-22) */
+export const CHANNELS_RHYTHM: 5;
+/** OPL3 internal sample rate (Hz), used for fnum calculation. 14.31818 MHz / 288. */
+export const OPL3_SAMPLE_RATE: 49716;
+/**
+ * Operator register offsets per channel.
+ *
+ * Maps per-chip channel index (0-17) to [modulator, carrier] register
+ * offsets. These are the low byte of the register address; for channels
+ * 9-17, add 0x100 (use {@link channelBank}).
+ *
+ * Derived from Nuked OPL3's `ad_slot` and `ch_slot` tables.
+ *
+ * @type {ReadonlyArray<readonly [number, number]>}
+ */
+export const CHANNEL_OPERATORS: ReadonlyArray<readonly [number, number]>;

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "libadlmidi-js",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "libadlmidi": {
     "version": "1.6.2",
-    "commit": "6528dafce641e81ded5d62809445267b82dc0d8d"
+    "commit": "ad001c83551779934bacd642fce801c51a5b7b4c"
   },
   "description": "WebAssembly build of libADLMIDI - OPL3/FM synthesis for the browser",
   "main": "dist/libadlmidi.js",
@@ -18,6 +18,10 @@
       "types": "./dist/utils/struct.d.ts",
       "import": "./src/utils/struct.js"
     },
+    "./opl3": {
+      "types": "./dist/utils/opl3.d.ts",
+      "import": "./src/utils/opl3.js"
+    },
     "./nuked": {
       "types": "./dist/profiles/nuked.d.ts",
       "import": "./src/profiles/nuked.js"
@@ -100,18 +104,18 @@
     "@arethetypeswrong/cli": "^0.18.2",
     "@commitlint/cli": "^21.0.1",
     "@commitlint/config-conventional": "^21.0.1",
-    "@emnapi/core": "1.10.0",
-    "@emnapi/runtime": "1.10.0",
+    "@emnapi/core": "1.11.1",
+    "@emnapi/runtime": "1.11.1",
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.57.0",
     "@types/node": "^25.0.3",
-    "esbuild": "^0.27.2",
+    "esbuild": "^0.28.0",
     "eslint": "^10.0.3",
     "globals": "^17.4.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.5",
     "playwright": "^1.57.0",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.5"
   },
   "files": [

package/src/core.js

@@ -609,6 +609,60 @@ export class AdlMidiCore {
         this._module._adl_rt_bankChangeLSB(this._player, channel, lsb);
     }
 
+    // =========================================================================
+    // Raw OPL3 Access
+    // =========================================================================
+
+    /**
+     * Write a raw OPL3 register on a specific chip.
+     *
+     * Bypasses the MIDI voice allocator. The caller is responsible for the
+     * state of targeted channels. Reserve channels first via
+     * {@link reserveChipChannels} to prevent the MIDI driver from
+     * overwriting your register state.
+     *
+     * @param {number} chipId - Zero-based chip index (0 to getNumChipsObtained()-1)
+     * @param {number} reg - OPL3 register address (0x000-0x1FF, bit 8 selects bank)
+     * @param {number} value - Register value (0-255)
+     * @returns {boolean} True on success, false if chipId is out of range
+     */
+    rawOPL3(chipId, reg, value) {
+        this._ensurePlayer();
+        return this._module._adl_rt_rawOPL3(this._player, chipId, reg, value) === 1;
+    }
+
+    /**
+     * Reserve chip channels so the MIDI voice allocator will not use them.
+     *
+     * After reservation, use {@link rawOPL3} to drive those channels
+     * directly. Pass channelMask = 0 to release all reservations.
+     *
+     * @param {number} chipId - Zero-based chip index (0 to getNumChipsObtained()-1)
+     * @param {number} channelMask - Bitmask of per-chip channels to reserve
+     *   (bits 0-22, where bit N reserves per-chip channel N)
+     * @returns {boolean} True on success
+     * @throws {Error} If the device is invalid
+     */
+    reserveChipChannels(chipId, channelMask) {
+        this._ensurePlayer();
+        const result = this._module._adl_reserveChipChannels(this._player, chipId, channelMask);
+        if (result === -1) {
+            throw new Error('Invalid device');
+        }
+        return result === 0;
+    }
+
+    /**
+     * Read back the chip-channel reservation mask.
+     *
+     * @param {number} chipId - Zero-based chip index
+     * @returns {number} Reservation bitmask (0 if invalid chipId)
+     */
+    getReservedChipChannels(chipId) {
+        this._ensurePlayer();
+        return this._module._adl_getReservedChipChannels(this._player, chipId);
+    }
+
     /**
      * Generate audio samples (real-time synthesis).
      *

package/src/libadlmidi.js

@@ -349,6 +349,64 @@ export class AdlMidi {
         this.#send({ type: 'panic' });
     }
 
+    // ================== Raw OPL3 API ==================
+
+    /**
+     * Write a raw OPL3 register on a specific chip (fire-and-forget).
+     *
+     * Bypasses the MIDI voice allocator. Reserve channels first via
+     * {@link reserveChipChannels} to prevent the MIDI driver from
+     * overwriting your register state.
+     *
+     * @param {number} chipId - Zero-based chip index (0 to getNumChipsObtained()-1)
+     * @param {number} reg - OPL3 register address (0x000-0x1FF, bit 8 selects bank)
+     * @param {number} value - Register value (0-255)
+     */
+    rawOPL3(chipId, reg, value) {
+        this.#send({ type: 'rawOPL3', chipId, reg, value });
+    }
+
+    /**
+     * Reserve chip channels so the MIDI voice allocator will not use them.
+     *
+     * After reservation, use {@link rawOPL3} to drive those channels
+     * directly. Pass channelMask = 0 to release all reservations.
+     *
+     * @param {number} chipId - Zero-based chip index (0 to getNumChipsObtained()-1)
+     * @param {number} channelMask - Bitmask of per-chip channels to reserve
+     *   (bits 0-22, where bit N reserves per-chip channel N)
+     * @returns {Promise<void>}
+     */
+    async reserveChipChannels(chipId, channelMask) {
+        const reqId = this.#nextRequestId++;
+        return new Promise((resolve, reject) => {
+            this.#onceCorrelatedMessage('chipChannelsReserved', reqId, /** @param {{success: boolean}} msg */ (msg) => {
+                if (msg.success) {
+                    resolve();
+                } else {
+                    reject(new Error(`Failed to reserve chip channels on chip ${chipId}`));
+                }
+            });
+            this.#send({ type: 'reserveChipChannels', chipId, channelMask, reqId });
+        });
+    }
+
+    /**
+     * Read back the chip-channel reservation mask.
+     *
+     * @param {number} chipId - Zero-based chip index
+     * @returns {Promise<number>} Reservation bitmask (0 if invalid chipId)
+     */
+    async getReservedChipChannels(chipId) {
+        const reqId = this.#nextRequestId++;
+        return new Promise((resolve) => {
+            this.#onceCorrelatedMessage('reservedChipChannels', reqId, /** @param {{mask: number}} msg */ (msg) => {
+                resolve(msg.mask);
+            });
+            this.#send({ type: 'getReservedChipChannels', chipId, reqId });
+        });
+    }
+
     /**
      * Configure synth settings at runtime
      * @param {ConfigureSettings} settings - Settings object

package/src/processor.js

@@ -701,6 +701,24 @@ class AdlMidiProcessor extends AudioWorkletProcessor {
                 break;
             }
 
+            // ================== Raw OPL3 ==================
+
+            case 'rawOPL3':
+                this.adl._adl_rt_rawOPL3(this.midi, msg.chipId, msg.reg, msg.value);
+                break;
+
+            case 'reserveChipChannels': {
+                const result = this.adl._adl_reserveChipChannels(this.midi, msg.chipId, msg.channelMask);
+                this.port.postMessage({ type: 'chipChannelsReserved', success: result === 0, chipId: msg.chipId, reqId: msg.reqId });
+                break;
+            }
+
+            case 'getReservedChipChannels': {
+                const mask = this.adl._adl_getReservedChipChannels(this.midi, msg.chipId);
+                this.port.postMessage({ type: 'reservedChipChannels', mask, chipId: msg.chipId, reqId: msg.reqId });
+                break;
+            }
+
             // ================== Debug / Diagnostics ==================
 
             case 'describeChannels': {

package/src/profiles/dosbox.js

@@ -90,3 +90,24 @@ export {
 
 // Re-export enums
 export { Emulator, TrackOption } from '../utils/constants.js';
+
+// Re-export OPL3 register helpers
+export {
+    CHANNELS_PER_CHIP,
+    CHANNELS_STANDARD,
+    CHANNELS_RHYTHM,
+    OPL3_SAMPLE_RATE,
+    CHANNEL_OPERATORS,
+    channelBank,
+    fnumLoReg,
+    keyOnBlockReg,
+    feedbackConnReg,
+    operatorReg,
+    noteToFnumBlock,
+    encodeFnumBlock,
+    keyOn,
+    keyOff,
+    encodeOperatorRegisters,
+    encodeChannelVoice,
+    channelMask
+} from '../utils/opl3.js';

package/src/profiles/dosbox.slim.js

@@ -90,3 +90,24 @@ export {
 
 // Re-export enums
 export { Emulator, TrackOption } from '../utils/constants.js';
+
+// Re-export OPL3 register helpers
+export {
+    CHANNELS_PER_CHIP,
+    CHANNELS_STANDARD,
+    CHANNELS_RHYTHM,
+    OPL3_SAMPLE_RATE,
+    CHANNEL_OPERATORS,
+    channelBank,
+    fnumLoReg,
+    keyOnBlockReg,
+    feedbackConnReg,
+    operatorReg,
+    noteToFnumBlock,
+    encodeFnumBlock,
+    keyOn,
+    keyOff,
+    encodeOperatorRegisters,
+    encodeChannelVoice,
+    channelMask
+} from '../utils/opl3.js';

package/src/profiles/full.js

@@ -90,3 +90,24 @@ export {
 
 // Re-export enums
 export { Emulator, TrackOption } from '../utils/constants.js';
+
+// Re-export OPL3 register helpers
+export {
+    CHANNELS_PER_CHIP,
+    CHANNELS_STANDARD,
+    CHANNELS_RHYTHM,
+    OPL3_SAMPLE_RATE,
+    CHANNEL_OPERATORS,
+    channelBank,
+    fnumLoReg,
+    keyOnBlockReg,
+    feedbackConnReg,
+    operatorReg,
+    noteToFnumBlock,
+    encodeFnumBlock,
+    keyOn,
+    keyOff,
+    encodeOperatorRegisters,
+    encodeChannelVoice,
+    channelMask
+} from '../utils/opl3.js';

package/src/profiles/full.slim.js

@@ -90,3 +90,24 @@ export {
 
 // Re-export enums
 export { Emulator, TrackOption } from '../utils/constants.js';
+
+// Re-export OPL3 register helpers
+export {
+    CHANNELS_PER_CHIP,
+    CHANNELS_STANDARD,
+    CHANNELS_RHYTHM,
+    OPL3_SAMPLE_RATE,
+    CHANNEL_OPERATORS,
+    channelBank,
+    fnumLoReg,
+    keyOnBlockReg,
+    feedbackConnReg,
+    operatorReg,
+    noteToFnumBlock,
+    encodeFnumBlock,
+    keyOn,
+    keyOff,
+    encodeOperatorRegisters,
+    encodeChannelVoice,
+    channelMask
+} from '../utils/opl3.js';

package/src/profiles/light.js

@@ -90,3 +90,24 @@ export {
 
 // Re-export enums
 export { Emulator, TrackOption } from '../utils/constants.js';
+
+// Re-export OPL3 register helpers
+export {
+    CHANNELS_PER_CHIP,
+    CHANNELS_STANDARD,
+    CHANNELS_RHYTHM,
+    OPL3_SAMPLE_RATE,
+    CHANNEL_OPERATORS,
+    channelBank,
+    fnumLoReg,
+    keyOnBlockReg,
+    feedbackConnReg,
+    operatorReg,
+    noteToFnumBlock,
+    encodeFnumBlock,
+    keyOn,
+    keyOff,
+    encodeOperatorRegisters,
+    encodeChannelVoice,
+    channelMask
+} from '../utils/opl3.js';

package/src/profiles/light.slim.js

@@ -90,3 +90,24 @@ export {
 
 // Re-export enums
 export { Emulator, TrackOption } from '../utils/constants.js';
+
+// Re-export OPL3 register helpers
+export {
+    CHANNELS_PER_CHIP,
+    CHANNELS_STANDARD,
+    CHANNELS_RHYTHM,
+    OPL3_SAMPLE_RATE,
+    CHANNEL_OPERATORS,
+    channelBank,
+    fnumLoReg,
+    keyOnBlockReg,
+    feedbackConnReg,
+    operatorReg,
+    noteToFnumBlock,
+    encodeFnumBlock,
+    keyOn,
+    keyOff,
+    encodeOperatorRegisters,
+    encodeChannelVoice,
+    channelMask
+} from '../utils/opl3.js';

package/src/profiles/nuked.js

@@ -90,3 +90,24 @@ export {
 
 // Re-export enums
 export { Emulator, TrackOption } from '../utils/constants.js';
+
+// Re-export OPL3 register helpers
+export {
+    CHANNELS_PER_CHIP,
+    CHANNELS_STANDARD,
+    CHANNELS_RHYTHM,
+    OPL3_SAMPLE_RATE,
+    CHANNEL_OPERATORS,
+    channelBank,
+    fnumLoReg,
+    keyOnBlockReg,
+    feedbackConnReg,
+    operatorReg,
+    noteToFnumBlock,
+    encodeFnumBlock,
+    keyOn,
+    keyOff,
+    encodeOperatorRegisters,
+    encodeChannelVoice,
+    channelMask
+} from '../utils/opl3.js';

package/src/profiles/nuked.slim.js

@@ -90,3 +90,24 @@ export {
 
 // Re-export enums
 export { Emulator, TrackOption } from '../utils/constants.js';
+
+// Re-export OPL3 register helpers
+export {
+    CHANNELS_PER_CHIP,
+    CHANNELS_STANDARD,
+    CHANNELS_RHYTHM,
+    OPL3_SAMPLE_RATE,
+    CHANNEL_OPERATORS,
+    channelBank,
+    fnumLoReg,
+    keyOnBlockReg,
+    feedbackConnReg,
+    operatorReg,
+    noteToFnumBlock,
+    encodeFnumBlock,
+    keyOn,
+    keyOff,
+    encodeOperatorRegisters,
+    encodeChannelVoice,
+    channelMask
+} from '../utils/opl3.js';