libadlmidi-js 2.0.0 → 2.2.0

package/dist/profiles/light.slim.d.ts

@@ -16,9 +16,10 @@ export class AdlMidi extends BaseAdlMidi {
      *
      * @param {string} [processorUrl] - Override processor URL (optional)
      * @param {string} [wasmUrl] - Override WASM URL (optional)
+     * @param {object} [defaultSettings] - Override profile's default synth settings
      * @returns {Promise<void>}
      */
-    init(processorUrl?: string, wasmUrl?: string): Promise<void>;
+    init(processorUrl?: string, wasmUrl?: string, defaultSettings?: object): Promise<void>;
 }
 /**
  * Pre-configured AdlMidiCore for light slim profile.
@@ -37,14 +38,18 @@ export class AdlMidiCore {
     /**
      * Create a new AdlMidiCore instance with this profile's WASM.
      *
-     * @param {{corePath?: string}} [options] - Options (corePath is pre-configured)
+     * @param {{corePath?: string, defaultEmulator?: number, wasmBinary?: ArrayBuffer}} [options]
+     *   Override profile defaults. corePath and defaultEmulator are pre-configured.
      * @returns {Promise<BaseAdlMidiCore>}
      */
     static create(options?: {
         corePath?: string;
+        defaultEmulator?: number;
+        wasmBinary?: ArrayBuffer;
     }): Promise<BaseAdlMidiCore>;
 }
 import { AdlMidi as BaseAdlMidi } from '../libadlmidi.js';
 import { AdlMidiCore as BaseAdlMidiCore } from '../core.js';
 export { encodeInstrument, decodeInstrument, defaultInstrument, encodeOperator, decodeOperator, defaultOperator } from "../utils/struct.js";
 export { Emulator, TrackOption } from "../utils/constants.js";
+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/dist/profiles/nuked.d.ts

@@ -16,9 +16,10 @@ export class AdlMidi extends BaseAdlMidi {
      *
      * @param {string} [processorUrl] - Override processor URL (optional)
      * @param {string} [wasmUrl] - Override WASM URL (optional)
+     * @param {object} [defaultSettings] - Override profile's default synth settings
      * @returns {Promise<void>}
      */
-    init(processorUrl?: string, wasmUrl?: string): Promise<void>;
+    init(processorUrl?: string, wasmUrl?: string, defaultSettings?: object): Promise<void>;
 }
 /**
  * Pre-configured AdlMidiCore for nuked profile.
@@ -37,14 +38,18 @@ export class AdlMidiCore {
     /**
      * Create a new AdlMidiCore instance with this profile's WASM.
      *
-     * @param {{corePath?: string}} [options] - Options (corePath is pre-configured)
+     * @param {{corePath?: string, defaultEmulator?: number, wasmBinary?: ArrayBuffer}} [options]
+     *   Override profile defaults. corePath and defaultEmulator are pre-configured.
      * @returns {Promise<BaseAdlMidiCore>}
      */
     static create(options?: {
         corePath?: string;
+        defaultEmulator?: number;
+        wasmBinary?: ArrayBuffer;
     }): Promise<BaseAdlMidiCore>;
 }
 import { AdlMidi as BaseAdlMidi } from '../libadlmidi.js';
 import { AdlMidiCore as BaseAdlMidiCore } from '../core.js';
 export { encodeInstrument, decodeInstrument, defaultInstrument, encodeOperator, decodeOperator, defaultOperator } from "../utils/struct.js";
 export { Emulator, TrackOption } from "../utils/constants.js";
+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/dist/profiles/nuked.slim.d.ts

@@ -16,9 +16,10 @@ export class AdlMidi extends BaseAdlMidi {
      *
      * @param {string} [processorUrl] - Override processor URL (optional)
      * @param {string} [wasmUrl] - Override WASM URL (optional)
+     * @param {object} [defaultSettings] - Override profile's default synth settings
      * @returns {Promise<void>}
      */
-    init(processorUrl?: string, wasmUrl?: string): Promise<void>;
+    init(processorUrl?: string, wasmUrl?: string, defaultSettings?: object): Promise<void>;
 }
 /**
  * Pre-configured AdlMidiCore for nuked slim profile.
@@ -37,14 +38,18 @@ export class AdlMidiCore {
     /**
      * Create a new AdlMidiCore instance with this profile's WASM.
      *
-     * @param {{corePath?: string}} [options] - Options (corePath is pre-configured)
+     * @param {{corePath?: string, defaultEmulator?: number, wasmBinary?: ArrayBuffer}} [options]
+     *   Override profile defaults. corePath and defaultEmulator are pre-configured.
      * @returns {Promise<BaseAdlMidiCore>}
      */
     static create(options?: {
         corePath?: string;
+        defaultEmulator?: number;
+        wasmBinary?: ArrayBuffer;
     }): Promise<BaseAdlMidiCore>;
 }
 import { AdlMidi as BaseAdlMidi } from '../libadlmidi.js';
 import { AdlMidiCore as BaseAdlMidiCore } from '../core.js';
 export { encodeInstrument, decodeInstrument, defaultInstrument, encodeOperator, decodeOperator, defaultOperator } from "../utils/struct.js";
 export { Emulator, TrackOption } from "../utils/constants.js";
+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/dist/utils/constants.d.ts

@@ -17,7 +17,9 @@ export type Emulator = number;
 export const Emulator: Readonly<{
     /** Nuked OPL3 v1.8 - Most accurate, higher CPU usage */
     NUKED: 0;
-    /** Nuked OPL3 v1.7.4 - Slightly older version */
+    /** Optimized Nuked 1.8 fork by tgies with identical output */
+    NUKED_FAST: 1;
+    /** @deprecated Use NUKED_FAST */
     NUKED_174: 1;
     /** DosBox OPL3 - Good accuracy, lower CPU usage */
     DOSBOX: 2;

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.0.0",
+  "version": "2.2.0",
   "libadlmidi": {
     "version": "1.6.2",
-    "commit": "89284b0b63e236ccaf84ac2763574738840d37b4"
+    "commit": "ad001c83551779934bacd642fce801c51a5b7b4c"
   },
   "description": "WebAssembly build of libADLMIDI - OPL3/FM synthesis for the browser",
   "main": "dist/libadlmidi.js",
@@ -11,35 +11,47 @@
   "exports": {
     ".": "./dist/libadlmidi.js",
     "./core": {
-      "import": "./src/core.js",
-      "types": "./dist/core.d.ts"
+      "types": "./dist/core.d.ts",
+      "import": "./src/core.js"
     },
     "./structs": {
-      "import": "./src/utils/struct.js",
-      "types": "./dist/utils/struct.d.ts"
+      "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"
     },
     "./nuked/slim": {
+      "types": "./dist/profiles/nuked.slim.d.ts",
       "import": "./src/profiles/nuked.slim.js"
     },
     "./dosbox": {
+      "types": "./dist/profiles/dosbox.d.ts",
       "import": "./src/profiles/dosbox.js"
     },
     "./dosbox/slim": {
+      "types": "./dist/profiles/dosbox.slim.d.ts",
       "import": "./src/profiles/dosbox.slim.js"
     },
     "./light": {
+      "types": "./dist/profiles/light.d.ts",
       "import": "./src/profiles/light.js"
     },
     "./light/slim": {
+      "types": "./dist/profiles/light.slim.d.ts",
       "import": "./src/profiles/light.slim.js"
     },
     "./full": {
+      "types": "./dist/profiles/full.d.ts",
       "import": "./src/profiles/full.js"
     },
     "./full/slim": {
+      "types": "./dist/profiles/full.slim.d.ts",
       "import": "./src/profiles/full.slim.js"
     },
     "./dist/*": "./dist/*"
@@ -66,7 +78,10 @@
     "lint:fix": "eslint . --fix",
     "check": "npm run lint && npm run typecheck && npm run sync-version -- --check",
     "sync-version": "node scripts/sync-libadlmidi-version.js",
-    "prepare": "command -v pre-commit >/dev/null && pre-commit install || echo 'pre-commit not found, run: pipx install pre-commit'"
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.js": "eslint --fix"
   },
   "types": "dist/libadlmidi.d.ts",
   "keywords": [
@@ -86,15 +101,22 @@
     "url": "https://github.com/libadlmidi-js/libadlmidi-js.git"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@commitlint/cli": "^21.0.1",
+    "@commitlint/config-conventional": "^21.0.1",
+    "@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",
-    "vitest": "^4.0.16"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   },
   "files": [
     "dist/",
@@ -109,5 +131,8 @@
     "light-slim.js",
     "full-slim.js",
     "README.md"
-  ]
+  ],
+  "overrides": {
+    "fflate": "0.8.2"
+  }
 }

package/src/core.js

@@ -51,6 +51,8 @@ export class AdlMidiCore {
      * @param {Object} options
      * @param {string} options.corePath - Path to the .core.js WASM loader module
      * @param {ArrayBuffer} [options.wasmBinary] - Pre-loaded WASM binary (optional)
+     * @param {number} [options.defaultEmulator] - Emulator to switch to after init.
+     *                            Profile wrappers use this to default to NUKED_FAST.
      * @returns {Promise<AdlMidiCore>}
      */
     static async create(options) {
@@ -73,6 +75,7 @@ export class AdlMidiCore {
         core._sampleRate = 44100;
         core._audioBuffer = null;
         core._audioBufferPtr = null;
+        core._defaultEmulator = options.defaultEmulator;
 
         return core;
     }
@@ -88,6 +91,8 @@ export class AdlMidiCore {
         this._audioBuffer = null;
         /** @private @type {number|null} */
         this._audioBufferPtr = null;
+        /** @private @type {number|undefined} */
+        this._defaultEmulator = undefined;
     }
 
     /**
@@ -108,6 +113,10 @@ export class AdlMidiCore {
             throw new Error('Failed to initialize ADL MIDI player');
         }
 
+        if (this._defaultEmulator !== undefined) {
+            this._module._adl_switchEmulator(this._player, this._defaultEmulator);
+        }
+
         return true;
     }
 
@@ -600,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

@@ -114,9 +114,11 @@ export class AdlMidi {
      * @param {string} processorUrl - URL to the bundled processor JavaScript file
      * @param {string | null} [wasmUrl=null] - Optional URL to the .wasm file for split builds.
      *                             If not provided, assumes bundled version with embedded WASM.
+     * @param {object} [defaultSettings={}] - Initial synth settings applied before ready.
+     *                             Profile wrappers use this to set a default emulator.
      * @returns {Promise<void>}
      */
-    async init(processorUrl, wasmUrl = null) {
+    async init(processorUrl, wasmUrl = null, defaultSettings = {}) {
         if (!this.ctx) {
             this.ctx = new AudioContext({ sampleRate: 44100 });
         }
@@ -143,7 +145,8 @@ export class AdlMidi {
         this.node = new AudioWorkletNode(this.ctx, 'adl-midi-processor', {
             processorOptions: {
                 sampleRate: this.ctx.sampleRate,
-                wasmBinary: wasmBinary  // null for bundled, ArrayBuffer for split
+                wasmBinary: wasmBinary,  // null for bundled, ArrayBuffer for split
+                settings: defaultSettings
             }
         });
 
@@ -346,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

@@ -45,6 +45,7 @@ class AdlMidiProcessor extends AudioWorkletProcessor {
             softPan: true,            // Soft stereo panning
             deepVibrato: false,       // Deep vibrato
             deepTremolo: false,       // Deep tremolo
+            emulator: undefined,      // Emulator core (undefined = libADLMIDI default)
             ...options.processorOptions?.settings
         };
 
@@ -104,6 +105,11 @@ class AdlMidiProcessor extends AudioWorkletProcessor {
     applySettings(settings) {
         if (!this.midi) return;
 
+        // Switch emulator first; adl_switchEmulator does a partialReset and a
+        // wrong-order subsequent setBank etc. would otherwise need re-applying.
+        if (settings.emulator !== undefined) {
+            this.adl._adl_switchEmulator(this.midi, settings.emulator);
+        }
         if (settings.numChips !== undefined) {
             this.adl._adl_setNumChips(this.midi, settings.numChips);
         }
@@ -695,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': {