@readium/speech 0.7.0 → 0.8.0

package/build/navigator.d.ts

@@ -6,7 +6,7 @@ import { ReadiumSpeechVoice } from './voices/types';
 import { ReadiumSpeechUtterance } from './utterance';
 export type ReadiumSpeechPlaybackState = "playing" | "paused" | "idle" | "loading" | "ready";
 export interface ReadiumSpeechPlaybackEvent {
-    type: "start" | "pause" | "resume" | "end" | "stop" | "skip" | "error" | "boundary" | "mark" | "idle" | "loading" | "ready" | "voiceschanged" | "languagefallback";
+    type: "start" | "pause" | "resume" | "end" | "stop" | "skip" | "error" | "boundary" | "mark" | "idle" | "loading" | "ready" | "voiceschanged" | "languagefallback" | "enginefallback" | "enginerecovered";
     detail?: any;
 }
 export interface ReadiumSpeechNavigatorContract extends Configurable<SpeechSettings, SpeechPreferences> {

package/build/provider.d.ts

@@ -3,7 +3,7 @@ import { ReadiumSpeechVoice } from './voices/types';
 export interface ReadiumSpeechEngineProvider {
     readonly id: string;
     readonly name: string;
-    getVoices(): Promise<ReadiumSpeechVoice[]>;
+    getVoices(forceRefresh?: boolean): Promise<ReadiumSpeechVoice[]>;
     createEngine(voice?: ReadiumSpeechVoice | string): Promise<ReadiumSpeechPlaybackEngine>;
     destroy(): Promise<void>;
 }

package/build/speechNavigator.d.ts

@@ -14,7 +14,7 @@ export interface ReadiumSpeechNavigatorConfiguration {
 export declare class ReadiumSpeechNavigator implements ReadiumSpeechNavigatorContract {
     private engine;
     private contentQueue;
-    private eventListeners;
+    private readonly events;
     private navigatorState;
     private pendingAdvanceTimeout;
     private _defaults;

package/build/utils/array.d.ts

@@ -0,0 +1 @@
+export declare const clampIndex: (index: number, length: number) => number;

package/build/utils/eventEmitter.d.ts

@@ -0,0 +1,6 @@
+export declare class EventEmitter<K, E> {
+    private listeners;
+    on(type: K, callback: (event: E) => void): () => void;
+    emit(type: K, event: E): void;
+    clear(): void;
+}

package/build/voices/languages.d.ts

@@ -23,6 +23,12 @@ export declare const getVoices: (lang: string) => Promise<ReadiumSpeechJSONVoice
  * @returns {string[]} Array of available language codes
  */
 export declare const getAvailableLanguages: () => string[];
+/**
+ * Get a display name for a language code (e.g. "fr" -> "French")
+ * @param code - Language code
+ * @param localization - Optional BCP 47 locale to display the name in
+ */
+export declare const getLanguageDisplayName: (code: string, localization?: string) => string;
 /**
  * Get the test utterance for a language
  * @param {string} lang - Language code (e.g., "en", "fr", "zh-CN")

package/build/voices/sorting.d.ts

@@ -1,7 +1,56 @@
 import { ReadiumSpeechVoice } from './types';
+import { LanguageWithRegions } from './languages';
 /**
  * Create a map of language codes to their respective voice order maps
  * @param voices Array of voices to analyze
  * @returns Map where key is language code and value is a map of voice names to their original JSON indices
  */
-export declare function createJsonOrderMap(voices: ReadiumSpeechVoice[]): Promise<Map<string, Map<string, number>>>;
+export declare const createJsonOrderMap: (voices: ReadiumSpeechVoice[]) => Promise<Map<string, Map<string, number>>>;
+export declare const getQualityValue: (quality: string | null | undefined) => number;
+/**
+ * Compares two voices by quality, using JSON name order as a tiebreaker for same-quality
+ * JSON-sourced voices, then falling back to alphabetical.
+ */
+export declare const sortByQuality: (a: ReadiumSpeechVoice, b: ReadiumSpeechVoice, jsonOrderMaps?: Map<string, Map<string, number>>, baseLang?: string) => number;
+/**
+ * Splits voices into those whose base language matches one of the processed preferred
+ * languages (grouped by base language) and everything else.
+ */
+export declare const groupVoicesByLanguage: (voices: ReadiumSpeechVoice[], processedLangs: LanguageWithRegions[]) => {
+    voicesByLang: Map<string, ReadiumSpeechVoice[]>;
+    otherLangVoices: ReadiumSpeechVoice[];
+};
+/**
+ * Compares two voices by region match against a preferred language: regions matching the
+ * preferred language's region list first (in preference order), then the default region, then
+ * everything else alphabetically by region — quality breaks ties at every level.
+ */
+export declare const compareByPreferredRegion: (a: ReadiumSpeechVoice, b: ReadiumSpeechVoice, processedLang: LanguageWithRegions, jsonOrderMaps: Map<string, Map<string, number>>) => number;
+/**
+ * Sorts voices in place: regions matching the preferred language's region list first (in
+ * preference order), then the default region, then everything else alphabetically by region —
+ * quality breaks ties at every level.
+ */
+export declare const sortByPreferredRegion: (voices: ReadiumSpeechVoice[], processedLang: LanguageWithRegions, jsonOrderMaps?: Map<string, Map<string, number>>) => Promise<void>;
+/**
+ * Compares two voices by language display name, then default region, then region
+ * alphabetically, then quality — used for voices outside the preferred-language groups.
+ */
+export declare const compareAlphabetically: (a: ReadiumSpeechVoice, b: ReadiumSpeechVoice, jsonOrderMaps: Map<string, Map<string, number>>) => number;
+/**
+ * Sorts voices in place by language display name, then default region, then region
+ * alphabetically, then quality — used for voices outside the preferred-language groups.
+ */
+export declare const sortAlphabetically: (voices: ReadiumSpeechVoice[], jsonOrderMaps?: Map<string, Map<string, number>>) => Promise<void>;
+/**
+ * Sorts voices by region preference within each preferred language (default region, then
+ * quality), with unmatched-language voices appended afterward, sorted alphabetically.
+ */
+export declare const sortVoicesByRegions: (preferredLanguages: string[], voices: ReadiumSpeechVoice[]) => Promise<ReadiumSpeechVoice[]>;
+/**
+ * Picks the single best-ranked voice for one language, without sorting the full candidate list.
+ * Mirrors sortVoicesByRegions' fallback tier for a single preferred language: prefers a voice
+ * whose base language matches, ranked by region/quality; if none match, falls back to the same
+ * ranking sortAlphabetically would produce over the rest.
+ */
+export declare const pickBestVoiceByRegion: (language: string, voices: ReadiumSpeechVoice[]) => Promise<ReadiumSpeechVoice | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readium/speech",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A TypeScript library for implementing read aloud features with Web technologies, following best practices for digital publishing.",
   "author": "Readium Foundation",
   "keywords": [