@readium/speech 0.1.1 → 0.3.0

package/README.md

@@ -30,22 +30,34 @@ In the second phase, we focused on implementing a WebSpeech API-based solution w
 
 Key features include advanced voice selection, cross-browser playback control, flexible content loading, and comprehensive event handling for UI feedback. The architecture is designed to be extensible for different TTS backends while maintaining TypeScript-first development practices.
 
-## Demos
+In the third phase, we added highlighting: content currently being spoken (e.g. the current word or sentence) can be highlighted as playback progresses. See the [Highlighting guide](docs/Highlighting.md).
 
-Two live demos are available:
+We are now focused on the fourth phase: extracting [Guided Navigation objects](https://readium.org/guided-navigation) from a document (or a fragment of a document), and generating utterances from these objects.
 
-1. [Voice selection with playback demo](https://readium.org/speech/demo)
-2. [In-context demo](https://readium.org/speech/demo/article)
+## Demos
 
-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.
+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
 
@@ -64,7 +76,12 @@ yarn add @readium/speech
 ## Quick Start
 
 ```typescript
-import { WebSpeechVoiceManager, WebSpeechReadAloudNavigator } from "@readium/speech";
+import {
+  WebSpeechVoiceManager,
+  WebSpeechReadAloudNavigator,
+  setupDecorations,
+  DecorationStyleType,
+} from "@readium/speech";
 
 // Initialize voice manager
 const voiceManager = await WebSpeechVoiceManager.initialize({ 
@@ -78,24 +95,48 @@ const voice = await voiceManager.getDefaultVoice("en-US");
 const navigator = new WebSpeechReadAloudNavigator();
 await navigator.setVoice(voice);
 
+const content = document.getElementById("content");
+if (!content) throw new Error("Missing #content element");
+
+// Set up highlighting for the current window
+const decorations = setupDecorations();
+
 // Handle playback events
 navigator.on("play", () => console.log("Playback started"));
 navigator.on("pause", () => console.log("Playback paused"));
 navigator.on("end", () => console.log("Playback completed"));
 
+// Highlight each word as it's spoken
+navigator.on("boundary", (event) => {
+  const { charIndex, charLength } = event.detail;
+  const utterance = content.textContent ?? "";
+  const word = utterance.substring(charIndex, charIndex + charLength);
+
+  decorations.decorate([{
+    id: "tts-word",
+    style: { type: DecorationStyleType.Highlight, tint: "#ffeb3b" },
+    highlight: word,
+  }], "tts");
+});
+
 // Load and play content
-const content = document.getElementById("content");
 navigator.loadContent(content);
 navigator.play();
 ```
 
+See the [Highlighting guide](docs/Highlighting.md) for the other ways to build and apply decorations.
+
 ## Docs
 
 Documentation provides guides for:
 
 - [SpeechSynthesis in browsers and OSes](docs/WebSpeech.md)
 - [Voices and Filtering](docs/VoicesAndFiltering.md)
-- [API Reference](docs/API.md)
+- [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
 
@@ -117,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
@@ -127,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
 
@@ -136,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/decorator/createLocator.d.ts

@@ -0,0 +1,9 @@
+import { Locator } from '@readium/shared';
+export interface LocatorOptions {
+    highlight?: string;
+    before?: string;
+    after?: string;
+    selector?: string;
+    fragment?: string;
+}
+export declare function createLocator(options: LocatorOptions, wnd?: Window): Locator;

package/build/decorator/index.d.ts

@@ -0,0 +1,2 @@
+export * from './setupDecorations';
+export * from './createLocator';

package/build/decorator/setupDecorations.d.ts

@@ -0,0 +1,15 @@
+import { DirectCommsChannel, Decorator, DecorationController, DecorationControllerConfig, DecorationStyle } from '@readium/decorator';
+import { LocatorOptions } from './createLocator';
+export interface DecorationInput extends LocatorOptions {
+    id: string;
+    style: DecorationStyle;
+}
+export declare class ReadiumSpeechDecorationController extends DecorationController {
+    private readonly channel;
+    private readonly wnd;
+    private readonly decorator;
+    constructor(channel: DirectCommsChannel, wnd: Window, decorator: Decorator, config?: DecorationControllerConfig);
+    decorate(decorations: DecorationInput[], group: string): void;
+    destroy(): void;
+}
+export declare function setupDecorations(wnd?: Window, config?: DecorationControllerConfig): ReadiumSpeechDecorationController;

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[];
+}