sci2-ts 0.0.0-stage → 0.2.2

package/packages/sci/src/audio/midi.ts

@@ -0,0 +1,262 @@
+/**
+ * SCI1.1/SCI2 sound resources and a sequencer for them.
+ *
+ * Resource layout:
+ *   [0xF0 priority, 6 unused]         optional 8-byte header
+ *   tracks until 0xFF:  u8 device, then 6-byte channel entries until 0xFF:
+ *                       u16 unused, u16 offset, u16 size
+ * Devices: 0x00 AdLib, 0x07 General MIDI, 0x0C MT-32 (plus a few others).
+ * Each channel stream: u8 channel (low nibble = MIDI channel), u8 priority/voices,
+ * then [delta][event]... where delta bytes of 0xF8 each add 240 ticks (1/60 s), and
+ * events are MIDI messages with running status. 0xFC ends the stream.
+ *
+ * Channel 15 is Sierra's control channel: program change N sets the sound object's
+ * signal to N (127 marks the loop point instead), controller 0x60 is a "cue".
+ */
+export const SoundDevice = { AdLib: 0x00, GeneralMidi: 0x07, Mt32: 0x0c } as const;
+
+const CONTROL_CHANNEL = 15;
+const LOOP_MARKER = 127;
+const CUE_CONTROLLER = 0x60;
+
+export interface MidiEvent {
+  tick: number;
+  /** Raw MIDI bytes, e.g. [0x91, 60, 100]. */
+  bytes: number[];
+}
+
+export interface SongChannel {
+  midiChannel: number;
+  /** Voices this channel wants from a voice-limited device (AdLib: 9 in total). */
+  voices: number;
+}
+
+export interface Song {
+  priority: number;
+  channels: SongChannel[];
+  /** All channels merged, sorted by tick. */
+  events: MidiEvent[];
+  /** Tick where the last event ends. */
+  length: number;
+}
+
+const dataBytes = (status: number) => ((status & 0xf0) === 0xc0 || (status & 0xf0) === 0xd0 ? 1 : 2);
+
+function readChannel(data: Uint8Array, start: number, end: number, midiChannel: number, out: MidiEvent[]): number {
+  let pos = start;
+  let tick = 0;
+  let running = 0;
+  while (pos < end) {
+    // Delta time.
+    let b = data[pos++]!;
+    while (b === 0xf8 && pos < end) {
+      tick += 240;
+      b = data[pos++]!;
+    }
+    tick += b;
+    if (pos >= end) break;
+
+    let status = data[pos]!;
+    if (status === 0xfc) break; // end of stream
+    if (status & 0x80) pos++;
+    else status = running; // running status: this byte is data
+    if (status === 0xf0) {
+      while (pos < end && data[pos] !== 0xf7) pos++; // skip sysex
+      pos++;
+      continue;
+    }
+    if (status === 0xff) {
+      pos += 1; // meta type
+      const len = data[pos++]!;
+      pos += len;
+      continue;
+    }
+    if (status < 0x80) break; // corrupt stream
+    running = status;
+    const n = dataBytes(status);
+    const bytes = [(status & 0xf0) | midiChannel];
+    for (let i = 0; i < n; i++) bytes.push(data[pos++]! & 0x7f);
+    out.push({ tick, bytes });
+  }
+  return tick;
+}
+
+/** Parses the track for `device` (falling back to MT-32, then any), merging its channels. */
+export function parseSound(data: Uint8Array, device: number = SoundDevice.GeneralMidi): Song | undefined {
+  const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  let pos = 0;
+  let priority = 0;
+  if (data[0] === 0xf0) {
+    priority = data[1]!;
+    pos = 8;
+  }
+  const tracks = new Map<number, { offset: number; size: number }[]>();
+  while (pos < data.length && data[pos] !== 0xff) {
+    const type = data[pos++]!;
+    const channels: { offset: number; size: number }[] = [];
+    while (pos + 6 <= data.length && data[pos] !== 0xff) {
+      channels.push({ offset: v.getUint16(pos + 2, true), size: v.getUint16(pos + 4, true) });
+      pos += 6;
+    }
+    pos++;
+    tracks.set(type, channels);
+  }
+  const channels = tracks.get(device) ?? tracks.get(SoundDevice.Mt32);
+  if (!channels?.length) return undefined;
+
+  const events: MidiEvent[] = [];
+  const songChannels: SongChannel[] = [];
+  let length = 0;
+  for (const { offset, size } of channels) {
+    if (!size || offset + 2 > data.length) continue;
+    const midiChannel = data[offset]! & 0x0f;
+    if (midiChannel !== CONTROL_CHANNEL) songChannels.push({ midiChannel, voices: data[offset + 1]! & 0x0f });
+    length = Math.max(length, readChannel(data, offset + 2, Math.min(data.length, offset + size), midiChannel, events));
+  }
+  // Stable sort keeps each channel's order for events on the same tick.
+  events.sort((a, b) => a.tick - b.tick);
+  return { priority, channels: songChannels, events, length };
+}
+
+/** Where MIDI bytes go: a SoundFont synth or the AdLib driver. */
+export interface MidiOutput {
+  send(bytes: number[]): void;
+  /** Voice-limited devices: a song claims (or, with a negative count, releases) voices. */
+  claimVoices?(channel: number, count: number): void;
+  setMasterVolume?(volume: number): void;
+}
+
+/** Signal values scripts see on the sound object. */
+export const SongSignal = { Finished: 0xffff } as const;
+
+/**
+ * Plays one song against a tick clock. Tracks the control channel so the kernel can
+ * report cues/signals, loops at the loop marker, and silences its notes when stopped.
+ */
+export class SongPlayer {
+  private index = 0;
+  private startTick = 0;
+  private loopIndex = 0;
+  private loopTick = 0;
+  private readonly held = new Set<number>(); // channel << 8 | note
+  /** Last channel volume (CC 7) the song asked for, to rescale on volume changes. */
+  private readonly channelVolume = new Map<number, number>();
+  finished = false;
+  /** Latest control-channel signal not yet reported (0 = none). */
+  signal = 0;
+  dataInc = 0;
+  private paused: number | undefined;
+
+  constructor(
+    readonly song: Song,
+    private readonly output: MidiOutput | undefined,
+    public loop: boolean,
+    public volume: number, // 0..127
+    now: number,
+  ) {
+    this.startTick = now;
+    for (const c of song.channels) output?.claimVoices?.(c.midiChannel, c.voices);
+  }
+
+  /** Sends every event due by tick `now`. */
+  update(now: number): void {
+    if (this.finished || this.paused !== undefined) return;
+    const pos = now - this.startTick;
+    const events = this.song.events;
+    while (this.index < events.length && events[this.index]!.tick <= pos) {
+      this.dispatch(events[this.index]!, this.index);
+      this.index++;
+    }
+    if (this.index >= events.length && pos >= this.song.length) {
+      if (this.loop) {
+        this.silence();
+        this.index = this.loopIndex;
+        this.startTick = now - this.loopTick;
+      } else {
+        this.stop();
+        this.finished = true;
+        this.signal = SongSignal.Finished;
+      }
+    }
+  }
+
+  private dispatch(e: MidiEvent, index: number): void {
+    const [status = 0, a = 0, b = 0] = e.bytes;
+    const channel = status & 0x0f;
+    const type = status & 0xf0;
+    if (channel === CONTROL_CHANNEL) {
+      if (type === 0xc0) {
+        if (a === LOOP_MARKER) {
+          this.loopIndex = index + 1;
+          this.loopTick = e.tick;
+        } else if (e.tick > 0) this.signal = a;
+      } else if (type === 0xb0 && a === CUE_CONTROLLER) {
+        this.dataInc++;
+        this.signal = this.dataInc + 127;
+      }
+      return;
+    }
+    if (type === 0x90 && b > 0) this.held.add((channel << 8) | a);
+    else if (type === 0x80 || type === 0x90) this.held.delete((channel << 8) | a);
+    // Scale channel volume by the sound object's volume.
+    if (type === 0xb0 && a === 7) {
+      this.channelVolume.set(channel, b);
+      return this.output?.send([status, a, Math.round((b * this.volume) / 127)]);
+    }
+    this.output?.send(e.bytes);
+  }
+
+  /** Releases every note this song is holding. */
+  private silence(): void {
+    for (const key of this.held) this.output?.send([0x80 | (key >> 8), key & 0xff, 0]);
+    this.held.clear();
+  }
+
+  private released = false;
+
+  stop(): void {
+    this.silence();
+    if (this.released) return;
+    this.released = true;
+    for (const c of this.song.channels) this.output?.claimVoices?.(c.midiChannel, -c.voices);
+  }
+
+  /** Position in ticks. */
+  position(now: number): number {
+    return (this.paused ?? now) - this.startTick;
+  }
+
+  /**
+   * Jumps to `pos` ticks without sounding notes: replays program, controller and pitch
+   * events so the (possibly new) output is in the right state. Used when switching devices.
+   */
+  seek(pos: number, now: number): void {
+    const events = this.song.events;
+    this.index = 0;
+    while (this.index < events.length && events[this.index]!.tick <= pos) {
+      const e = events[this.index]!;
+      const type = e.bytes[0]! & 0xf0;
+      if (type !== 0x90 && type !== 0x80) this.dispatch(e, this.index);
+      this.index++;
+    }
+    this.signal = 0;
+    this.startTick = now - pos;
+  }
+
+  pause(now: number): void {
+    if (this.paused !== undefined) return;
+    this.paused = now;
+    this.silence();
+  }
+
+  resume(now: number): void {
+    if (this.paused === undefined) return;
+    this.startTick += now - this.paused;
+    this.paused = undefined;
+  }
+
+  setVolume(volume: number): void {
+    this.volume = volume;
+    for (const [channel, v] of this.channelVolume) this.output?.send([0xb0 | channel, 7, Math.round((v * volume) / 127)]);
+  }
+}

package/packages/sci/src/audio/opl2.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Yamaha YM3812 (OPL2) FM synthesizer: the chip on AdLib and Sound Blaster cards.
+ *
+ * 9 channels, each with two operators: a *modulator* and a *carrier*. Each operator is a
+ * sine-ish oscillator with its own envelope. In FM mode the modulator's output bends the
+ * carrier's phase (that's where the metallic/brassy timbres come from); in additive mode
+ * both are simply mixed. Sound is shaped entirely through register writes, exactly as the
+ * game's AdLib driver did it in 1994.
+ *
+ * This is a behavioural model, not a gate-level one: it follows the documented register
+ * layout and datasheet timings (log-domain attenuation in 0.1875 dB steps, a 10-bit sine
+ * table, exponential attack, linear-in-dB decay) closely enough to sound like the chip.
+ */
+export declare const OPL_RATE = 49716;
+declare enum Env {
+    Attack = 0,
+    Decay = 1,
+    Sustain = 2,
+    Release = 3,
+    Off = 4
+}
+declare class Operator {
+    am: boolean;
+    vib: boolean;
+    sustained: boolean;
+    ksr: boolean;
+    mult: number;
+    ksl: number;
+    tl: number;
+    ar: number;
+    dr: number;
+    sl: number;
+    rr: number;
+    wave: number;
+    phase: number;
+    inc: number;
+    att: number;
+    state: Env;
+    kslAtt: number;
+    keyCode: number;
+    attackK: number;
+    decayStep: number;
+    releaseStep: number;
+    private effectiveRate;
+    updateRates(): void;
+    get sustainLevel(): number;
+    keyOn(): void;
+    keyOff(): void;
+    stepEnvelope(): void;
+    /** Output in -1..1 for a phase offset (modulation) in cycles. */
+    output(mod: number, tremolo: number, waveEnabled: boolean): number;
+}
+declare class Channel {
+    readonly ops: readonly [Operator, Operator];
+    fnum: number;
+    block: number;
+    keyOn: boolean;
+    feedback: number;
+    additive: boolean;
+    fb1: number;
+    fb2: number;
+    updatePitch(): void;
+}
+export declare class Opl2 {
+    readonly channels: Channel[];
+    private waveSelect;
+    private deepTremolo;
+    private deepVibrato;
+    private lfoTime;
+    write(reg: number, value: number): void;
+    /** Renders `count` mono samples at OPL_RATE into `out` starting at `offset`. */
+    generate(out: Float32Array, offset?: number, count?: number): void;
+}
+export {};

package/packages/sci/src/audio/opl2.js

@@ -0,0 +1,283 @@
+/**
+ * Yamaha YM3812 (OPL2) FM synthesizer: the chip on AdLib and Sound Blaster cards.
+ *
+ * 9 channels, each with two operators: a *modulator* and a *carrier*. Each operator is a
+ * sine-ish oscillator with its own envelope. In FM mode the modulator's output bends the
+ * carrier's phase (that's where the metallic/brassy timbres come from); in additive mode
+ * both are simply mixed. Sound is shaped entirely through register writes, exactly as the
+ * game's AdLib driver did it in 1994.
+ *
+ * This is a behavioural model, not a gate-level one: it follows the documented register
+ * layout and datasheet timings (log-domain attenuation in 0.1875 dB steps, a 10-bit sine
+ * table, exponential attack, linear-in-dB decay) closely enough to sound like the chip.
+ */
+export const OPL_RATE = 49716; // 3.579545 MHz / 72
+const MULT = [0.5, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 10, 12, 12, 15, 15];
+const KSL_ROM = [0, 32, 40, 45, 48, 51, 53, 55, 56, 58, 59, 60, 61, 62, 63, 64];
+const KSL_SHIFT = [8, 1, 2, 0];
+/** Attenuation units are 0.1875 dB; 511 units ≈ 96 dB = silence. */
+const ATT_MAX = 511;
+const ATT_DB = 0.1875;
+const SINE = new Float32Array(1024).map((_, i) => Math.sin(((i + 0.5) / 1024) * 2 * Math.PI));
+const AMPLITUDE = new Float32Array(2048).map((_, u) => Math.pow(10, (-u * ATT_DB) / 20));
+/** OPL2 waveforms: sine, half-sine, abs-sine, and "quarter" pulses of abs-sine. */
+function wave(form, phase) {
+    const i = Math.floor(phase * 1024) & 1023;
+    const s = SINE[i];
+    switch (form) {
+        case 1: return s > 0 ? s : 0;
+        case 2: return Math.abs(s);
+        case 3: return (i & 256) === 0 ? Math.abs(s) : 0;
+        default: return s;
+    }
+}
+var Env;
+(function (Env) {
+    Env[Env["Attack"] = 0] = "Attack";
+    Env[Env["Decay"] = 1] = "Decay";
+    Env[Env["Sustain"] = 2] = "Sustain";
+    Env[Env["Release"] = 3] = "Release";
+    Env[Env["Off"] = 4] = "Off";
+})(Env || (Env = {}));
+/** Datasheet timings (ms) for the slowest rate (effective rate 4); each +4 halves them. */
+const ATTACK_MS = 2826.24;
+const DECAY_MS = 39280.64;
+function rateTime(baseMs, rate) {
+    if (rate < 4)
+        return Infinity;
+    const r = Math.min(rate, 60);
+    return (baseMs * 4) / ((4 + (r & 3)) * Math.pow(2, (r >> 2) - 1));
+}
+class Operator {
+    // Registers
+    am = false;
+    vib = false;
+    sustained = false; // EG type: hold at sustain level until key-off
+    ksr = false;
+    mult = 1;
+    ksl = 0;
+    tl = 0;
+    ar = 0;
+    dr = 0;
+    sl = 0;
+    rr = 0;
+    wave = 0;
+    // State
+    phase = 0; // in cycles, 0..1
+    inc = 0; // cycles per sample
+    att = ATT_MAX; // envelope attenuation, units of 0.1875 dB
+    state = Env.Off;
+    kslAtt = 0;
+    keyCode = 0; // (block << 1) | fnum bit 9, for rate key scaling
+    // Per-sample envelope steps, recomputed when rates or pitch change.
+    attackK = 0;
+    decayStep = 0;
+    releaseStep = 0;
+    effectiveRate(r) {
+        return r === 0 ? 0 : Math.min(63, r * 4 + (this.ksr ? this.keyCode : this.keyCode >> 2));
+    }
+    updateRates() {
+        const at = rateTime(ATTACK_MS, this.effectiveRate(this.ar));
+        // Exponential attack: reach ~0 attenuation from full in `at`.
+        this.attackK = this.effectiveRate(this.ar) >= 60 ? 1 : at === Infinity ? 0 : 1 - Math.pow(1 / 512, 1000 / (at * OPL_RATE));
+        const step = (rate) => {
+            const t = rateTime(DECAY_MS, this.effectiveRate(rate));
+            return t === Infinity ? 0 : (ATT_MAX * 1000) / (t * OPL_RATE);
+        };
+        this.decayStep = step(this.dr);
+        this.releaseStep = step(this.rr);
+    }
+    get sustainLevel() {
+        return (this.sl === 15 ? 31 : this.sl) * 16; // 3 dB steps; 15 means 93 dB
+    }
+    keyOn() {
+        this.phase = 0;
+        this.state = Env.Attack;
+    }
+    keyOff() {
+        if (this.state !== Env.Off)
+            this.state = Env.Release;
+    }
+    stepEnvelope() {
+        switch (this.state) {
+            case Env.Attack:
+                this.att -= (this.att + 1) * this.attackK;
+                if (this.att <= 0) {
+                    this.att = 0;
+                    this.state = Env.Decay;
+                }
+                break;
+            case Env.Decay:
+                this.att += this.decayStep;
+                if (this.att >= this.sustainLevel) {
+                    this.att = this.sustainLevel;
+                    this.state = Env.Sustain;
+                }
+                break;
+            case Env.Sustain:
+                // Percussive envelopes (EG type 0) keep falling at the release rate.
+                if (!this.sustained)
+                    this.att += this.releaseStep;
+                break;
+            case Env.Release:
+                this.att += this.releaseStep;
+                break;
+        }
+        if (this.att >= ATT_MAX && this.state !== Env.Attack) {
+            this.att = ATT_MAX;
+            if (this.state === Env.Release || this.state === Env.Sustain)
+                this.state = Env.Off;
+        }
+    }
+    /** Output in -1..1 for a phase offset (modulation) in cycles. */
+    output(mod, tremolo, waveEnabled) {
+        if (this.state === Env.Off)
+            return 0;
+        const att = this.att + this.tl * 4 + this.kslAtt + (this.am ? tremolo : 0);
+        if (att >= ATT_MAX)
+            return 0;
+        return wave(waveEnabled ? this.wave : 0, this.phase + mod) * AMPLITUDE[att | 0];
+    }
+}
+class Channel {
+    ops = [new Operator(), new Operator()];
+    fnum = 0;
+    block = 0;
+    keyOn = false;
+    feedback = 0;
+    additive = false;
+    fb1 = 0;
+    fb2 = 0;
+    updatePitch() {
+        const keyCode = (this.block << 1) | ((this.fnum >> 9) & 1);
+        const kslBase = Math.max(0, KSL_ROM[this.fnum >> 6] * 4 - (8 - this.block) * 32);
+        for (const op of this.ops) {
+            op.inc = (this.fnum * Math.pow(2, this.block) * MULT[op.mult]) / (1 << 20);
+            op.keyCode = keyCode;
+            op.kslAtt = kslBase >> KSL_SHIFT[op.ksl];
+            op.updateRates();
+        }
+    }
+}
+/** Operator register offsets 0x00-0x15 → (channel, operator), with gaps at 6-7 and 0x0e-0x0f. */
+function slotFor(offset) {
+    const group = offset >> 3;
+    const within = offset & 7;
+    if (group > 2 || within > 5)
+        return undefined;
+    return [group * 3 + (within % 3), within >= 3 ? 1 : 0];
+}
+export class Opl2 {
+    channels = Array.from({ length: 9 }, () => new Channel());
+    waveSelect = false;
+    deepTremolo = false;
+    deepVibrato = false;
+    lfoTime = 0;
+    write(reg, value) {
+        reg &= 0xff;
+        value &= 0xff;
+        if (reg === 0x01) {
+            this.waveSelect = (value & 0x20) !== 0;
+            return;
+        }
+        if (reg === 0xbd) {
+            this.deepTremolo = (value & 0x80) !== 0;
+            this.deepVibrato = (value & 0x40) !== 0;
+            return;
+        }
+        const hi = reg & 0xe0;
+        if (hi >= 0x20 && hi <= 0x80 || hi === 0xe0) {
+            const slot = slotFor(reg & 0x1f);
+            if (!slot)
+                return;
+            const ch = this.channels[slot[0]];
+            const op = ch.ops[slot[1]];
+            switch (hi) {
+                case 0x20:
+                    op.am = (value & 0x80) !== 0;
+                    op.vib = (value & 0x40) !== 0;
+                    op.sustained = (value & 0x20) !== 0;
+                    op.ksr = (value & 0x10) !== 0;
+                    op.mult = value & 0x0f;
+                    ch.updatePitch();
+                    break;
+                case 0x40:
+                    op.ksl = value >> 6;
+                    op.tl = value & 0x3f;
+                    ch.updatePitch();
+                    break;
+                case 0x60:
+                    op.ar = value >> 4;
+                    op.dr = value & 0x0f;
+                    op.updateRates();
+                    break;
+                case 0x80:
+                    op.sl = value >> 4;
+                    op.rr = value & 0x0f;
+                    op.updateRates();
+                    break;
+                case 0xe0:
+                    op.wave = value & 3;
+                    break;
+            }
+            return;
+        }
+        const c = reg & 0x0f;
+        if (c > 8)
+            return;
+        const ch = this.channels[c];
+        switch (reg & 0xf0) {
+            case 0xa0:
+                ch.fnum = (ch.fnum & 0x300) | value;
+                ch.updatePitch();
+                break;
+            case 0xb0: {
+                ch.fnum = (ch.fnum & 0xff) | ((value & 3) << 8);
+                ch.block = (value >> 2) & 7;
+                ch.updatePitch();
+                const on = (value & 0x20) !== 0;
+                if (on && !ch.keyOn)
+                    for (const op of ch.ops)
+                        op.keyOn();
+                if (!on && ch.keyOn)
+                    for (const op of ch.ops)
+                        op.keyOff();
+                ch.keyOn = on;
+                break;
+            }
+            case 0xc0:
+                ch.feedback = (value >> 1) & 7;
+                ch.additive = (value & 1) !== 0;
+                break;
+        }
+    }
+    /** Renders `count` mono samples at OPL_RATE into `out` starting at `offset`. */
+    generate(out, offset = 0, count = out.length - offset) {
+        const tremoloDepth = this.deepTremolo ? 4.8 / ATT_DB : 1 / ATT_DB;
+        const vibratoCents = this.deepVibrato ? 14 : 7;
+        for (let n = 0; n < count; n++) {
+            this.lfoTime += 1 / OPL_RATE;
+            const tremolo = tremoloDepth * (0.5 - 0.5 * Math.cos(2 * Math.PI * 3.7 * this.lfoTime));
+            const vibrato = Math.pow(2, (vibratoCents * Math.sin(2 * Math.PI * 6.07 * this.lfoTime)) / 1200);
+            let mix = 0;
+            for (const ch of this.channels) {
+                const [mod, car] = ch.ops;
+                if (mod.state === Env.Off && car.state === Env.Off)
+                    continue;
+                const fb = ch.feedback ? (ch.fb1 + ch.fb2) * Math.pow(2, ch.feedback - 7) : 0;
+                const m = mod.output(fb, tremolo, this.waveSelect);
+                ch.fb2 = ch.fb1;
+                ch.fb1 = m;
+                // Full-scale modulator output shifts the carrier's phase by ±4 cycles, as on the chip.
+                const c = car.output(ch.additive ? 0 : m * 4, tremolo, this.waveSelect);
+                mix += ch.additive ? m + c : c;
+                for (const op of ch.ops) {
+                    op.phase = (op.phase + op.inc * (op.vib ? vibrato : 1)) % 1;
+                    op.stepEnvelope();
+                }
+            }
+            // Each channel peaks at ~1/8 of the DAC's range; the sum can clip, as on real cards.
+            out[offset + n] = Math.max(-1, Math.min(1, mix * 0.125 * 2));
+        }
+    }
+}