@readium/speech 0.3.0 → 0.5.0

package/README.md

@@ -24,7 +24,7 @@ The outline of this work has been explored in a [GitHub discussion](https://gith
 In the second phase, we focused on implementing a WebSpeech API-based solution with an architecture designed for future extensibility:
 
 - **Engine Layer**: Core TTS functionality through `ReadiumSpeechPlaybackEngine`
-- **Navigator Layer**: Content and playback management via (a temporary) `ReadiumSpeechNavigator`
+- **Navigator Layer**: Content and playback management via `ReadiumSpeechNavigator`
 - **Current Implementation**: WebSpeech API with cross-browser compatibility
 - **Future-Proof Design**: Architecture prepared for additional TTS service adapters
 
@@ -32,7 +32,9 @@ Key features include advanced voice selection, cross-browser playback control, f
 
 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.
+In the fourth phase, we extracted [Guided Navigation objects](https://readium.org/guided-navigation) from a document (or a fragment of a document), and generated utterances from these objects.
+
+We are now on the fifth phase: a second `ReadiumSpeechPlaybackEngine` implementation, backed by [speech-server](https://github.com/readium/speech-server) instead of the browser's Web Speech API.
 
 ## Demos
 
@@ -78,7 +80,8 @@ yarn add @readium/speech
 ```typescript
 import {
   WebSpeechVoiceManager,
-  WebSpeechReadAloudNavigator,
+  WebSpeechEngine,
+  ReadiumSpeechNavigator,
   setupDecorations,
   DecorationStyleType,
 } from "@readium/speech";
@@ -92,7 +95,7 @@ const voiceManager = await WebSpeechVoiceManager.initialize({
 const voice = await voiceManager.getDefaultVoice("en-US");
 
 // Create a navigator instance
-const navigator = new WebSpeechReadAloudNavigator();
+const navigator = new ReadiumSpeechNavigator(new WebSpeechEngine());
 await navigator.setVoice(voice);
 
 const content = document.getElementById("content");
@@ -137,6 +140,7 @@ Documentation provides guides for:
 - [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
+- [Provider Registry](docs/ProviderRegistry.md) — using more than one `ReadiumSpeechEngineProvider` (e.g. WebSpeech and speech-server) side by side
 
 ## Development
 

package/build/SpeechServer/chunkText.d.ts

@@ -0,0 +1,6 @@
+export interface TextChunk {
+    text: string;
+    offset: number;
+}
+export declare function chunkPlainText(text: string, maxLength: number): TextChunk[];
+export declare function chunkSsmlText(text: string, maxLength: number): TextChunk[];

package/build/SpeechServer/errors.d.ts

@@ -0,0 +1,20 @@
+export interface SpeechServerProblemDetails {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    instance?: string;
+}
+export declare class SpeechServerError extends Error {
+    readonly status: number;
+    readonly type?: string;
+    readonly title?: string;
+    readonly instance?: string;
+    constructor(message: string, options: {
+        status: number;
+        type?: string;
+        title?: string;
+        instance?: string;
+    });
+}
+export declare function toSpeechServerError(response: Response): Promise<SpeechServerError>;

package/build/SpeechServer/index.d.ts

@@ -0,0 +1,7 @@
+export * from './chunkText';
+export * from './selectFormat';
+export * from './speechServerEngine';
+export * from './speechServerEngineProvider';
+export * from './speechServerVoiceMapping';
+export * from './errors';
+export * from './types';

package/build/SpeechServer/selectFormat.d.ts

@@ -0,0 +1,18 @@
+import { SpeechServerAudioFormat } from './types';
+export type CanPlayTypeResult = "probably" | "maybe" | "";
+export type CanPlayType = (mime: string) => CanPlayTypeResult;
+export declare function mimeTypeForFormat(format: string): string;
+export interface SpeechServerFormatOptions {
+    preferredFormat?: SpeechServerAudioFormat | (string & {});
+    strategy?: "quality" | "bandwidth";
+    adaptBitrateToNetwork?: boolean;
+}
+export declare function selectFormat(output: {
+    formats: string[];
+    default: string;
+}, options: Pick<SpeechServerFormatOptions, "preferredFormat" | "strategy">, canPlay: CanPlayType): string;
+export interface NetworkInfo {
+    saveData?: boolean;
+    effectiveType?: string;
+}
+export declare function selectBitrate(format: string, adaptBitrateToNetwork: boolean, network: NetworkInfo | undefined): number | undefined;

package/build/SpeechServer/speechServerEngine.d.ts

@@ -0,0 +1,91 @@
+import { ReadiumSpeechPlaybackEngine } from '../engine';
+import { ReadiumSpeechPlaybackEvent, ReadiumSpeechPlaybackState } from '../navigator';
+import { ReadiumSpeechUtterance } from '../utterance';
+import { ReadiumSpeechVoice } from '../voices/types';
+import { SpeechServerFormatOptions } from './selectFormat';
+export interface SpeechServerEndpoints {
+    voices: string;
+    synthesize: string;
+    service: string;
+}
+export interface SpeechServerEngineOptions {
+    endpoints: SpeechServerEndpoints;
+    fetch?: typeof fetch;
+    prefetchWindow?: number;
+    readyBufferChars?: number;
+    overLengthText?: "split" | "error";
+    format?: SpeechServerFormatOptions;
+}
+export declare class SpeechServerEngine implements ReadiumSpeechPlaybackEngine {
+    private endpoints;
+    private fetchImpl;
+    private currentVoice;
+    private voices;
+    private serviceInfo;
+    private serviceInfoPromise;
+    private currentUtterances;
+    private currentUtteranceIndex;
+    private playbackState;
+    private eventListeners;
+    private speakInContentLanguage;
+    private speakGeneration;
+    private loadGeneration;
+    private readonly prefetchWindow;
+    private readonly readyBufferChars;
+    private readonly overLengthText;
+    private readonly formatOptions;
+    private readonly canPlayType;
+    private prefetchCache;
+    private prefetchChainTail;
+    private audioContext;
+    private masterGain;
+    private scheduledChunks;
+    private boundaryRafHandle;
+    private rate;
+    private pitch;
+    private volume;
+    constructor(options: SpeechServerEngineOptions);
+    setAvailableVoices(voices: ReadiumSpeechVoice[]): void;
+    loadUtterances(contents: ReadiumSpeechUtterance[]): void;
+    private bufferUntilReady;
+    private indexCoveringChars;
+    setVoice(voice: ReadiumSpeechVoice | string): void;
+    getCurrentVoice(): ReadiumSpeechVoice | null;
+    getAvailableVoices(): Promise<ReadiumSpeechVoice[]>;
+    private getServiceInfo;
+    private fetchServiceInfo;
+    setSpeakInContentLanguage(enabled: boolean): void;
+    getSpeakInContentLanguage(): boolean;
+    speak(utteranceIndex?: number): void;
+    private synthesizeAndPlay;
+    private resolveSynthesisStream;
+    private fillPrefetchWindow;
+    private queuePrefetch;
+    private clearPrefetchCache;
+    private synthesizeStream;
+    private synthesizeChunk;
+    private ensureAudioContext;
+    private scheduleChunksStreaming;
+    private handleUtteranceEnded;
+    private startBoundaryPolling;
+    private stopBoundaryPolling;
+    private checkBoundaries;
+    private stopAudio;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    setRate(rate: number): void;
+    getRate(): number;
+    setPitch(pitch: number): void;
+    getPitch(): number;
+    setVolume(volume: number): void;
+    getVolume(): number;
+    getState(): ReadiumSpeechPlaybackState;
+    getCurrentUtteranceIndex(): number;
+    setCurrentUtteranceIndex(index: number, onComplete?: (success: boolean) => void): void;
+    getUtteranceCount(): number;
+    on(event: ReadiumSpeechPlaybackEvent["type"], callback: (event: ReadiumSpeechPlaybackEvent) => void): () => void;
+    private emitEvent;
+    private setState;
+    destroy(): Promise<void>;
+}

package/build/SpeechServer/speechServerEngineProvider.d.ts

@@ -0,0 +1,16 @@
+import { ReadiumSpeechEngineProvider } from '../provider';
+import { ReadiumSpeechPlaybackEngine } from '../engine';
+import { ReadiumSpeechVoice } from '../voices/types';
+import { SpeechServerEngineOptions } from './speechServerEngine';
+export type SpeechServerEngineProviderOptions = SpeechServerEngineOptions;
+export declare class SpeechServerEngineProvider implements ReadiumSpeechEngineProvider {
+    readonly id: string;
+    readonly name: string;
+    private options;
+    private fetchImpl;
+    private voices;
+    constructor(options: SpeechServerEngineProviderOptions);
+    getVoices(): Promise<ReadiumSpeechVoice[]>;
+    createEngine(voice?: ReadiumSpeechVoice | string): Promise<ReadiumSpeechPlaybackEngine>;
+    destroy(): Promise<void>;
+}

package/build/SpeechServer/speechServerVoiceMapping.d.ts

@@ -0,0 +1,3 @@
+import { ReadiumSpeechVoice } from '../voices/types';
+import { SpeechServerVoice } from './types';
+export declare function mapServerVoice(voice: SpeechServerVoice): ReadiumSpeechVoice;

package/build/SpeechServer/types.d.ts

@@ -0,0 +1,56 @@
+import { TGender, TQuality, TServerVoiceControls } from '../voices/types';
+export interface SpeechServerVoice {
+    name: string;
+    originalName: string;
+    provider: string;
+    identifier: string;
+    language: string;
+    otherLanguages?: string[];
+    gender?: TGender | null;
+    quality?: TQuality;
+    controls?: TServerVoiceControls;
+}
+export interface SpeechServerTimingMark {
+    name: "word" | "sentence";
+    charIndex: number;
+    charLength: number;
+    elapsedTime: number;
+}
+export type SpeechServerAudioFormat = "wav" | "mp3" | "opus" | "aac" | "flac" | "ogg" | "webm" | "m4a";
+export interface SpeechServerSynthesizeRequest {
+    id?: string;
+    text: string;
+    ssml?: boolean;
+    language?: string;
+    voice?: string;
+    prev_utterance?: string;
+    next_utterance?: string;
+    publication_id?: string;
+    boundary?: boolean;
+    output?: {
+        format?: SpeechServerAudioFormat;
+        bitrate?: number | null;
+        sample_rate?: number | null;
+        speed?: number;
+        pitch?: number | null;
+    };
+}
+export interface SpeechServerSynthesizeBoundaryResponse {
+    audio: string;
+    format: SpeechServerAudioFormat;
+    boundaries: SpeechServerTimingMark[] | null;
+}
+export interface SpeechServerServiceInfo {
+    output: {
+        formats: SpeechServerAudioFormat[];
+        default: SpeechServerAudioFormat;
+    };
+    limits: {
+        maxTextLength: number;
+        maxConcurrentSyntheses: number;
+    };
+    providers: {
+        id: string;
+        installedLanguages: string[];
+    }[];
+}

package/build/WebSpeech/WebSpeechVoiceManager.d.ts

@@ -41,13 +41,19 @@ export declare class WebSpeechVoiceManager {
     private voices;
     private browserVoices;
     private isInitialized;
+    private scopedLanguages;
+    private broadenPromises;
     private constructor();
     /**
-     * Initialize voice manager
+     * Initialize voice manager, or broaden an already-initialized singleton to
+     * also cover new languages. `languages` scope voice parsing to reduce
+     * per-language JSON loading; omitting it on the first call loads everything,
+     * but omitting it on a later call to an already-scoped instance is a no-op,
+     * not a retroactive broaden-to-everything.
      * @param options Configuration options for voice loading
-     * @param options.languages Optional array of preferred language codes to filter voices during initialization
-     * @param options.maxTimeout Maximum time in milliseconds to wait for voices to load (passed to getBrowserVoices)
-     * @param options.interval Interval in milliseconds between voice loading checks (passed to getBrowserVoices)
+     * @param options.languages Optional array of preferred language codes to filter (or broaden to) voices
+     * @param options.maxTimeout Maximum time in milliseconds to wait for voices to load (passed to getBrowserVoices, first call only)
+     * @param options.interval Interval in milliseconds between voice loading checks (passed to getBrowserVoices, first call only)
      * @returns Promise that resolves with the WebSpeechVoiceManager instance
      */
     static initialize(options?: {
@@ -60,6 +66,18 @@ export declare class WebSpeechVoiceManager {
      * @private
      */
     private filterBrowserVoicesByLanguages;
+    /**
+     * Extract base language codes (e.g. "en", "fr") from a list of BCP47 tags
+     * @private
+     */
+    private static toBaseLangSet;
+    /**
+     * Broaden an already-initialized instance to also cover the given languages,
+     * reusing the already-fetched `browserVoices` (no new speechSynthesis fetch).
+     * No-op if the instance is already unscoped or already covers these languages.
+     * @private
+     */
+    private broadenLanguages;
     /**
      * Extract language and region from BCP47 language tag
      * @param lang - The BCP47 language tag (e.g., "en-US", "zh-CN")

package/build/WebSpeech/index.d.ts

@@ -1,4 +1,3 @@
 export * from './WebSpeechVoiceManager';
 export * from './webSpeechEngine';
 export * from './webSpeechEngineProvider';
-export * from './TmpNavigator';

package/build/WebSpeech/webSpeechEngine.d.ts

@@ -13,6 +13,10 @@ export declare class WebSpeechEngine implements ReadiumSpeechPlaybackEngine {
     private voiceManager;
     private voices;
     private defaultVoice;
+    private speakInContentLanguage;
+    private languageVoiceCache;
+    private warmingLanguages;
+    private speakGeneration;
     private resumeInfinityTimer?;
     private isSpeakingInternal;
     private isPausedInternal;
@@ -37,7 +41,13 @@ export declare class WebSpeechEngine implements ReadiumSpeechPlaybackEngine {
     }): Promise<boolean>;
     private validateText;
     private getCurrentVoiceForUtterance;
+    private voiceMatchesLanguage;
+    private voiceForUtteranceSync;
+    private voiceForUtterance;
+    private warmLanguageVoiceCache;
     getCurrentVoice(): ReadiumSpeechVoice | null;
+    setSpeakInContentLanguage(enabled: boolean): void;
+    getSpeakInContentLanguage(): boolean;
     private toPlainText;
     loadUtterances(contents: ReadiumSpeechUtterance[]): void;
     setVoice(voice: ReadiumSpeechVoice | string): Promise<void>;

package/build/WebSpeech/webSpeechEngineProvider.d.ts

@@ -4,7 +4,7 @@ import { ReadiumSpeechVoice } from '../voices/types';
 export declare class WebSpeechEngineProvider implements ReadiumSpeechEngineProvider {
     readonly id: string;
     readonly name: string;
-    private engine;
+    private voiceEngine;
     getVoices(): Promise<ReadiumSpeechVoice[]>;
     createEngine(voice?: ReadiumSpeechVoice | string): Promise<ReadiumSpeechPlaybackEngine>;
     destroy(): Promise<void>;

package/build/engine.d.ts

@@ -2,10 +2,13 @@ import { ReadiumSpeechPlaybackEvent, ReadiumSpeechPlaybackState } from './naviga
 import { ReadiumSpeechUtterance } from './utterance';
 import { ReadiumSpeechVoice } from './voices/types';
 export interface ReadiumSpeechPlaybackEngine {
+    initialize?(): Promise<unknown>;
     loadUtterances(contents: ReadiumSpeechUtterance[]): void;
     setVoice(voice: ReadiumSpeechVoice | string): void;
     getCurrentVoice(): ReadiumSpeechVoice | null;
     getAvailableVoices(): Promise<ReadiumSpeechVoice[]>;
+    setSpeakInContentLanguage(enabled: boolean): void;
+    getSpeakInContentLanguage(): boolean;
     speak(utteranceIndex?: number): void;
     pause(): void;
     resume(): void;