@readium/speech 0.8.1 → 0.9.0

package/README.md

@@ -51,7 +51,11 @@ We are now on the sixth phase: verbosity and prosody, in particular contextualiz
 
 ### [In-context demo](https://readium.org/speech/demo/article)
 
-In-context reading with seamless voice selection (grouped by region and sorted based on quality), and playback control, providing an optional read-along experience that integrates naturally with the content. Also showcases highlighting, as above.
+In-context reading with seamless voice selection (grouped by region and sorted based on quality), and playback control, providing an optional read-along experience that integrates naturally with the content.
+
+Settings include a verbosity selector (none/few/some/most) demonstrating [contextualization](docs/Preferences.md) — synthesized announcements spoken around content based on its role (entering/leaving a section, a footnote, a pullquote…) — and, for the read-along experience, independent highlight styles (highlight, underline, strikethrough, outline, text color, mask) and colors for the current utterance and the current word.
+
+The panel alongside the article shows the [Guided Navigation](docs/GuidedNavigation.md) object and the [utterances](docs/UtteranceExtraction.md) extracted from it, live.
 
 ### [Extraction playground](https://readium.org/speech/demo/playground)
 
@@ -144,6 +148,11 @@ Documentation provides guides for:
 - [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
+- [WebSpeechEngine](docs/WebSpeechEngine.md) — the `ReadiumSpeechPlaybackEngine` backed by the browser's Web Speech API
+- [SpeechServerEngine](docs/SpeechServerEngine.md) — the `ReadiumSpeechPlaybackEngine` backed by a remote [Readium Speech Server](https://github.com/readium/speech-server) instance
+- [FallbackEngine](docs/FallbackEngine.md) — pairing a primary and fallback engine so playback swaps transparently when one is unreachable or stalls
+
+See [CHANGELOG.md](CHANGELOG.md) for what's new in each release.
 
 ## Development
 

package/build/SpeechServer/speechServerEngine.d.ts

@@ -40,6 +40,9 @@ export declare class SpeechServerEngine implements ReadiumSpeechPlaybackEngine {
     private prefetchCache;
     private prefetchChainTail;
     private activeControllers;
+    private liveControllers;
+    private isSpeakingInternal;
+    private restartPending;
     private audioContext;
     private masterGain;
     private scheduledChunks;
@@ -66,6 +69,7 @@ export declare class SpeechServerEngine implements ReadiumSpeechPlaybackEngine {
     private fillPrefetchWindow;
     private queuePrefetch;
     private clearPrefetchCache;
+    private abortLiveControllers;
     private synthesizeStream;
     private synthesizeChunk;
     private ensureAudioContext;
@@ -85,6 +89,7 @@ export declare class SpeechServerEngine implements ReadiumSpeechPlaybackEngine {
     getPitch(): number;
     setVolume(volume: number): void;
     getVolume(): number;
+    private scheduleRestartIfSpeaking;
     getState(): ReadiumSpeechPlaybackState;
     getCurrentUtteranceIndex(): number;
     setCurrentUtteranceIndex(index: number, onComplete?: (success: boolean) => void): void;

package/build/WebSpeech/webSpeechEngine.d.ts

@@ -19,6 +19,7 @@ export declare class WebSpeechEngine implements ReadiumSpeechPlaybackEngine {
     private speakGeneration;
     private resumeInfinityTimer?;
     private isSpeakingInternal;
+    private restartPending;
     private isPausedInternal;
     private isAndroidPaused;
     private pausedAtUtteranceIndex;
@@ -66,6 +67,7 @@ export declare class WebSpeechEngine implements ReadiumSpeechPlaybackEngine {
     getPitch(): number;
     setVolume(volume: number): void;
     getVolume(): number;
+    private scheduleRestartIfSpeaking;
     getState(): ReadiumSpeechPlaybackState;
     getCurrentUtteranceIndex(): number;
     setCurrentUtteranceIndex(index: number, onComplete?: (success: boolean) => void): void;

package/build/decorator/createLocator.d.ts

@@ -1,9 +1,13 @@
 import { Locator } from '@readium/shared';
+import { DomRangeJSON } from '../gnd/textrefFragment.js';
 export interface LocatorOptions {
-    highlight?: string;
-    before?: string;
-    after?: string;
-    selector?: string;
+    text?: {
+        highlight?: string;
+        before?: string;
+        after?: string;
+    };
+    cssSelector?: string;
+    domRange?: DomRangeJSON;
     fragment?: string;
 }
 export declare function createLocator(options: LocatorOptions, wnd?: Window): Locator;

package/build/gnd/a11y.d.ts

@@ -1,6 +1,8 @@
 import { GndText } from './types.js';
 /** Normalized (whitespace-coalesced and trimmed) text content of a node's subtree. */
 export declare function normalizedNodeText(el: Node): string;
+/** Same as `normalizedNodeText`, excluding explicitly-role-bearing descendants. */
+export declare function normalizedNodeTextExcludingExplicitRoles(el: Node): string;
 /**
  * Computes the text that becomes a node's `GndObject.description`, and
  * whether the node is visible in the first place. Follows the AccName

package/build/gnd/converter.d.ts

@@ -1,26 +1,36 @@
-import { GndObject } from './types.js';
+import { GndObject, GndRole } from './types.js';
+import { ObjBuilder } from './object.js';
 import { GndMediaType } from './dom.js';
+import { GndGenerationOptions } from './options.js';
+import { IdAllocator } from './idAllocator.js';
 /** Walks a DOM subtree, building the Guided Navigation object tree. */
 export declare class Converter {
     xmlParsed: boolean;
     ids: Map<string, Element>;
     suppressed: Set<Element>;
-    idAlloc: {
-        claimed: Set<string>;
-        counters: Map<string, number>;
-    };
+    idAlloc: IdAllocator;
     noterefDepth: number;
     allowNode: Element | null;
+    selectorPredicate: ((roles: GndRole[]) => boolean) | null;
+    domRangeEnabled: boolean;
+    textFragmentEnabled: boolean;
+    docRoot: Document | null;
     private root;
     private current;
+    private foldedCaptions;
     private segments;
     private textAcc;
     private currentCtx;
     private flowEndsWithSpace;
     private pendingChildren;
+    private flowFirstNode;
+    private flowFirstOffset;
+    private flowLastNode;
+    private flowLastOffset;
+    private lastFlowRange;
+    private lastFlowText;
     constructor(xmlParsed: boolean);
-    private allocateId;
-    private claimId;
+    spawnChild(allowNode: Element, depthDelta?: number): Converter;
     prescan(root: Element): void;
     convert(root: Element): void;
     convertChildren(root: Element): void;
@@ -29,24 +39,32 @@ export declare class Converter {
     private appendChild;
     private walk;
     private head;
+    private implicitCaptionOf;
     private tail;
+    private applyTextref;
     private text;
     private textContext;
     private updateFlowSpace;
     private closeSegment;
     private resetFlow;
-    private placeholder;
-    private pagebreak;
-    private noteref;
-    private link;
+    placeholder(el: Element, tag: string, object: ObjBuilder, candidateID?: string): void;
     private flushText;
 }
 /**
  * Converts an HTML or XHTML fragment or document into Guided Navigation
- * objects, reflecting exactly the input it's given: a real, author-written
- * <body> becomes its own role: ["body"] node like any other element; a
- * <body> synthesized only by text/html parsing around a bodyless fragment
- * is not content and is skipped through; a bodyless XHTML fragment's root
- * element is itself the content.
+ * objects.
+ *
+ * Given a string, `input` is parsed into a detached document that's never
+ * seen again — `options.textrefs.domRange` has nothing to resolve back
+ * against there, so it's ignored. Reflects exactly the input it's given: a
+ * real, author-written <body> becomes its own role: ["body"] node like any
+ * other element; a <body> synthesized only by text/html parsing around a
+ * bodyless fragment is not content and is skipped through; a bodyless XHTML
+ * fragment's root element is itself the content.
+ *
+ * Given a live, already-rendered element instead, it's converted in place —
+ * no parsing, no detached copy — so `domRange` can pinpoint exact text
+ * nodes a DOM-highlighting consumer can resolve straight back against that
+ * same document.
  */
-export declare function parseMarkup(input: string, mediaType?: GndMediaType): GndObject[];
+export declare function parseMarkup(input: string | Element, mediaType?: GndMediaType, options?: GndGenerationOptions): GndObject[];

package/build/gnd/dom.d.ts

@@ -1,5 +1,6 @@
 export declare function nodeLanguage(el: Element | null): string;
 export declare function hasElementChild(el: Element): boolean;
 export declare function isAncestorOf(anc: Element, n: Element): boolean;
+export declare function isInlineTag(tagName: string): boolean;
 export type GndMediaType = "text/html" | "application/xhtml+xml";
 export declare function sniffMediaType(input: string): GndMediaType;

package/build/gnd/domRangeGenerator.d.ts

@@ -0,0 +1,9 @@
+import { DomRangeJSON } from './textrefFragment.js';
+export interface KnownSelector {
+    el: Element;
+    selector: string;
+}
+export declare function generateDomRange(range: {
+    first: [Text, number];
+    last: [Text, number];
+}, docRoot: Document | null, known?: KnownSelector): DomRangeJSON | undefined;

package/build/gnd/elementHandlers.d.ts

@@ -0,0 +1,5 @@
+import { GndRole, GndText } from './types.js';
+import { Converter } from './converter.js';
+export declare function pagebreak(converter: Converter, el: Element, aria: GndText | null, roles: GndRole[]): boolean;
+export declare function noteref(converter: Converter, el: Element, roles: GndRole[]): void;
+export declare function link(converter: Converter, el: Element, roles: GndRole[], aria: GndText | null): void;

package/build/gnd/idAllocator.d.ts

@@ -0,0 +1,6 @@
+export declare class IdAllocator {
+    private claimed;
+    private counters;
+    allocate(prefix: string, isTaken: (id: string) => boolean): string;
+    claim(id: string): boolean;
+}

package/build/gnd/index.d.ts

@@ -2,3 +2,6 @@ export type { GndRole, GndText, GndObject, GndDocument } from './types.js';
 export { makeGnd } from './makeGnd.js';
 export { parseMarkup } from './converter.js';
 export type { GndMediaType } from './dom.js';
+export type { GndGenerationOptions, TextrefOptions } from './options.js';
+export { encodeCssSelectorFragment, decodeCssSelectorFragment, encodeDomRangeFragment, decodeDomRangeFragment, decodeTextref, } from './textrefFragment.js';
+export type { DomRangeJSON } from './textrefFragment.js';

package/build/gnd/makeGnd.d.ts

@@ -1,8 +1,9 @@
 import { GndDocument } from './types.js';
 import { GndMediaType } from './dom.js';
+import { GndGenerationOptions } from './options.js';
 export type { GndMediaType };
 /**
  * Builds a Guided Navigation document from an HTML or XHTML fragment or
  * document, following https://github.com/readium/guided-navigation.
  */
-export declare function makeGnd(input: string, mediaType?: GndMediaType): GndDocument;
+export declare function makeGnd(input: string | Element, mediaType?: GndMediaType, options?: GndGenerationOptions): GndDocument;

package/build/gnd/options.d.ts

@@ -0,0 +1,15 @@
+import { GndRole } from './types.js';
+export interface TextrefOptions {
+    roles?: boolean | GndRole[];
+    domRange?: boolean;
+    textFragment?: boolean;
+}
+export interface GndGenerationOptions {
+    textrefs?: boolean | GndRole[] | TextrefOptions;
+}
+export interface NormalizedTextrefOptions {
+    predicate: ((roles: GndRole[]) => boolean) | null;
+    domRange: boolean;
+    textFragment: boolean;
+}
+export declare function normalizeTextrefOptions(opt: GndGenerationOptions["textrefs"]): NormalizedTextrefOptions;

package/build/gnd/prescan.d.ts

@@ -0,0 +1 @@
+export declare function prescan(root: Element, ids: Map<string, Element>, suppressed: Set<Element>): void;

package/build/gnd/roles.d.ts

@@ -1,8 +1,3 @@
 import { GndRole } from './types.js';
-/**
- * Determines the Guided Navigation roles of an element, combining the roles
- * derived from the element type itself with the ones from its ARIA `role` and
- * `epub:type` attributes, e.g. `<section epub:type="chapter">` -> `[section, chapter]`.
- * An ARIA role of "presentation"/"none" strips the element of its native semantics.
- */
+export declare function hasExplicitRole(el: Element): boolean;
 export declare function extractNodeRoles(el: Element): GndRole[];

package/build/gnd/selectorGenerator.d.ts

@@ -0,0 +1,2 @@
+export declare function selectorForElement(el: Element, docRoot: Document | null): string | undefined;
+export declare function textrefForSelector(selector: string | undefined): string | undefined;

package/build/gnd/textFragmentGenerator.d.ts

@@ -0,0 +1,2 @@
+import { TextFragmentDirective } from './textrefFragment.js';
+export declare function textFragmentDirectiveFor(range: Range): TextFragmentDirective | undefined;

package/build/gnd/textrefFragment.d.ts

@@ -0,0 +1,38 @@
+export declare function encodeCssSelectorFragment(selector: string): string;
+export declare function decodeCssSelectorFragment(textref: string | undefined): string | undefined;
+export interface DomRangeJSON {
+    start: {
+        cssSelector: string;
+        textNodeIndex: number;
+        charOffset?: number;
+    };
+    end?: {
+        cssSelector: string;
+        textNodeIndex: number;
+        charOffset?: number;
+    };
+}
+export declare function encodeDomRangeFragment(domRange: DomRangeJSON): string;
+export declare function decodeDomRangeFragment(textref: string | undefined): DomRangeJSON | undefined;
+export interface TextFragmentDirective {
+    textStart: string;
+    textEnd?: string;
+    prefix?: string;
+    suffix?: string;
+}
+export declare function encodeTextFragmentDirective(fragment: TextFragmentDirective): string;
+export declare function decodeTextFragmentDirective(textref: string | undefined): TextFragmentDirective | undefined;
+export interface DecodedTextref {
+    cssSelector?: string;
+    domRange?: DomRangeJSON;
+    text?: {
+        highlight?: string;
+        before?: string;
+        after?: string;
+    };
+    fragment?: string;
+}
+export declare function decodeTextref(node: {
+    id?: string;
+    textref?: string;
+} | undefined): DecodedTextref | undefined;