sci2-ts 0.0.0-stage → 0.2.2

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

@@ -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: number, phase: number): number {
+  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;
+  }
+}
+
+enum Env { Attack, Decay, Sustain, Release, Off }
+
+/** 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: number, rate: number): number {
+  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;
+
+  private effectiveRate(r: number): number {
+    return r === 0 ? 0 : Math.min(63, r * 4 + (this.ksr ? this.keyCode : this.keyCode >> 2));
+  }
+
+  updateRates(): void {
+    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: number) => {
+      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(): number {
+    return (this.sl === 15 ? 31 : this.sl) * 16; // 3 dB steps; 15 means 93 dB
+  }
+
+  keyOn(): void {
+    this.phase = 0;
+    this.state = Env.Attack;
+  }
+
+  keyOff(): void {
+    if (this.state !== Env.Off) this.state = Env.Release;
+  }
+
+  stepEnvelope(): void {
+    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: number, tremolo: number, waveEnabled: boolean): number {
+    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 {
+  readonly ops = [new Operator(), new Operator()] as const;
+  fnum = 0;
+  block = 0;
+  keyOn = false;
+  feedback = 0;
+  additive = false;
+  fb1 = 0;
+  fb2 = 0;
+
+  updatePitch(): void {
+    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: number): [channel: number, op: 0 | 1] | undefined {
+  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 {
+  readonly channels = Array.from({ length: 9 }, () => new Channel());
+  private waveSelect = false;
+  private deepTremolo = false;
+  private deepVibrato = false;
+  private lfoTime = 0;
+
+  write(reg: number, value: number): void {
+    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: Float32Array, offset = 0, count = out.length - offset): void {
+    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));
+    }
+  }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Sierra SOL audio, used for speech (RESOURCE.AUD) and digital effects (RESOURCE.SFX).
+ *
+ *   +0 u8  resource type (0x8D = audio)     +1 u8 header size (data starts at 2 + this)
+ *   +2 "SOL\0"   +6 u16 sample rate   +8 u8 flags   +9 u32 data size
+ *
+ * Flags: 1 = DPCM compressed, 4 = 16-bit, 8 = signed, 0x10 = stereo.
+ * DPCM stores one delta per byte (16-bit) or per nibble (8-bit); tables and the x86-style
+ * 16-bit wraparound follow the original interpreter (as documented by ScummVM).
+ */
+export interface SolAudio {
+    rate: number;
+    channels: number;
+    /** Samples in -1..1, interleaved if stereo. */
+    samples: Float32Array;
+}
+export declare const SolFlag: {
+    readonly Compressed: 1;
+    readonly Bits16: 4;
+    readonly Signed: 8;
+    readonly Stereo: 16;
+};
+export interface SolHeader {
+    rate: number;
+    flags: number;
+    dataOffset: number;
+    dataSize: number;
+}
+export declare function parseSolHeader(data: Uint8Array): SolHeader | undefined;
+/** Samples a SOL clip of `dataBytes` bytes decodes to, per channel. */
+export declare function solSampleCount(flags: number, dataBytes: number): number;
+export declare function decodeSol(data: Uint8Array): SolAudio | undefined;

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

@@ -0,0 +1,81 @@
+export const SolFlag = { Compressed: 1, Bits16: 4, Signed: 8, Stereo: 0x10 };
+export function parseSolHeader(data) {
+    if (data[2] !== 0x53 || data[3] !== 0x4f || data[4] !== 0x4c)
+        return undefined; // "SOL"
+    const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const headerSize = data[1];
+    return {
+        rate: v.getUint16(6, true),
+        flags: data[8],
+        dataOffset: 2 + headerSize,
+        dataSize: headerSize >= 11 ? v.getUint32(9, true) : data.length - 2 - headerSize,
+    };
+}
+/** Samples a SOL clip of `dataBytes` bytes decodes to, per channel. */
+export function solSampleCount(flags, dataBytes) {
+    const channels = flags & SolFlag.Stereo ? 2 : 1;
+    const bytesPerSample = flags & SolFlag.Compressed ? (flags & SolFlag.Bits16 ? 1 : 0.5) : flags & SolFlag.Bits16 ? 2 : 1;
+    return Math.floor(dataBytes / bytesPerSample / channels);
+}
+const DPCM16 = [
+    0x0000, 0x0008, 0x0010, 0x0020, 0x0030, 0x0040, 0x0050, 0x0060, 0x0070, 0x0080, 0x0090, 0x00a0, 0x00b0, 0x00c0,
+    0x00d0, 0x00e0, 0x00f0, 0x0100, 0x0110, 0x0120, 0x0130, 0x0140, 0x0150, 0x0160, 0x0170, 0x0180, 0x0190, 0x01a0,
+    0x01b0, 0x01c0, 0x01d0, 0x01e0, 0x01f0, 0x0200, 0x0208, 0x0210, 0x0218, 0x0220, 0x0228, 0x0230, 0x0238, 0x0240,
+    0x0248, 0x0250, 0x0258, 0x0260, 0x0268, 0x0270, 0x0278, 0x0280, 0x0288, 0x0290, 0x0298, 0x02a0, 0x02a8, 0x02b0,
+    0x02b8, 0x02c0, 0x02c8, 0x02d0, 0x02d8, 0x02e0, 0x02e8, 0x02f0, 0x02f8, 0x0300, 0x0308, 0x0310, 0x0318, 0x0320,
+    0x0328, 0x0330, 0x0338, 0x0340, 0x0348, 0x0350, 0x0358, 0x0360, 0x0368, 0x0370, 0x0378, 0x0380, 0x0388, 0x0390,
+    0x0398, 0x03a0, 0x03a8, 0x03b0, 0x03b8, 0x03c0, 0x03c8, 0x03d0, 0x03d8, 0x03e0, 0x03e8, 0x03f0, 0x03f8, 0x0400,
+    0x0440, 0x0480, 0x04c0, 0x0500, 0x0540, 0x0580, 0x05c0, 0x0600, 0x0640, 0x0680, 0x06c0, 0x0700, 0x0740, 0x0780,
+    0x07c0, 0x0800, 0x0900, 0x0a00, 0x0b00, 0x0c00, 0x0d00, 0x0e00, 0x0f00, 0x1000, 0x1400, 0x1800, 0x1c00, 0x2000,
+    0x3000, 0x4000,
+];
+const DPCM8 = [0, 1, 2, 3, 6, 10, 15, 21];
+export function decodeSol(data) {
+    const h = parseSolHeader(data);
+    if (!h)
+        return undefined;
+    const channels = h.flags & SolFlag.Stereo ? 2 : 1;
+    const body = data.subarray(h.dataOffset, Math.min(data.length, h.dataOffset + h.dataSize));
+    const out = new Float32Array(solSampleCount(h.flags, body.length) * channels);
+    if (h.flags & SolFlag.Compressed) {
+        if (h.flags & SolFlag.Bits16) {
+            const last = [0, 0];
+            for (let i = 0; i < out.length; i++) {
+                const ch = i % channels;
+                const delta = body[i];
+                let s = last[ch] + (delta & 0x80 ? -DPCM16[delta & 0x7f] : DPCM16[delta]);
+                if (s > 32767)
+                    s -= 65536; // x86 16-bit register wraparound
+                else if (s < -32768)
+                    s += 65536;
+                last[ch] = s;
+                out[i] = s / 32768;
+            }
+        }
+        else {
+            let sample = 0x80;
+            let o = 0;
+            const nibble = (d) => {
+                const prev = sample;
+                sample = Math.max(0, Math.min(255, sample + (d & 8 ? -DPCM8[d & 7] : DPCM8[d & 7])));
+                out[o++] = ((prev + sample) / 2 - 128) / 128;
+            };
+            for (let i = 0; i < body.length && o < out.length; i++) {
+                nibble(body[i] >> 4);
+                if (o < out.length)
+                    nibble(body[i] & 0xf);
+            }
+        }
+    }
+    else if (h.flags & SolFlag.Bits16) {
+        const v = new DataView(body.buffer, body.byteOffset, body.byteLength);
+        for (let i = 0; i < out.length; i++)
+            out[i] = v.getInt16(i * 2, true) / 32768;
+    }
+    else {
+        const signed = (h.flags & SolFlag.Signed) !== 0;
+        for (let i = 0; i < out.length; i++)
+            out[i] = signed ? ((body[i] << 24) >> 24) / 128 : (body[i] - 128) / 128;
+    }
+    return { rate: h.rate, channels, samples: out };
+}

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

@@ -0,0 +1,100 @@
+/**
+ * Sierra SOL audio, used for speech (RESOURCE.AUD) and digital effects (RESOURCE.SFX).
+ *
+ *   +0 u8  resource type (0x8D = audio)     +1 u8 header size (data starts at 2 + this)
+ *   +2 "SOL\0"   +6 u16 sample rate   +8 u8 flags   +9 u32 data size
+ *
+ * Flags: 1 = DPCM compressed, 4 = 16-bit, 8 = signed, 0x10 = stereo.
+ * DPCM stores one delta per byte (16-bit) or per nibble (8-bit); tables and the x86-style
+ * 16-bit wraparound follow the original interpreter (as documented by ScummVM).
+ */
+export interface SolAudio {
+  rate: number;
+  channels: number;
+  /** Samples in -1..1, interleaved if stereo. */
+  samples: Float32Array;
+}
+
+export const SolFlag = { Compressed: 1, Bits16: 4, Signed: 8, Stereo: 0x10 } as const;
+
+export interface SolHeader {
+  rate: number;
+  flags: number;
+  dataOffset: number;
+  dataSize: number;
+}
+
+export function parseSolHeader(data: Uint8Array): SolHeader | undefined {
+  if (data[2] !== 0x53 || data[3] !== 0x4f || data[4] !== 0x4c) return undefined; // "SOL"
+  const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const headerSize = data[1]!;
+  return {
+    rate: v.getUint16(6, true),
+    flags: data[8]!,
+    dataOffset: 2 + headerSize,
+    dataSize: headerSize >= 11 ? v.getUint32(9, true) : data.length - 2 - headerSize,
+  };
+}
+
+/** Samples a SOL clip of `dataBytes` bytes decodes to, per channel. */
+export function solSampleCount(flags: number, dataBytes: number): number {
+  const channels = flags & SolFlag.Stereo ? 2 : 1;
+  const bytesPerSample = flags & SolFlag.Compressed ? (flags & SolFlag.Bits16 ? 1 : 0.5) : flags & SolFlag.Bits16 ? 2 : 1;
+  return Math.floor(dataBytes / bytesPerSample / channels);
+}
+
+const DPCM16 = [
+  0x0000, 0x0008, 0x0010, 0x0020, 0x0030, 0x0040, 0x0050, 0x0060, 0x0070, 0x0080, 0x0090, 0x00a0, 0x00b0, 0x00c0,
+  0x00d0, 0x00e0, 0x00f0, 0x0100, 0x0110, 0x0120, 0x0130, 0x0140, 0x0150, 0x0160, 0x0170, 0x0180, 0x0190, 0x01a0,
+  0x01b0, 0x01c0, 0x01d0, 0x01e0, 0x01f0, 0x0200, 0x0208, 0x0210, 0x0218, 0x0220, 0x0228, 0x0230, 0x0238, 0x0240,
+  0x0248, 0x0250, 0x0258, 0x0260, 0x0268, 0x0270, 0x0278, 0x0280, 0x0288, 0x0290, 0x0298, 0x02a0, 0x02a8, 0x02b0,
+  0x02b8, 0x02c0, 0x02c8, 0x02d0, 0x02d8, 0x02e0, 0x02e8, 0x02f0, 0x02f8, 0x0300, 0x0308, 0x0310, 0x0318, 0x0320,
+  0x0328, 0x0330, 0x0338, 0x0340, 0x0348, 0x0350, 0x0358, 0x0360, 0x0368, 0x0370, 0x0378, 0x0380, 0x0388, 0x0390,
+  0x0398, 0x03a0, 0x03a8, 0x03b0, 0x03b8, 0x03c0, 0x03c8, 0x03d0, 0x03d8, 0x03e0, 0x03e8, 0x03f0, 0x03f8, 0x0400,
+  0x0440, 0x0480, 0x04c0, 0x0500, 0x0540, 0x0580, 0x05c0, 0x0600, 0x0640, 0x0680, 0x06c0, 0x0700, 0x0740, 0x0780,
+  0x07c0, 0x0800, 0x0900, 0x0a00, 0x0b00, 0x0c00, 0x0d00, 0x0e00, 0x0f00, 0x1000, 0x1400, 0x1800, 0x1c00, 0x2000,
+  0x3000, 0x4000,
+];
+const DPCM8 = [0, 1, 2, 3, 6, 10, 15, 21];
+
+export function decodeSol(data: Uint8Array): SolAudio | undefined {
+  const h = parseSolHeader(data);
+  if (!h) return undefined;
+  const channels = h.flags & SolFlag.Stereo ? 2 : 1;
+  const body = data.subarray(h.dataOffset, Math.min(data.length, h.dataOffset + h.dataSize));
+  const out = new Float32Array(solSampleCount(h.flags, body.length) * channels);
+
+  if (h.flags & SolFlag.Compressed) {
+    if (h.flags & SolFlag.Bits16) {
+      const last = [0, 0];
+      for (let i = 0; i < out.length; i++) {
+        const ch = i % channels;
+        const delta = body[i]!;
+        let s = last[ch]! + (delta & 0x80 ? -DPCM16[delta & 0x7f]! : DPCM16[delta]!);
+        if (s > 32767) s -= 65536; // x86 16-bit register wraparound
+        else if (s < -32768) s += 65536;
+        last[ch] = s;
+        out[i] = s / 32768;
+      }
+    } else {
+      let sample = 0x80;
+      let o = 0;
+      const nibble = (d: number) => {
+        const prev = sample;
+        sample = Math.max(0, Math.min(255, sample + (d & 8 ? -DPCM8[d & 7]! : DPCM8[d & 7]!)));
+        out[o++] = ((prev + sample) / 2 - 128) / 128;
+      };
+      for (let i = 0; i < body.length && o < out.length; i++) {
+        nibble(body[i]! >> 4);
+        if (o < out.length) nibble(body[i]! & 0xf);
+      }
+    }
+  } else if (h.flags & SolFlag.Bits16) {
+    const v = new DataView(body.buffer, body.byteOffset, body.byteLength);
+    for (let i = 0; i < out.length; i++) out[i] = v.getInt16(i * 2, true) / 32768;
+  } else {
+    const signed = (h.flags & SolFlag.Signed) !== 0;
+    for (let i = 0; i < out.length; i++) out[i] = signed ? ((body[i]! << 24) >> 24) / 128 : (body[i]! - 128) / 128;
+  }
+  return { rate: h.rate, channels, samples: out };
+}

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

@@ -0,0 +1,35 @@
+import type { MidiEvent } from "./midi.ts";
+/**
+ * Writers for sound: sound resources (music, in the layout parseSound reads), SOL clips, and
+ * the effects file RESOURCE.SFX with its index, map 65535 (the layout AudioIndex reads).
+ */
+export interface SoundChannel {
+    /** 0-15; 15 is the control channel (signals and cues to the scripts), not music. */
+    midiChannel: number;
+    /** Voices it wants from a voice-limited device (AdLib); others ignore it. */
+    voices: number;
+    /** Absolute ticks (1/60 s); bytes are MIDI messages (their channel nibble is replaced). */
+    events: MidiEvent[];
+}
+export interface SoundSpec {
+    priority?: number;
+    /** One per sound device (SoundDevice): each device plays its own arrangement. */
+    tracks: {
+        device: number;
+        channels: SoundChannel[];
+    }[];
+}
+export declare function writeSound(spec: SoundSpec): Uint8Array;
+/** A SOL clip: 16-bit samples at `rate`, uncompressed. */
+export declare function writeSol(samples: Int16Array, rate: number): Uint8Array;
+/**
+ * RESOURCE.SFX (the SOL clips, one after another) and its index, map 65535: per clip, u16
+ * sound number and u24 offset from the previous clip; 0xFFFF ends it.
+ */
+export declare function writeEffects(clips: readonly {
+    number: number;
+    sol: Uint8Array;
+}[]): {
+    sfx: Uint8Array;
+    map: Uint8Array;
+};

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

@@ -0,0 +1,91 @@
+import { SolFlag } from "./sol.js";
+const dataBytes = (status) => ((status & 0xf0) === 0xc0 || (status & 0xf0) === 0xd0 ? 1 : 2);
+/** A channel stream: channel, voices, then delta-timed events with running status, then 0xFC. */
+function channelStream(c) {
+    if (c.midiChannel < 0 || c.midiChannel > 15)
+        throw new Error(`MIDI channel ${c.midiChannel} isn't 0-15`);
+    const out = [c.midiChannel, c.voices & 0x0f];
+    const events = [...c.events].sort((a, b) => a.tick - b.tick);
+    let tick = 0, running = -1;
+    for (const e of events) {
+        if (e.tick < tick)
+            throw new Error(`event at tick ${e.tick} before ${tick}`);
+        let delta = Math.round(e.tick - tick);
+        tick += delta;
+        // A delta of 240 or more is 0xF8 bytes of 240 each, then the rest.
+        for (; delta >= 240; delta -= 240)
+            out.push(0xf8);
+        out.push(delta);
+        const status = (e.bytes[0] & 0xf0) | c.midiChannel;
+        if (status < 0x80 || status >= 0xf0)
+            throw new Error(`not a channel message: ${e.bytes.map((b) => b.toString(16)).join(" ")}`);
+        if (status !== running)
+            out.push(status);
+        running = status;
+        const n = dataBytes(status);
+        for (let i = 1; i <= n; i++)
+            out.push((e.bytes[i] ?? 0) & 0x7f);
+    }
+    out.push(0, 0xfc);
+    return out;
+}
+export function writeSound(spec) {
+    const header = [0xf0, spec.priority ?? 0, 0, 0, 0, 0, 0, 0];
+    const streams = spec.tracks.map((t) => t.channels.map(channelStream));
+    // Track table: device, 6-byte entries (u16 0, u16 offset, u16 size), 0xFF; then 0xFF.
+    const tableSize = spec.tracks.reduce((n, t) => n + 1 + t.channels.length * 6 + 1, 0) + 1;
+    let at = header.length + tableSize;
+    const table = [];
+    const body = [];
+    spec.tracks.forEach((t, i) => {
+        table.push(t.device);
+        for (const s of streams[i]) {
+            if (at + s.length > 0xffff)
+                throw new Error("sound too large: offsets are 16-bit (64 KB)");
+            table.push(0, 0, at & 0xff, at >> 8, s.length & 0xff, s.length >> 8);
+            body.push(...s);
+            at += s.length;
+        }
+        table.push(0xff);
+    });
+    table.push(0xff);
+    return Uint8Array.from([...header, ...table, ...body]);
+}
+/** A SOL clip: 16-bit samples at `rate`, uncompressed. */
+export function writeSol(samples, rate) {
+    const out = new Uint8Array(13 + samples.length * 2);
+    const v = new DataView(out.buffer);
+    out[0] = 0x8d; // audio
+    out[1] = 11; // header bytes after these two
+    out.set([0x53, 0x4f, 0x4c, 0], 2); // "SOL\0"
+    v.setUint16(6, rate, true);
+    out[8] = SolFlag.Bits16 | SolFlag.Signed;
+    v.setUint32(9, samples.length * 2, true);
+    samples.forEach((s, i) => v.setInt16(13 + i * 2, s, true));
+    return out;
+}
+/**
+ * RESOURCE.SFX (the SOL clips, one after another) and its index, map 65535: per clip, u16
+ * sound number and u24 offset from the previous clip; 0xFFFF ends it.
+ */
+export function writeEffects(clips) {
+    const sorted = [...clips].sort((a, b) => a.number - b.number);
+    const sfx = new Uint8Array(sorted.reduce((n, c) => n + c.sol.length, 0));
+    const map = new Uint8Array(sorted.length * 5 + 5);
+    const v = new DataView(map.buffer);
+    let at = 0, prev = 0;
+    sorted.forEach((c, i) => {
+        if (i && c.number === sorted[i - 1].number)
+            throw new Error(`sound effect ${c.number} is there twice`);
+        if (at - prev > 0xffffff)
+            throw new Error("sound effect too large");
+        sfx.set(c.sol, at);
+        v.setUint16(i * 5, c.number, true);
+        const delta = at - prev;
+        map.set([delta & 0xff, (delta >> 8) & 0xff, delta >> 16], i * 5 + 2);
+        prev = at;
+        at += c.sol.length;
+    });
+    v.setUint16(sorted.length * 5, 0xffff, true);
+    return { sfx, map };
+}