@readium/speech 0.19.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +18 -3
  2. package/build/Fallback/fallbackEngineProvider.d.ts +1 -0
  3. package/build/Fallback/fallbackSpeechEngine.d.ts +7 -1
  4. package/build/Fallback/recoverableFailure.d.ts +2 -1
  5. package/build/SpeechServer/index.d.ts +7 -7
  6. package/build/SpeechServer/speechServerEngine.d.ts +1 -1
  7. package/build/SpeechServer/speechServerEngineProvider.d.ts +1 -0
  8. package/build/WebSpeech/WebSpeechVoiceManager.d.ts +1 -1
  9. package/build/WebSpeech/webSpeechEngine.d.ts +3 -2
  10. package/build/WebSpeech/webSpeechEngineProvider.d.ts +1 -0
  11. package/build/engine.d.ts +1 -1
  12. package/build/index.js +2773 -2053
  13. package/build/navigator.d.ts +59 -4
  14. package/build/preferences/index.d.ts +1 -1
  15. package/build/provider.d.ts +1 -0
  16. package/build/speechNavigator.d.ts +3 -19
  17. package/build/utils/patches.d.ts +1 -0
  18. package/build/utils/text.d.ts +2 -1
  19. package/build/utterances/abbreviationAlias.d.ts +28 -0
  20. package/build/utterances/blocks.d.ts +5 -0
  21. package/build/utterances/boundaryLocate.d.ts +2 -1
  22. package/build/utterances/contextualization.d.ts +4 -4
  23. package/build/utterances/index.d.ts +3 -1
  24. package/build/utterances/language.d.ts +5 -5
  25. package/build/utterances/locate.d.ts +3 -2
  26. package/build/utterances/mergeUtterances.d.ts +9 -12
  27. package/build/utterances/nodeFields.d.ts +2 -1
  28. package/build/utterances/piece.d.ts +50 -0
  29. package/build/utterances/plainText.d.ts +31 -0
  30. package/build/utterances/sentenceBoundaryMerge.d.ts +1 -0
  31. package/build/utterances/sentenceReconstruction.d.ts +3 -6
  32. package/build/utterances/sentenceSegmenter.d.ts +2 -0
  33. package/build/utterances/sourceSpans.d.ts +45 -0
  34. package/build/utterances/splitSsmlAtSentences.d.ts +2 -1
  35. package/build/utterances/ssml.d.ts +49 -0
  36. package/build/utterances/tableStructure.d.ts +2 -0
  37. package/build/utterances/text.d.ts +17 -21
  38. package/build/utterances/utteranceOutput.d.ts +7 -6
  39. package/build/utterances/walk.d.ts +3 -3
  40. package/build/utterances/walkContext.d.ts +1 -16
  41. package/build/voices/languageCode.d.ts +1 -0
  42. package/build/voices/reachability.d.ts +2 -0
  43. package/build/voices/voiceSelection.d.ts +35 -0
  44. package/package.json +9 -6
  45. package/build/voices/voiceForLanguage.d.ts +0 -6
package/README.md CHANGED
@@ -148,6 +148,7 @@ Documentation provides guides for:
148
148
  - [Voice Management](docs/VoiceManagement.md)
149
149
  - [Playback API](docs/Playback.md)
150
150
  - [Preferences](docs/Preferences.md) — verbosity and prosody settings via `SpeechPreferences`/`SpeechSettings`
151
+ - [Verbosity](docs/Verbosity.md) — roles each verbosity preset skips and contextualizes
151
152
  - [Highlighting](docs/Highlighting.md)
152
153
  - [Guided Navigation](docs/GuidedNavigation.md) — getting [Guided Navigation objects](https://readium.org/guided-navigation) from HTML/XHTML content with `@readium/guided-navigation`
153
154
  - [Utterance Extraction](docs/UtteranceExtraction.md) — extracting utterances from Guided Navigation objects
@@ -166,7 +167,7 @@ The playback logic is more complex and may not be suitable for this approach yet
166
167
 
167
168
  ### Building the Library
168
169
 
169
- To build the library:
170
+ Development requires Node.js 24 or later. To build the library:
170
171
  ```bash
171
172
  npm run build
172
173
  ```
@@ -199,16 +200,30 @@ For ChromeOS development, the project includes a debug mode that mocks the Web S
199
200
 
200
201
  ### Testing
201
202
 
202
- `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:
203
+ `npm test` builds the library, typechecks `src/` and `test/` (`npm run typecheck`), and runs the full test suite (`ava`) across `test/**/*.test.ts`. Narrower scripts are available for working on one area at a time:
203
204
 
204
205
  ```bash
205
- npm test # build + full suite
206
+ npm test # build + typecheck + full suite
207
+ npm run typecheck # src/ and test/, after a build
206
208
  npm run test:voices # WebSpeechVoiceManager only
207
209
  npm run test:utterances # Guided Navigation -> utterance extraction
208
210
  ```
209
211
 
210
212
  `test:utterances` is driven by [`fixtures/`](fixtures/README.md): the expected utterances, one option combination at a time, for every fixture of [`@readium/guided-navigation`](https://github.com/readium/ts-toolkit/tree/develop/guided-navigation)'s language-agnostic conformance suite. 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".
211
213
 
214
+ ### Generated files
215
+
216
+ Rerun the matching script after changing its source, and commit the output:
217
+
218
+ | Script | Source | Writes |
219
+ | --- | --- | --- |
220
+ | `npm run generate-metadata` | `json/*.json` | `src/generated/language-metadata.ts` |
221
+ | `npm run generate-role-sets` | `skippableRoles`, `interruptionRoles`, `blockLevelRoles` | role lists in `docs/UtteranceExtraction.md` |
222
+ | `npm run generate-verbosity-tables` | `src/preferences/verbosityTables.ts`, `locales/en.json` | tables in `docs/Verbosity.md` |
223
+ | `npm run generate-utterances` | extraction code, GND fixtures | `fixtures/*/utterances.json` |
224
+
225
+ The last three build the library first. In docs, they only replace what's between `<!-- generated:name -->` and `<!-- /generated:name -->`: edit around those markers, not inside them.
226
+
212
227
  ## Acknowledgments
213
228
 
214
229
  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.
@@ -16,6 +16,7 @@ export declare class FallbackEngineProvider implements ReadiumSpeechEngineProvid
16
16
  private readonly healthCheckIntervalMs?;
17
17
  constructor(options: FallbackEngineProviderOptions);
18
18
  getVoices(forceRefresh?: boolean): Promise<ReadiumSpeechVoice[]>;
19
+ isAvailable(): Promise<boolean>;
19
20
  createEngine(voice?: ReadiumSpeechVoice | string): Promise<ReadiumSpeechPlaybackEngine>;
20
21
  destroy(): Promise<void>;
21
22
  }
@@ -27,6 +27,7 @@ export declare class FallbackSpeechEngine implements ReadiumSpeechPlaybackEngine
27
27
  private swapInFlight;
28
28
  private teardownEpoch;
29
29
  private loadToken;
30
+ private readonly listedVoices;
30
31
  private readonly events;
31
32
  private unbindActiveEngine;
32
33
  constructor(options: FallbackSpeechEngineOptions);
@@ -50,7 +51,7 @@ export declare class FallbackSpeechEngine implements ReadiumSpeechPlaybackEngine
50
51
  getCurrentUtteranceIndex(): number;
51
52
  setCurrentUtteranceIndex(index: number, onComplete?: (success: boolean) => void): void;
52
53
  getUtteranceCount(): number;
53
- on(event: ReadiumSpeechPlaybackEvent["type"], callback: (event: ReadiumSpeechPlaybackEvent) => void): () => void;
54
+ on<T extends ReadiumSpeechPlaybackEvent["type"]>(event: T, callback: (event: ReadiumSpeechPlaybackEvent<T>) => void): () => void;
54
55
  private emitEvent;
55
56
  private bindActiveEngine;
56
57
  private handleError;
@@ -59,9 +60,14 @@ export declare class FallbackSpeechEngine implements ReadiumSpeechPlaybackEngine
59
60
  private startHealthCheck;
60
61
  private maybeRecoverNow;
61
62
  private swapToFallback;
63
+ private utteranceVoice;
62
64
  private recoverToPrimary;
63
65
  private performSwap;
64
66
  private reachableVoices;
67
+ private recordListedVoices;
68
+ private listedVoice;
69
+ private listUtteranceVoices;
70
+ private withReachableVoices;
65
71
  private pickBestFallbackVoice;
66
72
  destroy(): Promise<void>;
67
73
  }
@@ -2,9 +2,10 @@ import { ReadiumSpeechPlaybackEvent } from '../navigator.js';
2
2
  export interface ErrorEventDetail {
3
3
  message: string;
4
4
  recoverable: boolean;
5
+ error?: string;
5
6
  status?: number;
6
7
  type?: string;
7
8
  title?: string;
8
9
  instance?: string;
9
10
  }
10
- export declare function isRecoverableFailure(event: ReadiumSpeechPlaybackEvent): boolean;
11
+ export declare function isRecoverableFailure(event: ReadiumSpeechPlaybackEvent<"error">): boolean;
@@ -1,7 +1,7 @@
1
- export * from './chunkText.js';
2
- export * from './selectFormat.js';
3
- export * from './speechServerEngine.js';
4
- export * from './speechServerEngineProvider.js';
5
- export * from './speechServerVoiceMapping.js';
6
- export * from './errors.js';
7
- export * from './types.js';
1
+ export { SpeechServerEngine } from './speechServerEngine.js';
2
+ export type { SpeechServerEndpoints, SpeechServerEngineOptions } from './speechServerEngine.js';
3
+ export { SpeechServerEngineProvider } from './speechServerEngineProvider.js';
4
+ export type { SpeechServerEngineProviderOptions } from './speechServerEngineProvider.js';
5
+ export type { SpeechServerFormatOptions } from './selectFormat.js';
6
+ export type { SpeechServerAudioFormat } from './types.js';
7
+ export { SpeechServerAudioDecodeError, SpeechServerError, SpeechServerNetworkError, SpeechServerStallError } from './errors.js';
@@ -98,7 +98,7 @@ export declare class SpeechServerEngine implements ReadiumSpeechPlaybackEngine {
98
98
  getCurrentUtteranceIndex(): number;
99
99
  setCurrentUtteranceIndex(index: number, onComplete?: (success: boolean) => void): void;
100
100
  getUtteranceCount(): number;
101
- on(event: ReadiumSpeechPlaybackEvent["type"], callback: (event: ReadiumSpeechPlaybackEvent) => void): () => void;
101
+ on<T extends ReadiumSpeechPlaybackEvent["type"]>(event: T, callback: (event: ReadiumSpeechPlaybackEvent<T>) => void): () => void;
102
102
  private emitEvent;
103
103
  private setState;
104
104
  destroy(): Promise<void>;
@@ -11,6 +11,7 @@ export declare class SpeechServerEngineProvider implements ReadiumSpeechEnginePr
11
11
  private voices;
12
12
  constructor(options: SpeechServerEngineProviderOptions);
13
13
  getVoices(forceRefresh?: boolean): Promise<ReadiumSpeechVoice[]>;
14
+ isAvailable(): Promise<boolean>;
14
15
  createEngine(voice?: ReadiumSpeechVoice | string): Promise<ReadiumSpeechPlaybackEngine>;
15
16
  destroy(): Promise<void>;
16
17
  }
@@ -165,7 +165,7 @@ export declare class WebSpeechVoiceManager {
165
165
  * @returns The default voice for the language, or null if no voices are available
166
166
  */
167
167
  getDefaultVoice(languages: string | string[], voices?: ReadiumSpeechVoice[]): Promise<ReadiumSpeechVoice | null>;
168
- getBrowserVoices(maxTimeout?: number, interval?: number): Promise<SpeechSynthesisVoice[]>;
168
+ private getBrowserVoices;
169
169
  /**
170
170
  * Convert SpeechSynthesisVoice array to ReadiumSpeechVoice array
171
171
  * @private
@@ -20,7 +20,8 @@ export declare class WebSpeechEngine implements ReadiumSpeechPlaybackEngine {
20
20
  private isSpeakingInternal;
21
21
  private restartPending;
22
22
  private isPausedInternal;
23
- private isAndroidPaused;
23
+ private lacksNativePause;
24
+ private restartOnResume;
24
25
  private pausedAtUtteranceIndex;
25
26
  private initialized;
26
27
  private maxLengthExceeded;
@@ -74,7 +75,7 @@ export declare class WebSpeechEngine implements ReadiumSpeechPlaybackEngine {
74
75
  getCurrentUtteranceIndex(): number;
75
76
  setCurrentUtteranceIndex(index: number, onComplete?: (success: boolean) => void): void;
76
77
  getUtteranceCount(): number;
77
- on(event: ReadiumSpeechPlaybackEvent["type"], callback: (event: ReadiumSpeechPlaybackEvent) => void): () => void;
78
+ on<T extends ReadiumSpeechPlaybackEvent["type"]>(event: T, callback: (event: ReadiumSpeechPlaybackEvent<T>) => void): () => void;
78
79
  private emitEvent;
79
80
  private setState;
80
81
  destroy(): Promise<void>;
@@ -6,6 +6,7 @@ export declare class WebSpeechEngineProvider implements ReadiumSpeechEngineProvi
6
6
  readonly name: string;
7
7
  private voiceEngine;
8
8
  getVoices(): Promise<ReadiumSpeechVoice[]>;
9
+ isAvailable(): Promise<boolean>;
9
10
  createEngine(voice?: ReadiumSpeechVoice | string): Promise<ReadiumSpeechPlaybackEngine>;
10
11
  destroy(): Promise<void>;
11
12
  }
package/build/engine.d.ts CHANGED
@@ -21,6 +21,6 @@ export interface ReadiumSpeechPlaybackEngine {
21
21
  getCurrentUtteranceIndex(): number;
22
22
  setCurrentUtteranceIndex(index: number, onComplete?: (success: boolean) => void): void;
23
23
  getUtteranceCount(): number;
24
- on(event: ReadiumSpeechPlaybackEvent["type"], callback: (event: ReadiumSpeechPlaybackEvent) => void): () => void;
24
+ on<T extends ReadiumSpeechPlaybackEvent["type"]>(event: T, callback: (event: ReadiumSpeechPlaybackEvent<T>) => void): () => void;
25
25
  destroy(): Promise<void>;
26
26
  }