tetorica-fm2612 0.2.0 → 0.2.2

package/README.md

@@ -96,7 +96,7 @@ not copy assets. Keep dependent files alongside each deployed entry point.
 
 ## Mega CD PCM with MegaSynth
 
-The `0.2.0` local build adds opt-in RF5C164 support. Enable `megaCD` before
+Since `0.2.0`, the package includes opt-in RF5C164 support. Enable `megaCD` before
 `start()`. YM2612, Sega PSG and RF5C164 share one AudioContext, master volume
 and effects chain. Sega PSG is enabled with Mega CD unless its URL is explicitly
 set to `null`. Existing FM-only construction stays unchanged.
@@ -137,6 +137,41 @@ otherwise they are siblings of the YM2612 assets. The FM command recorder
 continues to record FM/DAC actions; PCM commands are not recorded. This adds
 the Mega CD PCM chip, not CD disc-image emulation or 32X PWM.
 
+## YM2608 ADPCM-B sample loading
+
+Since `0.2.2`, `YM2608Synth` provides `synth.adpcm.loadSample()`.
+It accepts decoded `{channels, sampleRate}`, AudioBuffer, PCM/Float RIFF WAV
+bytes, Blob, a browser URL, or a Node.js path/file URL. It mixes channels to
+mono, encodes Yamaha ADPCM-B, transfers it, and configures the sample range
+and playback rate. It does not start playback or change volume/pan.
+
+```js
+const wave = Float32Array.from({length: 8000}, (_, i) =>
+  0.5 * Math.sin(i * 2 * Math.PI * 440 / 8000));
+const info = await synth.adpcm.loadSample(
+  {channels: [wave], sampleRate: 8000},
+  {address: 0},
+);
+synth.adpcm.setVolume(180);
+synth.adpcm.setPan(true, true);
+synth.adpcm.keyOn();
+```
+
+Use a 32-byte aligned address and reserve non-overlapping areas of the 2 MiB
+memory yourself. Loading stops ADPCM-B; it preserves FM, SSG and rhythm.
+`info` contains `start`, exclusive `end`, `frames`, `paddedFrames`, actual
+`sampleRate`, `deltaN` and padded `duration`. Alignment adds at most 63 decoded
+frames of encoded silence. `keyOn({repeat: true})` repeats the padded range.
+The optional `sampleRate` selects a conversion rate; by default the source
+rate is capped to the chip range. Rate conversion uses linear interpolation.
+WAV PCM 8/16/24/32-bit and float 32/64-bit work without AudioContext in Node
+and browsers. Other formats require an optional `decodeAudio(arrayBuffer)`
+callback returning AudioBuffer or decoded PCM. `signal` can cancel loading.
+Worklet uploads complete before the returned promise resolves.
+
+`loadMemory()` remains the API for already-encoded ADPCM-B bytes.
+This does not add arbitrary sample loading to YM2608's fixed ADPCM-A rhythm.
+
 ## Local packaging
 
 From the repository root:
@@ -161,10 +196,10 @@ FM/PSG/PCM mixing, stop/reset and close/restart. Playwright is a development
 dependency; it is not required by users of the sound-chip runtime.
 
 The build is staged in `dist/fm2612/`; packing produces
-`tetorica-fm2612-0.2.0.tgz`. To install a local build in another project:
+`tetorica-fm2612-0.2.2.tgz`. To install a local build in another project:
 
 ```sh
-npm install /absolute/path/to/tetorica-fm2612-0.2.0.tgz
+npm install /absolute/path/to/tetorica-fm2612-0.2.2.tgz
 ```
 
 The existing `tetorica-vgm` CLI package is built separately. This first package
@@ -177,3 +212,14 @@ Project code is BSD-3-Clause. Third-party notices and component licenses are
 included; Nuked-OPN2 is LGPL-2.1-or-later, with its source and build script in
 `sources/`. The OPNA rhythm data is Tetorica-generated and includes its license
 and generator. External instrument/sample ROMs are not included.
+
+## Release notes
+
+`0.2.2` adds YM2608 ADPCM-B `loadSample()` for decoded PCM, AudioBuffer and
+PCM/Float WAV sources, with mono conversion, ADPCM-B encoding, memory upload
+and range/rate setup. Worklet memory uploads are acknowledged, and OPN browser
+runtimes release routing nodes when closed so they can restart safely.
+
+`0.2.1` updates the npm Homepage link to
+[tetorica-fm2612-examples](https://github.com/kyorohiro/tetorica-fm2612-examples).
+Sound-chip runtime behavior is unchanged from `0.2.0`.

package/RUNTIME.md

@@ -1,6 +1,6 @@
 # Full web runtime
 
-Includes all 131 top-level web runtime modules and 23 generated chip/engine pairs.
+Includes all 132 top-level web runtime modules and 23 generated chip/engine pairs.
 
 ay8910, gameboy_apu, huc6280, k051649, nuked_opn2, okim6258, rf5c164, segapcm, segapsg, y8950, ym2151, ym2203, ym2413, ym2608, ym2610b, ym2612, ym3438, ym3526, ym3812, ymf262, ymf276, ymf278b, ymf288
 

package/adpcm_b_sample.js

@@ -0,0 +1,117 @@
+/** Browser / Worker / Node: decode PCM WAV and encode Yamaha ADPCM-B.
+ * No AudioContext is created. Other formats can use an injected decodeAudio.
+ */
+export async function readSamplePCM(source, {signal, decodeAudio} = {}) {
+  signal?.throwIfAborted();
+  if (source?.channels) return source;
+  if (typeof source?.getChannelData === 'function') {
+    return {sampleRate: source.sampleRate, channels: Array.from(
+      {length: source.numberOfChannels}, (_, i) => source.getChannelData(i))};
+  }
+  if (typeof source === 'string' || source instanceof URL) {
+    const node = typeof process !== 'undefined' && process.versions?.node;
+    if (node && (source instanceof URL ? source.protocol === 'file:' :
+        !/^(https?:|data:|blob:)/i.test(source))) {
+      const {readFile} = await import('node:fs/promises');
+      source = await readFile(typeof source === 'string' && source.startsWith('file:') ? new URL(source) : source, {signal});
+    } else {
+      const response = await fetch(source, {signal});
+      if (!response.ok) throw new Error(`Sample: HTTP ${response.status}`);
+      source = await response.arrayBuffer();
+    }
+  }
+  if (typeof Blob !== 'undefined' && source instanceof Blob) source = await source.arrayBuffer();
+  signal?.throwIfAborted();
+  if (source instanceof Uint8Array) source = source.buffer.slice(source.byteOffset, source.byteOffset + source.byteLength);
+  if (!(source instanceof ArrayBuffer)) throw new TypeError('Expected decoded PCM, AudioBuffer, WAV bytes, Blob, path or URL');
+  const view = new DataView(source);
+  const text = (offset, length) => Array.from({length}, (_, i) => String.fromCharCode(view.getUint8(offset + i))).join('');
+  if (view.byteLength < 12 || text(0, 4) !== 'RIFF' || text(8, 4) !== 'WAVE') {
+    if (!decodeAudio) throw new TypeError('Expected PCM/Float RIFF WAV; other formats require decodeAudio');
+    return readSamplePCM(await decodeAudio(source), {signal});
+  }
+  const end = view.getUint32(4, true) + 8;
+  if (end > view.byteLength || end < 12) throw new RangeError('Truncated WAV');
+  let format, data;
+  for (let offset = 12; offset + 8 <= end;) {
+    const size = view.getUint32(offset + 4, true), start = offset + 8;
+    if (start + size > end) throw new RangeError('Truncated WAV chunk');
+    const tag = text(offset, 4);
+    if (tag === 'fmt ') {
+      if (size < 16) throw new RangeError('Invalid WAV format');
+      format = {type: view.getUint16(start, true), count: view.getUint16(start + 2, true),
+        sampleRate: view.getUint32(start + 4, true), block: view.getUint16(start + 12, true),
+        bits: view.getUint16(start + 14, true)};
+    } else if (tag === 'data' && !data) data = {start, size};
+    offset = start + size + (size & 1);
+  }
+  if (!format || !data) throw new TypeError('WAV requires fmt and data chunks');
+  const {type, count, sampleRate, block, bits} = format;
+  if (!((type === 1 && [8, 16, 24, 32].includes(bits)) || (type === 3 && [32, 64].includes(bits)))) {
+    if (decodeAudio) return readSamplePCM(await decodeAudio(source), {signal});
+    throw new TypeError('Supported WAV: PCM 8/16/24/32-bit or float 32/64-bit');
+  }
+  if (count < 1 || count > 32 || !sampleRate || block !== count * bits / 8 || data.size % block) throw new RangeError('Invalid WAV layout');
+  const frames = data.size / block;
+  const channels = Array.from({length: count}, () => new Float32Array(frames));
+  for (let i = 0; i < frames; i++) for (let channel = 0; channel < count; channel++) {
+    const offset = data.start + i * block + channel * bits / 8;
+    let value;
+    if (type === 3) value = bits === 32 ? view.getFloat32(offset, true) : view.getFloat64(offset, true);
+    else if (bits === 8) value = (view.getUint8(offset) - 128) / 128;
+    else if (bits === 16) value = view.getInt16(offset, true) / 32768;
+    else if (bits === 32) value = view.getInt32(offset, true) / 2147483648;
+    else {
+      let raw = view.getUint8(offset) | view.getUint8(offset + 1) << 8 | view.getUint8(offset + 2) << 16;
+      if (raw & 0x800000) raw -= 0x1000000;
+      value = raw / 8388608;
+    }
+    channels[channel][i] = value;
+  }
+  return {channels, sampleRate};
+}
+
+/** Greedy encoder matching ymfm ADPCM-B: high nibble first, signed 16-bit
+ * predictor, initial step 127 and Yamaha's multiplicative step adjustment.
+ * Linear interpolation handles rate conversion; pad with encoded silence to
+ * the chip's 32-byte addressing boundary (64 decoded frames).
+ */
+export function encodeAdpcmB({channels, sampleRate}, outputRate, maxBytes = 0x200000) {
+  if (!Array.isArray(channels) || !channels.length || channels.length > 32 ||
+      !Number.isFinite(sampleRate) || sampleRate <= 0 || !Number.isFinite(outputRate) || outputRate <= 0) throw new TypeError('Invalid PCM');
+  const length = channels[0]?.length;
+  if (!Number.isSafeInteger(length) || !length || channels.some(c => c.length !== length)) throw new RangeError('Invalid PCM channel lengths');
+  const frames = Math.max(1, Math.round(length * outputRate / sampleRate));
+  const byteLength = Math.ceil(frames / 64) * 32;
+  if (!Number.isSafeInteger(byteLength) || byteLength > maxBytes) throw new RangeError('Sample exceeds ADPCM-B memory');
+  const mono = new Float32Array(length);
+  for (let i = 0; i < length; i++) {
+    let value = 0;
+    for (const channel of channels) {
+      if (!Number.isFinite(channel[i])) throw new TypeError('Nonfinite PCM');
+      value += Math.max(-1, Math.min(1, channel[i])) / channels.length;
+    }
+    mono[i] = value;
+  }
+  const bytes = new Uint8Array(byteLength), scales = [57, 57, 57, 57, 77, 102, 128, 153];
+  let predictor = 0, step = 127;
+  for (let i = 0; i < byteLength * 2; i++) {
+    let target = 0;
+    if (i < frames) {
+      const position = Math.min(i * sampleRate / outputRate, length - 1);
+      const first = Math.floor(position), fraction = position - first;
+      const value = mono[first] * (1 - fraction) + mono[Math.min(first + 1, length - 1)] * fraction;
+      target = Math.round(value * (value < 0 ? 32768 : 32767));
+    }
+    let best = 0, bestValue = 0, error = Infinity;
+    for (let code = 0; code < 16; code++) {
+      const delta = Math.floor((2 * (code & 7) + 1) * step / 8) * (code & 8 ? -1 : 1);
+      const value = Math.max(-32768, Math.min(32767, predictor + delta));
+      if (Math.abs(value - target) < error) { best = code; bestValue = value; error = Math.abs(value - target); }
+    }
+    bytes[i >> 1] |= best << (i & 1 ? 0 : 4);
+    predictor = bestValue;
+    step = Math.max(127, Math.min(24576, Math.floor(step * scales[best & 7] / 64)));
+  }
+  return {bytes, frames, paddedFrames: byteLength * 2, sampleRate: outputRate};
+}

package/assets/opna-rhythm/README.md

@@ -86,7 +86,7 @@ CLI, pass the installed `dist/web/tetorica_ym2608_adpcm_rom.bin`
 path to `--ym2608-rom`. Version 0.2.1 predates this bundled asset.
 
 The YM2608 browser RuntimeSynth (including Playground) loads this synthetic
-ROM by default at startup. Select YM2608 and run `chip-saw/ym2608-rhythm.js` in
+ROM by default at startup. Select YM2608 and run `pc98/ym2608-rhythm.js` in
 Playground to hear all six voices. Browser API callers can override the default
 using `new YM2608RuntimeSynth({rhythmRom: bytes})` or `{rhythmRomUrl: url}`;
 after startup, `synth.fm.rhythm.loadRom(bytes)` replaces the loaded data.

package/opn_fm_synth.js

@@ -97,6 +97,37 @@ export class OPNWorkletTransport {
     this.node = node;
     this.portCount = portCount;
     this.chipName = chipName;
+    this.memorySequence = 0;
+    this.memoryRequests = new Map();
+    this.disposed = false;
+    this.onMemoryMessage = ({data}) => {
+      if (data?.type !== 'adpcm-memory-loaded') return;
+      const request = this.memoryRequests.get(data.id);
+      if (!request) return;
+      this.memoryRequests.delete(data.id);
+      data.error ? request.reject(new Error(data.error)) : request.resolve();
+    };
+    this.node.port.addEventListener?.('message', this.onMemoryMessage);
+    this.node.port.start?.();
+  }
+
+  loadAdpcmMemory(bytes, address = 0) {
+    if (this.disposed) return Promise.reject(new Error('ADPCM transport disposed'));
+    if (this.chipName !== 'YM2608') return Promise.reject(new Error('ADPCM memory upload requires YM2608'));
+    if (!(bytes instanceof Uint8Array) || !Number.isInteger(address) || address < 0 || address + bytes.length > 0x200000) return Promise.reject(new RangeError('Invalid ADPCM memory upload'));
+    const id = ++this.memorySequence;
+    return new Promise((resolve, reject) => {
+      this.memoryRequests.set(id, {resolve, reject});
+      try { this.node.port.postMessage({type: 'loadAdpcmMemory', id, bytes, address}); }
+      catch (error) { this.memoryRequests.delete(id); reject(error); }
+    });
+  }
+
+  dispose() {
+    this.disposed = true;
+    this.node.port.removeEventListener?.('message', this.onMemoryMessage);
+    for (const request of this.memoryRequests.values()) request.reject(new Error('ADPCM transport disposed'));
+    this.memoryRequests.clear();
   }
 
   reset() {

package/opn_runtime_synth.js

@@ -137,10 +137,13 @@ export class OPNRuntimeSynth {
   async #close() {
     this.audio.closeMedia();
     this.audio.disposeFXChain();
+    this.fm?.transport.dispose?.();
     this.node?.disconnect();
     this.node?.port.close();
     this.node = null;
     this.audio.disconnectRouting();
+    this.audio.masterInputNode = null;
+    this.audio.masterOutputNode = null;
     this.fm = null;
     this.readyPromise = null;
     this.state = "closed";

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "tetorica-fm2612",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Tetorica sound chip WASM cores, Synth helpers and browser audio runtime",
   "type": "module",
   "license": "BSD-3-Clause",
+  "homepage": "https://github.com/kyorohiro/tetorica-fm2612-examples",
   "engines": { "node": ">=22" },
   "repository": {
     "type": "git",

package/runtime-manifest.json

@@ -1,5 +1,6 @@
 {
   "modules": [
+    "adpcm_b_sample.js",
     "ay8910.js",
     "ay8910audioengine.js",
     "bitcrusher-worklet.js",

package/ym2608-worklet.js

@@ -18,6 +18,15 @@ class YM2608Processor extends AudioWorkletProcessor {
     const handle = data => {
       if (data.type === "initialize") void this.initialize(data.wasmBinary, data.rhythmRom);
       if (data.type === 'loadRhythmRom' && this.chip) this.chip.loadAdpcmARom(data.bytes);
+      if (data.type === 'loadAdpcmMemory') {
+        try {
+          if (!this.chip) throw new Error('YM2608 is not ready');
+          this.chip.loadAdpcmBMemory(data.bytes, data.address);
+          this.port.postMessage({type: 'adpcm-memory-loaded', id: data.id});
+        } catch (error) {
+          this.port.postMessage({type: 'adpcm-memory-loaded', id: data.id, error: String(error.message ?? error)});
+        }
+      }
       if (data.type === "write" && this.chip) this.write(data.port, data.register, data.value);
       if (data.type === "reset") this.chip?.reset();
     };

package/ym2608synth.js

@@ -8,6 +8,7 @@ import { OPNDirectTransport, OPNFMSynth } from "./opn_fm_synth.js";
 import { OPNRuntimeSynth } from "./opn_runtime_synth.js";
 import { SSGSynth } from "./ssgsynth.js?v=ssg-period-1";
 import { YM2608_CLOCK } from "./ym2608.js";
+import {readSamplePCM, encodeAdpcmB} from './adpcm_b_sample.js';
 
 /** Direct transport for YM2608 register operations. */
 export class YM2608DirectTransport extends OPNDirectTransport {
@@ -97,7 +98,7 @@ const adpcmInteger = (name, value, max) => {
 };
 
 /** YM2608 ADPCM-B external-memory playback, using 8-bit DRAM addressing (32-byte units).
- * Browser / Worker / Node.js: no file decoding, audio output or memory ownership here.
+ * Browser / Worker / Node.js. loadSample decodes PCM WAV without an audio device.
  */
 export class YM2608AdpcmSynth {
   /** @param {{write: function(number, number): void, loadMemory: function(Uint8Array, number): void}} transport
@@ -133,6 +134,33 @@ export class YM2608AdpcmSynth {
     if (bytes.length > 0x200000 - address) throw new RangeError("ADPCM-B memory exceeds 2 MiB");
     return this.transport.loadMemory(bytes, address);
   }
+  /** Decode PCM/AudioBuffer/WAV, mix to mono, encode ADPCM-B and select it.
+   * Does not start playback. The caller owns memory allocation: repeated calls
+   * at the same address replace the data. Range padding may add up to 63 frames.
+   * @param {*} source Decoded {channels, sampleRate}, AudioBuffer, WAV bytes, Blob or path/URL.
+   * @param {{address?: number, sampleRate?: number, signal?: AbortSignal, decodeAudio?: Function}} options
+   * @returns {Promise<{start:number,end:number,frames:number,paddedFrames:number,sampleRate:number,deltaN:number,duration:number}>}
+   */
+  async loadSample(source, {address = 0, sampleRate, signal, decodeAudio} = {}) {
+    adpcmInteger('address', address, 0x1fffff);
+    if (address % 32) throw new RangeError('ADPCM-B address must be 32-byte aligned');
+    const pcm = await readSamplePCM(source, {signal, decodeAudio});
+    const requested = sampleRate ?? Math.min(pcm.sampleRate, Math.floor(this.clock / 144));
+    if (!Number.isFinite(requested) || requested <= 0) throw new RangeError('Invalid ADPCM-B sample rate');
+    const deltaN = Math.round(requested * 144 * 65536 / this.clock);
+    if (deltaN < 1 || deltaN > 65535) throw new RangeError('ADPCM-B sample rate is outside the chip range');
+    const actualRate = deltaN * this.clock / (144 * 65536);
+    const encoded = encodeAdpcmB(pcm, actualRate, 0x200000 - address);
+    signal?.throwIfAborted();
+    this.keyOff();
+    await this.loadMemory(encoded.bytes, address);
+    signal?.throwIfAborted();
+    this.setSample({start: address, end: address + encoded.bytes.length});
+    this.setDeltaN(deltaN);
+    return {start: address, end: address + encoded.bytes.length, frames: encoded.frames,
+      paddedFrames: encoded.paddedFrames, sampleRate: actualRate, deltaN,
+      duration: encoded.paddedFrames / actualRate};
+  }
   /** Configure a byte range [start, end). Both boundaries must be 32-byte aligned.
    * Selects 8-bit DRAM mode and the full 2 MiB address limit; call while stopped.
    * @param {{start: number, end: number}} range End is exclusive, unlike the hardware register.