@oat-sa/tao-core-ui 1.6.2 → 1.6.3

package/src/mediaplayer/utils/reminder.js

@@ -0,0 +1,184 @@
+/**
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * Copyright (c) 2021 (original work) Open Assessment Technologies SA ;
+ */
+
+/**
+ * Creates a reminder manager.
+ *
+ * A reminder manager allows to register callback functions that will be called after a particular amount of time.
+ * The schedule can be created and cancelled at any time.
+ *
+ * @example
+ * // Create a reminder manager
+ * const manager = reminderManagerFactory();
+ *
+ * // Add a reminder that will be called after 2s (delay is given in milliseconds)
+ * manager.remind(() => console.log('Hello!'), 2000);
+ *
+ * // Start the schedule
+ * manager.start();
+ *
+ * // We can know how many time elapsed since the last schedule
+ * const elapsed = manager.elapsed;
+ *
+ * // The schedule can be cancelled
+ * if (needToCancel) {
+ *     manager.stop();
+ * }
+ *
+ * // The schedule should be cancelled
+ * console.log('schedule running:', manager.running)
+ *
+ * @returns {reminderManager}
+ */
+export default function reminderManagerFactory() {
+    // Keep track of the running state
+    let running = false;
+
+    // Timestamp of the last start
+    let last = 0;
+
+    // A list of reminders to callback
+    const reminders = new Map();
+
+    /**
+     * Cancels a schedule for a particular reminder.
+     * @param {object} state - A sate object containing the timeout handler for the reminder.
+     * @private
+     */
+    const stopReminder = state => {
+        if (state && state.timeout) {
+            clearTimeout(state.timeout);
+            state.timeout = null;
+        }
+    };
+
+    /**
+     * Cancel the schedule for all reminders.
+     * @private
+     */
+    const stopAllReminders = () => reminders.forEach(stopReminder);
+
+    /**
+     * Schedule all reminders.
+     * @private
+     */
+    const startAllReminders = () => {
+        reminders.forEach((state, reminder) => {
+            stopReminder(state);
+            state.timeout = setTimeout(reminder, state.delay);
+        });
+    };
+
+    /**
+     * Defines the API of a reminder manager.
+     *
+     * A reminder manager allows to register callback functions that will be called after a particular amount of time.
+     * The schedule can be created and cancelled at any time.
+     *
+     * @namespace reminderManager
+     */
+    return {
+        /**
+         * Tells whether or not the schedule is running.
+         * @type {boolean}
+         * @member running
+         * @memberOf reminderManager
+         */
+        get running() {
+            return running;
+        },
+
+        /**
+         * Gives the amount of time elapsed since the start of the schedule. It is given in milliseconds.
+         * If the schedule is not running, it will always be 0.
+         * @type {number}
+         * @member running
+         * @memberOf reminderManager
+         */
+        get elapsed() {
+            if (!running) {
+                return 0;
+            }
+            return performance.now() - last;
+        },
+
+        /**
+         * Schedules all reminders from now on.
+         *
+         * @returns {reminderManager}
+         * @function start
+         * @memberOf reminderManager
+         */
+        start() {
+            running = true;
+            last = performance.now();
+            startAllReminders();
+            return this;
+        },
+
+        /**
+         * Cancels all scheduled reminders.
+         *
+         * @returns {reminderManager}
+         * @function stop
+         * @memberOf reminderManager
+         */
+        stop() {
+            running = false;
+            stopAllReminders();
+            return this;
+        },
+
+        /**
+         * Adds a callback to be scheduled.
+         * It won't be scheduled until the schedule is restarted.
+         *
+         * @param {Function} cb - A function to call after the delay elapsed.
+         * @param {number} delay - The delay after what call back the reminder. It is given in milliseconds.
+         * @returns {reminderManager}
+         * @function remind
+         * @memberOf reminderManager
+         */
+        remind(cb, delay) {
+            if ('function' === typeof cb && delay) {
+                stopReminder(reminders.get(cb));
+                reminders.set(cb, { delay });
+            }
+            return this;
+        },
+
+        /**
+         * Removes a scheduled callback. If a schedule was running, it will be cancelled first.
+         *
+         * @param {Function} [cb] - The callback function to remove. If omitted, all reminders will be removed.
+         * @returns {reminderManager}
+         * @function forget
+         * @memberOf reminderManager
+         */
+        forget(cb) {
+            if ('undefined' !== typeof cb) {
+                stopReminder(reminders.get(cb));
+                reminders.delete(cb);
+            } else {
+                stopAllReminders();
+                reminders.clear();
+            }
+            return this;
+        }
+    };
+}

package/src/mediaplayer/utils/timeObserver.js

@@ -0,0 +1,143 @@
+/**
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; under version 2
+ * of the License (non-upgradable).
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *
+ * Copyright (c) 2021 (original work) Open Assessment Technologies SA ;
+ */
+
+import eventifier from 'core/eventifier';
+
+/**
+ * Creates a time observer.
+ *
+ * It observes the updates applied to a timeline, raising a flag when an irregularity occurs.
+ *
+ * It works as follow:
+ * - an initial state is defined (example: current: 0, duration: 100)
+ * - each time a position is forced (say the position is changed outside of the regular time update), the observer needs
+ *   to be notified.
+ * - each time the position is updated (say regular time update), the observer needs to be called.
+ * - if the difference between the last regular update and the last one is too high, an event is triggered
+ *
+ * @example
+ * // Create a time observer with an expected interval of 2 seconds
+ * const observer = timeObserverFactory(2);
+ *
+ * // Init the state
+ * observer.start(player.position, player.duration);
+ *
+ * // Update on a regular basis
+ * player.on('timeupdate', () => observer.update(player.position));
+ *
+ * // Notify any position change outside of the regular update
+ * player.on('seek', () => observer.seek(player.position));
+ *
+ * // Gets informed from any irregularity
+ * observer.on('irregularity', () => console.log('irregular jump in time');
+ *
+ * @param {number} interval - The typical interval expected between two updates. It is given in seconds.
+ * @returns {timeObserver}
+ */
+export default function timeObserverFactory(interval = 1) {
+    // Current time position
+    let position = 0;
+
+    // Total duration expected
+    let duration = 0;
+
+    // Last position forced
+    let seek = 0;
+
+    /**
+     * Defines the API of a time observer.
+     *
+     * It observes the updates applied to a timeline, raising a flag when an irregularity occurs.
+     *
+     * @namespace timeObserver
+     */
+    return eventifier({
+        /**
+         * Gets the current time position reported to the observer.
+         *
+         * @returns {number}
+         * @type {number}
+         * @member position
+         * @memberOf timeObserver
+         */
+        get position() {
+            return position;
+        },
+
+        /**
+         * Gets the total duration reported to the observer.
+         *
+         * @returns {number}
+         * @type {number}
+         * @member duration
+         * @memberOf timeObserver
+         */
+        get duration() {
+            return duration;
+        },
+
+        /**
+         * Initialises the time state.
+         *
+         * @param {number} initPosition - The initial time position
+         * @param {number} initDuration - The total duration expected
+         * @returns {timeObserver}
+         * @function init
+         * @memberOf timeObserver
+         */
+        init(initPosition, initDuration) {
+            position = seek = initPosition;
+            duration = initDuration;
+            return this;
+        },
+
+        /**
+         * Updates the time position. If the difference with the previous update is too high, an `irregularity` event
+         * will be emitted.
+         *
+         * @param {number} newPosition - The new time position
+         * @returns {timeObserver}
+         *
+         * @fires irregularity
+         */
+        update(newPosition) {
+            if (newPosition > seek && newPosition - position > interval) {
+                /**
+                 * Notifies an irregularity in the time update
+                 * @event irregularity
+                 * @param {number} position - last regular position
+                 * @param {number} newPosition - new irregular position
+                 */
+                this.trigger('irregularity', position, newPosition);
+            }
+            position = newPosition;
+            return this;
+        },
+
+        /**
+         * Notifies the observer about a change in the position outside of the regular update.
+         *
+         * @param {number} seekPosition
+         * @returns {timeObserver}
+         */
+        seek(seekPosition) {
+            position = seek = seekPosition;
+            return this;
+        }
+    });
+}

package/src/mediaplayer.js

@@ -77,7 +77,6 @@ const defaults = {
         startMuted: false,
         maxPlays: 0,
         replayTimeout: 0,
-        stalledTimeout: 2000,
         canPause: true,
         canSeek: true,
         loop: false,
@@ -190,8 +189,14 @@ const isResponsiveSize = sizeProps => {
 /**
  * Builds a media player instance
  * @param {Object} config
- * @param {String} config.type - The type of media to play
- * @param {String|Array} config.url - The URL to the media
+ * @param {String} config.type - The type of media to play, say `audio`, `video`, or `youtube`. The default is `video`.
+ * It might also contain the MIME type of the media as a shorthand.
+ * @param {String|Array} [config.url] - The URL to the media. If several media are proposed as alternatives,
+ * please look at the `sources` option instead.
+ * @param {String} [config.mimeType] - The MIME type of the media. If omitted, the player will try to extract it
+ * from the `type` property, otherwise it will request the server to get the content-type.
+ * @param {Array} [config.sources] - A list of URL if several media can be proposed. Each entry may be either a
+ * string (single URL), or an object containing both the URL and the MIME type ({src: string, type: string}).
  * @param {String|jQuery|HTMLElement} [config.renderTo] - An optional container in which renders the player
  * @param {Boolean} [config.canSeek] - The player allows to reach an arbitrary position within the media using the duration bar
  * @param {Boolean} [config.loop] - The media will be played continuously
@@ -201,15 +206,14 @@ const isResponsiveSize = sizeProps => {
  * @param {Number} [config.autoStartAt] - The time position at which the player should start
  * @param {Number} [config.maxPlays] - Sets a few number of plays (default: infinite)
  * @param {Number} [config.replayTimeout] - disable the possibility to replay a media after this timeout, in seconds (default: 0)
- * @param {Number} [config.stalledTimeout] - delay before considering stalled playback (default: 2000)
  * @param {Number} [config.volume] - Sets the sound volume (default: 80)
  * @param {Number} [config.width] - Sets the width of the player (default: depends on media type)
  * @param {Number} [config.height] - Sets the height of the player (default: depends on media type)
  * @param {Boolean} [config.preview] - Enables the media preview (load media metadata)
  * @param {Boolean} [config.debug] - Enables the debug mode
+ * @param {number} [config.config.stalledDetectionDelay] - The delay before considering a media is stalled
  * @event render - Event triggered when the player is rendering
  * @event error - Event triggered when the player throws an unrecoverable error
- * @event recovererror - Event triggered when the player throws a recoverable error
  * @event ready - Event triggered when the player is fully ready
  * @event play - Event triggered when the playback is starting
  * @event update - Event triggered while the player is playing
@@ -234,6 +238,9 @@ function mediaplayerFactory(config) {
             // load the config set, discard null values in order to allow defaults to be set
             this.config = _.omit(config || {}, value => typeof value === 'undefined' || value === null);
             _.defaults(this.config, defaults.options);
+            if (!this.config.mimeType && 'string' === typeof this.config.type && this.config.type.indexOf('/') > 0) {
+                this.config.mimeType = this.config.type;
+            }
             this._setType(this.config.type || defaults.type);
 
             this._reset();
@@ -345,23 +352,11 @@ function mediaplayerFactory(config) {
              */
             this.trigger('reload');
 
-            // destroy player
             if (this.player) {
-                this.player.destroy();
-            }
-
-            // remove events and component
-            if (this.$component) {
-                this._unbindEvents();
-                this._destroySlider(this.$seekSlider);
-                this._destroySlider(this.$volumeSlider);
-
-                this.$component.remove();
-                this.$component = null;
+                this.player.recover();
             }
-
-            // rerender
-            this.render();
+            this._setState('stalled', false);
+            this.setInitialStates();
         },
 
         /**
@@ -788,8 +783,12 @@ function mediaplayerFactory(config) {
                 source = _.clone(src);
             }
 
-            if (this.is('youtube') && !source.type) {
-                source.type = defaults.type;
+            if (!source.type) {
+                if (this.is('youtube')) {
+                    source.type = defaults.type;
+                } else if (this.config.mimeType) {
+                    source.type = this.config.mimeType;
+                }
             }
 
             if (!source.type) {
@@ -872,7 +871,8 @@ function mediaplayerFactory(config) {
                         type: this.getType(),
                         sources: this.getSources(),
                         preview: this.config.preview,
-                        debug: this.config.debug
+                        debug: this.config.debug,
+                        stalledDetectionDelay: this.config.stalledDetectionDelay
                     };
                     this.player = playerFactory(this.$player, playerConfig)
                         .on('resize', (width, height) => {
@@ -887,8 +887,7 @@ function mediaplayerFactory(config) {
                         .on('stalled', () => this._onStalled())
                         .on('playing', () => this._onPlaying())
                         .on('end', () => this._onEnd())
-                        .on('error', () => this._onError())
-                        .on('recovererror', fromLoading => this._onRecoverError(fromLoading));
+                        .on('error', () => this._onError());
                 }
 
                 if (this.player) {
@@ -903,7 +902,11 @@ function mediaplayerFactory(config) {
             this._setState('error', error);
             this._setState('nogui', !support.canControl());
             this._setState('preview', this.config.preview);
-            this._setState('loading', true);
+            this._setState('loading', !error);
+            if (error) {
+                this._setState('ready', true);
+                this.trigger('ready');
+            }
         },
 
         /**
@@ -1236,7 +1239,7 @@ function mediaplayerFactory(config) {
          */
         _onReady() {
             if (this.is('error')) {
-                this._onRecoverError();
+                this._setState('error', false);
             }
 
             const duration = this.player.getDuration();
@@ -1264,11 +1267,6 @@ function mediaplayerFactory(config) {
             if (this.config.preview && this.$container && this.config.height && this.config.height !== 'auto') {
                 this._setMaxHeight();
             }
-
-            // seek back to the previous position after recover from stalled
-            if (this.is('stalled')) {
-                this.play(this.positionBeforeStalled);
-            }
         },
 
         /**
@@ -1332,26 +1330,6 @@ function mediaplayerFactory(config) {
             this.trigger('error');
         },
 
-        /**
-         * Event called when the media throws recoverable error
-         * @param {Boolean} fromLoading - recover from an error while loading the media
-         * @private
-         */
-        _onRecoverError(fromLoading = false) {
-            // recover from playing error
-            if (fromLoading && this.is('playing')) {
-                this.render();
-            }
-
-            this._setState('error', false);
-
-            /**
-             * Triggers a recoverable media error event
-             * @event mediaplayer#recovererror
-             */
-            this.trigger('recovererror');
-        },
-
         /**
          * Event called when the media is played
          * @private
@@ -1390,10 +1368,11 @@ function mediaplayerFactory(config) {
             this._playingState(false, true);
             this._updatePosition(0);
 
-            // disable GUI when the play limit is reached
+            // disable when the play limit is reached
             if (this._playLimitReached()) {
-                this._disableGUI();
-
+                if (!this.is('disabled')) {
+                    this.disable();
+                }
                 /**
                  * Triggers a play limit reached event
                  * @event mediaplayer#limitreached
@@ -1428,15 +1407,8 @@ function mediaplayerFactory(config) {
          * @private
          */
         _onStalled() {
-            this.stalledTimeUpdateCount = 0;
-            this.stalledTimer = window.setTimeout(() => {
-                const position = this.getPosition();
-                if (position) {
-                    this.positionBeforeStalled = position;
-                }
-                this._setState('stalled', true);
-                this._setState('ready', false);
-            }, this.config.stalledTimeout);
+            this._setState('stalled', true);
+            this._setState('ready', false);
         },
 
         /**
@@ -1444,15 +1416,6 @@ function mediaplayerFactory(config) {
          * @private
          */
         _onTimeUpdate() {
-            if (this.stalledTimer) {
-                if (this.stalledTimeUpdateCount === 5) {
-                    window.clearTimeout(this.stalledTimer);
-                    this.stalledTimer = null;
-                } else {
-                    this.stalledTimeUpdateCount++;
-                }
-            }
-
             this._updatePosition(this.player.getPosition());
 
             /**
@@ -1473,21 +1436,11 @@ function mediaplayerFactory(config) {
             this.timerId = requestAnimationFrame(this._replayTimeout.bind(this));
 
             if (elapsedSeconds >= parseInt(this.config.replayTimeout, 10)) {
-                this._disableGUI();
                 this.disable();
                 cancelAnimationFrame(this.timerId);
             }
         },
 
-        /**
-         * Disable the player GUI
-         * @private
-         */
-        _disableGUI() {
-            this._setState('ready', false);
-            this._setState('canplay', false);
-        },
-
         /**
          * Checks if the play limit has been reached
          * @returns {Boolean}
@@ -1605,11 +1558,8 @@ function mediaplayerFactory(config) {
          * @private
          */
         execute(command, ...args) {
-            const ctx = this.player;
-            const method = ctx && ctx[command];
-
-            if (_.isFunction(method)) {
-                return method.apply(ctx, args);
+            if (this.player && 'function' === typeof this.player[command]) {
+                return this.player[command](...args);
             }
         }
     };