@readium/navigator 2.11.1 → 2.12.0

package/src/readaloud/ReadingUnit.ts

@@ -0,0 +1,154 @@
+import { GuidedNavigationObject, Layout, Link, Profile, Publication } from "@readium/shared";
+import { Navigator, VisualNavigatorViewport } from "../Navigator.ts";
+import { GuidedNavigationProvider } from "./GuidedNavigationProvider.ts";
+
+/** Reading order links whose Guided Navigation objects are read as one sequence. */
+export interface ReadingUnit {
+    links: Link[];
+}
+
+/**
+ * Splits the publication into reading units: the displayed spread for fixed layouts, Divina excepted,
+ * and a single resource otherwise. Spreads are only known to the navigator, so it's moved to find them;
+ * FXL navigators update their viewport synchronously, so it's read without waiting for the callback.
+ */
+export class ReadingUnits {
+    private readonly spreads: boolean;
+
+    constructor(private readonly navigator: Navigator & { readonly viewport?: VisualNavigatorViewport }) {
+        const metadata = navigator.publication.metadata;
+        this.spreads = metadata.effectiveLayout === Layout.fixed && !metadata.conformsTo?.includes(Profile.DIVINA);
+    }
+
+    /** The unit containing `href`. */
+    around(href: string): ReadingUnit | undefined {
+        const link = this.navigator.publication.readingOrder.findWithHref(href);
+        if (!link) return undefined;
+        if (this.spreads && !this.displays(link.href)) this.navigator.go(link.locator, false, () => {});
+        return this.displayedFrom(link, () => true);
+    }
+
+    /** The first link of the unit following `unit`, without moving the navigator. */
+    linkAfter(unit: ReadingUnit): Link | undefined {
+        const index = this.indexOf(unit.links[unit.links.length - 1]);
+        return index < 0 ? undefined : this.navigator.publication.readingOrder.items[index + 1];
+    }
+
+    /** The last link of the unit preceding `unit`, without moving the navigator. */
+    linkBefore(unit: ReadingUnit): Link | undefined {
+        const index = this.indexOf(unit.links[0]);
+        return index <= 0 ? undefined : this.navigator.publication.readingOrder.items[index - 1];
+    }
+
+    after(unit: ReadingUnit): ReadingUnit | undefined {
+        const link = this.linkAfter(unit);
+        if (!link) return undefined;
+        const last = unit.links[unit.links.length - 1];
+        if (this.spreads) this.move(last, link, (cb) => this.navigator.goForward(false, cb));
+        return this.displayedFrom(link, displayed => this.indexOf(displayed) > this.indexOf(last));
+    }
+
+    before(unit: ReadingUnit): ReadingUnit | undefined {
+        const link = this.linkBefore(unit);
+        if (!link) return undefined;
+        const first = unit.links[0];
+        if (this.spreads) this.move(first, link, (cb) => this.navigator.goBackward(false, cb));
+        return this.displayedFrom(link, displayed => this.indexOf(displayed) < this.indexOf(first));
+    }
+
+    /** Whether `href` is a page of the displayed spread. */
+    displays(href: string): boolean {
+        return this.spreads && (this.navigator.viewport?.readingOrder ?? []).includes(href);
+    }
+
+    private move(edge: Link, link: Link, step: (cb: (ok: boolean) => void) => void) {
+        if (this.displays(edge.href)) step(() => {});
+        else this.navigator.go(link.locator, false, () => {});
+    }
+
+    // The displayed pages kept by `keep`, if they include `link`, otherwise `link` alone.
+    private displayedFrom(link: Link, keep: (displayed: Link) => boolean): ReadingUnit {
+        if (!this.spreads) return { links: [link] };
+        const links = (this.navigator.viewport?.readingOrder ?? [])
+            .map(href => this.navigator.publication.readingOrder.findWithHref(href))
+            .filter((displayed): displayed is Link => displayed !== undefined && keep(displayed))
+            .sort((a, b) => this.indexOf(a) - this.indexOf(b));
+        return links.some(displayed => displayed.href === link.href) ? { links } : { links: [link] };
+    }
+
+    private indexOf(link: Link): number {
+        return this.navigator.publication.readingOrder.findIndexWithHref(link.href);
+    }
+}
+
+export interface StitchedUnit {
+    /** The unit's Guided Navigation objects, concatenated in reading order. */
+    guided: GuidedNavigationObject[];
+    /** Links whose objects couldn't be obtained, left out of `guided`. */
+    failures: { link: Link; error: unknown }[];
+}
+
+const UPPER_BOUNDARY = 10;
+const LOWER_BOUNDARY = 5;
+
+/**
+ * Keeps the Guided Navigation objects of the resources around the unit being read,
+ * fetching those within LOWER_BOUNDARY reading order items and releasing those beyond UPPER_BOUNDARY.
+ */
+export class GuidedNavigationPool {
+    private readonly guides = new Map<string, Promise<GuidedNavigationObject[] | undefined>>();
+
+    constructor(private readonly publication: Publication, private readonly provider: GuidedNavigationProvider) {}
+
+    /**
+     * Concatenates the Guided Navigation objects of every link in the unit, in reading order,
+     * fetching at most `concurrency` resources at once, then fetches the unit's neighbours.
+     */
+    async stitch(unit: ReadingUnit, concurrency = 6): Promise<StitchedUnit> {
+        const guides: (GuidedNavigationObject[] | undefined)[] = new Array(unit.links.length);
+        const failures: { index: number; link: Link; error: unknown }[] = [];
+        let next = 0;
+        const worker = async () => {
+            while (next < unit.links.length) {
+                const index = next++;
+                const link = unit.links[index];
+                try {
+                    guides[index] = await this.guideFor(link);
+                } catch (error) {
+                    failures.push({ index, link, error });
+                }
+            }
+        };
+        const stitched = Promise.all(Array.from({ length: Math.min(concurrency, unit.links.length) }, worker));
+        this.update(unit);
+        await stitched;
+        return {
+            guided: guides.flatMap(guide => guide ?? []),
+            failures: failures.sort((a, b) => a.index - b.index).map(({ link, error }) => ({ link, error })),
+        };
+    }
+
+    private update(unit: ReadingUnit) {
+        const items = this.publication.readingOrder.items;
+        const i = this.publication.readingOrder.findIndexWithHref(unit.links[0].href);
+        if (i < 0) return;
+        items.forEach((link, j) => {
+            const href = link.href.split("#")[0];
+            if (j > i + UPPER_BOUNDARY || j < i - UPPER_BOUNDARY) this.guides.delete(href);
+            else if (j < i + LOWER_BOUNDARY && j > i - LOWER_BOUNDARY) this.guideFor(link).catch(() => {});
+        });
+    }
+
+    private guideFor(link: Link): Promise<GuidedNavigationObject[] | undefined> {
+        const href = link.href.split("#")[0];
+        let guide = this.guides.get(href);
+        if (!guide) {
+            guide = this.provider.guideFor(link);
+            this.guides.set(href, guide);
+            guide.catch(() => {
+                if (this.guides.get(href) === guide) this.guides.delete(href);
+            });
+        }
+        return guide;
+    }
+}

package/src/readaloud/SpeechProgress.ts

@@ -0,0 +1,60 @@
+import { ReadiumSpeechUtterance } from "@readium/speech";
+
+// Characters per second at rate 1 until a voice is measured, on the slow side so pages turn late rather than early.
+const DEFAULT_SPEED = 12;
+// Shorter utterances are dominated by the voice's start latency.
+const MIN_MEASURED_LENGTH = 40;
+
+/** Times the utterance being spoken, and measures each voice's speed on the utterances it finishes. */
+export class SpeechProgress {
+    private readonly speeds = new Map<string, number>();
+    private utterance?: ReadiumSpeechUtterance;
+    private startedAt = 0;
+    private pausedAt?: number;
+
+    start(utterance: ReadiumSpeechUtterance) {
+        this.utterance = utterance;
+        this.startedAt = performance.now();
+        this.pausedAt = undefined;
+    }
+
+    pause() {
+        if (this.utterance && this.pausedAt === undefined) this.pausedAt = performance.now();
+    }
+
+    resume() {
+        if (this.pausedAt === undefined) return;
+        this.startedAt += performance.now() - this.pausedAt;
+        this.pausedAt = undefined;
+    }
+
+    /** Measures the speed of `voice` once it has spoken `utterance` through. */
+    end(utterance: ReadiumSpeechUtterance | null, voice: string, rate: number) {
+        const length = (utterance?.plain ?? "").length;
+        if (utterance === this.utterance && this.pausedAt === undefined && length >= MIN_MEASURED_LENGTH && rate > 0) {
+            const seconds = (performance.now() - this.startedAt) / 1000;
+            if (seconds > 0) this.speeds.set(voice, length / seconds / rate);
+        }
+        this.reset();
+    }
+
+    reset() {
+        this.utterance = undefined;
+        this.pausedAt = undefined;
+    }
+
+    get speaking(): boolean {
+        return this.utterance !== undefined && this.pausedAt === undefined;
+    }
+
+    /** Seconds spent speaking the current utterance. */
+    elapsed(): number {
+        if (!this.utterance) return 0;
+        return ((this.pausedAt ?? performance.now()) - this.startedAt) / 1000;
+    }
+
+    /** Characters per second of `voice` at `rate`. */
+    speed(voice: string, rate: number): number {
+        return (this.speeds.get(voice) ?? DEFAULT_SPEED) * rate;
+    }
+}

package/src/readaloud/index.ts

@@ -0,0 +1,17 @@
+export * from './GuidedNavigationProvider.ts';
+export * from './ReadAloudNavigator.ts';
+export * from './preferences/index.ts';
+export {
+    defaultContextualizations,
+    skippableRoles,
+    filterByLanguages,
+    filterOutNoveltyVoices,
+    filterOutVeryLowQualityVoices,
+    getQualityValue,
+    groupVoicesByLanguage,
+    sortAlphabetically,
+    sortByQuality,
+    sortVoicesByRegions
+} from "@readium/speech";
+export type { ExtractionFormat, LanguageMode, ReadiumSpeechPlaybackEngine, ReadiumSpeechVoice, Segmentation, VerbosityPreset } from "@readium/speech";
+export type { GndRole } from "@readium/guided-navigation";

package/src/readaloud/preferences/ReadAloudDefaults.ts

@@ -0,0 +1,24 @@
+import { DecorationStyleType } from "../../decorations/index.ts";
+import { ensureBoolean, ensureDecorationStyle, ensureEnumValue } from "../../preferences/guards.ts";
+import { IReadAloudPreferences, ReadAloudAutoPause, ReadAloudDecorationStyle } from "./ReadAloudPreferences.ts";
+
+export type IReadAloudDefaults = IReadAloudPreferences;
+
+export class ReadAloudDefaults {
+  /** Defaults of the speech fields, validated by speech itself. */
+  speech: IReadAloudPreferences;
+  autoPause: ReadAloudAutoPause;
+  speakInContentLanguage: boolean;
+  utteranceStyle: ReadAloudDecorationStyle;
+  wordStyle: ReadAloudDecorationStyle;
+
+  constructor(defaults: IReadAloudDefaults = {}) {
+    const { autoPause, speakInContentLanguage, utteranceStyle, wordStyle, ...speech } = defaults;
+    // Sentences are only joined across objects, and so across pages, in sentence segmentation.
+    this.speech = { segmentation: "sentence", skip: ["pagebreak"], ...speech };
+    this.autoPause = ensureEnumValue<ReadAloudAutoPause>(autoPause, ReadAloudAutoPause) || ReadAloudAutoPause.none;
+    this.speakInContentLanguage = ensureBoolean(speakInContentLanguage) ?? false;
+    this.utteranceStyle = ensureDecorationStyle(utteranceStyle) ?? { type: DecorationStyleType.Highlight };
+    this.wordStyle = ensureDecorationStyle(wordStyle) ?? { type: DecorationStyleType.Underline };
+  }
+}

package/src/readaloud/preferences/ReadAloudPreferences.ts

@@ -0,0 +1,104 @@
+import type { GndRole } from "@readium/guided-navigation";
+import { ExtractionFormat, LanguageMode, Segmentation, SpeechPreferences, VerbosityPreset } from "@readium/speech";
+import { ConfigurablePreferences } from "../../preferences/Configurable.ts";
+import { ensureBoolean, ensureDecorationStyle, ensureEnumValue } from "../../preferences/guards.ts";
+import { BuiltinDecorationStyle, NamedDecorationStyle } from "../../decorations/index.ts";
+
+/**
+ * When playback pauses on its own: never, after every utterance, before every block,
+ * or before the first utterance starting on another page or outside the displayed spread.
+ */
+export const ReadAloudAutoPause = {
+  none: "none",
+  utterance: "utterance",
+  block: "block",
+  page: "page",
+  spread: "spread",
+} as const;
+export type ReadAloudAutoPause = typeof ReadAloudAutoPause[keyof typeof ReadAloudAutoPause];
+
+/** A decoration style, or `false` to not decorate at all. */
+export type ReadAloudDecorationStyle = BuiltinDecorationStyle | NamedDecorationStyle | false;
+
+export interface IReadAloudPreferences {
+  format?: ExtractionFormat | null,
+  inlineContextualization?: boolean | null,
+  verbosity?: VerbosityPreset | null,
+  skip?: GndRole[] | null,
+  contextualize?: GndRole[] | null,
+  language?: LanguageMode | null,
+  segmentation?: Segmentation | null,
+  pauseDuration?: number | null,
+  autoPause?: ReadAloudAutoPause | null,
+  speakInContentLanguage?: boolean | null,
+  rate?: number | null,
+  pitch?: number | null,
+  volume?: number | null,
+  /** Style of the utterance being spoken */
+  utteranceStyle?: ReadAloudDecorationStyle | null,
+  /** Style of the word being spoken */
+  wordStyle?: ReadAloudDecorationStyle | null
+}
+
+export class ReadAloudPreferences implements ConfigurablePreferences<ReadAloudPreferences> {
+  format?: ExtractionFormat | null;
+  inlineContextualization?: boolean | null;
+  verbosity?: VerbosityPreset | null;
+  skip?: GndRole[] | null;
+  contextualize?: GndRole[] | null;
+  language?: LanguageMode | null;
+  segmentation?: Segmentation | null;
+  pauseDuration?: number | null;
+  autoPause?: ReadAloudAutoPause | null;
+  speakInContentLanguage?: boolean | null;
+  rate?: number | null;
+  pitch?: number | null;
+  volume?: number | null;
+  utteranceStyle?: ReadAloudDecorationStyle | null;
+  wordStyle?: ReadAloudDecorationStyle | null;
+
+  constructor(preferences: IReadAloudPreferences = {}) {
+    const { speakInContentLanguage, ...speechPreferences } = preferences;
+    const speech = new SpeechPreferences({ ...speechPreferences, autoPause: undefined });
+    this.format = speech.format;
+    this.inlineContextualization = speech.inlineContextualization;
+    this.verbosity = speech.verbosity;
+    this.skip = speech.skip;
+    this.contextualize = speech.contextualize;
+    this.language = speech.language;
+    this.segmentation = speech.segmentation;
+    this.pauseDuration = speech.pauseDuration;
+    this.autoPause = ensureEnumValue<ReadAloudAutoPause>(preferences.autoPause, ReadAloudAutoPause);
+    this.speakInContentLanguage = ensureBoolean(speakInContentLanguage);
+    this.rate = speech.rate;
+    this.pitch = speech.pitch;
+    this.volume = speech.volume;
+    this.utteranceStyle = ensureDecorationStyle(preferences.utteranceStyle);
+    this.wordStyle = ensureDecorationStyle(preferences.wordStyle);
+  }
+
+  static serialize(preferences: ReadAloudPreferences): string {
+    const { ...properties } = preferences;
+    return JSON.stringify(properties);
+  }
+
+  static deserialize(preferences: string): ReadAloudPreferences | null {
+    try {
+      const parsedPreferences = JSON.parse(preferences);
+      return new ReadAloudPreferences(parsedPreferences);
+    } catch (error) {
+      console.error("Failed to deserialize preferences:", error);
+      return null;
+    }
+  }
+
+  merging(other: ReadAloudPreferences): ReadAloudPreferences {
+    const merged: IReadAloudPreferences = { ...this };
+    for (const key of Object.keys(other) as (keyof IReadAloudPreferences)[]) {
+      if (other[key] !== undefined) {
+        (merged as Record<string, unknown>)[key] = other[key];
+      }
+    }
+    return new ReadAloudPreferences(merged);
+  }
+}

package/src/readaloud/preferences/ReadAloudPreferencesEditor.ts

@@ -0,0 +1,115 @@
+import { Layout } from "@readium/shared";
+import { SpeechPreferences, SpeechPreferencesEditor, SpeechSettings } from "@readium/speech";
+import { IPreferencesEditor } from "../../preferences/PreferencesEditor.ts";
+import { BooleanPreference, EnumPreference, Preference } from "../../preferences/Preference.ts";
+import { ReadAloudAutoPause, ReadAloudDecorationStyle, ReadAloudPreferences } from "./ReadAloudPreferences.ts";
+import { ReadAloudSettings } from "./ReadAloudSettings.ts";
+
+/**
+ * Edits read-aloud preferences, speech's own fields through speech's editor.
+ */
+export class ReadAloudPreferencesEditor implements IPreferencesEditor {
+  private speech: SpeechPreferencesEditor;
+  private own: ReadAloudPreferences;
+  private settings: ReadAloudSettings;
+  private layout: Layout;
+
+  /**
+   * @param layout How the publication is displayed: `Layout.reflowable` for columns, `Layout.scrolled` when scrolled.
+   */
+  constructor(initialPreferences: ReadAloudPreferences, settings: ReadAloudSettings, speechSettings: SpeechSettings, layout: Layout) {
+    const { speakInContentLanguage, ...speechPreferences } = initialPreferences;
+    this.speech = new SpeechPreferencesEditor(new SpeechPreferences({ ...speechPreferences, autoPause: undefined }), speechSettings);
+    this.own = new ReadAloudPreferences({
+      autoPause: initialPreferences.autoPause,
+      speakInContentLanguage,
+      utteranceStyle: initialPreferences.utteranceStyle,
+      wordStyle: initialPreferences.wordStyle
+    });
+    this.settings = settings;
+    this.layout = layout;
+  }
+
+  get preferences(): ReadAloudPreferences {
+    return new ReadAloudPreferences({
+      ...this.speech.preferences,
+      autoPause: this.own.autoPause,
+      speakInContentLanguage: this.own.speakInContentLanguage,
+      utteranceStyle: this.own.utteranceStyle,
+      wordStyle: this.own.wordStyle
+    });
+  }
+
+  clear(): void {
+    this.speech.clear();
+    this.own = new ReadAloudPreferences({
+      autoPause: null,
+      speakInContentLanguage: null,
+      utteranceStyle: null,
+      wordStyle: null
+    });
+  }
+
+  private updatePreference<K extends keyof ReadAloudPreferences>(key: K, value: ReadAloudPreferences[K]) {
+    this.own[key] = value;
+  }
+
+  get format() { return this.speech.format; }
+  get inlineContextualization() { return this.speech.inlineContextualization; }
+  get verbosity() { return this.speech.verbosity; }
+  get skip() { return this.speech.skip; }
+  get contextualize() { return this.speech.contextualize; }
+  get language() { return this.speech.language; }
+  get segmentation() { return this.speech.segmentation; }
+  get pauseDuration() { return this.speech.pauseDuration; }
+  get rate() { return this.speech.rate; }
+  get pitch() { return this.speech.pitch; }
+  get volume() { return this.speech.volume; }
+
+  get autoPause(): EnumPreference<ReadAloudAutoPause> {
+    return new EnumPreference<ReadAloudAutoPause>({
+      initialValue: this.own.autoPause,
+      effectiveValue: this.settings.autoPause,
+      isEffective: this.layout === Layout.fixed || this.settings.autoPause !== ReadAloudAutoPause.spread &&
+        (this.layout === Layout.reflowable || this.settings.autoPause !== ReadAloudAutoPause.page),
+      onChange: (newValue) => {
+        this.updatePreference("autoPause", newValue ?? null);
+      },
+      supportedValues: Object.values(ReadAloudAutoPause)
+        .filter(value => value !== ReadAloudAutoPause.spread || this.layout === Layout.fixed)
+    });
+  }
+
+  get speakInContentLanguage(): BooleanPreference {
+    return new BooleanPreference({
+      initialValue: this.own.speakInContentLanguage,
+      effectiveValue: this.settings.speakInContentLanguage,
+      isEffective: this.settings.language !== "none",
+      onChange: (newValue) => {
+        this.updatePreference("speakInContentLanguage", newValue ?? null);
+      }
+    });
+  }
+
+  get utteranceStyle(): Preference<ReadAloudDecorationStyle> {
+    return new Preference<ReadAloudDecorationStyle>({
+      initialValue: this.own.utteranceStyle,
+      effectiveValue: this.settings.utteranceStyle,
+      isEffective: true,
+      onChange: (newValue) => {
+        this.updatePreference("utteranceStyle", newValue ?? null);
+      }
+    });
+  }
+
+  get wordStyle(): Preference<ReadAloudDecorationStyle> {
+    return new Preference<ReadAloudDecorationStyle>({
+      initialValue: this.own.wordStyle,
+      effectiveValue: this.settings.wordStyle,
+      isEffective: true,
+      onChange: (newValue) => {
+        this.updatePreference("wordStyle", newValue ?? null);
+      }
+    });
+  }
+}

package/src/readaloud/preferences/ReadAloudSettings.ts

@@ -0,0 +1,44 @@
+import type { GndRole } from "@readium/guided-navigation";
+import { ExtractionFormat, LanguageMode, Segmentation, SpeechSettings, VerbosityPreset } from "@readium/speech";
+import { ConfigurableSettings } from "../../preferences/Configurable.ts";
+import { ReadAloudDefaults } from "./ReadAloudDefaults.ts";
+import { ReadAloudAutoPause, ReadAloudDecorationStyle, ReadAloudPreferences } from "./ReadAloudPreferences.ts";
+
+export class ReadAloudSettings implements ConfigurableSettings {
+  format: ExtractionFormat;
+  inlineContextualization: boolean;
+  verbosity: VerbosityPreset;
+  skip: GndRole[];
+  contextualize: GndRole[];
+  language: LanguageMode;
+  segmentation: Segmentation;
+  pauseDuration: number;
+  autoPause: ReadAloudAutoPause;
+  speakInContentLanguage: boolean;
+  rate: number;
+  pitch: number;
+  volume: number;
+  utteranceStyle: ReadAloudDecorationStyle;
+  wordStyle: ReadAloudDecorationStyle;
+
+  /**
+   * @param speech The settings speech resolved for its own fields.
+   */
+  constructor(speech: SpeechSettings, preferences: ReadAloudPreferences, defaults: ReadAloudDefaults) {
+    this.format = speech.format;
+    this.inlineContextualization = speech.inlineContextualization;
+    this.verbosity = speech.verbosity;
+    this.skip = speech.skip;
+    this.contextualize = speech.contextualize;
+    this.language = speech.language;
+    this.segmentation = speech.segmentation;
+    this.pauseDuration = speech.pauseDuration;
+    this.autoPause = preferences.autoPause ?? defaults.autoPause;
+    this.speakInContentLanguage = preferences.speakInContentLanguage ?? defaults.speakInContentLanguage;
+    this.rate = speech.rate;
+    this.pitch = speech.pitch;
+    this.volume = speech.volume;
+    this.utteranceStyle = preferences.utteranceStyle ?? defaults.utteranceStyle;
+    this.wordStyle = preferences.wordStyle ?? defaults.wordStyle;
+  }
+}

package/src/readaloud/preferences/index.ts

@@ -0,0 +1,4 @@
+export * from "./ReadAloudDefaults.ts";
+export * from "./ReadAloudPreferences.ts";
+export * from "./ReadAloudPreferencesEditor.ts";
+export * from "./ReadAloudSettings.ts";

package/src/webpub/WebPubFrameManager.ts

@@ -232,6 +232,10 @@ export class WebPubFrameManager {
         return this.frame.getBoundingClientRect();
     }
 
+    get isDestroyed() {
+        return this.destroyed;
+    }
+
     get window() {
         if(this.destroyed || !this.frame.contentWindow) throw Error("Trying to use frame window when it doesn't exist");
         return this.frame.contentWindow;

package/src/webpub/WebPubFramePoolManager.ts

@@ -252,6 +252,11 @@ export class WebPubFramePoolManager {
         return [this._currentFrame];
     }
 
+    /** The pooled frame of `href`, whether or not it's shown. */
+    _frameFor(href: string): WebPubFrameManager | undefined {
+        return this.pool.get(href);
+    }
+
     get currentBounds(): DOMRect {
         const ret = {
             x: 0,