@readium/speech 0.5.0 → 0.6.0

package/build/navigator.d.ts

@@ -1,3 +1,7 @@
+import { GndObject } from './gnd/types';
+import { Configurable } from './preferences/Configurable';
+import { SpeechPreferences } from './preferences/SpeechPreferences';
+import { SpeechSettings } from './preferences/SpeechSettings';
 import { ReadiumSpeechVoice } from './voices/types';
 import { ReadiumSpeechUtterance } from './utterance';
 export type ReadiumSpeechPlaybackState = "playing" | "paused" | "idle" | "loading" | "ready";
@@ -5,13 +9,14 @@ export interface ReadiumSpeechPlaybackEvent {
     type: "start" | "pause" | "resume" | "end" | "stop" | "skip" | "error" | "boundary" | "mark" | "idle" | "loading" | "ready" | "voiceschanged" | "languagefallback";
     detail?: any;
 }
-export interface ReadiumSpeechNavigatorContract {
+export interface ReadiumSpeechNavigatorContract extends Configurable<SpeechSettings, SpeechPreferences> {
     getVoices(): Promise<ReadiumSpeechVoice[]>;
     setVoice(voice: ReadiumSpeechVoice | string): void;
     getCurrentVoice(): ReadiumSpeechVoice | null;
     setSpeakInContentLanguage(enabled: boolean): void;
     getSpeakInContentLanguage(): boolean;
     loadContent(content: ReadiumSpeechUtterance | ReadiumSpeechUtterance[]): void;
+    loadGndContent(nodes: GndObject[]): void;
     getCurrentContent(): ReadiumSpeechUtterance | null;
     getContentQueue(): ReadiumSpeechUtterance[];
     play(): void;
@@ -20,12 +25,6 @@ export interface ReadiumSpeechNavigatorContract {
     next(): boolean;
     previous(): boolean;
     jumpTo(utteranceIndex: number): void;
-    setRate(rate: number): void;
-    getRate(): number;
-    setPitch(pitch: number): void;
-    getPitch(): number;
-    setVolume(volume: number): void;
-    getVolume(): number;
     getState(): ReadiumSpeechPlaybackState;
     on(event: ReadiumSpeechPlaybackEvent["type"] | "contentchange", listener: (event: ReadiumSpeechPlaybackEvent) => void): () => void;
     destroy(): Promise<void>;

package/build/preferences/Configurable.d.ts

@@ -0,0 +1,12 @@
+import { IPreferencesEditor } from './PreferencesEditor.js';
+export interface ConfigurableSettings {
+    [key: string]: unknown;
+}
+export interface ConfigurablePreferences<T> {
+    merging(other: T): T;
+}
+export interface Configurable<S extends ConfigurableSettings, P extends ConfigurablePreferences<P>> {
+    settings: S;
+    submitPreferences(preferences: P): void;
+    preferencesEditor: IPreferencesEditor;
+}

package/build/preferences/Preference.d.ts

@@ -0,0 +1,74 @@
+export interface IPreference<T> {
+    value: T | null | undefined;
+    effectiveValue: T | null | undefined;
+    isEffective: boolean;
+    clear(): void;
+}
+export interface IEnumPreference<T> extends IPreference<T> {
+    supportedValues: T[];
+}
+export interface IRangePreference<T> extends IPreference<T> {
+    supportedRange: [T, T];
+    step: number;
+    increment(): void;
+    decrement(): void;
+    format(value: T): string;
+}
+export declare class Preference<T> implements IPreference<T> {
+    protected _value?: T | null;
+    protected readonly _effectiveValue?: T | null;
+    protected readonly _isEffective: boolean;
+    protected _onChange: (newValue: T | null | undefined) => void;
+    constructor({ initialValue, effectiveValue, isEffective, onChange, }: {
+        initialValue?: T | null;
+        effectiveValue?: T | null;
+        isEffective: boolean;
+        onChange: (newValue: T | null | undefined) => void;
+    });
+    set value(value: T | null | undefined);
+    get value(): T | null | undefined;
+    get effectiveValue(): T | null | undefined;
+    get isEffective(): boolean;
+    clear(): void;
+}
+export declare class EnumPreference<T extends string | number | symbol> extends Preference<T> implements IEnumPreference<T> {
+    private readonly _supportedValues;
+    constructor({ initialValue, effectiveValue, isEffective, onChange, supportedValues, }: {
+        initialValue?: T | null;
+        effectiveValue?: T | null;
+        isEffective: boolean;
+        onChange: (newValue: T | null | undefined) => void;
+        supportedValues: T[];
+    });
+    set value(value: T | null | undefined);
+    get value(): T | null | undefined;
+    get supportedValues(): T[];
+}
+export declare class BooleanPreference extends Preference<boolean> {
+    set value(value: boolean | null | undefined);
+    get value(): boolean | null | undefined;
+}
+export declare class StringArrayPreference extends Preference<string[]> {
+    set value(value: string[] | null | undefined);
+    get value(): string[] | null | undefined;
+}
+export declare class RangePreference<T extends number> extends Preference<T> implements IRangePreference<T> {
+    private readonly _supportedRange;
+    private readonly _step;
+    private readonly _decimals;
+    constructor({ initialValue, effectiveValue, isEffective, onChange, supportedRange, step, }: {
+        initialValue?: T | null;
+        effectiveValue?: T | null;
+        isEffective: boolean;
+        onChange: (newValue: T | null | undefined) => void;
+        supportedRange: [T, T];
+        step: number;
+    });
+    set value(value: T | null | undefined);
+    get value(): T | null | undefined;
+    get supportedRange(): [T, T];
+    get step(): number;
+    increment(): void;
+    decrement(): void;
+    format(value: T): string;
+}

package/build/preferences/PreferencesEditor.d.ts

@@ -0,0 +1,5 @@
+import { ConfigurablePreferences } from './Configurable.js';
+export interface IPreferencesEditor {
+    preferences: ConfigurablePreferences<unknown>;
+    clear(): void;
+}

package/build/preferences/SpeechDefaults.d.ts

@@ -0,0 +1,31 @@
+import { GndRole } from '../gnd/types.js';
+import { ExtractionFormat, LanguageMode, PauseScope, VerbosityPreset } from './SpeechPreferences.js';
+export interface ISpeechDefaults {
+    format?: ExtractionFormat | null;
+    inlineContextualization?: boolean | null;
+    verbosity?: VerbosityPreset | null;
+    skip?: GndRole[] | null;
+    contextualize?: GndRole[] | null;
+    language?: LanguageMode | null;
+    pauseDuration?: number | null;
+    pauseScope?: PauseScope | null;
+    automaticPausesAtPageOrSpreadEnd?: boolean | null;
+    rate?: number | null;
+    pitch?: number | null;
+    volume?: number | null;
+}
+export declare class SpeechDefaults {
+    readonly format: ExtractionFormat;
+    readonly inlineContextualization: boolean;
+    readonly verbosity: VerbosityPreset;
+    readonly skip: GndRole[];
+    readonly contextualize: GndRole[];
+    readonly language: LanguageMode;
+    readonly pauseDuration: number;
+    readonly pauseScope: PauseScope;
+    readonly automaticPausesAtPageOrSpreadEnd: boolean;
+    readonly rate: number;
+    readonly pitch: number;
+    readonly volume: number;
+    constructor(defaults?: ISpeechDefaults);
+}

package/build/preferences/SpeechPreferences.d.ts

@@ -0,0 +1,36 @@
+import { GndRole } from '../gnd/types.js';
+import { ConfigurablePreferences } from './Configurable.js';
+export type VerbosityPreset = "none" | "few" | "some" | "most" | "custom";
+export type LanguageMode = "none" | "block-level" | "always";
+export type ExtractionFormat = "plain" | "ssml";
+export type PauseScope = "utterance" | "block";
+export interface ISpeechPreferences {
+    format?: ExtractionFormat | null;
+    inlineContextualization?: boolean | null;
+    verbosity?: VerbosityPreset | null;
+    skip?: GndRole[] | null;
+    contextualize?: GndRole[] | null;
+    language?: LanguageMode | null;
+    pauseDuration?: number | null;
+    pauseScope?: PauseScope | null;
+    automaticPausesAtPageOrSpreadEnd?: boolean | null;
+    rate?: number | null;
+    pitch?: number | null;
+    volume?: number | null;
+}
+export declare class SpeechPreferences implements ISpeechPreferences, ConfigurablePreferences<SpeechPreferences> {
+    format: ExtractionFormat | null | undefined;
+    inlineContextualization: boolean | null | undefined;
+    verbosity: VerbosityPreset | null | undefined;
+    skip: GndRole[] | null | undefined;
+    contextualize: GndRole[] | null | undefined;
+    language: LanguageMode | null | undefined;
+    pauseDuration: number | null | undefined;
+    pauseScope: PauseScope | null | undefined;
+    automaticPausesAtPageOrSpreadEnd: boolean | null | undefined;
+    rate: number | null | undefined;
+    pitch: number | null | undefined;
+    volume: number | null | undefined;
+    constructor(preferences?: ISpeechPreferences);
+    merging(other: SpeechPreferences): SpeechPreferences;
+}

package/build/preferences/SpeechPreferencesEditor.d.ts

@@ -0,0 +1,23 @@
+import { IPreferencesEditor } from './PreferencesEditor.js';
+import { BooleanPreference, EnumPreference, RangePreference, StringArrayPreference } from './Preference.js';
+import { SpeechPreferences, VerbosityPreset, LanguageMode, ExtractionFormat, PauseScope } from './SpeechPreferences.js';
+import { SpeechSettings } from './SpeechSettings.js';
+export declare class SpeechPreferencesEditor implements IPreferencesEditor {
+    preferences: SpeechPreferences;
+    private settings;
+    constructor(initialPreferences: SpeechPreferences, settings: SpeechSettings);
+    clear(): void;
+    private updatePreference;
+    get format(): EnumPreference<ExtractionFormat>;
+    get inlineContextualization(): BooleanPreference;
+    get verbosity(): EnumPreference<VerbosityPreset>;
+    get skip(): StringArrayPreference;
+    get contextualize(): StringArrayPreference;
+    get language(): EnumPreference<LanguageMode>;
+    get pauseDuration(): RangePreference<number>;
+    get pauseScope(): EnumPreference<PauseScope>;
+    get automaticPausesAtPageOrSpreadEnd(): BooleanPreference;
+    get rate(): RangePreference<number>;
+    get pitch(): RangePreference<number>;
+    get volume(): RangePreference<number>;
+}

package/build/preferences/SpeechSettings.d.ts

@@ -0,0 +1,20 @@
+import { GndRole } from '../gnd/types.js';
+import { ConfigurableSettings } from './Configurable.js';
+import { SpeechDefaults } from './SpeechDefaults.js';
+import { ExtractionFormat, LanguageMode, PauseScope, SpeechPreferences, VerbosityPreset } from './SpeechPreferences.js';
+export declare class SpeechSettings implements ConfigurableSettings {
+    [key: string]: unknown;
+    readonly format: ExtractionFormat;
+    readonly inlineContextualization: boolean;
+    readonly verbosity: VerbosityPreset;
+    readonly skip: GndRole[];
+    readonly contextualize: GndRole[];
+    readonly language: LanguageMode;
+    readonly pauseDuration: number;
+    readonly pauseScope: PauseScope;
+    readonly automaticPausesAtPageOrSpreadEnd: boolean;
+    readonly rate: number;
+    readonly pitch: number;
+    readonly volume: number;
+    constructor(preferences: SpeechPreferences, defaults: SpeechDefaults);
+}

package/build/preferences/constraints.d.ts

@@ -0,0 +1,14 @@
+import { ExtractionFormat, ISpeechPreferences, LanguageMode, PauseScope, VerbosityPreset } from './SpeechPreferences.js';
+export interface RangeConfig {
+    range: [number, number];
+    step: number;
+}
+export declare const pauseDurationRangeConfig: RangeConfig;
+export declare const rateRangeConfig: RangeConfig;
+export declare const pitchRangeConfig: RangeConfig;
+export declare const volumeRangeConfig: RangeConfig;
+export declare const verbosityPresets: VerbosityPreset[];
+export declare const languageModes: LanguageMode[];
+export declare const extractionFormats: ExtractionFormat[];
+export declare const pauseScopes: PauseScope[];
+export declare const extractionPreferenceKeys: (keyof ISpeechPreferences)[];

package/build/preferences/guards.d.ts

@@ -0,0 +1,4 @@
+export declare function ensureBoolean(value: boolean | null | undefined): boolean | null | undefined;
+export declare function ensureEnumValue<T extends string | number | symbol>(value: T | null | undefined, supportedValues: readonly T[]): T | null | undefined;
+export declare function ensureValueInRange(value: number | null | undefined, range: [number, number]): number | null | undefined;
+export declare function ensureStringArray(value: string[] | null | undefined): string[] | null | undefined;

package/build/preferences/index.d.ts

@@ -0,0 +1,11 @@
+export type { Configurable, ConfigurablePreferences, ConfigurableSettings } from './Configurable.js';
+export type { IPreferencesEditor } from './PreferencesEditor.js';
+export { BooleanPreference, EnumPreference, Preference, RangePreference, StringArrayPreference } from './Preference.js';
+export type { IEnumPreference, IPreference, IRangePreference } from './Preference.js';
+export { SpeechPreferences } from './SpeechPreferences.js';
+export type { ISpeechPreferences, LanguageMode, VerbosityPreset } from './SpeechPreferences.js';
+export { SpeechDefaults } from './SpeechDefaults.js';
+export type { ISpeechDefaults } from './SpeechDefaults.js';
+export { SpeechSettings } from './SpeechSettings.js';
+export { SpeechPreferencesEditor } from './SpeechPreferencesEditor.js';
+export { contextualizedAtVerbosity, skippableAtVerbosity } from './verbosityTables.js';

package/build/preferences/verbosityTables.d.ts

@@ -0,0 +1,4 @@
+import { GndRole } from '../gnd/types.js';
+import { VerbosityPreset } from './SpeechPreferences.js';
+export declare const skippableAtVerbosity: Readonly<Record<Exclude<VerbosityPreset, "custom">, ReadonlySet<GndRole>>>;
+export declare const contextualizedAtVerbosity: Readonly<Record<Exclude<VerbosityPreset, "custom">, ReadonlySet<GndRole>>>;

package/build/speechNavigator.d.ts

@@ -1,13 +1,32 @@
 import { ReadiumSpeechPlaybackEngine } from './engine';
+import { GndObject } from './gnd/types';
 import { ReadiumSpeechNavigatorContract, ReadiumSpeechPlaybackEvent, ReadiumSpeechPlaybackState } from './navigator';
+import { ISpeechDefaults } from './preferences/SpeechDefaults';
+import { ISpeechPreferences, SpeechPreferences } from './preferences/SpeechPreferences';
+import { SpeechPreferencesEditor } from './preferences/SpeechPreferencesEditor';
+import { SpeechSettings } from './preferences/SpeechSettings';
 import { ReadiumSpeechUtterance } from './utterance';
 import { ReadiumSpeechVoice } from './voices/types';
+export interface ReadiumSpeechNavigatorConfiguration {
+    preferences?: ISpeechPreferences;
+    defaults?: ISpeechDefaults;
+}
 export declare class ReadiumSpeechNavigator implements ReadiumSpeechNavigatorContract {
     private engine;
     private contentQueue;
     private eventListeners;
     private navigatorState;
-    constructor(engine: ReadiumSpeechPlaybackEngine);
+    private pendingAdvanceTimeout;
+    private _defaults;
+    private _preferences;
+    private _settings;
+    private _preferencesEditor;
+    private source;
+    private contentSources;
+    private pendingResumeIndex;
+    private pendingResumeState;
+    constructor(engine: ReadiumSpeechPlaybackEngine, configuration?: ReadiumSpeechNavigatorConfiguration);
+    private applyEngineParameters;
     private initializeEngine;
     private setupEngineListeners;
     private setNavigatorState;
@@ -17,25 +36,29 @@ export declare class ReadiumSpeechNavigator implements ReadiumSpeechNavigatorCon
     setSpeakInContentLanguage(enabled: boolean): void;
     getSpeakInContentLanguage(): boolean;
     loadContent(content: ReadiumSpeechUtterance | ReadiumSpeechUtterance[]): void;
+    loadGndContent(nodes: GndObject[]): void;
+    private setContentQueue;
+    private reextract;
+    private resolveResumeIndex;
     getCurrentContent(): ReadiumSpeechUtterance | null;
     getContentQueue(): ReadiumSpeechUtterance[];
     private getCurrentUtteranceIndex;
     play(): void;
     pause(): void;
     stop(): void;
+    private clearPendingAdvance;
     private skipToPosition;
     next(forcePlay?: boolean): boolean;
     previous(forcePlay?: boolean): boolean;
     jumpTo(utteranceIndex: number, forcePlay?: boolean): boolean;
-    setRate(rate: number): void;
-    getRate(): number;
-    setPitch(pitch: number): void;
-    getPitch(): number;
-    setVolume(volume: number): void;
-    getVolume(): number;
     getState(): ReadiumSpeechPlaybackState;
     on(event: ReadiumSpeechPlaybackEvent["type"] | "contentchange", listener: (event: ReadiumSpeechPlaybackEvent) => void): () => void;
     private emitEvent;
     private emitContentChangeEvent;
+    get settings(): SpeechSettings;
+    get preferencesEditor(): SpeechPreferencesEditor;
+    submitPreferences(preferences: SpeechPreferences): void;
+    private applyPreferences;
+    private sameSettingValue;
     destroy(): Promise<void>;
 }

package/build/utterance.d.ts

@@ -3,4 +3,5 @@ export interface ReadiumSpeechUtterance {
     plain?: string;
     ssml?: string;
     language?: string;
+    startsNewBlock?: true;
 }

package/build/utterances/extractUtterances.d.ts

@@ -10,3 +10,10 @@ import { ExtractUtterancesOptions } from './types.js';
  * rather than a wrapped document.
  */
 export declare function extractUtterances(nodes: GndObject[], options: ExtractUtterancesOptions): ReadiumSpeechUtterance[];
+/**
+ * Same as `extractUtterances()`, plus `sources[i]`: the node that produced `utterances[i]`.
+ */
+export declare function extractUtterancesWithSources(nodes: GndObject[], options: ExtractUtterancesOptions): {
+    utterances: ReadiumSpeechUtterance[];
+    sources: (GndObject | undefined)[];
+};

package/build/utterances/index.d.ts

@@ -1,4 +1,4 @@
 export { extractUtterances } from './extractUtterances.js';
-export { skippableRoles } from './roles.js';
+export { blockLevelRoles, skippableRoles } from './roles.js';
 export { defaultAnnouncements } from './announcements.js';
 export type { Announcement, AnnouncementKey, AnnouncementPair, Announcements, RoleAnnouncement, ExtractUtterancesOptions, } from './types.js';

package/build/utterances/roles.d.ts

@@ -1,2 +1,3 @@
 import { GndRole } from '../gnd/types.js';
 export declare const skippableRoles: GndRole[];
+export declare const blockLevelRoles: GndRole[];

package/build/utterances/text.d.ts

@@ -47,7 +47,7 @@ export interface SsmlSegment {
 export declare function hasPlaceholder(ssml: string): boolean;
 /**
  * Splits a raw (pre-`stripPlaceholders`) SSML string on its embedded
- * `<readium:TAG id="...">` placeholders, for `interruptSentence`: each
+ * `<readium:TAG id="...">` placeholders, for `inlineContextualization`: each
  * placeholder becomes its own segment (resolved via the `GndObject` sharing
  * its `id`) instead of being spoken after the whole enclosing text.
  */

package/build/utterances/types.d.ts

@@ -12,7 +12,7 @@ export interface ExtractUtterancesOptions {
     format?: "plain" | "ssml";
     announcements?: Announcements;
     skip?: GndRole[];
+    contextualize?: GndRole[];
     language?: "none" | "block-level" | "always";
-    interruptSentence?: boolean;
-    contextualize?: boolean;
+    inlineContextualization?: boolean;
 }

package/package.json

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