narrator-ts 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gareth Davidson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,116 @@
 # narrator-ts
 
-Placeholder. npm cannot configure trusted publishing for a package that does
-not exist yet, so this version exists only to create the name.
+TypeScript reimplementation of the Amiga's speech pair: `translator.library`
+(English to phonemes) and `narrator.device` 33.2 (phoneme formant synthesis).
 
-The real thing is 0.1.0 and later — published from CI, with provenance.
+Output is Paula-native — 8-bit signed samples and the period they were written
+with. Verified against the real binaries running under a 68000 emulator:
+byte-exact translation on 15,405 phrases, sample-exact synthesis end to end.
+
+```sh
+npm install narrator-ts
+```
+
+```ts
+import { speak } from 'narrator-ts'
+import { translate } from 'narrator-ts/translator'
+import rules from 'narrator-ts/reference/nrl-table.json' with { type: 'json' }
+import voice from 'narrator-ts/reference/voice-free.json' with { type: 'json' }
+
+const { phonemes } = translate('hello world', rules)   // '/HEHLOW WERLD '
+const { pcm, sampleRate } = speak(Buffer.from(phonemes, 'latin1'), voice)
+// Int8Array(26112) at 22030 Hz
+```
+
+Both tables are the free ones, so that runs with nothing else installed. Swap
+either for an extracted Amiga table to get the authentic voice — see below.
+
+`pcm` is 8-bit signed. `speak` takes `narrator_rb`'s own parameters —
+`pitch`, `rate`, `sex`, `mode`, `sampfreq`, `mouths` — and returns one entry
+per sentence alongside the joined samples, because that is how the device
+produces them.
+
+## Voices
+
+A voice is ~12 KB of tables: formant frequencies and amplitudes per phoneme,
+durations, allophonic rewrite rules, the glottal waveform, fricative noise.
+They are a *parameter*, not built in.
+
+**The authentic Amiga voice** is Commodore and SoftVoice's, so it is not in
+this repository. Extract it from Workbench disk images you already own:
+
+```sh
+python3 tools/extract-devices.py /path/to/workbench-disks -o fixtures/amiga
+python3 tools/gen-voice.py   fixtures/amiga/narrator_device-33.2-*.bin     -o data
+python3 tools/gen-tables.py  fixtures/amiga/translator_library-33.2-1*.bin -o data
+```
+
+**The free voice** is `reference/voice-free.json`, built from published
+phonetics by `tools/gen-free-voice.py` and owing nothing to anyone. It is the
+default, so a fresh clone speaks. It is not the Amiga's voice and does not
+claim to be — `reference/README.md` says what is measured and what is still
+provisional.
+
+The letter-to-sound half has its free equivalent too, and is the default when
+no Amiga table has been extracted:
+
+```ts
+import nrl from 'narrator-ts/reference/nrl-table.json' with { type: 'json' }
+translate('hello world', nrl)   // '/HEHLOW WERLD '
+```
+
+That is the rule set of NRL Report 7948 (Elovitz et al., 1976 — a US
+Government work), rebuilt from the report alone. It is not byte-compatible
+with the Amiga and is not meant to be: 64.6% of distinct words match.
+`research/03-nrl-provenance.md` has the measurements.
+
+## Command line
+
+```sh
+npm run say -- 'hello world' -o hello.wav          # the free voice
+npm run say -- 'hello world' -o hello.wav -V 33.2  # an extracted Amiga one
+npm run say -- -p '/HEH4LOW WER4LD' -o hello.wav
+npm run say -- 'is this a question' --pitch 200 --rate 100
+```
+
+`--pitch --rate --sex --mode --sampfreq --mouths` are `narrator_rb`'s own
+fields. `npm run say` with no arguments prints them.
+
+Every tool under `tools/` takes `--help`.
+
+## Status
+
+| | |
+|---|---|
+| translator | byte-exact against all 6 shipped builds |
+| narrator 33.2 | byte-exact front half, sample-exact renderer, end to end |
+| free letter-to-sound table | built, divergence measured |
+| free voice | **speaks**; texture within a few percent of 33.2's, no allophonic rules yet |
+
+`narrator.device` 37.7 is a rewrite and is **out of scope** — one voice done
+properly. 1.6, 31.13, 33.2 and 36.9 are sample-identical over 4,865 phrases,
+so 33.2 covers four of the five shipped builds anyway.
+
+## Licence
+
+Code is MIT.
+
+The Amiga binaries and everything derived by running them are not
+redistributable and are gitignored: `fixtures/amiga/*.bin`,
+`fixtures/golden/`, `data/`. None has ever been committed.
+
+`reference/` is the opposite — material that can be redistributed, with its
+provenance recorded in `reference/README.md`.
+
+`narrator.device`'s copyright line reads *Mark Barton / Joseph Katz*. It was
+licensed in from SoftVoice, Inc.; Commodore never owned it.
+
+## Documentation
+
+| | |
+|---|---|
+| `docs/development.md` | building the oracle, regenerating fixtures, coverage |
+| `research/00-findings.md` | what the binaries turned out to be |
+| `research/01-translator.md` | the letter-to-sound engine |
+| `research/02-narrator.md` | the synthesizer, stage by stage |
+| `research/03-nrl-provenance.md` | which rules came from NRL and which SoftVoice added |

package/dist/narrator/contour.d.ts

@@ -0,0 +1,90 @@
+/**
+ * narrator.device's contour marker — hunk+0x19c4 of build 33.2.
+ *
+ * The last thing that happens to the stress array. Everything the spreader and
+ * the duration stage put in the low nibble is thrown away, and three flags go
+ * back in their place marking where the pitch contour has to be pinned:
+ *
+ * | | |
+ * |---|---|
+ * | 1 | a vowel, the syllable's pitch peak |
+ * | 2 | the phoneme just after it, where the fall begins |
+ * | 4 | the last voiced phoneme before the fall runs out |
+ *
+ * `hunk+0x1a8e` then writes a pitch value into the frame array at each of
+ * those, and the renderer's last stage interpolates between them — which is
+ * why a captured frame array has a pitch byte at a handful of frames and
+ * zeroes in between until `0x29d8` has run.
+ */
+import type { Attrs } from './rewrite.js';
+/** Flags this stage writes into the low nibble of the stress byte. */
+export declare const CONTOUR: {
+    /** The vowel. */
+    readonly PEAK: 1;
+    /** The phoneme after it. */
+    readonly FALL: 2;
+    /** The end of the voiced run. */
+    readonly END: 4;
+};
+export interface ContourState {
+    phonemes: Uint8Array;
+    stress: Uint8Array;
+}
+/** Mark where the pitch contour is pinned, in place. */
+export declare function markContour(state: ContourState, attrs: Attrs): void;
+/**
+ * The numerator of every pitch period this device computes — `hunk+0x1a9e`.
+ *
+ * 1,221,000 is exactly 11,100 x the default pitch of 110, and the whole
+ * routine below is `constant / pitch / contourValue`. It is a constant in the
+ * binary, so it assumes the default sample rate; changing `sampfreq` does not
+ * move it.
+ */
+export declare const PERIOD_NUMERATOR = 1221000;
+/**
+ * The four per-syllable arrays `hunk+0x2160` fills, one entry per vowel.
+ *
+ * `arr0`, `arr1` and `arr2` are the three points of one syllable's pitch, in
+ * the order the device reads them out — where it starts, how high it gets,
+ * where it ends. `peak` sits between the other two in memory, which is what
+ * makes the layout confusing; it is nonetheless the highest of the three, and
+ * `hunk+0x2642` builds the other two by subtracting distances from it.
+ *
+ * They are frequencies, so a larger number is a higher note. The frame array
+ * holds periods, and every value here is divided into a constant on its way in.
+ */
+export interface PitchArrays {
+    /** `arr0`: the pitch the syllable starts on. */
+    onset: Uint8Array;
+    /** `arr1`: the pitch it reaches. */
+    peak: Uint8Array;
+    /** `arr2`: the pitch it ends on — above the peak for a question. */
+    end: Uint8Array;
+    /** `arr3`: bits 4-6 are a rise added after the fall; zero means no third leg. */
+    tail: Uint8Array;
+}
+export interface PitchOptions {
+    /** `A5+0x1c` — the device's `pitch` parameter. */
+    pitch: number;
+    /** `A5+0x30` — 1 selects the monotone robot voice. */
+    mode: number;
+}
+/**
+ * narrator.device's pitch pass — hunk+0x1a8e of build 33.2.
+ *
+ * It writes a period into the pitch byte of a *handful* of frames — the ones
+ * the contour marker pinned — and leaves the rest at zero for the renderer's
+ * last stage to interpolate between. So a captured frame array at this point
+ * has three or four pitch values in it and nothing in between.
+ *
+ * Every value is `1221000 / pitch / v`, so a larger `v` in the arrays is a
+ * *lower* note: they hold frequencies and the frame holds a period.
+ *
+ * Per syllable it pins up to four points — the onset on the syllable's first
+ * frame, the end on the last frame before the fall, the peak at a position
+ * weighted by how far the pitch has to travel between them, and, when the
+ * fourth array is non-zero, a rise back up at the end of the voiced run.
+ */
+export declare function assignPitch(state: ContourState & {
+    flags: Uint8Array;
+}, arrays: PitchArrays, frames: Uint8Array, opts: PitchOptions): void;

package/dist/narrator/contour.js

@@ -0,0 +1,235 @@
+/**
+ * narrator.device's contour marker — hunk+0x19c4 of build 33.2.
+ *
+ * The last thing that happens to the stress array. Everything the spreader and
+ * the duration stage put in the low nibble is thrown away, and three flags go
+ * back in their place marking where the pitch contour has to be pinned:
+ *
+ * | | |
+ * |---|---|
+ * | 1 | a vowel, the syllable's pitch peak |
+ * | 2 | the phoneme just after it, where the fall begins |
+ * | 4 | the last voiced phoneme before the fall runs out |
+ *
+ * `hunk+0x1a8e` then writes a pitch value into the frame array at each of
+ * those, and the renderer's last stage interpolates between them — which is
+ * why a captured frame array has a pitch byte at a handful of frames and
+ * zeroes in between until `0x29d8` has run.
+ */
+import { TERMINATOR } from './parse.js';
+/** Flags this stage writes into the low nibble of the stress byte. */
+export const CONTOUR = {
+    /** The vowel. */
+    PEAK: 1,
+    /** The phoneme after it. */
+    FALL: 2,
+    /** The end of the voiced run. */
+    END: 4,
+};
+/** Bits this stage reads. */
+const ATTR = {
+    /** Bit 0: a vowel. */
+    VOWEL: 1 << 0,
+    /** Bit 7: the duration is split across two slots. */
+    SPLIT: 1 << 7,
+    /** Bit 9: voiced. */
+    VOICED: 1 << 9,
+    /** Bit 25: ends a phrase. */
+    TERMINAL: 1 << 25,
+};
+/** 0x80 in a stress byte: the spreader marked this phoneme. */
+const MARK = 0x80;
+/** The two that are vowels by attribute but never syllable nuclei. */
+const RX = 0x17;
+const LX = 0x18;
+/** Mark where the pitch contour is pinned, in place. */
+export function markContour(state, attrs) {
+    const { phonemes, stress } = state;
+    // 0x19c4: clear every low nibble first. Nothing downstream wants what the
+    // earlier stages left there.
+    for (let i = 0; stress[i] !== TERMINATOR; i++)
+        stress[i] &= 0xf0;
+    // `i` is the index just read; the device's A0 and A1 are then one past it,
+    // so `stress[i + 1]` is its `(A1)` and `stress[i - 1]` its `(-2,A1)`.
+    let i = -1;
+    /**
+     * A lookup past the attribute table's 102 entries reads unrelated bytes in
+     * the device and zero here. Reachable only for the `0xff` terminator, whose
+     * stress byte is tested before its attributes are, so no utterance gets
+     * there — but the difference is real and is written down rather than
+     * guarded against.
+     */
+    const attrOf = (p) => attrs[p] ?? 0;
+    for (;;) {
+        // ---------------------------------------------------------- 0x19e6
+        i++;
+        if (phonemes[i] === TERMINATOR)
+            return;
+        let a = attrOf(phonemes[i]);
+        let s = stress[i];
+        // 0x19fa: only a phoneme the spreader marked starts a contour.
+        marked: while (s & MARK) {
+            // 0x1a00: walk forward to the syllable's vowel. Note this loop is
+            // re-entered at the *vowel* test, not at the mark test above — a
+            // consonant inside the span does not need marking again.
+            while (!(a & ATTR.VOWEL)) {
+                i++;
+                a = attrOf(phonemes[i]);
+                s = stress[i];
+                if (s & MARK || a & ATTR.TERMINAL) {
+                    // 0x1a78: the span ran out before a vowel turned up — pin all three
+                    // flags across the last two slots and go back to the mark test.
+                    stress[i - 1] |= CONTOUR.PEAK;
+                    stress[i] |= CONTOUR.FALL | CONTOUR.END;
+                    continue marked;
+                }
+            }
+            // ---------------------------------------------------------- 0x1a24
+            stress[i] |= CONTOUR.PEAK;
+            // 0x1a2a: the fall normally starts on the phoneme after the vowel, but
+            // a split phoneme and the two non-nucleus vowels push it one further.
+            const after = phonemes[i + 1];
+            if (a & ATTR.SPLIT || after === LX || after === RX)
+                stress[i + 2] |= CONTOUR.FALL;
+            else
+                stress[i + 1] |= CONTOUR.FALL;
+            // 0x1a44: `end` tracks the last voiced phoneme seen, and starts on the
+            // one holding the fall.
+            let end = i + 1;
+            // ---------------------------------------------------------- 0x1a50
+            for (;;) {
+                i++;
+                a = attrOf(phonemes[i]);
+                s = stress[i];
+                if (s & MARK || a & ATTR.TERMINAL)
+                    break;
+                if (a & ATTR.VOICED)
+                    end = i + 1;
+            }
+            stress[end] |= CONTOUR.END;
+            // 0x1a76 re-enters at the mark test rather than the outer loop, so a
+            // span that ends on another marked phoneme starts the next contour
+            // without stepping over it.
+        }
+    }
+}
+/**
+ * The numerator of every pitch period this device computes — `hunk+0x1a9e`.
+ *
+ * 1,221,000 is exactly 11,100 x the default pitch of 110, and the whole
+ * routine below is `constant / pitch / contourValue`. It is a constant in the
+ * binary, so it assumes the default sample rate; changing `sampfreq` does not
+ * move it.
+ */
+export const PERIOD_NUMERATOR = 0x12a188;
+/** The `pitch` the monotone mode uses regardless of the parameter. */
+const MONOTONE_PITCH = 0x6e;
+/** Frame stride, and the offset of the pitch byte within a frame. */
+const FRAME = 8;
+const PITCH_BYTE = 7;
+/**
+ * narrator.device's pitch pass — hunk+0x1a8e of build 33.2.
+ *
+ * It writes a period into the pitch byte of a *handful* of frames — the ones
+ * the contour marker pinned — and leaves the rest at zero for the renderer's
+ * last stage to interpolate between. So a captured frame array at this point
+ * has three or four pitch values in it and nothing in between.
+ *
+ * Every value is `1221000 / pitch / v`, so a larger `v` in the arrays is a
+ * *lower* note: they hold frequencies and the frame holds a period.
+ *
+ * Per syllable it pins up to four points — the onset on the syllable's first
+ * frame, the end on the last frame before the fall, the peak at a position
+ * weighted by how far the pitch has to travel between them, and, when the
+ * fourth array is non-zero, a rise back up at the end of the voiced run.
+ */
+export function assignPitch(state, arrays, frames, opts) {
+    const { stress, flags } = state;
+    // 0x1a9e. The immediate is loaded twice; the first is dead.
+    const c = Math.floor(PERIOD_NUMERATOR / opts.pitch) & 0xffff;
+    /** `divu.w`: 32-bit over 16-bit, quotient in the low word. */
+    const period = (v) => (v === 0 ? 0xff : Math.floor(c / v) & 0xff);
+    if (opts.mode === 1) {
+        // 0x1bca: one period everywhere, and it ignores `pitch` for the contour
+        // even though `pitch` is still in `c`. This is the robot voice.
+        const flat = period(MONOTONE_PITCH);
+        for (let at = PITCH_BYTE; frames[at] !== 0xff; at += FRAME)
+            frames[at] = flat;
+        return;
+    }
+    let i = 0; // A1 and A2, which move together
+    let v = 0; // A3, one step per syllable
+    let at = 0; // A6, a byte offset into the frame array
+    for (;;) {
+        // -------------------------------------------------------------- 0x1ad2
+        if (flags[i] === TERMINATOR) {
+            // 0x1ada: `(-1,A3,0x100)` is where the *previous* syllable ended, and
+            // it goes on the frame before the cursor — the utterance's last pitch.
+            frames[at - 1] = period(arrays.end[v - 1]);
+            return;
+        }
+        const duration = flags[i] & 0x3f;
+        const peak = stress[i] & CONTOUR.PEAK;
+        i++;
+        if (!peak) {
+            at += duration * FRAME;
+            continue;
+        }
+        // -------------------------------------------------------------- 0x1b00
+        const hi = arrays.onset[v];
+        const mid = arrays.peak[v];
+        const lo = arrays.end[v];
+        // 0x1b2a: only bits 4-6, halved. Zero here means the contour stops at the
+        // fall instead of rising again.
+        const rise = (arrays.tail[v] & 0x70) >> 1;
+        v++;
+        frames[at + PITCH_BYTE] = period(hi);
+        // 0x1b32: the run to the fall starts with the peak phoneme's own length,
+        // which is why the entry is into the middle of the loop.
+        let span = duration * FRAME;
+        for (;;) {
+            const d = flags[i] & 0x3f;
+            const fall = stress[i] & CONTOUR.FALL;
+            i++;
+            if (fall)
+                break;
+            span = (span + d * FRAME) & 0xffff;
+        }
+        // 0x1b4e: with a third leg to come, the fall is squeezed into the first
+        // half of the run — `n - n/2`, so an odd number of frames rounds up.
+        let off = span;
+        if (rise !== 0) {
+            const f = off >> 3;
+            off = ((f - (f >> 1)) << 3) & 0xffff;
+        }
+        frames[at + off - 1] = period(lo);
+        // 0x1b66: the middle is placed by how far the pitch has to travel on each
+        // leg, not at the halfway point in time — a big drop early puts it early.
+        let travel = Math.abs(((hi - mid) << 16) >> 16) & 0xffff;
+        const scaled = (travel << 5) & 0xffff;
+        travel = (travel + (Math.abs(((mid - lo) << 16) >> 16) & 0xffff)) & 0xffff;
+        if (travel !== 0) {
+            let atMid = Math.floor(scaled / travel) & 0xffff;
+            atMid = (atMid * off) & 0xffff;
+            atMid = ((atMid >> 8) << 3) & 0xffff;
+            frames[at + atMid - 1] = period(mid);
+        }
+        // 0x1b90: step back over the phoneme that carried the fall — it is the
+        // start of the next span, not the end of this one.
+        i--;
+        at += span;
+        if (rise === 0)
+            continue;
+        // -------------------------------------------------------------- 0x1ba0
+        for (;;) {
+            const d = flags[i] & 0x3f;
+            const end = stress[i] & CONTOUR.END;
+            i++;
+            if (end)
+                break;
+            at += d * FRAME;
+        }
+        frames[at - 1] = period((lo + rise) & 0xffff);
+        i--;
+    }
+}

package/dist/narrator/duration.d.ts

@@ -0,0 +1,39 @@
+/**
+ * narrator.device's duration assignment — hunk+0x1be8 of build 33.2.
+ *
+ * Every phoneme has two durations in the binary, in frames: one for when it
+ * carries stress and one for when it does not (`hunk+0x3806` and `+0x3886`,
+ * extracted into fixtures/golden/phonemes-33.2.json). This stage picks a point
+ * between them.
+ *
+ * It does that by accumulating a scale factor in 1/32nds, starting at 32 —
+ * exactly 1.0 — and multiplying in a factor for each thing it notices about
+ * the phoneme's surroundings: a vowel that is not its syllable's nucleus is
+ * shortened, a phrase-final one is stretched by nearly half, a liquid before a
+ * vowel is cut to 3/32 of its length. The factors are integers over 32 and the
+ * rounding is the device's, so the arithmetic here is deliberately not
+ * floating point.
+ *
+ * The result is written into the *flags* array, under the two bits the stress
+ * spreader put there — from here on `flags[i] & 0x3f` is a frame count. That
+ * reuse is why the driver's later stages read durations out of what looks like
+ * the wrong array.
+ *
+ * Runs between the pitch loop and the second rewrite pass. See
+ * research/02-narrator.md.
+ */
+import type { Attrs } from './rewrite.js';
+/** The low six bits of a flag byte are the duration once this has run. */
+export declare const DURATION_MASK = 63;
+export interface DurationState {
+    phonemes: Uint8Array;
+    stress: Uint8Array;
+    flags: Uint8Array;
+}
+/** Per-phoneme frame counts, stressed and unstressed. */
+export interface Durations {
+    stressed: readonly number[];
+    unstressed: readonly number[];
+}
+/** Assign each phoneme a duration in frames, in place. */
+export declare function assignDurations(state: DurationState, attrs: Attrs, table: Durations): void;