narrator-ts 0.1.0 → 0.1.2

package/README.md

@@ -78,6 +78,34 @@ fields. `npm run say` with no arguments prints them.
 
 Every tool under `tools/` takes `--help`.
 
+## AROS resource export
+
+Create the versioned IFF resource consumed by AROS `translator.library`,
+`narrator.device`, and `speech.device`:
+
+```sh
+npm run export:aros -- -o speech.iff
+npm run export:aros -- -o speech.iff \
+  --translator data/translator-33.2.json \
+  --voice data/narrator-33.2.json \
+  --translator-license "User supplied; redistribution not granted" \
+  --voice-license "User supplied; redistribution not granted"
+npm run export:aros -- -o speech-resource.c --format c
+```
+
+The first command uses the redistributable reference tables. The second uses
+locally extracted authentic tables; the resulting file has the same legal
+status as those inputs and should not be redistributed.
+The C form contains the identical IFF payload as a byte array for ROM builds.
+
+`FORM NARR` uses ordinary length-delimited Latin-1 IFF chunks rather than an
+embedded serialization format. `VERS` is the binary resource schema version;
+`FVER` records the narrator-ts package version. `TVER`/`TSRC`/`TLIC` describe
+the translator and `VVER`/`VSRC`/`VLIC` describe the voice, followed by their
+`LTRS` and `NVOI` table chunks. The built-in free inputs are labelled public
+domain. Explicit table paths conservatively default to `User supplied;
+redistribution not granted`; the two `--*-license` options override that text.
+
 ## Status
 
 | | |

package/dist/aros-resource/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * AROS Narrator resource interchange.
+ *
+ * The file is an ordinary big-endian IFF FORM. `LTRS` holds the compact
+ * letter-to-sound table and `NVOI` the subset of a voice consumed by AROS's
+ * bounded narrator engine. Unknown chunks can be skipped by older readers.
+ */
+import type { VoiceData } from '../narrator/voice.js';
+import type { TranslatorTables } from '../translator/types.js';
+export declare const AROS_RESOURCE_FORM = "NARR";
+export declare const AROS_RESOURCE_VERSION = 1;
+declare const VOICE_COLUMNS: readonly ["f1", "f2", "f3", "a1", "a2", "a3", "voicing", "mouth"];
+declare const ALT_VOICE_COLUMNS: readonly ["f1", "f2", "f3"];
+export interface ArosResourceInput {
+    translator?: TranslatorTables;
+    voice?: VoiceData;
+    metadata: {
+        generator: string;
+        translatorLicense?: string;
+        voiceLicense?: string;
+    };
+}
+export interface ArosComponentMetadata {
+    version?: string;
+    source?: string;
+    license?: string;
+}
+export interface ArosResourceMetadata {
+    generator?: string;
+    translator?: ArosComponentMetadata;
+    voice?: ArosComponentMetadata;
+}
+export interface ArosVoiceTables {
+    names: string[];
+    attrs: number[];
+    params: Record<(typeof VOICE_COLUMNS)[number], number[]>;
+    paramsAlt: Record<(typeof ALT_VOICE_COLUMNS)[number], number[]>;
+    stressed: number[];
+    unstressed: number[];
+    fricatives: number[][];
+}
+export interface DecodedArosResource {
+    version: number;
+    metadata: ArosResourceMetadata;
+    translator?: TranslatorTables;
+    voice?: ArosVoiceTables;
+}
+/** Encode free or extracted tables as the AROS deployment resource. */
+export declare function encodeArosResource(input: ArosResourceInput): Uint8Array;
+/** Emit the same IFF bytes as a C array for ROM or built-in resource use. */
+export declare function emitArosCResource(input: ArosResourceInput, symbol?: string): string;
+/** Decode and validate an AROS resource, primarily for tools and tests. */
+export declare function decodeArosResource(bytes: Uint8Array): DecodedArosResource;
+export {};

package/dist/aros-resource/index.js

@@ -0,0 +1,340 @@
+/**
+ * AROS Narrator resource interchange.
+ *
+ * The file is an ordinary big-endian IFF FORM. `LTRS` holds the compact
+ * letter-to-sound table and `NVOI` the subset of a voice consumed by AROS's
+ * bounded narrator engine. Unknown chunks can be skipped by older readers.
+ */
+export const AROS_RESOURCE_FORM = 'NARR';
+export const AROS_RESOURCE_VERSION = 1;
+const VOICE_COLUMNS = [
+    'f1', 'f2', 'f3', 'a1', 'a2', 'a3', 'voicing', 'mouth',
+];
+const ALT_VOICE_COLUMNS = ['f1', 'f2', 'f3'];
+class Writer {
+    bytes = [];
+    u8(value) {
+        if (!Number.isInteger(value) || value < 0 || value > 0xff)
+            throw new RangeError(`not a byte: ${value}`);
+        this.bytes.push(value);
+    }
+    u16(value) {
+        if (!Number.isInteger(value) || value < 0 || value > 0xffff)
+            throw new RangeError(`not a u16: ${value}`);
+        this.bytes.push(value >>> 8, value & 0xff);
+    }
+    u32(value) {
+        if (!Number.isInteger(value) || value < 0 || value > 0xffffffff)
+            throw new RangeError(`not a u32: ${value}`);
+        this.bytes.push((value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff);
+    }
+    raw(values) {
+        for (let i = 0; i < values.length; i++)
+            this.u8(values[i]);
+    }
+    id(value) {
+        if (value.length !== 4)
+            throw new RangeError(`IFF ID must have four characters: ${value}`);
+        for (const c of value)
+            this.u8(c.charCodeAt(0));
+    }
+    latin8(value) {
+        if (value.length > 0xff)
+            throw new RangeError('string is too long');
+        this.u8(value.length);
+        for (const c of value) {
+            const code = c.charCodeAt(0);
+            if (code > 0xff)
+                throw new RangeError(`not Latin-1: ${JSON.stringify(c)}`);
+            this.u8(code);
+        }
+    }
+    text(value, label) {
+        if (value.length === 0 || value.length > 0xff)
+            throw new RangeError(`${label} must be 1..255 bytes`);
+        for (const c of value) {
+            const code = c.charCodeAt(0);
+            if (code === 0 || code > 0xff)
+                throw new RangeError(`${label} is not non-NUL Latin-1 text`);
+            this.u8(code);
+        }
+    }
+    finish() { return Uint8Array.from(this.bytes); }
+}
+class Reader {
+    bytes;
+    at = 0;
+    constructor(bytes) {
+        this.bytes = bytes;
+    }
+    need(count) {
+        if (this.at + count > this.bytes.length)
+            throw new RangeError('truncated AROS speech resource');
+    }
+    u8() { this.need(1); return this.bytes[this.at++]; }
+    u16() { return (this.u8() << 8) | this.u8(); }
+    u32() { return ((this.u8() * 0x1000000) + (this.u8() << 16) + (this.u8() << 8) + this.u8()) >>> 0; }
+    latin8() {
+        const n = this.u8();
+        this.need(n);
+        let out = '';
+        for (let i = 0; i < n; i++)
+            out += String.fromCharCode(this.u8());
+        return out;
+    }
+    vector(count) {
+        this.need(count);
+        const out = Array.from(this.bytes.subarray(this.at, this.at + count));
+        this.at += count;
+        return out;
+    }
+    done() { return this.at === this.bytes.length; }
+}
+function concat(parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const part of parts) {
+        out.set(part, at);
+        at += part.length;
+    }
+    return out;
+}
+function chunk(id, payload) {
+    const w = new Writer();
+    w.id(id);
+    w.u32(payload.length);
+    w.raw(payload);
+    if (payload.length & 1)
+        w.u8(0);
+    return w.finish();
+}
+function textChunk(id, value) {
+    const w = new Writer();
+    w.text(value, id);
+    return chunk(id, w.finish());
+}
+function translatorChunk(data) {
+    if (data.classes.length !== 128 || data.buckets.length !== 28)
+        throw new RangeError('invalid translator table shape');
+    const w = new Writer();
+    w.u16(data.classes.length);
+    for (const value of data.classes)
+        w.u16(value);
+    w.latin8(data.wildcards);
+    w.u8(data.vowels.length);
+    for (const vowel of data.vowels)
+        w.latin8(vowel);
+    w.u16(data.buckets.length);
+    for (const bucket of data.buckets) {
+        w.u16(bucket.length);
+        for (const [left, match, right, out, term] of bucket) {
+            w.latin8(left);
+            w.latin8(match);
+            w.latin8(right);
+            w.latin8(out);
+            if (term.length !== 1)
+                throw new RangeError('translator rule terminator must be one byte');
+            w.u8(term.charCodeAt(0));
+        }
+    }
+    return w.finish();
+}
+function padded(values, count) {
+    const out = new Array(count).fill(0);
+    if (values)
+        for (let i = 0; i < Math.min(values.length, count); i++)
+            out[i] = values[i];
+    return out;
+}
+function voiceChunk(data) {
+    const count = data.names.length;
+    if (count === 0 || count > 0xffff)
+        throw new RangeError('invalid voice name count');
+    const w = new Writer();
+    w.u16(count);
+    for (const name of data.names) {
+        if (name.length > 2)
+            throw new RangeError(`phoneme name is longer than two bytes: ${name}`);
+        w.u8(name.charCodeAt(0) || 0);
+        w.u8(name.charCodeAt(1) || 0);
+    }
+    for (const value of padded(data.attrs, count))
+        w.u32(value);
+    for (const name of VOICE_COLUMNS.slice(0, 3))
+        w.raw(padded(data.params[name], count));
+    for (const name of ALT_VOICE_COLUMNS)
+        w.raw(padded(data.paramsAlt[name], count));
+    for (const name of VOICE_COLUMNS.slice(3))
+        w.raw(padded(data.params[name], count));
+    w.raw(padded(data.stressed, count));
+    w.raw(padded(data.unstressed, count));
+    const fricativeLength = data.fricatives[0]?.length ?? 0;
+    w.u16(data.fricatives.length);
+    w.u16(fricativeLength);
+    for (const table of data.fricatives) {
+        if (table.length !== fricativeLength)
+            throw new RangeError('fricative tables have unequal lengths');
+        w.raw(table);
+    }
+    return w.finish();
+}
+/** Encode free or extracted tables as the AROS deployment resource. */
+export function encodeArosResource(input) {
+    if (!input.translator && !input.voice)
+        throw new RangeError('resource contains no tables');
+    if (!input.metadata?.generator)
+        throw new RangeError('resource generator is required');
+    if (input.translator && !input.metadata.translatorLicense)
+        throw new RangeError('translator license is required');
+    if (input.voice && !input.metadata.voiceLicense)
+        throw new RangeError('voice license is required');
+    const version = new Writer();
+    version.u32(AROS_RESOURCE_VERSION);
+    const chunks = [chunk('VERS', version.finish()), textChunk('FVER', input.metadata.generator)];
+    if (input.translator) {
+        chunks.push(textChunk('TVER', input.translator.version));
+        chunks.push(textChunk('TSRC', input.translator.source));
+        chunks.push(textChunk('TLIC', input.metadata.translatorLicense));
+        chunks.push(chunk('LTRS', translatorChunk(input.translator)));
+    }
+    if (input.voice) {
+        chunks.push(textChunk('VVER', input.voice.version));
+        chunks.push(textChunk('VSRC', input.voice.source));
+        chunks.push(textChunk('VLIC', input.metadata.voiceLicense));
+        chunks.push(chunk('NVOI', voiceChunk(input.voice)));
+    }
+    const body = concat(chunks);
+    const head = new Writer();
+    head.id('FORM');
+    head.u32(body.length + 4);
+    head.id(AROS_RESOURCE_FORM);
+    return concat([head.finish(), body]);
+}
+/** Emit the same IFF bytes as a C array for ROM or built-in resource use. */
+export function emitArosCResource(input, symbol = 'sc_speech_resource') {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(symbol))
+        throw new RangeError(`invalid C symbol: ${symbol}`);
+    const bytes = encodeArosResource(input);
+    const rows = [];
+    for (let at = 0; at < bytes.length; at += 12) {
+        rows.push(`    ${Array.from(bytes.subarray(at, at + 12), (b) => `0x${b.toString(16).padStart(2, '0')}`).join(', ')},`);
+    }
+    return [
+        '/* Generated by narrator-ts; do not edit. */',
+        '#include <stddef.h>',
+        '#include <stdint.h>',
+        '',
+        `const uint8_t ${symbol}[] = {`,
+        ...rows,
+        '};',
+        `const size_t ${symbol}_length = sizeof(${symbol});`,
+        '',
+    ].join('\n');
+}
+function chunksFrom(bytes) {
+    if (bytes.length < 12)
+        throw new RangeError('truncated IFF FORM');
+    const ascii = (at) => String.fromCharCode(...bytes.subarray(at, at + 4));
+    const u32 = (at) => new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(at);
+    if (ascii(0) !== 'FORM' || ascii(8) !== AROS_RESOURCE_FORM || u32(4) + 8 !== bytes.length)
+        throw new RangeError('not an AROS Narrator IFF resource');
+    const chunks = new Map();
+    const singletons = new Set(['VERS', 'FVER', 'TVER', 'TSRC', 'TLIC', 'LTRS', 'VVER', 'VSRC', 'VLIC', 'NVOI']);
+    let at = 12;
+    while (at < bytes.length) {
+        if (at + 8 > bytes.length)
+            throw new RangeError('truncated IFF chunk');
+        const id = ascii(at), size = u32(at + 4), start = at + 8, end = start + size;
+        if (end > bytes.length)
+            throw new RangeError('truncated IFF chunk payload');
+        if (singletons.has(id) && chunks.has(id))
+            throw new RangeError(`duplicate ${id} chunk`);
+        chunks.set(id, bytes.subarray(start, end));
+        at = end + (size & 1);
+    }
+    if (at !== bytes.length)
+        throw new RangeError('missing IFF pad byte');
+    return chunks;
+}
+function decodeText(bytes, id) {
+    if (!bytes)
+        return undefined;
+    if (bytes.length === 0 || bytes.length > 0xff || bytes.includes(0))
+        throw new RangeError(`invalid ${id} text chunk`);
+    return String.fromCharCode(...bytes);
+}
+function decodeTranslator(bytes, metadata) {
+    const r = new Reader(bytes);
+    const classes = Array.from({ length: r.u16() }, () => r.u16());
+    const wildcards = r.latin8();
+    const vowels = Array.from({ length: r.u8() }, () => r.latin8());
+    const buckets = [];
+    const bucketCount = r.u16();
+    for (let b = 0; b < bucketCount; b++) {
+        const rules = [];
+        const count = r.u16();
+        for (let i = 0; i < count; i++)
+            rules.push([r.latin8(), r.latin8(), r.latin8(), r.latin8(), String.fromCharCode(r.u8())]);
+        buckets.push(rules);
+    }
+    if (!r.done())
+        throw new RangeError('trailing translator data');
+    return {
+        version: metadata?.version ?? 'resource',
+        source: metadata?.source ?? 'IFF LTRS',
+        classes, wildcards, vowels, buckets,
+    };
+}
+function decodeVoice(bytes) {
+    const r = new Reader(bytes), count = r.u16();
+    const names = Array.from({ length: count }, () => {
+        const a = r.u8(), b = r.u8();
+        return String.fromCharCode(a, b).replace(/\0+$/, '');
+    });
+    const attrs = Array.from({ length: count }, () => r.u32());
+    const params = {};
+    for (const name of VOICE_COLUMNS.slice(0, 3))
+        params[name] = r.vector(count);
+    const paramsAlt = {};
+    for (const name of ALT_VOICE_COLUMNS)
+        paramsAlt[name] = r.vector(count);
+    for (const name of VOICE_COLUMNS.slice(3))
+        params[name] = r.vector(count);
+    const stressed = r.vector(count), unstressed = r.vector(count);
+    const fricativeCount = r.u16(), fricativeLength = r.u16();
+    const fricatives = Array.from({ length: fricativeCount }, () => r.vector(fricativeLength));
+    if (!r.done())
+        throw new RangeError('trailing voice data');
+    return { names, attrs, params, paramsAlt, stressed, unstressed, fricatives };
+}
+/** Decode and validate an AROS resource, primarily for tools and tests. */
+export function decodeArosResource(bytes) {
+    const chunks = chunksFrom(bytes);
+    const versionBytes = chunks.get('VERS');
+    if (!versionBytes || versionBytes.length !== 4)
+        throw new RangeError('missing resource version');
+    const version = new DataView(versionBytes.buffer, versionBytes.byteOffset, 4).getUint32(0);
+    if (version !== AROS_RESOURCE_VERSION)
+        throw new RangeError(`unsupported resource version ${version}`);
+    const translatorMetadata = {
+        version: decodeText(chunks.get('TVER'), 'TVER'),
+        source: decodeText(chunks.get('TSRC'), 'TSRC'),
+        license: decodeText(chunks.get('TLIC'), 'TLIC'),
+    };
+    const voiceMetadata = {
+        version: decodeText(chunks.get('VVER'), 'VVER'),
+        source: decodeText(chunks.get('VSRC'), 'VSRC'),
+        license: decodeText(chunks.get('VLIC'), 'VLIC'),
+    };
+    const metadata = {};
+    const generator = decodeText(chunks.get('FVER'), 'FVER');
+    if (generator !== undefined)
+        metadata.generator = generator;
+    if (Object.values(translatorMetadata).some((value) => value !== undefined))
+        metadata.translator = translatorMetadata;
+    if (Object.values(voiceMetadata).some((value) => value !== undefined))
+        metadata.voice = voiceMetadata;
+    const translator = chunks.has('LTRS') ? decodeTranslator(chunks.get('LTRS'), metadata.translator) : undefined;
+    const voice = chunks.has('NVOI') ? decodeVoice(chunks.get('NVOI')) : undefined;
+    return { version, metadata, translator, voice };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "narrator-ts",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "TypeScript reimplementation of the Amiga narrator.device and translator.library",
   "type": "module",
   "license": "MIT",
@@ -27,9 +27,14 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "release": "npm version",
+    "preversion": "npm run typecheck && npm test",
+    "postversion": "git push --follow-tags",
     "prepublishOnly": "npm run build && npm test",
     "test": "vitest run",
     "test:watch": "vitest",
+    "export:aros": "vite-node tools/export-aros.ts --",
     "say": "vite-node tools/say.ts --",
     "oracle:build": "bash tools/fetch-musashi.sh && make -C tools/oracle"
   },
@@ -49,6 +54,10 @@
       "types": "./dist/translator/index.d.ts",
       "default": "./dist/translator/index.js"
     },
+    "./aros-resource": {
+      "types": "./dist/aros-resource/index.d.ts",
+      "default": "./dist/aros-resource/index.js"
+    },
     "./reference/nrl-table.json": "./reference/nrl-table.json",
     "./reference/voice-free.json": "./reference/voice-free.json",
     "./package.json": "./package.json"