zx-kit 0.35.0 → 0.37.0

package/dist/aydump.d.ts

@@ -0,0 +1,291 @@
+/**
+ * @module aydump
+ *
+ * **Sample-accurate AY register-dump player** — the "sample-accurate
+ * AudioWorklet backend" that {@link "ay" | ay.ts} promises on its roadmap.
+ * Where `ay.ts` *synthesises* notes (`AYNote[]` → band-limited oscillators),
+ * this module *reproduces the hardware*: it feeds a cycle-level emulation of
+ * the AY-3-8910 / YM2149 chip a stream of register writes (a **PSG dump**) and
+ * renders real PCM — so you can play **actual ZX-scene tunes** in a game.
+ *
+ * The pipeline is data-driven, exactly like a bitmap font:
+ *
+ * ```
+ *   .psg file (register dump, bundled as data)
+ *        │  parsePSG()
+ *        ▼
+ *   AYDump  (flat typed-array frames: who-writes-what-when)
+ *        │  AYDumpPlayer  (applies each frame's writes every sampleRate/50 samples)
+ *        ▼
+ *   AYChipCore  (16 registers → L/R PCM, HW logic from the datasheet)
+ *        │  playAYDump()  (realtime AudioWorklet)  or  renderAYDump() (offline)
+ *        ▼
+ *   master GainNode (shared with audio.ts / ay.ts — global M mute works for free)
+ * ```
+ *
+ * **Scope:** v1 is the **PSG** format (a raw register dump — HW-level, unambiguous,
+ * dependency-free). Anything from zxart.ee (PT3, STC…) is converted to `.psg`
+ * **offline** on a PC (Ay_Emul "save as PSG", `zxtune123 --convert`, Vortex
+ * Tracker II). The dump is *data*, not a code dependency — Zero Dependencies stays
+ * clean. A native PT3 replay routine over the same {@link AYChipCore} is a future
+ * (v2) module.
+ *
+ * **Authorship:** a PSG dump is a derivative of the original tune. zxart hosting is
+ * not a licence — ship a track only with the composer's permission (credit + link).
+ *
+ * @see {@link "ay" | ay.ts} for note-based music, {@link "audio" | audio.ts} for the beeper.
+ */
+import type { AYStereoMode } from './ay.js';
+/** Chip variant: `ay` = 16-step envelope; `ym` = 32-step envelope (finer). */
+export type AYChipVariant = 'ay' | 'ym';
+/** How to configure the emulated chip. All fields optional — see defaults below. */
+export interface AYChipConfig {
+    /** Chip clock in Hz. Default `1_773_400` (ZX 128K). Melodik = `1_750_000`. */
+    clockHz?: number;
+    /** Chip variant. Default `'ay'`. */
+    variant?: AYChipVariant;
+    /** Stereo preset. Default `'acb'` (Melodik jack: A left, C centre, B right). */
+    stereo?: AYStereoMode;
+    /** 16-entry DAC table (level → amplitude). Default zx-kit `AY_VOL`; hook for measured tables. */
+    dacTable?: readonly number[];
+}
+/** Ready-made presets for real machines. */
+export declare const AY_MACHINE: {
+    /** ZX Spectrum 128K / +2 / +3 — TV speaker, mono. */
+    readonly zx128: {
+        readonly clockHz: 1773400;
+        readonly variant: "ay";
+        readonly stereo: "mono";
+    };
+    /** Didaktik + Melodik add-on — 1.75 MHz, ACB stereo jack. */
+    readonly melodik: {
+        readonly clockHz: 1750000;
+        readonly variant: "ay";
+        readonly stereo: "acb";
+    };
+    /** Pentagon clone — 1.75 MHz, ACB. */
+    readonly pentagon: {
+        readonly clockHz: 1750000;
+        readonly variant: "ay";
+        readonly stereo: "acb";
+    };
+    /** Atari ST — YM2149 at 2 MHz, mono. */
+    readonly atariST: {
+        readonly clockHz: 2000000;
+        readonly variant: "ym";
+        readonly stereo: "mono";
+    };
+};
+/**
+ * Cycle-level AY-3-8910 / YM2149 emulator: register writes in, PCM samples out.
+ * Three square-wave tone channels, a shared 17-bit LFSR noise generator, and the
+ * hardware envelope generator (16 or 32 steps). Pure and self-contained so it runs
+ * inside an AudioWorklet **and** in a headless test with no `AudioContext`.
+ *
+ * Named `AYChipCore` (not `AYChip`) so it does not collide with the real-time
+ * {@link "ay".AYChip} handle interface exported from `ay.ts`.
+ */
+export declare class AYChipCore {
+    private readonly envSteps;
+    private readonly dac;
+    private readonly regs;
+    private readonly toneCnt;
+    private readonly toneOut;
+    private noiseCnt;
+    private lfsr;
+    private noiseOut;
+    private envCnt;
+    private envPos;
+    private envAttack;
+    private envHolding;
+    private envCont;
+    private envAlt;
+    private envHold;
+    private cycleAcc;
+    private readonly cyclesPerSample;
+    private panL;
+    private panR;
+    private dcxL;
+    private dcyL;
+    private dcxR;
+    private dcyR;
+    /**
+     * @param sampleRate Output sample rate (Hz).
+     * @param clockHz    Chip master clock (Hz).
+     * @param envSteps   Envelope resolution: 16 (AY) or 32 (YM).
+     * @param dac        16-entry DAC amplitude table (level → 0..1).
+     * @param stereo     Stereo preset (mono / abc / acb).
+     */
+    constructor(sampleRate: number, clockHz: number, envSteps: number, dac: readonly number[], stereo: AYStereoMode);
+    /** Clears counters, registers, LFSR, envelope and DC state. Call at start / seek. */
+    reset(): void;
+    /**
+     * Applies a demoscene stereo preset. Soft panning (0.75/0.25), so headphones
+     * don't get a hard 1/0 split; L+R gain per channel always sums to 1.
+     */
+    setStereo(mode: AYStereoMode): void;
+    /**
+     * Writes a chip register (0..15), masking to the hardware register width.
+     * Writing R13 (envelope shape) always restarts the envelope.
+     */
+    setRegister(r: number, v: number): void;
+    /** Steps the 17-bit LFSR once (feedback = bit0 XOR bit3) and latches the output bit. */
+    private stepNoise;
+    /** Advances the envelope generator by one step (called when its counter elapses). */
+    private envStep;
+    /** Current envelope amplitude as a DAC index (0..15). */
+    private envLevel;
+    /**
+     * Renders `count` stereo samples into `left`/`right` starting at `offset`.
+     * Box-filters the chip's raw ticks within each output sample (a cheap
+     * anti-alias), then DC-blocks each output channel.
+     */
+    renderInto(left: Float32Array, right: Float32Array, offset: number, count: number): void;
+    /**
+     * @internal Test hook — steps the LFSR `n` times, returning each output bit.
+     * Locks the noise sequence against a tap/shift typo (see stepNoise).
+     */
+    _stepNoiseForTest(n: number): number[];
+    /**
+     * @internal Test hook — advances the envelope generator `n` times (after an R13
+     * write), returning the amplitude level (0..15) after each step.
+     */
+    _stepEnvelopeForTest(n: number): number[];
+}
+/**
+ * A parsed PSG register dump — flat typed arrays so it transfers into the
+ * AudioWorklet with zero copying and allocates nothing on the audio thread.
+ * Frame `f`'s writes are `writeRegs[frameOffsets[f] .. frameOffsets[f+1])`.
+ */
+export interface AYDump {
+    /** Frame rate (PSG = 50 Hz). */
+    frameRateHz: number;
+    /** Number of frames. */
+    frameCount: number;
+    /** Register index (0..15) per write, all frames concatenated. */
+    writeRegs: Uint8Array;
+    /** Value per write, parallel to {@link writeRegs}. */
+    writeVals: Uint8Array;
+    /** Length `frameCount + 1`; last element = `writeRegs.length`. */
+    frameOffsets: Uint32Array;
+}
+/**
+ * Parses a PSG register dump (the format Ay_Emul / zxtune produce) into an
+ * {@link AYDump}. A PSG file is a `"PSG\x1a"` header then a byte stream:
+ *
+ * - `0xFF`        — start a new frame
+ * - `0xFE n`      — `n × 4` empty frames (chip holds its state)
+ * - `0xFD`        — end of song (often absent: end-of-data ends the song)
+ * - `0x00..0x0F`  — register index; the next byte is its value
+ * - `0x10..0xFC`  — foreign device (MSX / 2nd chip) → skip this byte and the next
+ *
+ * @throws if the header is wrong or a register/`0xFE` pair is truncated.
+ */
+export declare function parsePSG(bytes: Uint8Array): AYDump;
+/**
+ * Drives an {@link AYChipCore} from an {@link AYDump}: applies each frame's
+ * register writes on the right sample and fills PCM buffers. Uses a *fractional*
+ * samples-per-frame accumulator so a 3-minute tune doesn't drift at exotic rates.
+ * Pure — testable with a spy chip, runnable inside the worklet.
+ */
+export declare class AYDumpPlayer {
+    private readonly chip;
+    private readonly writeRegs;
+    private readonly writeVals;
+    private readonly frameOffsets;
+    private readonly loop;
+    private readonly loopFrame;
+    private readonly frameCount;
+    private readonly samplesPerFrame;
+    private frame;
+    private frameAcc;
+    private ended;
+    /**
+     * @param chip         The chip to drive.
+     * @param writeRegs    Concatenated register indices (see {@link AYDump}).
+     * @param writeVals    Concatenated values.
+     * @param frameOffsets Frame boundaries (length `frameCount + 1`).
+     * @param frameRateHz  Frames per second (PSG = 50).
+     * @param sampleRate   Output sample rate (Hz).
+     * @param loop         Restart at `loopFrame` after the last frame.
+     * @param loopFrame    Frame to jump to when looping.
+     */
+    constructor(chip: AYChipCore, writeRegs: Uint8Array, writeVals: Uint8Array, frameOffsets: Uint32Array, frameRateHz: number, sampleRate: number, loop: boolean, loopFrame: number);
+    private applyFrame;
+    /** Fills `left`/`right` completely. Returns `true` once the (non-looping) song has ended. */
+    render(left: Float32Array, right: Float32Array): boolean;
+    /** Fast-forwards to frame `f` by replaying its register writes without rendering. */
+    seekToFrame(f: number): void;
+}
+/** Live handle to a {@link playAYDump} call. */
+export interface AYDumpHandle {
+    /** Detach the node and stop playback (irreversible). */
+    stop(): void;
+    /** Silence via the gain node (the worklet keeps running) — instant. */
+    pause(): void;
+    /** Restore the pre-pause volume. */
+    resume(): void;
+    /** Per-track volume, 0..1 (master volume stays with audio.ts). */
+    setVolume(v: number): void;
+    /** Change the stereo preset live. */
+    setStereo(mode: AYStereoMode): void;
+    /** `true` while the node is connected and not stopped. */
+    readonly playing: boolean;
+    /** Called once when a non-looping song finishes. */
+    onEnded?: () => void;
+}
+/** Options for {@link playAYDump}. */
+export interface PlayAYDumpOptions extends AYChipConfig {
+    /** Loop at `loopFrame` after the last frame. Default `false`. */
+    loop?: boolean;
+    /** Frame to loop back to. Default `0`. */
+    loopFrame?: number;
+    /** Initial per-track volume 0..1. Default `1`. */
+    volume?: number;
+}
+/**
+ * Assembles the AudioWorklet source: the two worklet-safe classes stringified,
+ * plus a processor that loads a dump and renders it. The class names are read via
+ * `.name` (not hardcoded) so the glue stays consistent even if a bundler mangles
+ * them — {@link AYChipCore}.name and its `toString()` agree under minification.
+ *
+ * Internal; exported only so a test can assert the source is self-contained.
+ */
+export declare function _buildAYDumpWorkletSource(): string;
+/**
+ * Plays a parsed {@link AYDump} in real time through an AudioWorklet, routed to the
+ * shared master gain (so global `M` mute / `setMasterVolume` apply for free).
+ * Call after {@link initAudio} inside a user gesture — same contract as `playAY`.
+ *
+ * @example
+ * const dump = await loadPSG('./music/tune.psg')
+ * const track = await playAYDump(dump, { loop: true, ...AY_MACHINE.melodik })
+ * // later: track.setVolume(0.6); track.stop()
+ */
+export declare function playAYDump(dump: AYDump, opts?: PlayAYDumpOptions): Promise<AYDumpHandle>;
+/** Options for {@link renderAYDump}. */
+export interface RenderAYDumpOptions extends AYChipConfig {
+    /** Output sample rate. Default `44100`. */
+    sampleRate?: number;
+    /** Cap the render length in seconds. Default = the whole song. */
+    maxSeconds?: number;
+}
+/**
+ * Renders a dump to stereo PCM **without an AudioContext** — deterministic, for
+ * unit tests, `AudioWorklet`-less fallbacks, and offline tooling (e.g. PSG → WAV).
+ * Beware RAM: a full 3-minute stereo render at 44.1 kHz is ≈ 64 MB — pass
+ * `maxSeconds` to bound it.
+ */
+export declare function renderAYDump(dump: AYDump, opts?: RenderAYDumpOptions): {
+    left: Float32Array;
+    right: Float32Array;
+};
+/**
+ * Fetches a `.psg` file and parses it into an {@link AYDump}. Network / parse
+ * errors propagate so the game decides how to handle them.
+ *
+ * @example
+ * const dump = await loadPSG('./music/tune.psg')
+ */
+export declare function loadPSG(url: string): Promise<AYDump>;
+//# sourceMappingURL=aydump.d.ts.map

package/dist/aydump.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aydump.d.ts","sourceRoot":"","sources":["../src/aydump.ts"],"names":[],"mappings":"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"}