@readium/speech 0.2.0 → 0.3.0

package/README.md

@@ -36,20 +36,28 @@ We are now focused on the fourth phase: extracting [Guided Navigation objects](h
 
 ## Demos
 
-Two live demos are available:
-
-1. [Voice selection with playback demo](https://readium.org/speech/demo)
-2. [In-context demo](https://readium.org/speech/demo/article)
-
-The first demo showcases the following features:
+### [Voice selection with playback demo](https://readium.org/speech/demo)
 
 - fetching a list of all available languages, translating them to the user's locale and sorting them based on these translations
 - returning a list of voices for a given language, grouped by region and sorted based on quality
 - filtering languages and voices based on gender and offline availability
 - using embedded test utterances to demo voices
 - using the current Navigator for playback control
+- highlighting: as playback progresses, the current word/sentence is highlighted
+
+### [In-context demo](https://readium.org/speech/demo/article)
+
+In-context reading with seamless voice selection (grouped by region and sorted based on quality), and playback control, providing an optional read-along experience that integrates naturally with the content. Also showcases highlighting, as above.
+
+### [Extraction playground](https://readium.org/speech/demo/playground)
 
-The second demo focuses on in-context reading with seamless voice selection (grouped by region and sorted based on quality), and playback control, providing an optional read-along experience that integrates naturally with the content. Both demos also showcase highlighting: as playback progresses, the current word/sentence is highlighted.
+Pick a sample piece of markup and watch it move through the whole pipeline:
+
+- the [Guided Navigation](docs/GuidedNavigation.md) document it produces
+- the [utterances](docs/UtteranceExtraction.md) extracted from that, with every extraction option (format, language handling, skipped roles, sentence interruption, contextualization) adjustable live
+- playback of the resulting utterances through the WebSpeech navigator, with word-boundary highlighting
+
+The sample markup is drawn from this project's own conformance test suite ([`fixtures/`](fixtures/README.md)), so each pane also shows a pass/fail badge against that suite's expected output — a side effect of reusing real test content, not the point of the demo.
 
 ## Installation
 
@@ -127,6 +135,8 @@ Documentation provides guides for:
 - [Voice Management](docs/VoiceManagement.md)
 - [Playback API](docs/Playback.md)
 - [Highlighting](docs/Highlighting.md)
+- [Guided Navigation](docs/GuidedNavigation.md) — extracting [Guided Navigation objects](https://readium.org/guided-navigation) from HTML/XHTML content
+- [Utterance Extraction](docs/UtteranceExtraction.md) — extracting utterances from Guided Navigation objects
 
 ## Development
 
@@ -148,7 +158,7 @@ This will compile the TypeScript code and generate the following outputs in the
 
 ### Running Demos Locally
 
-The project includes two demo applications that can be served locally:
+The project includes demo applications that can be served locally:
 
 1. Start the local development server:
    ```bash
@@ -158,6 +168,7 @@ The project includes two demo applications that can be served locally:
 2. Open your browser to:
    - [Voice selection demo](http://localhost:8080/demo)
    - [In-context reading demo](http://localhost:8080/demo/article)
+   - [Extraction playground](http://localhost:8080/demo/playground)
 
 ### ChromeOS Debugging
 
@@ -167,12 +178,19 @@ For ChromeOS development, the project includes a debug mode that mocks the Web S
 
 2. The debug page loads mock voices from a json file which contains a snapshot of ChromeOS voices.
 
-### Running Tests
+### Testing
+
+`npm test` builds the library and runs the full test suite (`ava`) across `test/**/*.test.ts`. Narrower scripts are available for working on one area at a time:
 
-To run the test suite for `WebSpeechVoiceManager`:
 ```bash
-npm test
+npm test           # build + full suite
+npm run test:voices     # WebSpeechVoiceManager only
+npm run test:gnd        # HTML/XHTML -> Guided Navigation conversion
+npm run test:utterances # Guided Navigation -> utterance extraction
 ```
+
+`test:gnd` and `test:utterances` are both driven by [`fixtures/`](fixtures/README.md), a language-agnostic conformance suite of paired input/expected-output files (`input.html`/`input.xhtml`, `gnd.json`, `utterances.json`) covering the [Guided Navigation](docs/GuidedNavigation.md) and [utterance extraction](docs/UtteranceExtraction.md) stages one role/encoding/option at a time. Each fixture is a plain-file test case any platform implementation can consume, not just this TypeScript one — see [fixtures/README.md](fixtures/README.md) for the format, how to add a fixture, and how a fixture "passes".
+
 ## Acknowledgments
 
 This project is based on the work done initially by [Hadrien Gardeur](https://github.com/hadriengardeur) in the [web-speech-recommended-voices](https://github.com/HadrienGardeur/web-speech-recommended-voices) repository.

package/build/WebSpeech/webSpeechEngine.d.ts

@@ -38,7 +38,7 @@ export declare class WebSpeechEngine implements ReadiumSpeechPlaybackEngine {
     private validateText;
     private getCurrentVoiceForUtterance;
     getCurrentVoice(): ReadiumSpeechVoice | null;
-    private escapeSSML;
+    private toPlainText;
     loadUtterances(contents: ReadiumSpeechUtterance[]): void;
     setVoice(voice: ReadiumSpeechVoice | string): Promise<void>;
     getAvailableVoices(): Promise<ReadiumSpeechVoice[]>;

package/build/gnd/a11y.d.ts

@@ -0,0 +1,18 @@
+import { GndText } from './types.js';
+/** Normalized (whitespace-coalesced and trimmed) text content of a node's subtree. */
+export declare function normalizedNodeText(el: Node): string;
+/**
+ * Computes the text that becomes a node's `GndObject.description`, and
+ * whether the node is visible in the first place. Follows the AccName
+ * precedence order (https://www.w3.org/TR/accname/#terminology, 2.A-2.D)
+ * for its accessible-name sources, with a non-AccName `aria-describedby`
+ * fallback spliced in between 2.C and 2.D — see that branch below.
+ */
+export declare function extractNodeAria(el: Element): [GndText | null, boolean];
+/**
+ * Maps an HTML element to the SSML tag its text should be wrapped in.
+ * https://www.w3.org/TR/speech-synthesis11/#S3.2.2
+ */
+export declare function convertElementToSSMLTag(tagName: string): [string, Record<string, string>?];
+/** Elements whose entire subtree carries no user-facing content. */
+export declare const skippedElements: Set<string>;

package/build/gnd/converter.d.ts

@@ -0,0 +1,52 @@
+import { GndObject } from './types.js';
+import { GndMediaType } from './dom.js';
+/** Walks a DOM subtree, building the Guided Navigation object tree. */
+export declare class Converter {
+    xmlParsed: boolean;
+    ids: Map<string, Element>;
+    suppressed: Set<Element>;
+    idAlloc: {
+        claimed: Set<string>;
+        counters: Map<string, number>;
+    };
+    noterefDepth: number;
+    allowNode: Element | null;
+    private root;
+    private current;
+    private segments;
+    private textAcc;
+    private currentCtx;
+    private flowEndsWithSpace;
+    private pendingChildren;
+    constructor(xmlParsed: boolean);
+    private allocateId;
+    private claimId;
+    prescan(root: Element): void;
+    convert(root: Element): void;
+    convertChildren(root: Element): void;
+    result(): GndObject[];
+    private descend;
+    private appendChild;
+    private walk;
+    private head;
+    private tail;
+    private text;
+    private textContext;
+    private updateFlowSpace;
+    private closeSegment;
+    private resetFlow;
+    private placeholder;
+    private pagebreak;
+    private noteref;
+    private link;
+    private flushText;
+}
+/**
+ * Converts an HTML or XHTML fragment or document into Guided Navigation
+ * objects, reflecting exactly the input it's given: a real, author-written
+ * <body> becomes its own role: ["body"] node like any other element; a
+ * <body> synthesized only by text/html parsing around a bodyless fragment
+ * is not content and is skipped through; a bodyless XHTML fragment's root
+ * element is itself the content.
+ */
+export declare function parseMarkup(input: string, mediaType?: GndMediaType): GndObject[];

package/build/gnd/dom.d.ts

@@ -0,0 +1,5 @@
+export declare function nodeLanguage(el: Element | null): string;
+export declare function hasElementChild(el: Element): boolean;
+export declare function isAncestorOf(anc: Element, n: Element): boolean;
+export type GndMediaType = "text/html" | "application/xhtml+xml";
+export declare function sniffMediaType(input: string): GndMediaType;

package/build/gnd/index.d.ts

@@ -0,0 +1,4 @@
+export type { GndRole, GndText, GndObject, GndDocument } from './types.js';
+export { makeGnd } from './makeGnd.js';
+export { parseMarkup } from './converter.js';
+export type { GndMediaType } from './dom.js';

package/build/gnd/makeGnd.d.ts

@@ -0,0 +1,8 @@
+import { GndDocument } from './types.js';
+import { GndMediaType } from './dom.js';
+export type { GndMediaType };
+/**
+ * Builds a Guided Navigation document from an HTML or XHTML fragment or
+ * document, following https://github.com/readium/guided-navigation.
+ */
+export declare function makeGnd(input: string, mediaType?: GndMediaType): GndDocument;

package/build/gnd/object.d.ts

@@ -0,0 +1,24 @@
+import { GndObject, GndRole } from './types.js';
+import { TextBuilder } from './text.js';
+export interface ObjBuilder {
+    id?: string;
+    audioref?: string;
+    imgref?: string;
+    textref?: string;
+    videoref?: string;
+    text?: TextBuilder;
+    role?: GndRole[];
+    children?: ObjBuilder[];
+    description?: string;
+}
+export declare function isEmptyObj(o: ObjBuilder): boolean;
+/** A node being built up during the tree walk, before its final shape is known. */
+export declare class NavObject {
+    el?: Element;
+    object: ObjBuilder;
+    children: NavObject[];
+    noText: boolean;
+    finalize(): ObjBuilder;
+}
+export declare function finalizeToGndObject(o: ObjBuilder): GndObject;
+export declare function gndObjectToObjBuilder(n: GndObject): ObjBuilder;

package/build/gnd/roles.d.ts

@@ -0,0 +1,8 @@
+import { GndRole } from './types.js';
+/**
+ * Determines the Guided Navigation roles of an element, combining the roles
+ * derived from the element type itself with the ones from its ARIA `role` and
+ * `epub:type` attributes, e.g. `<section epub:type="chapter">` -> `[section, chapter]`.
+ * An ARIA role of "presentation"/"none" strips the element of its native semantics.
+ */
+export declare function extractNodeRoles(el: Element): GndRole[];

package/build/gnd/text.d.ts

@@ -0,0 +1,18 @@
+import { GndText } from './types.js';
+export interface TextBuilder {
+    plain: string;
+    ssml: string;
+    language: string;
+}
+export declare function textIsEmpty(t: TextBuilder): boolean;
+export declare function finalizeText(t?: TextBuilder): string | GndText | undefined;
+export interface SSMLContext {
+    lang: string;
+    tag: string;
+    attrs?: Record<string, string>;
+}
+export declare function ctxEqual(a: SSMLContext, b: SSMLContext): boolean;
+export declare const ssmlTextEscape: (s: string) => string;
+export declare const ssmlAttrEscape: (s: string) => string;
+export declare function isNoBreakSpace(ch: string): boolean;
+export declare function normalizeWhitespace(text: string, stripLeading: boolean): string;

package/build/gnd/types.d.ts

@@ -0,0 +1,21 @@
+export type GndRole = string;
+export interface GndText {
+    language: string;
+    plain?: string;
+    ssml?: string;
+}
+export interface GndObject {
+    role?: GndRole[];
+    text?: string | GndText;
+    description?: string;
+    imgref?: string;
+    audioref?: string;
+    videoref?: string;
+    textref?: string;
+    id?: string;
+    children?: GndObject[];
+}
+export interface GndDocument {
+    links?: unknown[];
+    guided: GndObject[];
+}