libadlmidi-js 1.2.0 → 2.1.0

package/README.md

@@ -9,6 +9,7 @@ Check out some [examples](https://libadlmidi-js.github.io):
 - [patch editor](https://libadlmidi-js.github.io/examples/patch-editor.html)
 - [midi to wav](https://libadlmidi-js.github.io/examples/midi-to-audio.html)
 - [connect any midi controller](https://libadlmidi-js.github.io/examples/webmidi.html)
+- [tr-262 drum machine](https://libadlmidi-js.github.io/examples/tr-262.html)
 
 ## Features
 
@@ -49,7 +50,7 @@ You can load the library from a CDN to use it right away.
 <script type="module">
   import { AdlMidi } from 'https://unpkg.com/libadlmidi-js/src/profiles/light.js';
   // or: https://cdn.jsdelivr.net/npm/libadlmidi-js/src/profiles/light.js
-  
+
   const synth = new AdlMidi();
   await synth.init();
 </script>
@@ -59,7 +60,7 @@ You can load the library from a CDN to use it right away.
 ```html
 <script type="module">
   import { AdlMidi } from 'https://esm.sh/libadlmidi-js/src/libadlmidi.js';
-  
+
   const synth = new AdlMidi();
   await synth.init(
     'https://esm.sh/libadlmidi-js/dist/libadlmidi.light.processor.js?raw',
@@ -138,10 +139,12 @@ const decoded = decodeInstrument(bytes);
 
 | Profile | Emulator(s) | Usage |
 |---------|-------------|-------|
-| `nuked` | Nuked OPL3 v1.8 | Maximum accuracy, highest CPU usage. |
+| `nuked` | Nuked OPL3 v1.8 + Nuked OPL3 Fast | Maximum accuracy. Defaults to Nuked Fast (bit-exact vs Nuked 1.8, faster). |
 | `dosbox` | DosBox OPL3 | Great balance of speed and accuracy. |
-| `light` | Nuked + DosBox | Flexible for varied performance needs. |
-| `full` | All supported | Includes Opal, Java OPL3, ESFMu, etc. |
+| `light` | Nuked + Nuked Fast, DosBox | Flexible for varied performance needs. Defaults to Nuked Fast. |
+| `full` | All supported | Includes Opal, Java OPL3, ESFMu, etc. Defaults to Nuked Fast where available. |
+
+To opt back to the original Nuked 1.8, pass `{ emulator: Emulator.NUKED }` as the third argument to `init()`, or call `await synth.switchEmulator(Emulator.NUKED)` after init.
 
 ## Documentation
 

package/dist/core.d.ts

@@ -30,11 +30,14 @@ 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 create(options: {
         corePath: string;
         wasmBinary?: ArrayBuffer | undefined;
+        defaultEmulator?: number | undefined;
     }): Promise<AdlMidiCore>;
     /** @private @type {any} */
     private _module;
@@ -46,6 +49,8 @@ export class AdlMidiCore {
     private _audioBuffer;
     /** @private @type {number|null} */
     private _audioBufferPtr;
+    /** @private @type {number|undefined} */
+    private _defaultEmulator;
     /**
      * Initialize the synthesizer.
      *
@@ -118,6 +123,12 @@ export class AdlMidiCore {
      * @returns {number} Count of channels
      */
     getNumFourOpChannels(): number;
+    /**
+     * Get the number of 4-operator channels obtained.
+     *
+     * @returns {number} Count of channels obtained
+     */
+    getNumFourOpChannelsObtained(): number;
     /**
      * Enable/disable scaling of modulators by volume.
      *
@@ -159,19 +170,31 @@ export class AdlMidiCore {
      *
      * @param {boolean} enabled
      */
-    setSoftPan(enabled: boolean): void;
+    setSoftPanEnabled(enabled: boolean): void;
     /**
      * Enable/disable deep vibrato.
      *
      * @param {boolean} enabled
      */
     setDeepVibrato(enabled: boolean): void;
+    /**
+     * Get deep vibrato state.
+     *
+     * @returns {boolean}
+     */
+    getDeepVibrato(): boolean;
     /**
      * Enable/disable deep tremolo.
      *
      * @param {boolean} enabled
      */
     setDeepTremolo(enabled: boolean): void;
+    /**
+     * Get deep tremolo state.
+     *
+     * @returns {boolean}
+     */
+    getDeepTremolo(): boolean;
     /**
      * Switch OPL3 emulator (if multiple are compiled in).
      *
@@ -185,6 +208,18 @@ export class AdlMidiCore {
      * @returns {string} Emulator name
      */
     getEmulatorName(): string;
+    /**
+     * Get the last global error string (static, no player needed).
+     *
+     * @returns {string} Error string or empty string
+     */
+    getErrorString(): string;
+    /**
+     * Get the last error info for this player instance.
+     *
+     * @returns {string} Error info string or empty string
+     */
+    getErrorInfo(): string;
     /**
      * Get the version string of the linked libADLMIDI library.
      *
@@ -218,13 +253,13 @@ export class AdlMidiCore {
      *
      * @returns {number}
      */
-    getVolumeModel(): number;
+    getVolumeRangeModel(): number;
     /**
      * Set the volume range model.
      *
      * @param {number} model - Volume model type
      */
-    setVolumeModel(model: number): void;
+    setVolumeRangeModel(model: number): void;
     /**
      * Run emulator with PCM rate to reduce CPU usage.
      *
@@ -331,6 +366,25 @@ export class AdlMidiCore {
      * @returns {string} Copyright or empty string
      */
     getMusicCopyright(): string;
+    /**
+     * Get the number of track titles in the loaded MIDI file.
+     *
+     * @returns {number} Number of track titles
+     */
+    getTrackTitleCount(): number;
+    /**
+     * Get a track title by index.
+     *
+     * @param {number} index - Track title index
+     * @returns {string} Track title or empty string
+     */
+    getTrackTitle(index: number): string;
+    /**
+     * Get the number of MIDI markers in the loaded file.
+     *
+     * @returns {number} Number of markers
+     */
+    getMarkerCount(): number;
     /**
      * Play MIDI file and generate audio.
      *
@@ -371,13 +425,127 @@ export class AdlMidiCore {
      *
      * @param {boolean} enabled
      */
-    setLooping(enabled: boolean): void;
+    setLoopEnabled(enabled: boolean): void;
+    /**
+     * Set the number of loop repetitions.
+     *
+     * @param {number} count - Loop count (-1 = infinite, 0 = no loops, 1+ = number of loops)
+     */
+    setLoopCount(count: number): void;
+    /**
+     * Enable/disable loop hooks only mode.
+     *
+     * @param {boolean} enabled
+     */
+    setLoopHooksOnly(enabled: boolean): void;
+    /**
+     * Get the loop start time in seconds.
+     *
+     * @returns {number} Loop start time in seconds
+     */
+    getLoopStartTime(): number;
+    /**
+     * Get the loop end time in seconds.
+     *
+     * @returns {number} Loop end time in seconds
+     */
+    getLoopEndTime(): number;
+    /**
+     * Select a song number for multi-song MIDI files.
+     *
+     * @param {number} num - Song number (0-based)
+     */
+    selectSongNum(num: number): void;
+    /**
+     * Get the number of songs in the loaded MIDI file.
+     *
+     * @returns {number} Number of songs
+     */
+    getSongsCount(): number;
+    /**
+     * Get the number of tracks in the loaded MIDI file.
+     *
+     * @returns {number} Number of tracks
+     */
+    getTrackCount(): number;
+    /**
+     * Set track options (enable, mute, or solo).
+     * Use the TrackOption enum: TrackOption.ON (1), TrackOption.OFF (2), TrackOption.SOLO (3).
+     * Note: Passing 0 is a silent no-op that returns true without changing state.
+     *
+     * @param {number} track - Track index
+     * @param {number} options - Track option from TrackOption enum
+     * @returns {boolean} True if successful
+     */
+    setTrackOptions(track: number, options: number): boolean;
+    /**
+     * Enable or disable a MIDI channel.
+     *
+     * @param {number} channel - MIDI channel (0-15)
+     * @param {boolean} enabled - Whether to enable the channel
+     * @returns {boolean} True if successful
+     */
+    setChannelEnabled(channel: number, enabled: boolean): boolean;
     /**
      * Set playback tempo multiplier.
      *
      * @param {number} tempo - Tempo multiplier (1.0 = normal)
      */
     setTempo(tempo: number): void;
+    /**
+     * Reserve a number of banks.
+     *
+     * @param {number} count - Number of banks to reserve
+     * @returns {boolean} True if successful
+     */
+    reserveBanks(count: number): boolean;
+    /**
+     * Get the bank ID for a given bank identifier.
+     *
+     * @param {Object} bankId - Bank identifier
+     * @param {boolean|number} bankId.percussive - True/1 for percussion, false/0 for melodic
+     * @param {number} bankId.msb - Bank MSB
+     * @param {number} bankId.lsb - Bank LSB
+     * @returns {{percussive: number, msb: number, lsb: number}|null} Bank ID or null if not found
+     */
+    getBankId(bankId: {
+        percussive: boolean | number;
+        msb: number;
+        lsb: number;
+    }): {
+        percussive: number;
+        msb: number;
+        lsb: number;
+    } | null;
+    /**
+     * Remove a bank by its identifier.
+     *
+     * @param {Object} bankId - Bank identifier
+     * @param {boolean|number} bankId.percussive - True/1 for percussion, false/0 for melodic
+     * @param {number} bankId.msb - Bank MSB
+     * @param {number} bankId.lsb - Bank LSB
+     * @returns {boolean} True if successfully removed
+     */
+    removeBank(bankId: {
+        percussive: boolean | number;
+        msb: number;
+        lsb: number;
+    }): boolean;
+    /**
+     * Load an embedded bank into a custom bank slot.
+     *
+     * @param {Object} bankId - Target bank identifier
+     * @param {boolean|number} bankId.percussive - True/1 for percussion, false/0 for melodic
+     * @param {number} bankId.msb - Bank MSB
+     * @param {number} bankId.lsb - Bank LSB
+     * @param {number} num - Embedded bank number to load
+     * @returns {boolean} True if successful
+     */
+    loadEmbeddedBank(bankId: {
+        percussive: boolean | number;
+        msb: number;
+        lsb: number;
+    }, num: number): boolean;
     /**
      * Get an instrument from a bank.
      *
@@ -409,6 +577,22 @@ export class AdlMidiCore {
         msb: number;
         lsb: number;
     }, program: number, instrument: import("./utils/struct.js").Instrument): boolean;
+    /**
+     * Send a System Exclusive (SysEx) message.
+     *
+     * @param {Uint8Array|ArrayBuffer} data - SysEx message data
+     * @returns {boolean} True if successful
+     */
+    systemExclusive(data: Uint8Array | ArrayBuffer): boolean;
+    /**
+     * Describe the current state of all channels (debug utility).
+     *
+     * @returns {{text: string, attr: Uint8Array}} Channel state text and raw per-channel attribute bytes
+     */
+    describeChannels(): {
+        text: string;
+        attr: Uint8Array;
+    };
     /**
      * Get the raw Emscripten module for advanced usage.
      *
@@ -431,3 +615,6 @@ export class AdlMidiCore {
     private _ensurePlayer;
 }
 export default AdlMidiCore;
+import { Emulator } from './utils/constants.js';
+import { TrackOption } from './utils/constants.js';
+export { Emulator, TrackOption };

package/dist/fm_banks/manifest.json

@@ -1,5 +1,5 @@
 {
-  "generated": "2026-03-17T14:43:16.332Z",
+  "generated": "2026-05-27T04:19:52.386Z",
   "categories": {
     "wopl": {
       "description": "General WOPL banks",

package/dist/libadlmidi.d.ts

@@ -1,25 +1,3 @@
-/**
- * Available OPL2/OPL3 emulator cores.
- * Use with switchEmulator() to change the synthesis engine at runtime.
- * Note: Only emulators compiled into the current profile are available.
- */
-export type Emulator = number;
-/**
- * libADLMIDI-JS - Main Thread Interface
- *
- * High-level API for real-time OPL3 FM synthesis in the browser.
- *
- * @example
- * ```javascript
- * import { AdlMidi } from 'libadlmidi-js';
- *
- * const synth = new AdlMidi();
- * await synth.init('/path/to/processor.js');
- *
- * synth.noteOn(0, 60, 100);  // Middle C on channel 0
- * synth.noteOff(0, 60);
- * ```
- */
 /**
  * Bank identifier for instrument access
  * @typedef {Object} BankId
@@ -74,39 +52,6 @@ export type Emulator = number;
  * @property {boolean} [deepVibrato] - Enable deep vibrato
  * @property {boolean} [deepTremolo] - Enable deep tremolo
  */
-/**
- * Available OPL2/OPL3 emulator cores.
- * Use with switchEmulator() to change the synthesis engine at runtime.
- * Note: Only emulators compiled into the current profile are available.
- * @readonly
- * @enum {number}
- */
-export const Emulator: Readonly<{
-    /** Nuked OPL3 v1.8 - Most accurate, higher CPU usage */
-    NUKED: 0;
-    /** Nuked OPL3 v1.7.4 - Slightly older version */
-    NUKED_174: 1;
-    /** DosBox OPL3 - Good accuracy, lower CPU usage */
-    DOSBOX: 2;
-    /** Opal - Reality Adlib Tracker emulator */
-    OPAL: 3;
-    /** Java OPL3 - Port of emu8950 */
-    JAVA: 4;
-    /** ESFMu - ESFM chip emulator */
-    ESFMU: 5;
-    /** MAME OPL2 */
-    MAME_OPL2: 6;
-    /** YMFM OPL2 */
-    YMFM_OPL2: 7;
-    /** YMFM OPL3 */
-    YMFM_OPL3: 8;
-    /** Nuked OPL2 LLE - Transistor-level emulation */
-    NUKED_OPL2_LLE: 9;
-    /** Nuked OPL3 LLE - Transistor-level emulation */
-    NUKED_OPL3_LLE: 10;
-    /** Nuked OPL2 Lite - Lightweight OPL2 emulation for AdLib-era music */
-    NUKED_OPL2_LITE: 11;
-}>;
 export class AdlMidi {
     /**
      * Create a new AdlMidi instance
@@ -130,9 +75,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>}
      */
-    init(processorUrl: string, wasmUrl?: string | null): Promise<void>;
+    init(processorUrl: string, wasmUrl?: string | null, defaultSettings?: object): Promise<void>;
     /**
      * Play a note
      * @param {number} channel - MIDI channel (0-15)
@@ -217,7 +164,7 @@ export class AdlMidi {
      * @param {ArrayBuffer} arrayBuffer - Bank file data
      * @returns {Promise<void>}
      */
-    loadBank(arrayBuffer: ArrayBuffer): Promise<void>;
+    loadBankData(arrayBuffer: ArrayBuffer): Promise<void>;
     /**
      * Set the embedded bank by number
      * @param {number} bank - Bank number
@@ -254,6 +201,11 @@ export class AdlMidi {
      * @returns {Promise<number>}
      */
     getNumFourOpChannels(): Promise<number>;
+    /**
+     * Get the number of 4-operator channels obtained
+     * @returns {Promise<number>}
+     */
+    getNumFourOpChannelsObtained(): Promise<number>;
     /**
      * Enable/disable scaling of modulators by volume
      * @param {boolean} enabled
@@ -285,25 +237,35 @@ export class AdlMidi {
      */
     getChannelAllocMode(): Promise<number>;
     /**
-     * Set the volume model
+     * Set the volume range model
      * @param {number} model - Volume model number
      */
-    setVolumeModel(model: number): void;
+    setVolumeRangeModel(model: number): void;
     /**
-     * Enable/disable rhythm mode (percussion)
+     * Enable/disable soft stereo panning
      * @param {boolean} enabled
      */
-    setPercussionMode(enabled: boolean): void;
+    setSoftPanEnabled(enabled: boolean): void;
     /**
      * Enable/disable deep vibrato
      * @param {boolean} enabled
      */
-    setVibrato(enabled: boolean): void;
+    setDeepVibrato(enabled: boolean): void;
+    /**
+     * Get deep vibrato state
+     * @returns {Promise<boolean>}
+     */
+    getDeepVibrato(): Promise<boolean>;
     /**
      * Enable/disable deep tremolo
      * @param {boolean} enabled
      */
-    setTremolo(enabled: boolean): void;
+    setDeepTremolo(enabled: boolean): void;
+    /**
+     * Get deep tremolo state
+     * @returns {Promise<boolean>}
+     */
+    getDeepTremolo(): Promise<boolean>;
     /**
      * Run emulator with PCM rate to reduce CPU usage
      * @param {boolean} enabled
@@ -316,7 +278,7 @@ export class AdlMidi {
      * - nuked profile: NUKED only
      * - dosbox profile: DOSBOX only
      * - light profile: NUKED, DOSBOX
-     * - full profile: NUKED, DOSBOX, OPAL, JAVA, ESFMU, YMFM_OPL2, YMFM_OPL3
+     * - full profile: NUKED, DOSBOX, OPAL, JAVA, ESFMu, YMFM_OPL2, YMFM_OPL3
      *
      * @param {number} emulator - Emulator ID from the Emulator enum
      * @returns {Promise<void>} Resolves when emulator is switched, rejects if unavailable
@@ -333,6 +295,11 @@ export class AdlMidi {
      * console.log(`Using: ${name}`);
      */
     getEmulatorName(): Promise<string>;
+    /**
+     * Get the last error info for the player instance
+     * @returns {Promise<string>}
+     */
+    getErrorInfo(): Promise<string>;
     /**
      * Get the version string of the linked libADLMIDI library
      * @returns {Promise<string>}
@@ -361,7 +328,7 @@ export class AdlMidi {
      * Get the volume range model
      * @returns {Promise<number>}
      */
-    getVolumeModel(): Promise<number>;
+    getVolumeRangeModel(): Promise<number>;
     /**
      * Get list of embedded banks available in this build
      * Note: Slim builds have no embedded banks and will return an empty array
@@ -374,6 +341,49 @@ export class AdlMidi {
         id: number;
         name: string;
     }[]>;
+    /**
+     * Reserve a number of banks
+     * @param {number} count - Number of banks to reserve
+     * @returns {Promise<void>} Resolves on success, rejects on failure
+     */
+    reserveBanks(count: number): Promise<void>;
+    /**
+     * Get the bank ID for a given bank identifier
+     * @param {BankId} bankId - Bank identifier
+     * @returns {Promise<{percussive: number, msb: number, lsb: number}|null>} Bank ID or null if not found
+     */
+    getBankId(bankId: BankId): Promise<{
+        percussive: number;
+        msb: number;
+        lsb: number;
+    } | null>;
+    /**
+     * Remove a bank by its identifier
+     * @param {BankId} bankId - Bank identifier
+     * @returns {Promise<void>} Resolves on success, rejects on failure
+     */
+    removeBank(bankId: BankId): Promise<void>;
+    /**
+     * Load an embedded bank into a custom bank slot
+     * @param {BankId} bankId - Target bank identifier
+     * @param {number} num - Embedded bank number to load
+     * @returns {Promise<void>} Resolves on success, rejects on failure
+     */
+    loadEmbeddedBank(bankId: BankId, num: number): Promise<void>;
+    /**
+     * Send a System Exclusive (SysEx) message
+     * @param {Uint8Array|ArrayBuffer} data - SysEx message data
+     * @returns {Promise<void>} Resolves on success, rejects on failure
+     */
+    systemExclusive(data: Uint8Array | ArrayBuffer): Promise<void>;
+    /**
+     * Describe the current state of all channels (debug utility)
+     * @returns {Promise<{text: string, attr: Uint8Array}>} Channel state text and raw per-channel attribute bytes
+     */
+    describeChannels(): Promise<{
+        text: string;
+        attr: Uint8Array;
+    }>;
     /**
      * Reset the synthesizer
      * @returns {void}
@@ -397,6 +407,22 @@ export class AdlMidi {
      * @returns {Promise<string>}
      */
     getMusicCopyright(): Promise<string>;
+    /**
+     * Get the number of track titles in the loaded MIDI file
+     * @returns {Promise<number>}
+     */
+    getTrackTitleCount(): Promise<number>;
+    /**
+     * Get a track title by index
+     * @param {number} index - Track title index
+     * @returns {Promise<string>}
+     */
+    getTrackTitle(index: number): Promise<string>;
+    /**
+     * Get the number of MIDI markers in the loaded file
+     * @returns {Promise<number>}
+     */
+    getMarkerCount(): Promise<number>;
     /**
      * Start or resume MIDI file playback
      * @returns {void}
@@ -418,7 +444,58 @@ export class AdlMidi {
      * @param {boolean} enabled - Whether to loop
      * @returns {void}
      */
-    setLoop(enabled: boolean): void;
+    setLoopEnabled(enabled: boolean): void;
+    /**
+     * Set the number of loop repetitions
+     * @param {number} count - Loop count (-1 = infinite, 0 = no loops, 1+ = number of loops)
+     */
+    setLoopCount(count: number): void;
+    /**
+     * Enable/disable loop hooks only mode
+     * @param {boolean} enabled
+     */
+    setLoopHooksOnly(enabled: boolean): void;
+    /**
+     * Get the loop start time in seconds
+     * @returns {Promise<number>}
+     */
+    getLoopStartTime(): Promise<number>;
+    /**
+     * Get the loop end time in seconds
+     * @returns {Promise<number>}
+     */
+    getLoopEndTime(): Promise<number>;
+    /**
+     * Select a song number for multi-song MIDI files
+     * @param {number} num - Song number (0-based)
+     */
+    selectSongNum(num: number): void;
+    /**
+     * Get the number of songs in the loaded MIDI file
+     * @returns {Promise<number>}
+     */
+    getSongsCount(): Promise<number>;
+    /**
+     * Get the number of tracks in the loaded MIDI file
+     * @returns {Promise<number>}
+     */
+    getTrackCount(): Promise<number>;
+    /**
+     * Set track options (enable, mute, or solo)
+     * Use the TrackOption enum: TrackOption.ON (1), TrackOption.OFF (2), TrackOption.SOLO (3).
+     * Note: Passing 0 is a silent no-op that resolves without changing state.
+     * @param {number} track - Track index
+     * @param {number} options - Track option from TrackOption enum
+     * @returns {Promise<void>} Resolves on success, rejects on failure
+     */
+    setTrackOptions(track: number, options: number): Promise<void>;
+    /**
+     * Enable or disable a MIDI channel
+     * @param {number} channel - MIDI channel (0-15)
+     * @param {boolean} enabled - Whether to enable the channel
+     * @returns {Promise<void>} Resolves on success, rejects on failure
+     */
+    setChannelEnabled(channel: number, enabled: boolean): Promise<void>;
     /**
      * Set the playback tempo multiplier
      * @param {number} tempo - Tempo multiplier (1.0 = normal speed)
@@ -643,3 +720,6 @@ export type ConfigureSettings = {
      */
     deepTremolo?: boolean | undefined;
 };
+import { Emulator } from './utils/constants.js';
+import { TrackOption } from './utils/constants.js';
+export { Emulator, TrackOption };