@readium/speech 0.1.1 → 0.2.0

package/README.md

@@ -30,6 +30,10 @@ 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.
 
+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).
+
+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.
+
 ## Demos
 
 Two live demos are available:
@@ -45,7 +49,7 @@ The first demo showcases the following features:
 - using embedded test utterances to demo voices
 - using the current Navigator for playback control
 
-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.
+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.
 
 ## Installation
 
@@ -64,7 +68,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 +87,46 @@ 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)
 
 ## Development
 

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;