sci2-ts 0.0.0-stage → 0.2.2

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

@@ -0,0 +1,43 @@
+import type { ResourceManager } from "../resource/manager.ts";
+export type AudioFile = "RESOURCE.AUD" | "RESOURCE.SFX";
+/** Where a clip's bytes live, without having read them. */
+export interface AudioClip {
+    file: AudioFile;
+    /** Offset of the SOL resource (type byte) in the file. */
+    offset: number;
+    /** Byte length up to the next clip in the file (an upper bound for the last one). */
+    length: number;
+    /** Exact duration in 60 Hz ticks, when the header was available at index time. */
+    ticks?: number;
+}
+export declare const speechKey: (module: number, noun: number, verb: number, cond: number, seq: number) => string;
+/**
+ * Index of every digital clip, built from the audio map resources:
+ *
+ * Speech maps (one per module): u32 base offset into RESOURCE.AUD, then entries of
+ *   u32 BIG-endian noun<<24|verb<<16|cond<<8|seq   (seq bit 7: u16 lip-sync size follows,
+ *   u24 delta added to the running offset           seq bit 6: u16 extra size follows)
+ *   terminated by 0xFFFFFFFF. Lip-sync data sits before the SOL audio.
+ * Map 65535 (sound effects): u16 number, u24 delta (running offset) into RESOURCE.SFX;
+ *   0xFFFF ends it.
+ *
+ * Lengths come from sorting all offsets per file: each clip runs to the next one.
+ */
+export declare class AudioIndex {
+    readonly speech: Map<string, AudioClip>;
+    readonly effects: Map<number, AudioClip>;
+    static build(rm: ResourceManager): AudioIndex;
+    /** Estimated duration in 60 Hz ticks, from the clip's byte length. */
+    static ticks(clip: AudioClip): number;
+}
+/** What a host (browser, test) provides to actually make noise. */
+export interface AudioOutput {
+    play(channel: string, clip: AudioClip, options: {
+        loop: boolean;
+        volume: number;
+    }): void;
+    stop(channel: string): void;
+    pause(channel: string): void;
+    resume(channel: string): void;
+    setVolume(channel: string, volume: number): void;
+}

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

@@ -0,0 +1,99 @@
+import { ResourceType } from "../resource/types.js";
+import { parseSolHeader, solSampleCount } from "./sol.js";
+const SFX_MAP = 65535;
+const SOL_HEADER = 14;
+/** Speech and effects are usually 11,025 Hz, 16-bit DPCM (1 byte per sample). */
+const DEFAULT_RATE = 11025;
+export const speechKey = (module, noun, verb, cond, seq) => `${module}:${noun}:${verb}:${cond}:${seq}`;
+/**
+ * Index of every digital clip, built from the audio map resources:
+ *
+ * Speech maps (one per module): u32 base offset into RESOURCE.AUD, then entries of
+ *   u32 BIG-endian noun<<24|verb<<16|cond<<8|seq   (seq bit 7: u16 lip-sync size follows,
+ *   u24 delta added to the running offset           seq bit 6: u16 extra size follows)
+ *   terminated by 0xFFFFFFFF. Lip-sync data sits before the SOL audio.
+ * Map 65535 (sound effects): u16 number, u24 delta (running offset) into RESOURCE.SFX;
+ *   0xFFFF ends it.
+ *
+ * Lengths come from sorting all offsets per file: each clip runs to the next one.
+ */
+export class AudioIndex {
+    speech = new Map();
+    effects = new Map();
+    static build(rm) {
+        const index = new AudioIndex();
+        const starts = { "RESOURCE.AUD": [], "RESOURCE.SFX": [] };
+        const pending = [];
+        for (const info of rm.list(ResourceType.Map)) {
+            const data = rm.loadSync(info).data;
+            const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
+            if (info.number === SFX_MAP) {
+                let offset = 0;
+                for (let p = 0; p + 5 <= data.length; p += 5) {
+                    const n = v.getUint16(p, true);
+                    if (n === 0xffff)
+                        break;
+                    offset += data[p + 2] | (data[p + 3] << 8) | (data[p + 4] << 16);
+                    const clip = { file: "RESOURCE.SFX", offset, length: 0 };
+                    index.effects.set(n, clip);
+                    starts["RESOURCE.SFX"].push(offset);
+                    pending.push({ clip, skip: 0 });
+                }
+                continue;
+            }
+            let offset = v.getUint32(0, true);
+            for (let p = 4; p + 7 <= data.length;) {
+                const n = v.getUint32(p, false);
+                if (n === 0xffffffff)
+                    break;
+                offset += data[p + 4] | (data[p + 5] << 8) | (data[p + 6] << 16);
+                p += 7;
+                let skip = 0;
+                const seqFlags = n & 0xff;
+                starts["RESOURCE.AUD"].push(offset);
+                if (seqFlags & 0x80)
+                    (skip += v.getUint16(p, true)), (p += 2);
+                if (seqFlags & 0x40)
+                    (skip += v.getUint16(p, true)), (p += 2);
+                const key = speechKey(info.number, n >>> 24, (n >>> 16) & 0xff, (n >>> 8) & 0xff, seqFlags & 0x3f);
+                const clip = { file: "RESOURCE.AUD", offset: offset + skip, length: 0 };
+                index.speech.set(key, clip);
+                pending.push({ clip, skip });
+            }
+        }
+        // Effects are small and preloaded: take exact durations from their headers.
+        const sfx = rm.file("RESOURCE.SFX");
+        if (sfx) {
+            for (const clip of index.effects.values()) {
+                const h = parseSolHeader(sfx.subarray(clip.offset, clip.offset + 16));
+                if (h)
+                    clip.ticks = Math.max(1, Math.round((solSampleCount(h.flags, h.dataSize) / h.rate) * 60));
+            }
+        }
+        for (const file of Object.keys(starts))
+            starts[file] = [...new Set(starts[file])].sort((a, b) => a - b);
+        for (const { clip, skip } of pending) {
+            const list = starts[clip.file];
+            const start = clip.offset - skip;
+            // Binary search for the next start after this clip.
+            let lo = 0, hi = list.length;
+            while (lo < hi) {
+                const mid = (lo + hi) >> 1;
+                if (list[mid] <= start)
+                    lo = mid + 1;
+                else
+                    hi = mid;
+            }
+            const next = list[lo] ?? clip.offset + 2_000_000;
+            clip.length = Math.max(0, next - clip.offset);
+        }
+        return index;
+    }
+    /** Estimated duration in 60 Hz ticks, from the clip's byte length. */
+    static ticks(clip) {
+        if (clip.ticks)
+            return clip.ticks;
+        const samples = Math.max(0, clip.length - SOL_HEADER);
+        return Math.max(1, Math.round((samples / DEFAULT_RATE) * 60));
+    }
+}

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

@@ -0,0 +1,122 @@
+import type { ResourceManager } from "../resource/manager.ts";
+import { ResourceType } from "../resource/types.ts";
+import { parseSolHeader, solSampleCount } from "./sol.ts";
+
+export type AudioFile = "RESOURCE.AUD" | "RESOURCE.SFX";
+
+/** Where a clip's bytes live, without having read them. */
+export interface AudioClip {
+  file: AudioFile;
+  /** Offset of the SOL resource (type byte) in the file. */
+  offset: number;
+  /** Byte length up to the next clip in the file (an upper bound for the last one). */
+  length: number;
+  /** Exact duration in 60 Hz ticks, when the header was available at index time. */
+  ticks?: number;
+}
+
+const SFX_MAP = 65535;
+const SOL_HEADER = 14;
+/** Speech and effects are usually 11,025 Hz, 16-bit DPCM (1 byte per sample). */
+const DEFAULT_RATE = 11025;
+
+export const speechKey = (module: number, noun: number, verb: number, cond: number, seq: number) =>
+  `${module}:${noun}:${verb}:${cond}:${seq}`;
+
+/**
+ * Index of every digital clip, built from the audio map resources:
+ *
+ * Speech maps (one per module): u32 base offset into RESOURCE.AUD, then entries of
+ *   u32 BIG-endian noun<<24|verb<<16|cond<<8|seq   (seq bit 7: u16 lip-sync size follows,
+ *   u24 delta added to the running offset           seq bit 6: u16 extra size follows)
+ *   terminated by 0xFFFFFFFF. Lip-sync data sits before the SOL audio.
+ * Map 65535 (sound effects): u16 number, u24 delta (running offset) into RESOURCE.SFX;
+ *   0xFFFF ends it.
+ *
+ * Lengths come from sorting all offsets per file: each clip runs to the next one.
+ */
+export class AudioIndex {
+  readonly speech = new Map<string, AudioClip>();
+  readonly effects = new Map<number, AudioClip>();
+
+  static build(rm: ResourceManager): AudioIndex {
+    const index = new AudioIndex();
+    const starts: Record<AudioFile, number[]> = { "RESOURCE.AUD": [], "RESOURCE.SFX": [] };
+    const pending: { clip: AudioClip; skip: number }[] = [];
+
+    for (const info of rm.list(ResourceType.Map)) {
+      const data = rm.loadSync(info).data;
+      const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
+      if (info.number === SFX_MAP) {
+        let offset = 0;
+        for (let p = 0; p + 5 <= data.length; p += 5) {
+          const n = v.getUint16(p, true);
+          if (n === 0xffff) break;
+          offset += data[p + 2]! | (data[p + 3]! << 8) | (data[p + 4]! << 16);
+          const clip: AudioClip = { file: "RESOURCE.SFX", offset, length: 0 };
+          index.effects.set(n, clip);
+          starts["RESOURCE.SFX"].push(offset);
+          pending.push({ clip, skip: 0 });
+        }
+        continue;
+      }
+      let offset = v.getUint32(0, true);
+      for (let p = 4; p + 7 <= data.length; ) {
+        const n = v.getUint32(p, false);
+        if (n === 0xffffffff) break;
+        offset += data[p + 4]! | (data[p + 5]! << 8) | (data[p + 6]! << 16);
+        p += 7;
+        let skip = 0;
+        const seqFlags = n & 0xff;
+        starts["RESOURCE.AUD"].push(offset);
+        if (seqFlags & 0x80) (skip += v.getUint16(p, true)), (p += 2);
+        if (seqFlags & 0x40) (skip += v.getUint16(p, true)), (p += 2);
+        const key = speechKey(info.number, n >>> 24, (n >>> 16) & 0xff, (n >>> 8) & 0xff, seqFlags & 0x3f);
+        const clip: AudioClip = { file: "RESOURCE.AUD", offset: offset + skip, length: 0 };
+        index.speech.set(key, clip);
+        pending.push({ clip, skip });
+      }
+    }
+
+    // Effects are small and preloaded: take exact durations from their headers.
+    const sfx = rm.file("RESOURCE.SFX");
+    if (sfx) {
+      for (const clip of index.effects.values()) {
+        const h = parseSolHeader(sfx.subarray(clip.offset, clip.offset + 16));
+        if (h) clip.ticks = Math.max(1, Math.round((solSampleCount(h.flags, h.dataSize) / h.rate) * 60));
+      }
+    }
+
+    for (const file of Object.keys(starts) as AudioFile[]) starts[file] = [...new Set(starts[file])].sort((a, b) => a - b);
+    for (const { clip, skip } of pending) {
+      const list = starts[clip.file];
+      const start = clip.offset - skip;
+      // Binary search for the next start after this clip.
+      let lo = 0, hi = list.length;
+      while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (list[mid]! <= start) lo = mid + 1;
+        else hi = mid;
+      }
+      const next = list[lo] ?? clip.offset + 2_000_000;
+      clip.length = Math.max(0, next - clip.offset);
+    }
+    return index;
+  }
+
+  /** Estimated duration in 60 Hz ticks, from the clip's byte length. */
+  static ticks(clip: AudioClip): number {
+    if (clip.ticks) return clip.ticks;
+    const samples = Math.max(0, clip.length - SOL_HEADER);
+    return Math.max(1, Math.round((samples / DEFAULT_RATE) * 60));
+  }
+}
+
+/** What a host (browser, test) provides to actually make noise. */
+export interface AudioOutput {
+  play(channel: string, clip: AudioClip, options: { loop: boolean; volume: number }): void;
+  stop(channel: string): void;
+  pause(channel: string): void;
+  resume(channel: string): void;
+  setVolume(channel: string, volume: number): void;
+}

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

@@ -0,0 +1,92 @@
+/**
+ * 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 declare const SoundDevice: {
+    readonly AdLib: 0;
+    readonly GeneralMidi: 7;
+    readonly Mt32: 12;
+};
+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;
+}
+/** Parses the track for `device` (falling back to MT-32, then any), merging its channels. */
+export declare function parseSound(data: Uint8Array, device?: number): Song | undefined;
+/** 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 declare const SongSignal: {
+    readonly Finished: 65535;
+};
+/**
+ * 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 declare class SongPlayer {
+    readonly song: Song;
+    private readonly output;
+    loop: boolean;
+    volume: number;
+    private index;
+    private startTick;
+    private loopIndex;
+    private loopTick;
+    private readonly held;
+    /** Last channel volume (CC 7) the song asked for, to rescale on volume changes. */
+    private readonly channelVolume;
+    finished: boolean;
+    /** Latest control-channel signal not yet reported (0 = none). */
+    signal: number;
+    dataInc: number;
+    private paused;
+    constructor(song: Song, output: MidiOutput | undefined, loop: boolean, volume: number, // 0..127
+    now: number);
+    /** Sends every event due by tick `now`. */
+    update(now: number): void;
+    private dispatch;
+    /** Releases every note this song is holding. */
+    private silence;
+    private released;
+    stop(): void;
+    /** Position in ticks. */
+    position(now: number): number;
+    /**
+     * 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;
+    pause(now: number): void;
+    resume(now: number): void;
+    setVolume(volume: number): void;
+}

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

@@ -0,0 +1,242 @@
+/**
+ * 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 };
+const CONTROL_CHANNEL = 15;
+const LOOP_MARKER = 127;
+const CUE_CONTROLLER = 0x60;
+const dataBytes = (status) => ((status & 0xf0) === 0xc0 || (status & 0xf0) === 0xd0 ? 1 : 2);
+function readChannel(data, start, end, midiChannel, out) {
+    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, device = SoundDevice.GeneralMidi) {
+    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();
+    while (pos < data.length && data[pos] !== 0xff) {
+        const type = data[pos++];
+        const channels = [];
+        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 = [];
+    const songChannels = [];
+    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 };
+}
+/** Signal values scripts see on the sound object. */
+export const SongSignal = { Finished: 0xffff };
+/**
+ * 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 {
+    song;
+    output;
+    loop;
+    volume;
+    index = 0;
+    startTick = 0;
+    loopIndex = 0;
+    loopTick = 0;
+    held = new Set(); // channel << 8 | note
+    /** Last channel volume (CC 7) the song asked for, to rescale on volume changes. */
+    channelVolume = new Map();
+    finished = false;
+    /** Latest control-channel signal not yet reported (0 = none). */
+    signal = 0;
+    dataInc = 0;
+    paused;
+    constructor(song, output, loop, volume, // 0..127
+    now) {
+        this.song = song;
+        this.output = output;
+        this.loop = loop;
+        this.volume = volume;
+        this.startTick = now;
+        for (const c of song.channels)
+            output?.claimVoices?.(c.midiChannel, c.voices);
+    }
+    /** Sends every event due by tick `now`. */
+    update(now) {
+        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;
+            }
+        }
+    }
+    dispatch(e, index) {
+        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. */
+    silence() {
+        for (const key of this.held)
+            this.output?.send([0x80 | (key >> 8), key & 0xff, 0]);
+        this.held.clear();
+    }
+    released = false;
+    stop() {
+        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) {
+        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, now) {
+        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) {
+        if (this.paused !== undefined)
+            return;
+        this.paused = now;
+        this.silence();
+    }
+    resume(now) {
+        if (this.paused === undefined)
+            return;
+        this.startTick += now - this.paused;
+        this.paused = undefined;
+    }
+    setVolume(volume) {
+        this.volume = volume;
+        for (const [channel, v] of this.channelVolume)
+            this.output?.send([0xb0 | channel, 7, Math.round((v * volume) / 127)]);
+    }
+}