narrator-ts 0.0.0 → 0.1.1

package/dist/narrator/render.d.ts

@@ -0,0 +1,64 @@
+/**
+ * narrator.device's sample renderer — the back half of the synthesizer.
+ *
+ * The device splits cleanly: phonemes become an array of 8-byte frames, and
+ * frames become samples. This is the second half, ported from the loop at hunk
+ * offsets 0x548a-0x55e4 of build 33.2. See research/02-narrator.md.
+ *
+ * It is written as a transcription of the 68k rather than as a tidy synthesis
+ * routine, because it has to be sample-exact and the registers carry two
+ * things at once in places the tidy version would separate. In particular D0
+ * holds *two* counters, one per half-word: the samples left in this frame and
+ * the samples left in this pitch period. The 68k swaps between them, so this
+ * does too.
+ */
+/** One 8-byte frame, as the device lays it out. */
+export declare const FRAME: {
+    /** Phase increment for the first formant. */
+    readonly F1_FREQ: 0;
+    /** Phase increment for the second. */
+    readonly F2_FREQ: 1;
+    /** Phase increment for the third — doubled into a word (0x5558). */
+    readonly F3_FREQ: 2;
+    readonly F1_AMP: 3;
+    readonly F2_AMP: 4;
+    readonly F3_AMP: 5;
+    /**
+     * Voicing. Zero is fully voiced. Otherwise bit 7 means "sum a voiced
+     * formant as well" (a voiced fricative), bits 4-6 pick one of eight
+     * fricative tables and bits 0-3 are the noise amplitude.
+     */
+    readonly VOICING: 6;
+    /** The pitch period, in samples. Amplitudes reload when it expires. */
+    readonly PITCH: 7;
+};
+export declare const FRAME_BYTES = 8;
+/**
+ * The audio buffer, in bytes. The renderer fills these and hands them to
+ * audio.device, so only *whole* buffers are ever heard: whatever the frames
+ * had left over at the end is still in the half-filled buffer when the
+ * utterance stops, and never gets written. Output is truncated to match.
+ */
+export declare const BUFFER_BYTES = 512;
+/** Everything the loop reads that is not in a frame. */
+export interface RenderTables {
+    /** The waveform table at hunk+0x4aae, stepped 0x40 at a time. */
+    wave: Uint8Array;
+    /** Indexed by `(amplitude << 5) | waveform`; does the multiply. */
+    ampTable: Uint8Array;
+    /** The eight fricative tables, selected by bits 4-6 of the voicing byte. */
+    fricatives?: Uint8Array[];
+    /** Samples per frame — `A5+0x24`, from `sampfreq` (hunk+0x53fa). */
+    periodCount: number;
+    /** How often the waveform pointer steps — `A5+0x32`, 9 or 11. */
+    waveStep: number;
+}
+/**
+ * Render frames to 8-bit signed samples.
+ *
+ * Voiced output is computed at half rate and each sample written twice
+ * (0x54c0-0x54c2); unvoiced is computed per sample (0x5648). That is not a
+ * detail — it is why the voice sounds the way it does, and a renderer that
+ * computes every sample at the output rate is neither exact nor right.
+ */
+export declare function render(input: Uint8Array, t: RenderTables): Int8Array;

package/dist/narrator/render.js

@@ -0,0 +1,273 @@
+/**
+ * narrator.device's sample renderer — the back half of the synthesizer.
+ *
+ * The device splits cleanly: phonemes become an array of 8-byte frames, and
+ * frames become samples. This is the second half, ported from the loop at hunk
+ * offsets 0x548a-0x55e4 of build 33.2. See research/02-narrator.md.
+ *
+ * It is written as a transcription of the 68k rather than as a tidy synthesis
+ * routine, because it has to be sample-exact and the registers carry two
+ * things at once in places the tidy version would separate. In particular D0
+ * holds *two* counters, one per half-word: the samples left in this frame and
+ * the samples left in this pitch period. The 68k swaps between them, so this
+ * does too.
+ */
+/** One 8-byte frame, as the device lays it out. */
+export const FRAME = {
+    /** Phase increment for the first formant. */
+    F1_FREQ: 0,
+    /** Phase increment for the second. */
+    F2_FREQ: 1,
+    /** Phase increment for the third — doubled into a word (0x5558). */
+    F3_FREQ: 2,
+    F1_AMP: 3,
+    F2_AMP: 4,
+    F3_AMP: 5,
+    /**
+     * Voicing. Zero is fully voiced. Otherwise bit 7 means "sum a voiced
+     * formant as well" (a voiced fricative), bits 4-6 pick one of eight
+     * fricative tables and bits 0-3 are the noise amplitude.
+     */
+    VOICING: 6,
+    /** The pitch period, in samples. Amplitudes reload when it expires. */
+    PITCH: 7,
+};
+export const FRAME_BYTES = 8;
+/**
+ * The audio buffer, in bytes. The renderer fills these and hands them to
+ * audio.device, so only *whole* buffers are ever heard: whatever the frames
+ * had left over at the end is still in the half-filled buffer when the
+ * utterance stops, and never gets written. Output is truncated to match.
+ */
+export const BUFFER_BYTES = 0x200;
+/** Where the fricative index turns round — one short of the table's 0x1e0. */
+const NOISE_END = 0x1df;
+const WORD = 0xffff;
+const lo = (v) => v & WORD;
+const hi = (v) => (v >>> 16) & WORD;
+const swap = (v) => ((v << 16) | (v >>> 16)) >>> 0;
+/** 68k `subq.w #1,Dn` then `bpl`: the *word* is signed for the test. */
+const dec = (v) => (v & ~WORD) | lo(v - 1);
+const sword = (v) => (lo(v) << 16) >> 16;
+/**
+ * Render frames to 8-bit signed samples.
+ *
+ * Voiced output is computed at half rate and each sample written twice
+ * (0x54c0-0x54c2); unvoiced is computed per sample (0x5648). That is not a
+ * detail — it is why the voice sounds the way it does, and a renderer that
+ * computes every sample at the output rate is neither exact nor right.
+ */
+export function render(input, t) {
+    // The device edits its frame array as it goes (see decode), so work on a
+    // copy rather than handing that surprise back to the caller.
+    const frames = Uint8Array.from(input);
+    const out = [];
+    const wave = t.wave;
+    const amp = t.ampTable;
+    let d0 = (t.periodCount << 16) >>> 0; // 0x5480: high = frame counter
+    let d1 = 0; // F1 phase
+    let d2 = 0; // F2 (low) and F3 (high) phases
+    let d3 = 0; // F1 amplitude, pre-shifted
+    let d4 = 0; // F2 (low) and F3 (high) amplitudes
+    let a0 = 0; // offset into `wave`
+    let waveCount = t.waveStep;
+    let fp = 0; // the frame pointer, A6
+    let cur = frames.subarray(0, FRAME_BYTES); // the frame the loop is on
+    let f1inc = 0;
+    let f2f3inc = 0;
+    let voicing = 0;
+    let noise;
+    let noiseIndex = 0; // A5+0x10
+    let noiseStep = 1; // A5+0x12, initialised at 0x53e6
+    let noiseAmp = 0;
+    /**
+     * Bit 31 of D6, the flag the noise path tests to decide whether to sum a
+     * voiced formant. A mixed frame *sets* it (0x5586 `bset`) and nothing ever
+     * clears it but `move.l D4,D6` on the voiced sample path (0x54aa) — there is
+     * no `bclr` anywhere. So it is sticky: after a voiced fricative, every
+     * pure-noise frame up to the next voiced one keeps behaving as mixed.
+     * Recomputing it per frame from bit 7 of the voicing byte is the obvious
+     * reading and does not match the binary.
+     *
+     * NOTE: no captured utterance distinguishes the two, and that is not for
+     * want of trying — `VF`, `DHTH` and `ZHSH` in fixtures/corpus/frames.txt
+     * exist to put a pure-noise frame directly after a mixed one. It stays
+     * hidden because 0x558c clears D3 on exactly those frames, so the voiced
+     * formant it sums is silent, and the amplitudes a differently-timed pitch
+     * pulse would load have been zeroed in the frame array anyway. This
+     * follows the instructions rather than the fixtures.
+     */
+    let mixed = false;
+    let done = false;
+    /**
+     * 0x55b6: a pitch pulse. The waveform restarts and the *current* frame's
+     * amplitudes are taken — they are sampled here and only here, so a frame
+     * whose pitch period has not expired keeps the previous pulse's levels.
+     */
+    const pitchPulse = (f) => {
+        d1 = 0;
+        d2 = 0;
+        a0 = 0;
+        waveCount = t.waveStep;
+        d0 = (d0 & ~WORD) | f[FRAME.PITCH];
+        d3 = (f[FRAME.F1_AMP] << 5) & WORD;
+        d4 = (((f[FRAME.F3_AMP] << 5) & WORD) << 16 |
+            ((f[FRAME.F2_AMP] << 5) & WORD)) >>> 0;
+    };
+    /** 0x5544: decode a frame's fields. Returns false at the end marker. */
+    const decode = () => {
+        if (fp + FRAME_BYTES > frames.length)
+            return false;
+        cur = frames.subarray(fp, fp + FRAME_BYTES);
+        if (cur[FRAME.F1_FREQ] & 0x80)
+            return false; // 0x5548 bmi
+        f1inc = cur[FRAME.F1_FREQ];
+        // 0x5550-0x5558. The increments are added as one longword read from
+        // A5+2, so F2's word is the *high* half and F3's (doubled) the low —
+        // and the add is bracketed by swaps, which lands each on its own
+        // accumulator. Assembling it the other way round is silently plausible
+        // and completely wrong.
+        f2f3inc = ((cur[FRAME.F2_FREQ] << 16) | ((cur[FRAME.F3_FREQ] << 1) & WORD)) >>> 0;
+        voicing = cur[FRAME.VOICING];
+        // 0x5574: unvoiced setup.
+        noise = undefined;
+        if (voicing !== 0) {
+            // 0x5580: this frame's own bit 7 decides D3, but only ever *arms* the
+            // sticky D6 flag above — see `mixed`.
+            if (voicing & 0x80)
+                mixed = true;
+            // 0x558c: without the mixed bit there is no voiced formant at all.
+            else
+                d3 = 0;
+            noiseAmp = (voicing & 0x0f) << 5;
+            noise = t.fricatives?.[(voicing >> 4) & 7];
+        }
+        // 0x5562-0x5570. `ble` is signed, so this runs for a voicing byte of
+        // 1..0x7f — pure noise, no mixed bit — and it *edits the frame array*:
+        // this frame's three amplitudes and the next frame's are zeroed on the
+        // spot. Amplitudes are only sampled at a pitch pulse, so a pulse landing
+        // on or just after a fricative reads the zeros rather than what the front
+        // end put there. Leaving it out is invisible until a plosive.
+        if (voicing > 0 && voicing < 0x80) {
+            for (const base of [fp, fp + FRAME_BYTES]) {
+                if (base + FRAME.F3_AMP < frames.length) {
+                    frames[base + FRAME.F1_AMP] = 0;
+                    frames[base + FRAME.F2_AMP] = 0;
+                    frames[base + FRAME.F3_AMP] = 0;
+                }
+            }
+        }
+        fp += FRAME_BYTES;
+        return true;
+    };
+    /** 0x55ac: the per-frame counter dance, for every frame after the first. */
+    const nextFrame = () => {
+        if (!decode())
+            return false;
+        d0 = (d0 & ~WORD) | t.periodCount;
+        d0 = swap(d0);
+        d0 = dec(d0);
+        if (sword(d0) < 0)
+            pitchPulse(cur);
+        d0 = swap(d0);
+        return true;
+    };
+    // 0x5486: the first frame skips all of that and goes straight to the pulse,
+    // with the frame counter already sitting in the high half from 0x5480.
+    if (!decode())
+        return Int8Array.from(out);
+    pitchPulse(cur);
+    d0 = swap(d0);
+    for (;;) {
+        if (voicing === 0) {
+            // ------------------------------------------------ 0x548a, voiced
+            let d7 = wave[a0 + ((lo(d1) >>> 4) & 0x3f)] | d3;
+            let acc = amp[d7 & (amp.length - 1)];
+            // 0x54a2: the shift is on the whole longword, *then* the halves are
+            // swapped apart — so F3's low nibbles pass through F2's word and are
+            // masked off there. Shifting after the swap gets a different number.
+            const ph = (d2 >>> 4) >>> 0;
+            // 0x54aa `move.l D4,D6` — and D4's bit 31 is always clear (its high word
+            // is an amplitude byte shifted left 5), so this is the one thing that
+            // disarms the sticky mixed flag.
+            mixed = false;
+            d7 = wave[a0 + (ph & 0xfff)] | lo(d4);
+            acc = (acc + amp[d7 & (amp.length - 1)]) & 0xff;
+            d7 = wave[a0 + (hi(ph) & 0xfff)] | hi(d4);
+            acc = (acc + amp[d7 & (amp.length - 1)]) & 0xff;
+            out.push(acc, acc); // 0x54c0-0x54c2: twice
+        }
+        else {
+            // ------------------------------------------------ 0x5610, unvoiced
+            // `moveq #$0,D4` opens this loop and D4 *is* the packed F2/F3
+            // amplitudes — the noise path reuses it as a scratch index. So an
+            // unvoiced frame destroys them, and the voiced frames that follow run
+            // with F2 and F3 silent until the next pitch pulse reloads the pair.
+            // That is audible: it is why a vowel after a fricative starts as F1
+            // alone. Nothing announces it; the register is simply gone.
+            d4 = 0;
+            // One noise byte yields *two* samples, from its low nibble then its
+            // high one — not a duplicated pair. That is why unvoiced output looks
+            // undoubled while voiced output is exactly doubled.
+            let voiced = 0;
+            if (mixed) { // 0x561a: bit 31 of the amplitudes
+                const w = wave[a0 + ((lo(d1) >>> 4) & 0x3f)] & 0x1f;
+                voiced = amp[(w | d3) & (amp.length - 1)];
+            }
+            const b = noise ? noise[noiseIndex] : 0;
+            const s1 = (voiced + amp[(((b & 0x0f) << 1) | noiseAmp) & (amp.length - 1)]) & 0xff;
+            const s2 = (amp[(((b & 0xf0) >>> 3) | noiseAmp) & (amp.length - 1)] + voiced) & 0xff;
+            out.push(s1, s2); // 0x5648 and 0x565a
+            // 0x56b2: the index ping-pongs rather than wrapping — it walks to the
+            // end of the 0x1e0-byte table, reverses, and walks back. Wrapping would
+            // put a discontinuity in the noise once per pass.
+            noiseIndex += noiseStep;
+            if (noiseIndex === 0 || noiseIndex === NOISE_END)
+                noiseStep = -noiseStep;
+        }
+        if (voicing === 0 || mixed) {
+            if (voicing === 0) {
+                // -------------------------------------------------------- 0x5518
+                d1 = lo(d1 + f1inc) & 0x3ff;
+                d2 = (((swap(d2) >>> 0) + f2f3inc) >>> 0);
+                d2 = swap(d2) & 0x03ff03ff;
+                if (--waveCount === 0) {
+                    a0 += 0x40;
+                    waveCount = t.waveStep;
+                }
+            }
+            else {
+                // 0x56ca: a mixed frame advances only F1, and zeroes the pair —
+                // it jumps straight to the counters, past the waveform stepping.
+                d1 = lo(d1 + f1inc) & 0x3ff;
+                d2 = 0;
+            }
+            // ---------------------------------------------------------- 0x5540
+            d0 = dec(d0);
+            if (sword(d0) < 0) {
+                if (!nextFrame())
+                    done = true;
+            }
+            else {
+                // 0x55b0: the frame is not over, but the pitch counter still ticks —
+                // and a pulse mid-frame reloads the amplitudes just the same.
+                d0 = swap(d0);
+                d0 = dec(d0);
+                if (sword(d0) < 0)
+                    pitchPulse(cur);
+                d0 = swap(d0);
+            }
+        }
+        else {
+            // 0x56dc: pure noise never ticks the pitch counter and never touches
+            // a phase. It only counts the frame down.
+            d0 = dec(d0);
+            if (sword(d0) < 0 && !nextFrame())
+                done = true;
+        }
+        if (done)
+            break;
+    }
+    const whole = out.length - (out.length % BUFFER_BYTES);
+    return Int8Array.from(out.slice(0, whole).map((v) => (v << 24) >> 24));
+}

package/dist/narrator/rewrite.d.ts

@@ -0,0 +1,55 @@
+/**
+ * narrator.device's allophonic rewrite engine — hunk+0x12d8 of build 33.2.
+ *
+ * One table-driven pass over the phoneme array, run twice by the driver with
+ * different rules. The first pass is allophony proper: `T` between vowels
+ * becomes the flap `DX`, `D` before `R` becomes `J`, `UL` becomes `AX L`. The
+ * second expands phonemes into the several frames they are really made of —
+ * diphthongs gain their second half, and `P`/`T`/`K` gain a release whose
+ * identity depends on whether an `S` precedes, which is the difference
+ * between "pin" and "spin".
+ *
+ * Both tables come out of the binary with `tools/extract-rewrite-rules.py`.
+ * See research/02-narrator.md.
+ */
+/** One rule, as `extract-rewrite-rules.py` reads it. */
+export interface Rule {
+    /** Phoneme to match, `0xff` for any. */
+    match: number;
+    /** Left neighbour, `0xff` for any. */
+    left: number;
+    /** Right neighbour, `0xff` for any. */
+    right: number;
+    /** Byte 3's high nibble — see `RULE`. The low nibble was the rule's length
+     *  and is consumed by the extractor. */
+    flags: number;
+    /** Replacement, `0xff` to leave the phoneme alone. */
+    replace: number;
+    insertBefore: number;
+    insertAfter: number;
+    /** Attribute tests, in three groups: this phoneme, then left, then right. */
+    tests: number[];
+}
+export declare const RULE: {
+    /** Bit 5: after applying, keep scanning rules at this same position. */
+    readonly RESCAN: number;
+    /** Bit 6: if the right neighbour is a space, test the one beyond it. */
+    readonly SKIP_RIGHT: number;
+    /** Bit 7: likewise leftwards. */
+    readonly SKIP_LEFT: number;
+};
+export interface RewriteState {
+    phonemes: Uint8Array;
+    stress: Uint8Array;
+    flags: Uint8Array;
+    /** The device's `A5+0x9a`. Insertions grow it. */
+    count: number;
+}
+/** Attribute longwords indexed by phoneme — the table at hunk+0x2f08. */
+export type Attrs = readonly number[];
+/**
+ * Run one rewrite pass, in place. False if an insertion would overflow the
+ * 0x200-entry arrays, which the device reports as an error rather than
+ * truncating.
+ */
+export declare function rewrite(state: RewriteState, rules: readonly Rule[], attrs: Attrs): boolean;

package/dist/narrator/rewrite.js

@@ -0,0 +1,155 @@
+/**
+ * narrator.device's allophonic rewrite engine — hunk+0x12d8 of build 33.2.
+ *
+ * One table-driven pass over the phoneme array, run twice by the driver with
+ * different rules. The first pass is allophony proper: `T` between vowels
+ * becomes the flap `DX`, `D` before `R` becomes `J`, `UL` becomes `AX L`. The
+ * second expands phonemes into the several frames they are really made of —
+ * diphthongs gain their second half, and `P`/`T`/`K` gain a release whose
+ * identity depends on whether an `S` precedes, which is the difference
+ * between "pin" and "spin".
+ *
+ * Both tables come out of the binary with `tools/extract-rewrite-rules.py`.
+ * See research/02-narrator.md.
+ */
+import { MAX_PHONEMES, TERMINATOR } from './parse.js';
+export const RULE = {
+    /** Bit 5: after applying, keep scanning rules at this same position. */
+    RESCAN: 1 << 1,
+    /** Bit 6: if the right neighbour is a space, test the one beyond it. */
+    SKIP_RIGHT: 1 << 2,
+    /** Bit 7: likewise leftwards. */
+    SKIP_LEFT: 1 << 3,
+};
+/** A test byte, from `+7` onwards. */
+const TEST = {
+    /** Bits 0-4: which bit of the subject to test. */
+    BIT: 0x1f,
+    /** Bit 5: invert the subject first. */
+    INVERT: 0x20,
+    /** Bit 6: the subject is the attribute longword, not the stress byte. */
+    ATTRS: 0x40,
+    /** Bit 7: this is the last test in its group. */
+    LAST: 0x80,
+};
+/**
+ * Run one rewrite pass, in place. False if an insertion would overflow the
+ * 0x200-entry arrays, which the device reports as an error rather than
+ * truncating.
+ */
+export function rewrite(state, rules, attrs) {
+    const { phonemes, stress, flags } = state;
+    /**
+     * 0x13e4: one group of attribute tests, starting at `from`. Returns the
+     * index just past the group, or -1 if it failed.
+     *
+     * A test *passes* when its bit is clear — which reads backwards until you
+     * notice the caller branches on `bne`.
+     */
+    const group = (rule, from, phoneme, stressByte) => {
+        let t = from;
+        for (;;) {
+            const test = rule.tests[t];
+            // A group with no bytes left passes: the rule simply has fewer tests
+            // than the three groups could use.
+            if (test === undefined)
+                return t;
+            let subject = test & TEST.ATTRS ? (attrs[phoneme] ?? 0) : stressByte;
+            if (test & TEST.INVERT)
+                subject = ~subject;
+            if ((subject >>> (test & TEST.BIT)) & 1)
+                return -1;
+            t++;
+            if (test & TEST.LAST)
+                return t;
+        }
+    };
+    /** 0x1308-0x139c: does this rule apply at `at`? */
+    const matches = (rule, at) => {
+        // 0x1308: byte 0, with 0xff as a wildcard rather than a terminator.
+        if (rule.match !== TERMINATOR && rule.match !== phonemes[at])
+            return false;
+        // 0x1324: byte 1, the left neighbour.
+        if (rule.left !== TERMINATOR && rule.left !== phonemes[at - 1])
+            return false;
+        // 0x1334: byte 2. A rule that wants a specific right neighbour never
+        // matches at the end of the array (0x133e).
+        if (rule.right !== TERMINATOR) {
+            if (phonemes[at + 1] === TERMINATOR)
+                return false;
+            if (rule.right !== phonemes[at + 1])
+                return false;
+        }
+        // Three groups of tests, consuming `tests` in order.
+        let t = group(rule, 0, phonemes[at], stress[at]);
+        if (t < 0)
+            return false;
+        // 0x1356: the left neighbour, skipping a space if the rule says to.
+        let li = at - 1;
+        if (phonemes[li] === 0 && rule.flags & RULE.SKIP_LEFT)
+            li = at - 2;
+        t = group(rule, t, phonemes[li], stress[li]);
+        if (t < 0)
+            return false;
+        // 0x1376: the right neighbour likewise, and 0x1390 treats the array's
+        // terminator as a space rather than looking it up. Its *stress* byte is
+        // passed through untouched, terminator and all.
+        let ri = at + 1;
+        if (phonemes[ri] === 0 && rule.flags & RULE.SKIP_RIGHT)
+            ri = at + 2;
+        const rp = phonemes[ri] === TERMINATOR ? 0 : phonemes[ri];
+        return group(rule, t, rp, stress[ri]) >= 0;
+    };
+    // 0x12f8: the scan starts at 1, so rules can see and rewrite the seeded QX.
+    let i = 1;
+    /**
+     * 0x1412: shift the three arrays right and drop `p` in.
+     *
+     * It inserts at `i + 1`, not at `i`, and leaves `i` pointing at what it
+     * inserted. That is why "insert before" is written as decrement, insert,
+     * increment — the caller moves the cursor rather than the routine taking a
+     * position.
+     */
+    const insert = (p) => {
+        const n = state.count;
+        if (n >= MAX_PHONEMES)
+            return false;
+        state.count = n + 1;
+        for (let k = n; k > i + 1; k--) {
+            phonemes[k] = phonemes[k - 1];
+            stress[k] = stress[k - 1];
+            flags[k] = flags[k - 1];
+        }
+        i++;
+        phonemes[i] = p;
+        stress[i] = 0;
+        flags[i] = 0;
+        return true;
+    };
+    for (; i <= MAX_PHONEMES; i++) {
+        if (phonemes[i] === TERMINATOR)
+            return true; // 0x12fe
+        // 0x12f6: every position restarts at the first rule.
+        for (let r = 0; r < rules.length; r++) {
+            const rule = rules[r];
+            if (!matches(rule, i))
+                continue;
+            // 0x13a0: replacement, then the two insertions.
+            if (rule.replace !== TERMINATOR)
+                phonemes[i] = rule.replace;
+            if (rule.insertBefore !== TERMINATOR) {
+                i--;
+                if (!insert(rule.insertBefore))
+                    return false;
+                i++;
+            }
+            if (rule.insertAfter !== TERMINATOR && !insert(rule.insertAfter))
+                return false;
+            // 0x13d6: with the rescan bit set the scan carries on through the
+            // remaining rules at this position; without it the position is done.
+            if (!(rule.flags & RULE.RESCAN))
+                break;
+        }
+    }
+    return true;
+}

package/dist/narrator/speak.d.ts

@@ -0,0 +1,120 @@
+/**
+ * narrator.device's front half, end to end — `hunk+0x7fe` to `hunk+0x872` of
+ * build 33.2.
+ *
+ * The device's `CMD_WRITE` is a straight run of eleven jumps, and this is
+ * those eleven with the arrays threaded between them. Nothing here is a
+ * decision of its own: every stage is a routine ported and checked on its own
+ * against the binary, and the only thing this adds is the order and the shape
+ * of the workspace they share.
+ *
+ * The output is a **frame array** — eight bytes per frame, the thing
+ * `render()` turns into samples — and, if asked, the mouth-shape stream that
+ * runs alongside it.
+ *
+ * The tables are a parameter rather than a constant. They are Commodore's,
+ * extracted from a binary this project does not redistribute, so the library
+ * takes them from the caller and ships none.
+ */
+import { type Params } from './frames.js';
+import { MAX_PHONEMES, TERMINATOR, type PhonemeTable } from './parse.js';
+import { type Attrs, type Rule } from './rewrite.js';
+import { type RenderOptions, type VoiceData } from './voice.js';
+/** Everything the synthesizer reads out of the device's own data. */
+export interface Voice {
+    /** The spellings the parser matches, and their attributes. */
+    table: PhonemeTable;
+    /** One attribute longword per phoneme — `hunk+0x2f08`. */
+    attrs: Attrs;
+    /** The per-phoneme parameter columns — `hunk+0x3506` onwards. */
+    params: Params;
+    /** The second voice's three frequency columns — `hunk+0x50ae`. */
+    altParams: Pick<Params, 'f1' | 'f2' | 'f3'>;
+    /** The 32-entry amplitude curve — `hunk+0x2cfc`. */
+    gain: readonly number[];
+    /** The two rewrite rule sets — `hunk+0x968` and `hunk+0xae3`. */
+    rules: readonly [readonly Rule[], readonly Rule[]];
+}
+/** The fields of `narrator_rb` the front half looks at. */
+export interface SpeakOptions {
+    /** `A5+0x1c`. Divided into a constant to get every pitch period. */
+    pitch?: number;
+    /** `A5+0x30`. 1 is the monotone robot voice. */
+    mode?: number;
+    /** `A5+0x34`. 1 swaps in the second voice's formant frequencies. */
+    sex?: number;
+    /** `A5+0xdb`. Asks for the lip-sync stream as well. */
+    mouths?: boolean;
+}
+export interface Speech {
+    /** Eight bytes per frame, with one terminator frame past the end. */
+    frames: Uint8Array;
+    /** Input bytes this sentence took — see {@link Parsed.consumed}. */
+    consumed: number;
+    /** Frames written, terminator excluded — the device's `A5+0x3a`. */
+    total: number;
+    /**
+     * One byte per frame, a width in the low nibble and a height in the high
+     * one. Only when `mouths` was asked for.
+     */
+    mouths?: Uint8Array;
+}
+/** What the device reports in `io_Error` rather than speaking. */
+export declare class SpeakError extends Error {
+    /** 1-based offset of the offending character, when the parser found one. */
+    readonly at?: number | undefined;
+    constructor(message: string, 
+    /** 1-based offset of the offending character, when the parser found one. */
+    at?: number | undefined);
+}
+/**
+ * Turn a phoneme string into frames, exactly as `CMD_WRITE` does.
+ *
+ * **One sentence per call.** The parser stops at the first `.` or `?` and
+ * reports how much of the input it took; `hunk+0x8ba` loops on that, speaking
+ * each sentence as a separate buffer. {@link synthesize} is that loop, and
+ * this is one turn of it — which is what a caller wants only if it is doing
+ * the looping itself.
+ *
+ * `input` is bytes rather than a string because the device works in Latin-1
+ * and reads one byte past what it was given.
+ */
+export declare function synthesizeSentence(input: Uint8Array, voice: Voice, opts?: SpeakOptions): Speech | null;
+/**
+ * Everything a string has to say, one buffer per sentence.
+ *
+ * `hunk+0x7e6` to `hunk+0x8bc` — the driver's outer loop. It runs the whole
+ * pipeline, hands the frames to `audio.device`, and comes back for whatever
+ * the parser did not take, until the parser reports nothing left.
+ *
+ * The buffers are kept apart rather than joined because the device keeps them
+ * apart: every one is a separate `CMD_WRITE` to the audio hardware, and the
+ * renderer's waveform pointer and pitch phase start again at each. Joining
+ * the frames and rendering once would give different samples.
+ */
+export declare function synthesize(input: Uint8Array, voice: Voice, opts?: SpeakOptions): Speech[];
+/** Re-exported so a caller can size a buffer without reaching into `parse`. */
+export { MAX_PHONEMES, TERMINATOR };
+/** Samples, and everything that came with them. */
+export interface SpeechResult {
+    /** 8-bit signed PCM, every sentence joined in order. */
+    pcm: Int8Array;
+    /** The Paula period the device would have played it at. */
+    period: number;
+    /** Samples per second, from that period on PAL. */
+    sampleRate: number;
+    /** One entry per sentence, as the device produces them. */
+    sentences: Speech[];
+}
+/**
+ * Phonemes in, samples out — `CMD_WRITE` and the audio it would have written.
+ *
+ * Each sentence is rendered on its own and the samples joined, because that
+ * is what the device does: every sentence is a separate buffer handed to
+ * `audio.device`, and the renderer's waveform pointer and pitch phase start
+ * again at each.
+ *
+ * `input` is bytes rather than a string because the device works in Latin-1
+ * and reads one byte past what it was given.
+ */
+export declare function speak(input: Uint8Array, data: VoiceData, opts?: SpeakOptions & RenderOptions): SpeechResult;