@internetarchive/bookreader 5.0.0-3 → 5.0.0-30-d

package/stat/plugins/tts/FestivalTTSEngine.js

@@ -0,0 +1,169 @@
+import AbstractTTSEngine from './AbstractTTSEngine.js';
+import { sleep } from './utils.js';
+/* global soundManager */
+import 'soundmanager2';
+import 'jquery.browser';
+
+/** @typedef {import("./AbstractTTSEngine.js").TTSEngineOptions} TTSEngineOptions */
+/** @typedef {import("./AbstractTTSEngine.js").AbstractTTSSound} AbstractTTSSound */
+
+/**
+ * @extends AbstractTTSEngine
+ * TTS using Festival endpoint
+ **/
+export default class FestivalTTSEngine extends AbstractTTSEngine {
+  /** @override */
+  static isSupported() {
+    return typeof(soundManager) !== 'undefined' && soundManager.supported();
+  }
+
+  /** @param {TTSEngineOptions} options */
+  constructor(options) {
+    super(options);
+    // $.browsers is sometimes undefined on some Android browsers :/
+    // Likely related to when $.browser was moved to npm
+    /** @type {'mp3' | 'ogg'} format of audio to get */
+    this.audioFormat = $.browser?.mozilla ? 'ogg' : 'mp3';
+  }
+
+  /** @override */
+  getVoices() {
+    return [
+      { default: true, lang: "en-US", localService: false, name: "Festival - English (US)", voiceURI: null }
+    ];
+  }
+
+  /** @override */
+  init() {
+    // setup sound manager
+    soundManager.setup({
+      debugMode: false,
+      // Note, there's a bug in Chrome regarding range requests.
+      // Flash is used as a workaround.
+      // See https://bugs.chromium.org/p/chromium/issues/detail?id=505707
+      preferFlash: true,
+      url: '/bookreader/BookReader/soundmanager/swf',
+      useHTML5Audio: true,
+      //flash 8 version of swf is buggy when calling play() on a sound that is still loading
+      flashVersion: 9
+    });
+  }
+
+  /**
+   * @override
+   * @param {number} leafIndex
+   * @param {number} numLeafs total number of leafs in the current book
+   */
+  start(leafIndex, numLeafs) {
+    let promise = null;
+
+    // Hack for iOS
+    if (navigator.userAgent.match(/mobile/i)) {
+      promise = this.iOSCaptureUserIntentHack();
+    }
+
+    promise = promise || Promise.resolve();
+    promise.then(() => super.start(leafIndex, numLeafs));
+  }
+
+  /** @override */
+  createSound(chunk) {
+    return new FestivalTTSSound(this.getSoundUrl(chunk.text));
+  }
+
+  /**
+   * @private
+   * Get URL for audio that says this text
+   * @param {String} dataString the thing to say
+   * @return {String} url
+   */
+  getSoundUrl(dataString) {
+    return 'https://' + this.opts.server + '/BookReader/BookReaderGetTTS.php?string='
+                  + encodeURIComponent(dataString)
+                  + '&format=.' + this.audioFormat;
+  }
+
+  /**
+   * @private
+   * Security restrictions require playback to be triggered
+   * by a user click/touch. This intention gets lost in the async calls
+   * on iOS, but, for some reason, if we start the audio here, it works.
+   * See https://stackoverflow.com/questions/12206631/html5-audio-cant-play-through-javascript-unless-triggered-manually-once
+   * @return {PromiseLike}
+   */
+  iOSCaptureUserIntentHack() {
+    const sound = soundManager.createSound({ url: SILENCE_1MS[this.audioFormat] });
+    return new Promise(res => sound.play({onfinish: res}))
+      .then(() => sound.destruct());
+  }
+}
+
+/** @extends AbstractTTSSound */
+class FestivalTTSSound {
+  /** @param {string} soundUrl **/
+  constructor(soundUrl) {
+    this.soundUrl = soundUrl;
+    /** @type {SMSound} */
+    this.sound = null;
+    this.rate = 1;
+    /** @type {function} calling this resolves the "play" promise */
+    this._finishResolver = null;
+  }
+
+  get loaded() {
+    return this.sound && this.sound.loaded;
+  }
+
+  load(onload) {
+    this.sound = soundManager.createSound({
+      url: this.soundUrl,
+      // API recommended, but only fires once play started on safari
+      onload: () => {
+        if (this.rate != 1) this.sound.setPlaybackRate(this.rate);
+        onload();
+      },
+      onresume: () => {
+        sleep(25).then(() => {
+          if (this.rate != 1) this.sound.setPlaybackRate(this.rate);
+        });
+      }
+    });
+    return this.sound.load();
+  }
+
+  play() {
+    return new Promise(res => {
+      this._finishResolver = res;
+      this.sound.play({ onfinish: res });
+    })
+      .then(() => this.sound.destruct());
+  }
+
+  /** @override */
+  stop() {
+    this.sound.stop();
+    return Promise.resolve();
+  }
+
+  /** @override */
+  pause() { this.sound.pause(); }
+  /** @override */
+  resume() { this.sound.resume(); }
+  /** @override */
+  setPlaybackRate(rate) {
+    this.rate = rate;
+    this.sound.setPlaybackRate(rate);
+  }
+
+  /** @override */
+  finish() {
+    this.sound.stop();
+    this._finishResolver();
+  }
+}
+
+/** Needed to capture the audio context for iOS hack. Generated using Audacity. */
+const SILENCE_1MS = {
+  mp3: 'data:audio/mp3;base64,//uQxAAAAAAAAAAAAAAAAAAAAAAAWGluZwAAAA8AAAACAAACcQCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA//////////////////////////////////////////////////////////////////8AAAAeTEFNRTMuOTlyBJwAAAAAAAAAADUgJAaUQQABrgAAAnHIf8sZAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA//sQxAADwlwBKGAAACAAAD/AAAAEAAAAH///////////////+UBAMExBTUUzLjk5LjOqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqr/+xDEIAPAAAGkAAAAIAAANIAAAASqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqg==',
+  ogg: 'data:audio/ogg;base64,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',
+};

package/stat/plugins/tts/PageChunk.js

@@ -0,0 +1,107 @@
+/**
+ * Class to manage a 'chunk' (approximately a paragraph) of text on a page.
+ */
+export default class PageChunk {
+  /**
+   * @param {number} leafIndex
+   * @param {number} chunkIndex
+   * @param {string} text
+   * @param {DJVURect[]} lineRects
+   */
+  constructor(leafIndex, chunkIndex, text, lineRects) {
+    this.leafIndex = leafIndex;
+    this.chunkIndex = chunkIndex;
+    this.text = text;
+    this.lineRects = lineRects;
+  }
+
+  /**
+   * @param {string} server
+   * @param {string} bookPath
+   * @param {number} leafIndex
+   * @return {Promise<PageChunk[]>}
+   */
+  static fetch(server, bookPath, leafIndex) {
+    // jquery's ajax "PromiseLike" implementation is inconsistent with
+    // modern Promises, so convert it to a full promise (it doesn't forward
+    // a returned promise to the next handler in the chain, which kind of
+    // defeats the entire point of using promises to avoid "callback hell")
+    return new Promise((res, rej) => {
+      $.ajax({
+        type: 'GET',
+        url: `https://${server}/BookReader/BookReaderGetTextWrapper.php`,
+        dataType:'jsonp',
+        cache: true,
+        data: {
+          path: `${bookPath}_djvu.xml`,
+          page: leafIndex
+        },
+        error: rej,
+      })
+        .then(chunks => {
+          res(PageChunk._fromTextWrapperResponse(leafIndex, chunks));
+        });
+    });
+  }
+
+  /**
+   * Convert the response from BookReaderGetTextWrapper.php into a {@link PageChunk} instance
+   * @param {number} leafIndex
+   * @param {Array<[String, ...DJVURect[]]>} chunksResponse
+   * @return {PageChunk[]}
+   */
+  static _fromTextWrapperResponse(leafIndex, chunksResponse) {
+    return chunksResponse.map((c, i) => {
+      const correctedLineRects = PageChunk._fixChunkRects(c.slice(1));
+      const correctedText = PageChunk._removeDanglingHyphens(c[0]);
+      return new PageChunk(leafIndex, i, correctedText, correctedLineRects);
+    });
+  }
+
+  /**
+   * @private
+   * Sometimes the first rectangle will be ridiculously wide/tall. Find those and fix them
+   * *NOTE*: Modifies the original array and returns it.
+   * *NOTE*: This should probably be fixed on the petabox side, and then removed here
+   * Has 2 problems:
+   *  - If the rect is the last rect on the page (and hence the only rect in the array),
+   *    the rect's size isn't fixed
+   * - Because this relies on the second rect, there's a chance it won't be the right
+   *   width
+   * @param {DJVURect[]} rects
+   * @return {DJVURect[]}
+   */
+  static _fixChunkRects(rects) {
+    if (rects.length < 2) return rects;
+
+    const [firstRect, secondRect] = rects;
+    const [left, bottom, right] = firstRect;
+    const width = right - left;
+    const secondHeight = secondRect[1] - secondRect[3];
+    const secondWidth = secondRect[2] - secondRect[0];
+    const secondRight = secondRect[2];
+
+    if (width > secondWidth * 30) {
+      // Set the end to be the same
+      firstRect[2] = secondRight;
+      // And the top to be the same height
+      firstRect[3] = bottom - secondHeight;
+    }
+
+    return rects;
+  }
+
+  /**
+   * Remove "dangling" hyphens from read aloud text to avoid TTS stuttering
+   * @param {string} text
+   * @return {string}
+   */
+  static _removeDanglingHyphens(text) {
+    return text.replace(/-\s+/g, '');
+  }
+}
+
+/**
+ * @typedef {[number, number, number, number]} DJVURect
+ * coords are in l,b,r,t order
+ */

package/stat/plugins/tts/PageChunkIterator.js

@@ -0,0 +1,163 @@
+import PageChunk from './PageChunk.js';
+
+/**
+ * Class that iterates over the page chunks of a book; caching/buffering
+ * as much as possible to try to ensure a smooth experience.
+ */
+export default class PageChunkIterator {
+  /**
+   * @param {number} pageCount total number of pages
+   * @param {number} start page to start on
+   * @param {PageChunkIteratorOptions} opts
+   */
+  constructor(pageCount, start, opts) {
+    this.pageCount = pageCount;
+    this.opts = Object.assign({}, DEFAULT_OPTS, opts);
+    /** Position in the chunk sequence */
+    this._cursor = { page: start, chunk: 0 };
+    /** @type {Object<number, PageChunk[]>} leaf index -> chunks*/
+    this._bufferedPages = {};
+    /** @type {Object<number, PromiseLike<PageChunk[]>} leaf index -> chunks*/
+    this._bufferingPages = {};
+    /**
+     * @type {Promise} promise that manages cursor modifications so that they
+     * happen in order triggered as opposed to order the server responds
+     **/
+    this._cursorLock = Promise.resolve();
+  }
+
+  /**
+   * Get the next chunk
+   * @return {PromiseLike<"__PageChunkIterator.AT_END__" | PageChunk>}
+   */
+  next() {
+    return this._cursorLock = this._cursorLock
+      .then(() => this._nextUncontrolled());
+  }
+
+  /**
+   * Sends the cursor back 1
+   * @return {Promise}
+   **/
+  decrement() {
+    return this._cursorLock = this._cursorLock
+      .then(() => this._decrementUncontrolled());
+  }
+
+  /**
+   * Gets without ensuring synchronization. Since this iterator has a lot of async
+   * code, calling e.g. "next" twice (before the first call to next has finished)
+   * would cause the system to be in a weird state. To avoid that, we make sure calls
+   * to next and decrement (functions that modify the cursor) are synchronized,
+   * so that regardless how long it takes for one to respond, they'll always be executed
+   * in the correct order.
+   * @return {PromiseLike<"__PageChunkIterator.AT_END__" | PageChunk>}
+   */
+  _nextUncontrolled() {
+    if (this._cursor.page == this.pageCount) {
+      return Promise.resolve(PageChunkIterator.AT_END);
+    }
+
+    this._recenterBuffer(this._cursor.page);
+
+    return this._fetchPageChunks(this._cursor.page)
+      .then(chunks => {
+        if (this._cursor.chunk == chunks.length) {
+          this._cursor.page++;
+          this._cursor.chunk = 0;
+          return this._nextUncontrolled();
+        }
+        return chunks[this._cursor.chunk++];
+      });
+  }
+
+  /**
+   * Decrements without ensuring synchronization. (See {@link PageChunkIterator._nextUncontrolled});
+   * @return {Promise}
+   */
+  _decrementUncontrolled() {
+    let cursorChangePromise = Promise.resolve();
+
+    if (this._cursor.chunk > 0) {
+      this._cursor.chunk--;
+    } else if (this._cursor.page > 0) {
+      this._cursor.page--;
+      // Go back possibly multiple pages, because pages can be blank
+      cursorChangePromise = this._fetchPageChunks(this._cursor.page)
+        .then(prevPageChunks => {
+          if (prevPageChunks.length == 0) return this._decrementUncontrolled();
+          else this._cursor.chunk = prevPageChunks.length - 1;
+        });
+    }
+
+    return cursorChangePromise
+      .then(() => this._fetchPageChunks(this._cursor.page));
+  }
+
+  /**
+   * Recenter the buffer around the provided page index
+   * @param {number} index
+   */
+  _recenterBuffer(index) {
+    const start = Math.max(0, index - this.opts.pageBufferSize);
+    const end = Math.min(this.pageCount, index + this.opts.pageBufferSize + 1);
+    for (let i = start; i < end; i++) {
+      this._fetchPageChunks(i);
+    }
+
+    this._removePageFromBuffer(start - 1);
+    this._removePageFromBuffer(end + 1);
+  }
+
+  /**
+   * @param {number} index
+   */
+  _removePageFromBuffer(index) {
+    delete this._bufferingPages[index];
+    delete this._bufferedPages[index];
+  }
+
+  /**
+   * Fetches the chunks on a page; checks the buffer, so it won't make unnecessary
+   * requests if it's called multiple times for the same index.
+   * @param {number} index
+   * @return {Promise<PageChunk[]>}
+   */
+  _fetchPageChunks(index) {
+    if (index in this._bufferingPages) return this._bufferingPages[index];
+    if (index in this._bufferedPages) return Promise.resolve(this._bufferedPages[index]);
+
+    this._bufferingPages[index] = this._fetchPageChunksDirect(index)
+      .then(chunks => {
+        delete this._bufferingPages[index];
+        this._bufferedPages[index] = chunks;
+        return chunks;
+      });
+
+    return this._bufferingPages[index];
+  }
+
+  /**
+   * Fetches a page without checking buffer
+   * @param {number} index
+   */
+  _fetchPageChunksDirect(index) {
+    return PageChunk.fetch(this.opts.server, this.opts.bookPath, index);
+  }
+}
+
+PageChunkIterator.AT_END = "__PageChunkIterator.AT_END__";
+
+/** @type {PageChunkIteratorOptions} */
+const DEFAULT_OPTS = {
+  server: null,
+  bookPath: null,
+  pageBufferSize: 2,
+};
+
+/**
+ * @typedef {Object} PageChunkIteratorOptions
+ * @property {string} server
+ * @property {string} bookPath
+ * @property {number} [pageBufferSize] number of pages to buffer before/after the current page
+ */