@readium/navigator 1.2.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@readium/navigator",
+  "version": "1.2.0",
+  "type": "module",
+  "description": "Next generation SDK for publications in Web Apps",
+  "author": "readium",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/readium/ts-toolkit.git",
+    "directory": "navigator"
+  },
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/readium/ts-toolkit/issues"
+  },
+  "homepage": "https://github.com/readium/ts-toolkit",
+  "keywords": [
+    "readium",
+    "epub",
+    "webpub",
+    "divina",
+    "reflowable",
+    "fixed-layout",
+    "publication",
+    "ebook",
+    "reader",
+    "viewer"
+  ],
+  "main": "./dist/index.umd.cjs",
+  "module": "./dist/index.js",
+  "types": "./types/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.umd.cjs",
+      "types": "./types/src/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "types"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@laynezh/vite-plugin-lib-assets": "^0.5.24",
+    "@readium/navigator-html-injectables": "0.0.1",
+    "@readium/shared": "1.2.0",
+    "@types/path-browserify": "^1.0.0",
+    "css-selector-generator": "^3.6.4",
+    "readium-css": "github:readium/readium-css",
+    "tslib": "^2.5.2",
+    "typescript": "^5.4.5",
+    "typescript-plugin-css-modules": "^5.1.0",
+    "vite": "^4.4.9"
+  },
+  "dependencies": {
+    "path-browserify": "^1.0.1"
+  },
+  "scripts": {
+    "build": "tsc && vite build"
+  }
+}

package/src/Navigator.ts

@@ -0,0 +1,66 @@
+import { Link, Locator, Publication, ReadingProgression } from "@readium/shared";
+
+type cbb = (ok: boolean) => void;
+
+export abstract class Navigator {
+    abstract get publication(): Publication; // Publication rendered by this navigator.
+    abstract get currentLocator(): Locator; // Current position (detailed) in the publication. Can be used to save a bookmark to the current position.
+
+    /**
+     * Moves to the position in the publication corresponding to the given {Locator}.
+     */
+    abstract go(locator: Locator, animated: boolean, cb: cbb): void;
+
+    /**
+     * Moves to the position in the publication targeted by the given link.
+     */
+    abstract goLink(link: Link, animated: boolean, cb: cbb): void;
+
+    /**
+     * Moves to the next content portion (eg. page) in the reading progression direction.
+     */
+    abstract goForward(animated: boolean, cb: cbb): void;
+
+    /**
+     * Moves to the previous content portion (eg. page) in the reading progression direction.
+     */
+    abstract goBackward(animated: boolean, cb: cbb): void;
+
+    // TODO listener
+
+    /**
+     * Destroy all resources associated with this navigator. Synonymous with "unmount"
+     */
+    abstract destroy(): void;
+}
+
+export abstract class VisualNavigator extends Navigator {
+    /**
+     * Current reading progression direction.
+     */
+     abstract get readingProgression(): ReadingProgression;
+
+
+     /**
+      * Moves to the left content portion (eg. page) relative to the reading progression direction.
+      */
+     goLeft(animated = false, completion: cbb) {
+        if(this.readingProgression === ReadingProgression.ltr || this.readingProgression === ReadingProgression.ttb || this.readingProgression === ReadingProgression.auto)
+            this.goBackward(animated, completion);
+        else if(this.readingProgression === ReadingProgression.rtl || this.readingProgression === ReadingProgression.btt)
+            this.goForward(animated, completion);
+     }
+
+     /**
+      * Moves to the right content portion (eg. page) relative to the reading progression direction.
+      */
+     goRight(animated = false, completion: cbb) {
+        if(this.readingProgression === ReadingProgression.ltr || this.readingProgression === ReadingProgression.ttb || this.readingProgression === ReadingProgression.auto)
+            this.goForward(animated, completion);
+        else if(this.readingProgression === ReadingProgression.rtl || this.readingProgression === ReadingProgression.btt)
+            this.goBackward(animated, completion);
+     }
+}
+
+
+// TODO MediaNavigator

package/src/audio/engine/AudioEngine.ts

@@ -0,0 +1,136 @@
+import { Locator } from '@readium/shared';
+import { Publication } from '@readium/shared';
+
+/**
+ * Initial state of the audio engine playback.
+ */
+export interface PlaybackState {
+    /**
+     * The current time of the audio resource.
+     */
+    currentTime: number;
+
+    /**
+     * The duration of the audio resource.
+     */
+    duration: number;
+
+    /**
+     * The volume of the audio resource.
+     */
+    volume: number;
+}
+
+/**
+ * Playback interface for an audio engine state
+ * @state The initial [PlaybackState].
+ * @playWhenReady Indicates if the navigator should play as soon as the state is Ready.
+ * @index Index of the reading order item currently being played.
+ * @offset Position of the playback in the current item.
+ * @buffered Position in the current item until which the content is buffered.
+ * 
+ */
+export interface Playback {
+    state: PlaybackState;
+    playWhenReady: boolean;
+    index: number;
+    offset?: number;
+    buffered?: number;
+}
+
+/**
+ * An audio engine that plays audio resources from a publication.
+ * @playback - The current [Playback] state.
+*/
+export interface AudioEngine {
+    /**
+     * The current playback state.
+     */
+    playback: Playback;
+
+    /**
+     * Plays the audio resource at the given locator.
+     */
+    playLocator(publication: Publication, locator: Locator): Promise<void>;
+
+    /**
+     * Adds an event listener to the audio engine.
+     * @param event The event name to listen.
+     * @param callback Callback function to be called when the event is triggered.
+     */
+    on(event: string, callback: (data: any) => void): void;
+    
+    /**
+     * Removes an event listener from the audio engine.
+     * @param event The event name to remove the listener.
+     * @param callback Callback function to be removed.
+     */
+    off(event: string, callback: (data: any) => void): void;
+
+    /**
+     * Loads the audio resource at the given URL.
+     * @param url The URL of the audio resource.
+     */
+    loadAudio(url: string): void;
+    
+    /**
+     * Plays the current audio resource.
+     */
+    play(): void;
+
+    /**
+     * Pauses the currently playing audio resource.
+     */
+    pause(): void;
+    
+    /**
+     * Stops the currently playing audio resource.
+     */
+    stop(): void;
+    
+    /**
+     * Skips [duration] either forward or backward if [duration] is negative.
+     */
+    skip(duration: number): void;
+    
+    /**
+     * Returns the duration of the audio resource.
+     */
+    duration(): number;
+    
+    /**
+     * Returns whether the audio resource is currently playing.
+     */
+    isPlaying(): boolean;
+    
+    /**
+     * Returns whether the audio resource is currently paused.
+     */
+    isPaused(): boolean;
+    
+    /**
+     * Returns whether the audio resource is currently stopped.
+     */
+    isStopped(): boolean;
+    
+    /**
+     * Returns whether the audio resource is currently loading.
+     */
+    isLoading(): boolean;
+    
+    /**
+     * Returns whether the audio resource is currently loaded.
+     */
+    isLoaded(): boolean;
+    
+    /**
+     * Returns whether the audio resource is currently ended.
+     */
+    isEnded(): boolean;
+    
+    /**
+     * Returns whether the audio resource is currently muted.
+     */
+    isMuted(): boolean;
+    
+}

package/src/audio/engine/WebAudioEngine.ts

@@ -0,0 +1,286 @@
+/* Implements the AudioEngine interface using the Web Audio API. */
+
+import {
+    AudioEngine,
+    Playback,
+  } from "./AudioEngine";
+  
+  import { Publication } from "@readium/shared";
+  import { Locator } from "@readium/shared";
+  
+  type EventCallback = (data: any) => void;
+  
+  export class WebAudioEngine implements AudioEngine {
+    /* Defines the current playback state. */
+    public readonly playback: Playback;
+    private audioContext: AudioContext;
+    private mediaElement: HTMLAudioElement;
+    private sourceNode: MediaElementAudioSourceNode | null = null;
+    private gainNode: GainNode;
+    private listeners: { [event: string]: EventCallback[] } = {};
+    private isMutedValue: boolean = false;
+    private isPlayingValue: boolean = false;
+    private isPausedValue: boolean = false;
+    private isLoadingValue: boolean = false;
+    private isLoadedValue: boolean = false;
+    private isEndedValue: boolean = false;
+  
+    constructor(values: { playback: Playback; audioContext: AudioContext }) {
+      this.playback = values.playback;
+      this.audioContext = values.audioContext;
+      this.gainNode = this.audioContext?.createGain();
+      this.setVolume(this.playback.state.volume); // Default initial volume
+  
+      // Create an HTML audio element
+      this.mediaElement = document.createElement("audio");
+      this.mediaElement.crossOrigin = "use-credentials"; // Optional: Handle cross-origin audio files
+  
+      // Event listeners (to report the client app about some async events)
+      this.mediaElement.addEventListener(
+        "canplaythrough",
+        this.onCanPlayThrough.bind(this)
+      );
+      this.mediaElement.addEventListener(
+        "timeupdate",
+        this.onTimeUpdate.bind(this)
+      );
+      this.mediaElement.addEventListener("error", this.onError.bind(this));
+      this.mediaElement.addEventListener("ended", this.onEnded.bind(this));
+  
+      //Set the start time
+      this.mediaElement.currentTime = this.playback.state.currentTime;
+    }
+  
+    /**
+     * Adds an event listener to the audio engine.
+     * @param event - event name to be listened.
+     * @param callback - callback function to be called when the event is triggered.
+     */
+    public on(event: string, callback: EventCallback) {
+      if (!this.listeners[event]) {
+        this.listeners[event] = [];
+      }
+      this.listeners[event].push(callback);
+    }
+  
+    /**
+     * Removes an event listener from the audio engine.
+     * @param event - event name to be removed from the listeners.
+     * @param callback - callback function to be removed.
+     */
+    public off(event: string, callback: EventCallback) {
+      if (!this.listeners[event]) return;
+      this.listeners[event] = this.listeners[event].filter(
+        (cb) => cb !== callback
+      );
+    }
+  
+    /**
+     * Load the audio resource at the given URL.
+     * @param url The URL of the audio resource.
+     * */
+    public loadAudio(url: string): void {
+      this.isLoadingValue = true;
+      this.mediaElement.src = url;
+      this.mediaElement.load();
+  
+      // Create a new source node only if it doesn't exist
+      if (!this.sourceNode) {
+        this.sourceNode = new MediaElementAudioSourceNode(this.audioContext, {
+          mediaElement: this.mediaElement,
+        });
+        this.sourceNode.connect(this.gainNode);
+        this.gainNode.connect(this.audioContext.destination);
+      }
+    }
+  
+    // Ensure AudioContext is running
+    private async ensureAudioContextRunning() {
+      if (this.audioContext.state === "suspended") {
+        await this.audioContext.resume();
+      }
+    }
+  
+    // Event handler for timeupdate
+    private onTimeUpdate() {
+      // Continuously track the current time of the media element
+      // You can update UI elements or perform other tasks here
+      this.emit("timeupdate", this.mediaElement.currentTime);
+    }
+  
+    // Event handler for canplaythrough
+    private onCanPlayThrough() {
+      this.isLoadingValue = false;
+      this.isLoadedValue = true;
+      this.emit("canplaythrough", null);
+    }
+  
+    // Event handler for error
+    private onError() {
+      console.error("Error loading media element");
+      this.emit("error", this.mediaElement.error);
+    }
+  
+    // Event handle for ended
+    private onEnded() {
+      this.isPlayingValue = false;
+      this.isPausedValue = false;
+      this.isEndedValue = true;
+      this.emit("ended", null);
+    }
+  
+    // Used to emit some events like timeupdate or ended
+    private emit(event: string, data: any) {
+      if (!this.listeners[event]) return;
+      this.listeners[event].forEach((callback) => callback(data));
+    }
+  
+    /**
+     * Plays the audio resource at the given locator.
+     */
+    public async playLocator(
+      _publication: Publication,
+      _locator: Locator
+    ): Promise<void> {
+      // Implementation details.
+    }
+  
+    /**
+     * Plays the current audio resource.
+     */
+    public async play(): Promise<void> {
+      await this.ensureAudioContextRunning();
+  
+      if (this.isPlayingValue) {
+        this.stop();
+        console.error("Audio is already playing");
+        return;
+      }
+  
+      try {
+        await this.mediaElement.play();
+        this.isPlayingValue = true;
+        this.isPausedValue = false;
+      } catch (err) {
+        console.error("error trying to play media element", err);
+      }
+    }
+  
+    /**
+     * Pauses the currently playing audio resource.
+     */
+    public pause(): void {
+      this.mediaElement.pause();
+      this.isPlayingValue = false;
+      this.isPausedValue = true;
+    }
+  
+    /**
+     * Stops the currently playing audio resource.
+     */
+    public stop(): void {
+      // Stop the audio and reset the current time
+      this.mediaElement.pause();
+      this.mediaElement.currentTime = 0;
+      this.isPlayingValue = false;
+      this.isPausedValue = false;
+    }
+  
+    /**
+     * Adjusts the [volume] of the audio resource.
+     * @volume The volume to set, in the range [0, 1].
+     */
+    public setVolume(volume: number): void {
+      if (volume < 0) {
+        this.gainNode.gain.value = 0;
+        this.isMutedValue = true;
+        return;
+      }
+      if (volume > 1) {
+        this.setVolume(volume / 100);
+        return;
+      }
+      this.gainNode.gain.value = volume;
+    }
+  
+    /**
+     * Skips [seconds] either forward or backward if [seconds] is negative.
+     */
+    public skip(seconds: number): void {
+      if (!this.mediaElement) {
+        console.error("Audio not loaded");
+        return;
+      }
+  
+      const newTime = this.mediaElement.currentTime + seconds;
+      if (newTime < 0) this.mediaElement.currentTime = 0;
+      else if (newTime > this.mediaElement.duration)
+        this.mediaElement.currentTime = this.mediaElement.duration;
+      else this.mediaElement.currentTime = newTime;
+    }
+  
+    /**
+     * Returns de current time in the audio resource.
+     */
+    public currentTime(): number {
+      return this.mediaElement.currentTime;
+    }
+  
+    /**
+     * Returns the duration in seconds of the current media element resource.
+     */
+    public duration(): number {
+      // Implementation details.
+      return this.mediaElement.duration;
+    }
+  
+    /**
+     * Returns whether the audio resource is currently playing.
+     */
+    public isPlaying(): boolean {
+      return this.isPlayingValue;
+    }
+  
+    /**
+     * Returns whether the audio resource is currently paused.
+     */
+    public isPaused(): boolean {
+      return this.isPausedValue;
+    }
+  
+    /**
+     * Returns whether the audio resource is currently stopped.
+     */
+    public isStopped(): boolean {
+      return false;
+    }
+  
+    /**
+     * Returns whether the audio resource is currently loading.
+     */
+    public isLoading(): boolean {
+      return this.isLoadingValue;
+    }
+  
+    /**
+     * Returns whether the audio resource is currently loaded.
+     */
+    public isLoaded(): boolean {
+      return this.isLoadedValue;
+    }
+  
+    /**
+     * Returns whether the audio resource is currently ended.
+     */
+    public isEnded(): boolean {
+      return this.isEndedValue;
+    }
+  
+    /**
+     * Returns whether the audio resource is currently muted.
+     */
+    public isMuted(): boolean {
+      return this.isMutedValue;
+    }
+  }
+  

package/src/audio/engine/index.ts

@@ -0,0 +1,2 @@
+export * from './AudioEngine';
+export * from './WebAudioEngine';

package/src/audio/index.ts

@@ -0,0 +1 @@
+export * from './engine';