web/video.js
1
0
Fork 0
mirror of https://github.com/videojs/video.js.git synced 2025-01-27 11:22:06 +02:00
Code Releases Activity

docs(jsdoc): Update the jsdoc comments to modern syntax - Part 5 (#3766)

Browse Source 
Files in this PR:
* src/js/tracks/audio-track-list.js
* src/js/tracks/audio-track.js
* src/js/tracks/html-track-element-list.js
* src/js/tracks/html-track-element.js
* src/js/tracks/text-track-cue-list.js
* src/js/tracks/text-track-display.js
* src/js/tracks/text-track-list-converter.js
* src/js/tracks/text-track-list.js
* src/js/tracks/text-track-settings.js
* src/js/tracks/text-track.js
* src/js/tracks/track-enums.js
* src/js/tracks/track-list.js
* src/js/tracks/track.js
* src/js/tracks/video-track-list.js
* src/js/tracks/video-track.js
* src/js/utils/browser.js
* src/js/utils/buffer.js
* src/js/utils/computed-style.js
* src/js/utils/fn.js
* src/js/utils/format-time.js
* src/js/utils/guid.js
* src/js/utils/obj.js
* src/js/utils/stylesheet.js
* src/js/utils/time-ranges.js
* src/js/utils/to-title-case.js
This commit is contained in:
Brandon Casey 2016-12-02 15:17:08 -05:00 committed by Gary Katsevman
parent 15ce37e45d
commit ba3cf1724f
25 changed files with 920 additions and 395 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
src/js/tracks/audio-track-list.js
View File

@ -6,11 +6,16 @@ import * as browser from '../utils/browser.js';
import document from 'global/document';
/**
* anywhere we call this function we diverge from the spec
* Anywhere we call this function we diverge from the spec
* as we only support one enabled audiotrack at a time
*
* @param {Array|AudioTrackList} list list to work on
* @param {AudioTrack} track the track to skip
* @param {AudioTrackList} list
* list to work on
*
* @param {AudioTrack} track
* The track to skip
*
* @private
*/
const disableOthers = function(list, track) {
for (let i = 0; i < list.length; i++) {
@ -23,25 +28,19 @@ const disableOthers = function(list, track) {
};
/**
* A list of possible audio tracks. All functionality is in the
* base class Tracklist and the spec for AudioTrackList is located at:
* @link https://html.spec.whatwg.org/multipage/embedded-content.html#audiotracklist
* The current list of {@link AudioTrack} for a media file.
*
* interface AudioTrackList : EventTarget {
* readonly attribute unsigned long length;
* getter AudioTrack (unsigned long index);
* AudioTrack? getTrackById(DOMString id);
*
* attribute EventHandler onchange;
* attribute EventHandler onaddtrack;
* attribute EventHandler onremovetrack;
* };
*
* @param {AudioTrack[]} tracks a list of audio tracks to instantiate the list with
* @see [Spec]{@link https://html.spec.whatwg.org/multipage/embedded-content.html#audiotracklist}
* @extends TrackList
* @class AudioTrackList
*/
class AudioTrackList extends TrackList {
/**
* Create an instance of this class.
*
* @param {AudioTrack[]} [tracks=[]]
* A list of `AudioTrack` to instantiate the list with.
*/
constructor(tracks = []) {
let list;
@ -76,6 +75,15 @@ class AudioTrackList extends TrackList {
return list;
}
/**
* Add an {@link AudioTrack} to the `AudioTrackList`.
*
* @param {AudioTrack} track
* The AudioTrack to add to the list
*
* @fires Track#addtrack
* @private
*/
addTrack_(track) {
if (track.enabled) {
disableOthers(this, track);
@ -87,6 +95,10 @@ class AudioTrackList extends TrackList {
return;
}
/**
* @listens AudioTrack#enabledchange
* @fires TrackList#change
*/
track.addEventListener('enabledchange', () => {
// when we are disabling other tracks (since we don't support
// more than one track at a time) we will set changing_
@ -101,10 +113,26 @@ class AudioTrackList extends TrackList {
});
}
/**
* Add an {@link AudioTrack} to the `AudioTrackList`.
*
* @param {AudioTrack} track
* The AudioTrack to add to the list
*
* @fires Track#addtrack
*/
addTrack(track) {
this.addTrack_(track);
}
/**
* Remove an {@link AudioTrack} from the `AudioTrackList`.
*
* @param {AudioTrack} track
* The AudioTrack to remove from the list
*
* @fires Track#removetrack
*/
removeTrack(track) {
super.removeTrack_(track);
}

58
src/js/tracks/audio-track.js
View File

@ -4,21 +4,36 @@ import merge from '../utils/merge-options';
import * as browser from '../utils/browser.js';
/**
* A single audio text track as defined in:
* @link https://html.spec.whatwg.org/multipage/embedded-content.html#audiotrack
* A representation of a single `AudioTrack`. If it is part of an {@link AudioTrackList}
* only one `AudioTrack` in the list will be enabled at a time.
*
* interface AudioTrack {
* readonly attribute DOMString id;
* readonly attribute DOMString kind;
* readonly attribute DOMString label;
* readonly attribute DOMString language;
* attribute boolean enabled;
* };
*
* @param {Object=} options Object of option names and values
* @class AudioTrack
* @see [Spec]{@link https://html.spec.whatwg.org/multipage/embedded-content.html#audiotrack}
* @extends Track
*/
class AudioTrack extends Track {
/**
* Create an instance of this class.
*
* @param {Object} [options={}]
* Object of option names and values
*
* @param {AudioTrack~Kind} [options.kind='']
* A valid audio track kind
*
* @param {string} [options.id='vjs_track_' + Guid.newGUID()]
* A unique id for this AudioTrack.
*
* @param {string} [options.label='']
* The menu label for this track.
*
* @param {string} [options.language='']
* A valid two character language code.
*
* @param {boolean} [options.enabled]
* If this track is the one that is currently playing. If this track is part of
* an {@link AudioTrackList}, only one {@link AudioTrack} will be enabled.
*/
constructor(options = {}) {
const settings = merge(options, {
kind: AudioTrackKind[options.kind] || ''
@ -35,7 +50,13 @@ class AudioTrack extends Track {
}
}
}
/**
* @member {boolean} enabled
* If this `AudioTrack` is enabled or not. When setting this will
* fire {@link AudioTrack#enabledchange} if the state of enabled is changed.
*
* @fires VideoTrack#selectedchange
*/
Object.defineProperty(track, 'enabled', {
get() {
return enabled;
@ -46,6 +67,17 @@ class AudioTrack extends Track {
return;
}
enabled = newEnabled;
/**
* An event that fires when enabled changes on this track. This allows
* the AudioTrackList that holds this track to act accordingly.
*
* > Note: This is not part of the spec! Native tracks will do
* this internally without an event.
*
* @event AudioTrack#enabledchange
* @type {EventTarget~Event}
*/
this.trigger('enabledchange');
}
});

42
src/js/tracks/html-track-element-list.js
View File

@ -5,7 +5,17 @@
import * as browser from '../utils/browser.js';
import document from 'global/document';
/**
* The current list of {@link HtmlTrackElement}s.
*/
class HtmlTrackElementList {
/**
* Create an instance of this class.
*
* @param {HtmlTrackElement[]} [tracks=[]]
* A list of `HtmlTrackElement` to instantiate the list with.
*/
constructor(trackElements = []) {
let list = this; // eslint-disable-line
@ -21,6 +31,10 @@ class HtmlTrackElementList {
list.trackElements_ = [];
/**
* @member {number} length
* The current number of `Track`s in the this Trackist.
*/
Object.defineProperty(list, 'length', {
get() {
return this.trackElements_.length;
@ -36,6 +50,14 @@ class HtmlTrackElementList {
}
}
/**
* Add an {@link HtmlTrackElement} to the `HtmlTrackElementList`
*
* @param {HtmlTrackElement} trackElement
* The track element to add to the list.
*
* @private
*/
addTrackElement_(trackElement) {
const index = this.trackElements_.length;
@ -53,6 +75,18 @@ class HtmlTrackElementList {
}
}
/**
* Get an {@link HtmlTrackElement} from the `HtmlTrackElementList` given an
* {@link TextTrack}.
*
* @param {TextTrack} track
* The track associated with a track element.
*
* @return {HtmlTrackElement|undefined}
* The track element that was found or undefined.
*
* @private
*/
getTrackElementByTrack_(track) {
let trackElement_;
@ -67,6 +101,14 @@ class HtmlTrackElementList {
return trackElement_;
}
/**
* Remove a {@link HtmlTrackElement} from the `HtmlTrackElementList`
*
* @param {HtmlTrackElement} trackElement
* The track element to remove from the list.
*
* @private
*/
removeTrackElement_(trackElement) {
for (let i = 0, length = this.trackElements_.length; i < length; i++) {
if (trackElement === this.trackElements_[i]) {

74
src/js/tracks/html-track-element.js
View File

@ -7,35 +7,57 @@ import document from 'global/document';
import EventTarget from '../event-target';
import TextTrack from '../tracks/text-track';
/**
* @typedef {HTMLTrackElement~ReadyState}
* @enum {number}
*/
const NONE = 0;
const LOADING = 1;
const LOADED = 2;
const ERROR = 3;
/**
* https://html.spec.whatwg.org/multipage/embedded-content.html#htmltrackelement
* A single track represented in the DOM.
*
* interface HTMLTrackElement : HTMLElement {
* attribute DOMString kind;
* attribute DOMString src;
* attribute DOMString srclang;
* attribute DOMString label;
* attribute boolean default;
*
* const unsigned short NONE = 0;
* const unsigned short LOADING = 1;
* const unsigned short LOADED = 2;
* const unsigned short ERROR = 3;
* readonly attribute unsigned short readyState;
*
* readonly attribute TextTrack track;
* };
*
* @param {Object} options TextTrack configuration
* @class HTMLTrackElement
* @see [Spec]{@link https://html.spec.whatwg.org/multipage/embedded-content.html#htmltrackelement}
* @extends EventTarget
*/
class HTMLTrackElement extends EventTarget {
/**
* Create an instance of this class.
*
* @param {Object} options={}
* Object of option names and values
*
* @param {Tech} options.tech
* A reference to the tech that owns this HTMLTrackElement.
*
* @param {TextTrack~Kind} [options.kind='subtitles']
* A valid text track kind.
*
* @param {TextTrack~Mode} [options.mode='disabled']
* A valid text track mode.
*
* @param {string} [options.id='vjs_track_' + Guid.newGUID()]
* A unique id for this TextTrack.
*
* @param {string} [options.label='']
* The menu label for this track.
*
* @param {string} [options.language='']
* A valid two character language code.
*
* @param {string} [options.srclang='']
* A valid two character language code. An alternative, but deprioritized
* vesion of `options.language`
*
* @param {string} [options.src]
* A url to TextTrack cues.
*
* @param {boolean} [options.default]
* If this track should default to on or off.
*/
constructor(options = {}) {
super();
@ -60,12 +82,20 @@ class HTMLTrackElement extends EventTarget {
trackElement.label = track.label;
trackElement.default = track.default;
/**
* @member {HTMLTrackElement~ReadyState} readyState
* The current ready state of the track element.
*/
Object.defineProperty(trackElement, 'readyState', {
get() {
return readyState;
}
});
/**
* @member {TextTrack} track
* The underlying TextTrack object.
*/
Object.defineProperty(trackElement, 'track', {
get() {
return track;
@ -74,6 +104,10 @@ class HTMLTrackElement extends EventTarget {
readyState = NONE;
/**
* @listens TextTrack#loadeddata
* @fires HTMLTrackElement#load
*/
track.addEventListener('loadeddata', function() {
readyState = LOADED;

56
src/js/tracks/text-track-cue-list.js
View File

@ -5,20 +5,36 @@ import * as browser from '../utils/browser.js';
import document from 'global/document';
/**
* A List of text track cues as defined in:
* https://html.spec.whatwg.org/multipage/embedded-content.html#texttrackcuelist
* @typedef {Object} TextTrackCue
*
* interface TextTrackCueList {
* readonly attribute unsigned long length;
* getter TextTrackCue (unsigned long index);
* TextTrackCue? getCueById(DOMString id);
* };
* @property {string} id
* The unique id for this text track cue
*
* @param {Array} cues A list of cues to be initialized with
* @class TextTrackCueList
* @property {number} startTime
* The start time for this text track cue
*
* @property {number} endTime
* The end time for this text track cue
*
* @property {boolean} pauseOnExit
* Pause when the end time is reached if true.
*
* @see [Spec]{@link https://html.spec.whatwg.org/multipage/embedded-content.html#texttrackcue}
*/
/**
* A List of TextTrackCues.
*
* @see [Spec]{@link https://html.spec.whatwg.org/multipage/embedded-content.html#texttrackcuelist}
*/
class TextTrackCueList {
/**
* Create an instance of this class..
*
* @param {Array} cues
* A list of cues to be initialized with
*/
constructor(cues) {
let list = this; // eslint-disable-line
@ -34,6 +50,10 @@ class TextTrackCueList {
TextTrackCueList.prototype.setCues_.call(list, cues);
/**
* @member {number} length
* The current number of `TextTrackCue`s in the TextTrackCueList.
*/
Object.defineProperty(list, 'length', {
get() {
return this.length_;
@ -46,10 +66,12 @@ class TextTrackCueList {
}
/**
* A setter for cues in this list
* A setter for cues in this list. Creates getters
* an an index for the cues.
*
* @param {Array} cues
* An array of cues to set
*
* @param {Array} cues an array of cues
* @method setCues_
* @private
*/
setCues_(cues) {
@ -80,11 +102,13 @@ class TextTrackCueList {
}
/**
* Get a cue that is currently in the Cue list by id
* Get a `TextTrackCue` that is currently in the `TextTrackCueList` by id.
*
* @param {String} id
* @method getCueById
* @return {Object} a single cue
* @param {string} id
* The id of the cue that should be searched for.
*
* @return {TextTrackCue|null}
* A single cue or null if none was found.
*/
getCueById(id) {
let result = null;

77
src/js/tracks/text-track-display.js
View File

@ -21,12 +21,18 @@ const fontMap = {
};
/**
* Add cue HTML to display
* Construct an rgba color from a given hex color code.
*
* @param {Number} color Hex number for color, like #f0e
* @param {Number} opacity Value for opacity,0.0 - 1.0
* @return {RGBAColor} In the form 'rgba(255, 0, 0, 0.3)'
* @method constructColor
* @param {number} color
* Hex number for color, like #f0e.
*
* @param {number} opacity
* Value for opacity, 0.0 - 1.0.
*
* @return {string}
* The rgba color that was created, like 'rgba(255, 0, 0, 0.3)'.
*
* @private
*/
function constructColor(color, opacity) {
return 'rgba(' +
@ -38,13 +44,17 @@ function constructColor(color, opacity) {
}
/**
* Try to update style
* Some style changes will throw an error, particularly in IE8. Those should be noops.
* Try to update the style of a DOM element. Some style changes will throw an error,
* particularly in IE8. Those should be noops.
*
* @param {Element} el The element to be styles
* @param {CSSProperty} style The CSS property to be styled
* @param {CSSStyle} rule The actual style to be applied to the property
* @method tryUpdateStyle
* @param {Element} el
* The DOM element to be styled.
*
* @param {string} style
* The CSS property on the element that should be styled.
*
* @param {string} rule
* The style rule that should be applied to the property.
*/
function tryUpdateStyle(el, style, rule) {
try {
@ -57,16 +67,24 @@ function tryUpdateStyle(el, style, rule) {
}
/**
* The component for displaying text track cues
* The component for displaying text track cues.
*
* @param {Object} player Main Player
* @param {Object=} options Object of option names and values
* @param {Function=} ready Ready callback function
* @extends Component
* @class TextTrackDisplay
*/
class TextTrackDisplay extends Component {
/**
* Creates an instance of this class.
*
* @param {Player} player
* The `Player` that this class should be attached to.
*
* @param {Object} [options]
* The key/value store of player options.
*
* @param {Component~ReadyCallback} [ready]
* The function to call when `TextTrackDisplay` is ready.
*/
constructor(player, options, ready) {
super(player, options, ready);
@ -123,9 +141,12 @@ class TextTrackDisplay extends Component {
}
/**
* Toggle display texttracks
* Turn display of {@link TextTrack}'s from the current state into the other state.
* There are only two states:
* - 'shown'
* - 'hidden'
*
* @method toggleDisplay
* @listens Player#loadstart
*/
toggleDisplay() {
if (this.player_.tech_ && this.player_.tech_.featuresNativeTextTracks) {
@ -136,10 +157,10 @@ class TextTrackDisplay extends Component {
}
/**
* Create the component's DOM element
* Create the {@link Component}'s DOM element.
*
* @return {Element}
* @method createEl
* The element that was created.
*/
createEl() {
return super.createEl('div', {
@ -151,9 +172,7 @@ class TextTrackDisplay extends Component {
}
/**
* Clear display texttracks
*
* @method clearDisplay
* Clear all displayed {@link TextTrack}s.
*/
clearDisplay() {
if (typeof window.WebVTT === 'function') {
@ -162,9 +181,11 @@ class TextTrackDisplay extends Component {
}
/**
* Update display texttracks
* Update the displayed TextTrack when a either a {@link Player#texttrackchange} or
* a {@link Player#fullscreenchange} is fired.
*
* @method updateDisplay
* @listens Player#texttrackchange
* @listens Player#fullscreenchange
*/
updateDisplay() {
const tracks = this.player_.textTracks();
@ -210,10 +231,10 @@ class TextTrackDisplay extends Component {
}
/**
* Add texttrack to texttrack list
* Add an {@link Texttrack} to to the {@link Tech}s {@link TextTrackList}.
*
* @param {TextTrackObject} track Texttrack object to be added to list
* @method updateForTrack
* @param {TextTrack} track
* Text track object to be added to the list.
*/
updateForTrack(track) {
if (typeof window.WebVTT !== 'function' || !track.activeCues) {

44
src/js/tracks/text-track-list-converter.js
View File

@ -3,13 +3,18 @@
* based on a capture.
*
* @file text-track-list-converter.js
* @module text-track-list-converter
*/
/**
* Examine a single text track and return a JSON-compatible javascript
* object that represents the text track's state.
* @param track {TextTrackObject} the text track to query
* @return {Object} a serializable javascript representation of the
* Examine a single {@link TextTrack} and return a JSON-compatible javascript object that
* represents the {@link TextTrack}'s state.
*
* @param {TextTrack} track
* The text track to query.
*
* @return {Object}
* A serializable javascript representation of the TextTrack.
* @private
*/
const trackToJson_ = function(track) {
@ -38,12 +43,16 @@ const trackToJson_ = function(track) {
};
/**
* Examine a tech and return a JSON-compatible javascript array that
* represents the state of all text tracks currently configured. The
* return array is compatible with `jsonToTextTracks`.
* @param tech {tech} the tech object to query
* @return {Array} a serializable javascript representation of the
* @function textTracksToJson
* Examine a {@link Tech} and return a JSON-compatible javascript array that represents the
* state of all {@link TextTrack}s currently configured. The return array is compatible with
* {@link text-track-list-converter:jsonToTextTracks}.
*
* @param {Tech} tech
* The tech object to query
*
* @return {Array}
* A serializable javascript representation of the {@link Tech}s
* {@link TextTrackList}.
*/
const textTracksToJson = function(tech) {
@ -65,12 +74,15 @@ const textTracksToJson = function(tech) {
};
/**
* Creates a set of remote text tracks on a tech based on an array of
* javascript text track representations.
* @param json {Array} an array of text track representation objects,
* like those that would be produced by `textTracksToJson`
* @param tech {tech} the tech to create text tracks on
* @function jsonToTextTracks
* Create a set of remote {@link TextTrack}s on a {@link Tech} based on an array of javascript
* object {@link TextTrack} representations.
*
* @param {Array} json
* An array of `TextTrack` representation objects, like those that would be
* produced by `textTracksToJson`.
*
* @param {Tech} tech
* The `Tech` to create the `TextTrack`s on.
*/
const jsonToTextTracks = function(json, tech) {
json.forEach(function(track) {

95
src/js/tracks/text-track-list.js
View File

@ -7,25 +7,19 @@ import * as browser from '../utils/browser.js';
import document from 'global/document';
/**
* A list of possible text tracks. All functionality is in the
* base class TrackList. The spec for TextTrackList is located at:
* @link https://html.spec.whatwg.org/multipage/embedded-content.html#texttracklist
* The current list of {@link TextTrack} for a media file.
*
* interface TextTrackList : EventTarget {
* readonly attribute unsigned long length;
* getter TextTrack (unsigned long index);
* TextTrack? getTrackById(DOMString id);
*
* attribute EventHandler onchange;
* attribute EventHandler onaddtrack;
* attribute EventHandler onremovetrack;
* };
*
* @param {TextTrack[]} tracks A list of tracks to initialize the list with
* @see [Spec]{@link https://html.spec.whatwg.org/multipage/embedded-content.html#texttracklist}
* @extends TrackList
* @class TextTrackList
*/
class TextTrackList extends TrackList {
/**
* Create an instance of this class.
*
* @param {TextTrack[]} [tracks=[]]
* A list of `TextTrack` to instantiate the list with.
*/
constructor(tracks = []) {
let list;
@ -49,68 +43,25 @@ class TextTrackList extends TrackList {
return list;
}
/**
* Add a {@link TextTrack} to the `TextTrackList`
*
* @param {TextTrack} track
* The text track to add to the list.
*
* @fires TrackList#addtrack
* @private
*/
addTrack_(track) {
super.addTrack_(track);
/**
* @listens TextTrack#modechange
* @fires TrackList#change
*/
track.addEventListener('modechange', Fn.bind(this, function() {
this.trigger('change');
}));
}
/**
* Remove TextTrack from TextTrackList
* NOTE: Be mindful of what is passed in as it may be a HTMLTrackElement
*
* @param {TextTrack} rtrack
* @method removeTrack_
* @private
*/
removeTrack_(rtrack) {
let track;
for (let i = 0, l = this.length; i < l; i++) {
if (this[i] === rtrack) {
track = this[i];
if (track.off) {
track.off();
}
this.tracks_.splice(i, 1);
break;
}
}
if (!track) {
return;
}
this.trigger({
track,
type: 'removetrack'
});
}
/**
* Get a TextTrack from TextTrackList by a tracks id
*
* @param {String} id - the id of the track to get
* @method getTrackById
* @return {TextTrack}
* @private
*/
getTrackById(id) {
let result = null;
for (let i = 0, l = this.length; i < l; i++) {
const track = this[i];
if (track.id === id) {
result = track;
break;
}
}
return result;
}
}
export default TextTrackList;

101
src/js/tracks/text-track-settings.js
View File

@ -158,14 +158,20 @@ const selectConfigs = {
selectConfigs.windowColor.options = selectConfigs.backgroundColor.options;
/**
* Parses out option values.
* Get the actual value of an option.
*
* @param {string} value
* The value to get
*
* @private
* @param {String} value
* @param {Function} [parser]
* Optional function to adjust the value.
*
* @return {Mixed}
* Will be `undefined` if no value exists (or if given value is "none").
* - Will be `undefined` if no value exists
* - Will be `undefined` if the given value is "none".
* - Will be the actual value otherwise.
*
* @private
*/
function parseOptionValue(value, parser) {
if (parser) {
@ -180,10 +186,18 @@ function parseOptionValue(value, parser) {
/**
* Gets the value of the selected <option> element within a <select> element.
*
* @param {Object} config
* @param {Element} el
* the element to look in
*
* @param {Function} [parser]
* Optional function to adjust the value.
*
* @return {Mixed}
* - Will be `undefined` if no value exists
* - Will be `undefined` if the given value is "none".
* - Will be the actual value otherwise.
*
* @private
*/
function getSelectedOptionValue(el, parser) {
const value = el.options[el.options.selectedIndex].value;
@ -195,10 +209,16 @@ function getSelectedOptionValue(el, parser) {
* Sets the selected <option> element within a <select> element based on a
* given value.
*
* @param {Object} el
* @param {String} value
* @param {Element} el
* The element to look in.
*
* @param {string} value
* the property to look on.
*
* @param {Function} [parser]
* Optional function to adjust the value before comparing.
*
* @private
*/
function setSelectedOption(el, value, parser) {
if (!value) {
@ -214,15 +234,21 @@ function setSelectedOption(el, value, parser) {
}
/**
* Manipulate settings of text tracks
* Manipulate Text Tracks settings.
*
* @param {Object} player Main Player
* @param {Object=} options Object of option names and values
* @extends Component
* @class TextTrackSettings
*/
class TextTrackSettings extends Component {
/**
* Creates an instance of this class.
*
* @param {Player} player
* The `Player` that this class should be attached to.
*
* @param {Object} [options]
* The key/value store of player options.
*/
constructor(player, options) {
super(player, options);
this.setDefaults();
@ -257,9 +283,12 @@ class TextTrackSettings extends Component {
/**
* Create a <select> element with configured options.
*
* @private
* @param {string} key
* Configuration key to use during creation.
*
* @return {Element}
* @method createElSelect_
* The DOM element that gets created.
* @private
*/
createElSelect_(key) {
const config = selectConfigs[key];
@ -284,9 +313,10 @@ class TextTrackSettings extends Component {
/**
* Create foreground color element for the component
*
* @private
* @return {Element}
* @method createElFgColor_
* The element that was created.
*
* @private
*/
createElFgColor_() {
const legend = createEl('legend', {
@ -307,9 +337,10 @@ class TextTrackSettings extends Component {
/**
* Create background color element for the component
*
* @private
* @return {Element}
* @method createElBgColor_
* The element that was created
*
* @private
*/
createElBgColor_() {
const legend = createEl('legend', {
@ -330,9 +361,10 @@ class TextTrackSettings extends Component {
/**
* Create window color element for the component
*
* @private
* @return {Element}
* @method createElWinColor_
* The element that was created
*
* @private
*/
createElWinColor_() {
const legend = createEl('legend', {
@ -353,9 +385,10 @@ class TextTrackSettings extends Component {
/**
* Create color elements for the component
*
* @private
* @return {Element}
* @method createElColors_
* The element that was created
*
* @private
*/
createElColors_() {
return createEl('div', {
@ -370,9 +403,10 @@ class TextTrackSettings extends Component {
/**
* Create font elements for the component
*
* @private
* @return {Element}
* @method createElFont_
* The element that was created.
*
* @private
*/
createElFont_() {
const fontPercent = createEl('div', {
@ -395,9 +429,10 @@ class TextTrackSettings extends Component {
/**
* Create controls for the component
*
* @private
* @return {Element}
* @method createElControls_
* The element that was created.
*
* @private
*/
createElControls_() {
const defaultsButton = createEl('button', {
@ -419,7 +454,7 @@ class TextTrackSettings extends Component {
* Create the component's DOM element
*
* @return {Element}
* @method createEl
* The element that was created.
*/
createEl() {
const settings = createEl('div', {
@ -464,7 +499,6 @@ class TextTrackSettings extends Component {
*
* @return {Object}
* An object with config values parsed from the DOM or localStorage.
* @method getValues
*/
getValues() {
return Obj.reduce(selectConfigs, (accum, config, key) => {
@ -483,7 +517,6 @@ class TextTrackSettings extends Component {
*
* @param {Object} values
* An object with config values parsed from the DOM or localStorage.
* @method setValues
*/
setValues(values) {
Obj.each(selectConfigs, (config, key) => {
@ -493,8 +526,6 @@ class TextTrackSettings extends Component {
/**
* Sets all <select> elements to their default values.
*
* @method setDefaults
*/
setDefaults() {
Obj.each(selectConfigs, (config) => {
@ -505,9 +536,7 @@ class TextTrackSettings extends Component {
}
/**
* Restore texttrack settings
*
* @method restoreSettings
* Restore texttrack settings from localStorage
*/
restoreSettings() {
let values;
@ -524,9 +553,7 @@ class TextTrackSettings extends Component {
}
/**
* Save text track settings to local storage
*
* @method saveSettings
* Save text track settings to localStorage
*/
saveSettings() {
if (!this.options_.persistTextTrackSettings) {
@ -548,8 +575,6 @@ class TextTrackSettings extends Component {
/**
* Update display of text track settings
*
* @method updateDisplay
*/
updateDisplay() {
const ttDisplay = this.player_.getChild('textTrackDisplay');

129
src/js/tracks/text-track.js
View File

@ -13,15 +13,20 @@ import merge from '../utils/merge-options';
import * as browser from '../utils/browser.js';
/**
* takes a webvtt file contents and parses it into cues
* Takes a webvtt file contents and parses it into cues
*
* @param {String} srcContent webVTT file contents
* @param {Track} track track to addcues to
* @param {string} srcContent
* webVTT file contents
*
* @param {TextTrack} track
* TextTrack to add cues to. Cues come from the srcContent.
*
* @private
*/
const parseCues = function(srcContent, track) {
const parser = new window.WebVTT.Parser(window,
window.vttjs,
window.WebVTT.StringDecoder());
window.vttjs,
window.WebVTT.StringDecoder());
const errors = [];
parser.oncue = function(cue) {
@ -54,10 +59,15 @@ const parseCues = function(srcContent, track) {
};
/**
* load a track from a specifed url
* Load a `TextTrack` from a specifed url.
*
* @param {String} src url to load track from
* @param {Track} track track to addcues to
* @param {string} src
* Url to load track from.
*
* @param {TextTrack} track
* Track to add cues to. Comes from the content at the end of `url`.
*
* @private
*/
const loadTrack = function(src, track) {
const opts = {
@ -97,33 +107,47 @@ const loadTrack = function(src, track) {
};
/**
* A single text track as defined in:
* @link https://html.spec.whatwg.org/multipage/embedded-content.html#texttrack
* A representation of a single `TextTrack`.
*
* interface TextTrack : EventTarget {
* readonly attribute TextTrackKind kind;
* readonly attribute DOMString label;
* readonly attribute DOMString language;
*
* readonly attribute DOMString id;
* readonly attribute DOMString inBandMetadataTrackDispatchType;
*
* attribute TextTrackMode mode;
*
* readonly attribute TextTrackCueList? cues;
* readonly attribute TextTrackCueList? activeCues;
*
* void addCue(TextTrackCue cue);
* void removeCue(TextTrackCue cue);
*
* attribute EventHandler oncuechange;
* };
*
* @param {Object=} options Object of option names and values
* @see [Spec]{@link https://html.spec.whatwg.org/multipage/embedded-content.html#texttrack}
* @extends Track
* @class TextTrack
*/
class TextTrack extends Track {
/**
* Create an instance of this class.
*
* @param {Object} options={}
* Object of option names and values
*
* @param {Tech} options.tech
* A reference to the tech that owns this TextTrack.
*
* @param {TextTrack~Kind} [options.kind='subtitles']
* A valid text track kind.
*
* @param {TextTrack~Mode} [options.mode='disabled']
* A valid text track mode.
*
* @param {string} [options.id='vjs_track_' + Guid.newGUID()]
* A unique id for this TextTrack.
*
* @param {string} [options.label='']
* The menu label for this track.
*
* @param {string} [options.language='']
* A valid two character language code.
*
* @param {string} [options.srclang='']
* A valid two character language code. An alternative, but deprioritized
* vesion of `options.language`
*
* @param {string} [options.src]
* A url to TextTrack cues.
*
* @param {boolean} [options.default]
* If this track should default to on or off.
*/
constructor(options = {}) {
if (!options.tech) {
throw new Error('A tech was not provided.');
@ -177,6 +201,13 @@ class TextTrack extends Track {
tt.tech_.on('timeupdate', timeupdateHandler);
}
/**
* @member {boolean} default
* If this track was set to be on or off by default. Cannot be changed after
* creation.
*
* @readonly
*/
Object.defineProperty(tt, 'default', {
get() {
return default_;
@ -184,6 +215,13 @@ class TextTrack extends Track {
set() {}
});
/**
* @member {string} mode
* Set the mode of this TextTrack to a valid {@link TextTrack~Mode}. Will
* not be set if setting to an invalid mode.
*
* @fires TextTrack#modechange
*/
Object.defineProperty(tt, 'mode', {
get() {
return mode;
@ -196,10 +234,23 @@ class TextTrack extends Track {
if (mode === 'showing') {
this.tech_.on('timeupdate', timeupdateHandler);
}
/**
* An event that fires when mode changes on this track. This allows
* the TextTrackList that holds this track to act accordingly.
*
* > Note: This is not part of the spec!
*
* @event TextTrack#modechange
* @type {EventTarget~Event}
*/
this.trigger('modechange');
}
});
/**
* @member {TextTrackCueList} cues
* The text track cue list for this TextTrack.
*/
Object.defineProperty(tt, 'cues', {
get() {
if (!this.loaded_) {
@ -211,6 +262,10 @@ class TextTrack extends Track {
set() {}
});
/**
* @member {TextTrackCueList} activeCues
* The list text track cues that are currently active for this TextTrack.
*/
Object.defineProperty(tt, 'activeCues', {
get() {
if (!this.loaded_) {
@ -268,10 +323,10 @@ class TextTrack extends Track {
}
/**
* add a cue to the internal list of cues
* Add a cue to the internal list of cues.
*
* @param {Object} cue the cue to add to our internal list
* @method addCue
* @param {TextTrack~Cue} cue
* The cue to add to our internal list
*/
addCue(cue) {
const tracks = this.tech_.textTracks();
@ -289,10 +344,10 @@ class TextTrack extends Track {
}
/**
* remvoe a cue from our internal list
* Remove a cue from our internal list
*
* @param {Object} removeCue the cue to remove from our internal list
* @method removeCue
* @param {TextTrack~Cue} removeCue
* The cue to remove from our internal list
*/
removeCue(removeCue) {
let removed = false;

46
src/js/tracks/track-enums.js
View File

@ -3,17 +3,11 @@
*/
/**
* https://html.spec.whatwg.org/multipage/embedded-content.html#dom-videotrack-kind
* All possible `VideoTrackKind`s
*
* enum VideoTrackKind {
* "alternative",
* "captions",
* "main",
* "sign",
* "subtitles",
* "commentary",
* "",
* };
* @see https://html.spec.whatwg.org/multipage/embedded-content.html#dom-videotrack-kind
* @typedef VideoTrack~Kind
* @enum
*/
export const VideoTrackKind = {
alternative: 'alternative',
@ -25,17 +19,11 @@ export const VideoTrackKind = {
};
/**
* https://html.spec.whatwg.org/multipage/embedded-content.html#dom-audiotrack-kind
* All possible `AudioTrackKind`s
*
* enum AudioTrackKind {
* "alternative",
* "descriptions",
* "main",
* "main-desc",
* "translation",
* "commentary",
* "",
* };
* @see https://html.spec.whatwg.org/multipage/embedded-content.html#dom-audiotrack-kind
* @typedef AudioTrack~Kind
* @enum
*/
export const AudioTrackKind = {
'alternative': 'alternative',
@ -47,15 +35,11 @@ export const AudioTrackKind = {
};
/**
* https://html.spec.whatwg.org/multipage/embedded-content.html#texttrackkind
* All possible `TextTrackKind`s
*
* enum TextTrackKind {
* "subtitles",
* "captions",
* "descriptions",
* "chapters",
* "metadata"
* };
* @see https://html.spec.whatwg.org/multipage/embedded-content.html#dom-texttrack-kind
* @typedef TextTrack~Kind
* @enum
*/
export const TextTrackKind = {
subtitles: 'subtitles',
@ -66,9 +50,11 @@ export const TextTrackKind = {
};
/**
* https://html.spec.whatwg.org/multipage/embedded-content.html#texttrackmode
* All possible `TextTrackMode`s
*
* enum TextTrackMode { "disabled", "hidden", "showing" };
* @see https://html.spec.whatwg.org/multipage/embedded-content.html#texttrackmode
* @typedef TextTrack~Mode
* @enum
*/
export const TextTrackMode = {
disabled: 'disabled',

72
src/js/tracks/track-list.js
View File

@ -6,16 +6,23 @@ import * as browser from '../utils/browser.js';
import document from 'global/document';
/**
* Common functionaliy between Text, Audio, and Video TrackLists
* Interfaces defined in the following spec:
* @link https://html.spec.whatwg.org/multipage/embedded-content.html
* Common functionaliy between {@link TextTrackList}, {@link AudioTrackList}, and
* {@link VideoTrackList}
*
* @param {Track[]} tracks A list of tracks to initialize the list with
* @param {Object} list the child object with inheritance done manually for ie8
* @extends EventTarget
* @class TrackList
*/
class TrackList extends EventTarget {
/**
* Create an instance of this class
*
* @param {Track[]} tracks
* A list of tracks to initialize the list with.
*
* @param {Object} [list]
* The child object with inheritance done manually for ie8.
*
* @abstract
*/
constructor(tracks = [], list = null) {
super();
if (!list) {
@ -31,6 +38,11 @@ class TrackList extends EventTarget {
}
list.tracks_ = [];
/**
* @member {number} length
* The current number of `Track`s in the this Trackist.
*/
Object.defineProperty(list, 'length', {
get() {
return this.tracks_.length;
@ -41,14 +53,18 @@ class TrackList extends EventTarget {
list.addTrack_(tracks[i]);
}
// must return the object, as for ie8 it will not be this
// but a reference to a document object
return list;
}
/**
* Add a Track from TrackList
* Add a {@link Track} to the `TrackList`
*
* @param {Mixed} track
* @method addTrack_
* @param {Track} track
* The audio, video, or text track to add to the list.
*
* @fires TrackList#addtrack
* @private
*/
addTrack_(track) {
@ -65,6 +81,14 @@ class TrackList extends EventTarget {
// Do not add duplicate tracks
if (this.tracks_.indexOf(track) === -1) {
this.tracks_.push(track);
/**
* Triggered when a track is added to a track list.
*
* @event TrackList#addtrack
* @type {EventTarget~Event}
* @property {Track} track
* A reference to track that was added.
*/
this.trigger({
track,
type: 'addtrack'
@ -73,10 +97,12 @@ class TrackList extends EventTarget {
}
/**
* Remove a Track from TrackList
* Remove a {@link Track} from the `TrackList`
*
* @param {Track} rtrack track to be removed
* @method removeTrack_
* @param {Track} track
* The audio, video, or text track to remove from the list.
*
* @fires TrackList#removetrack
* @private
*/
removeTrack_(rtrack) {
@ -99,6 +125,14 @@ class TrackList extends EventTarget {
return;
}
/**
* Triggered when a track is removed from track list.
*
* @event TrackList#removetrack
* @type {EventTarget~Event}
* @property {Track} track
* A reference to track that was removed.
*/
this.trigger({
track,
type: 'removetrack'
@ -130,9 +164,17 @@ class TrackList extends EventTarget {
}
/**
* change - One or more tracks in the track list have been enabled or disabled.
* addtrack - A track has been added to the track list.
* removetrack - A track has been removed from the track list.
* Triggered when a different track is selected/enabled.
*
* @event TrackList#change
* @type {EventTarget~Event}
*/
/**
* Events that can be called with on + eventName. See {@link EventHandler}.
*
* @property
* @private
*/
TrackList.prototype.allowedEvents_ = {
change: 'change',

61
src/js/tracks/track.js
View File

@ -7,15 +7,37 @@ import * as Guid from '../utils/guid.js';
import EventTarget from '../event-target';
/**
* setup the common parts of an audio, video, or text track
* @link https://html.spec.whatwg.org/multipage/embedded-content.html
* A Track class that contains all of the common functionality for {@link AudioTrack},
* {@link VideoTrack}, and {@link TextTrack}.
*
* @param {String} type The type of track we are dealing with audio|video|text
* @param {Object=} options Object of option names and values
* > Note: This class should not be used directly
*
* @see {@link https://html.spec.whatwg.org/multipage/embedded-content.html}
* @extends EventTarget
* @class Track
* @abstract
*/
class Track extends EventTarget {
/**
* Create an instance of this class.
*
* @param {Object} [options={}]
* Object of option names and values
*
* @param {string} [options.kind='']
* A valid kind for the track type you are creating.
*
* @param {string} [options.id='vjs_track_' + Guid.newGUID()]
* A unique id for this AudioTrack.
*
* @param {string} [options.label='']
* The menu label for this track.
*
* @param {string} [options.language='']
* A valid two character language code.
*
* @abstract
*/
constructor(options = {}) {
super();
@ -37,6 +59,35 @@ class Track extends EventTarget {
language: options.language || ''
};
/**
* @member {string} id
* The id of this track. Cannot be changed after creation.
*
* @readonly
*/
/**
* @member {string} kind
* The kind of track that this is. Cannot be changed after creation.
*
* @readonly
*/
/**
* @member {string} label
* The label of this track. Cannot be changed after creation.
*
* @readonly
*/
/**
* @member {string} language
* The two letter language code for this track. Cannot be changed after
* creation.
*
* @readonly
*/
for (const key in trackProps) {
Object.defineProperty(track, key, {
get() {

73
src/js/tracks/video-track-list.js
View File

@ -6,43 +6,40 @@ import * as browser from '../utils/browser.js';
import document from 'global/document';
/**
* disable other video tracks before selecting the new one
* Un-select all other {@link VideoTrack}s that are selected.
*
* @param {Array|VideoTrackList} list list to work on
* @param {VideoTrack} track the track to skip
* @param {VideoTrackList} list
* list to work on
*
* @param {VideoTrack} track
* The track to skip
*
* @private
*/
const disableOthers = function(list, track) {
for (let i = 0; i < list.length; i++) {
if (track.id === list[i].id) {
continue;
}
// another audio track is enabled, disable it
// another video track is enabled, disable it
list[i].selected = false;
}
};
/**
* A list of possiblee video tracks. Most functionality is in the
* base class Tracklist and the spec for VideoTrackList is located at:
* @link https://html.spec.whatwg.org/multipage/embedded-content.html#videotracklist
* The current list of {@link VideoTrack} for a video.
*
* interface VideoTrackList : EventTarget {
* readonly attribute unsigned long length;
* getter VideoTrack (unsigned long index);
* VideoTrack? getTrackById(DOMString id);
* readonly attribute long selectedIndex;
*
* attribute EventHandler onchange;
* attribute EventHandler onaddtrack;
* attribute EventHandler onremovetrack;
* };
*
* @param {VideoTrack[]} tracks a list of video tracks to instantiate the list with
# @extends TrackList
* @class VideoTrackList
* @see [Spec]{@link https://html.spec.whatwg.org/multipage/embedded-content.html#videotracklist}
* @extends TrackList
*/
class VideoTrackList extends TrackList {
/**
* Create an instance of this class.
*
* @param {VideoTrack[]} [tracks=[]]
* A list of `VideoTrack` to instantiate the list with.
*/
constructor(tracks = []) {
let list;
@ -74,6 +71,10 @@ class VideoTrackList extends TrackList {
list = super(tracks, list);
list.changing_ = false;
/**
* @member {number} VideoTrackList#selectedIndex
* The current index of the selected {@link VideoTrack`}.
*/
Object.defineProperty(list, 'selectedIndex', {
get() {
for (let i = 0; i < this.length; i++) {
@ -89,6 +90,15 @@ class VideoTrackList extends TrackList {
return list;
}
/**
* Add a {@link VideoTrack} to the `VideoTrackList`.
*
* @param {VideoTrack} track
* The VideoTrack to add to the list
*
* @fires TrackList#addtrack
* @private
*/
addTrack_(track) {
if (track.selected) {
disableOthers(this, track);
@ -99,6 +109,11 @@ class VideoTrackList extends TrackList {
if (!track.addEventListener) {
return;
}
/**
* @listens VideoTrack#selectedchange
* @fires TrackList#change
*/
track.addEventListener('selectedchange', () => {
if (this.changing_) {
return;
@ -110,10 +125,26 @@ class VideoTrackList extends TrackList {
});
}
/**
* Add a {@link VideoTrack} to the `VideoTrackList`.
*
* @param {VideoTrack} track
* The VideoTrack to add to the list
*
* @fires TrackList#addtrack
*/
addTrack(track) {
this.addTrack_(track);
}
/**
* Remove a {@link VideoTrack} to the `VideoTrackList`.
*
* @param {VideoTrack} track
* The VideoTrack to remove from the list.
*
* @fires TrackList#removetrack
*/
removeTrack(track) {
super.removeTrack_(track);
}

55
src/js/tracks/video-track.js
View File

@ -4,21 +4,34 @@ import merge from '../utils/merge-options';
import * as browser from '../utils/browser.js';
/**
* A single video text track as defined in:
* @link https://html.spec.whatwg.org/multipage/embedded-content.html#videotrack
* A representation of a single `VideoTrack`.
*
* interface VideoTrack {
* readonly attribute DOMString id;
* readonly attribute DOMString kind;
* readonly attribute DOMString label;
* readonly attribute DOMString language;
* attribute boolean selected;
* };
*
* @param {Object=} options Object of option names and values
* @class VideoTrack
* @see [Spec]{@link https://html.spec.whatwg.org/multipage/embedded-content.html#videotrack}
* @extends Track
*/
class VideoTrack extends Track {
/**
* Create an instance of this class.
*
* @param {Object} [options={}]
* Object of option names and values
*
* @param {string} [options.kind='']
* A valid {@link VideoTrack~Kind}
*
* @param {string} [options.id='vjs_track_' + Guid.newGUID()]
* A unique id for this AudioTrack.
*
* @param {string} [options.label='']
* The menu label for this track.
*
* @param {string} [options.language='']
* A valid two character language code.
*
* @param {boolean} [options.selected]
* If this track is the one that is currently playing.
*/
constructor(options = {}) {
const settings = merge(options, {
kind: VideoTrackKind[options.kind] || ''
@ -37,6 +50,13 @@ class VideoTrack extends Track {
}
}
/**
* @member {boolean} selected
* If this `VideoTrack` is selected or not. When setting this will
* fire {@link VideoTrack#selectedchange} if the state of selected changed.
*
* @fires VideoTrack#selectedchange
*/
Object.defineProperty(track, 'selected', {
get() {
return selected;
@ -47,6 +67,17 @@ class VideoTrack extends Track {
return;
}
selected = newSelected;
/**
* An event that fires when selected changes on this track. This allows
* the VideoTrackList that holds this track to act accordingly.
*
* > Note: This is not part of the spec! Native tracks will do
* this internally without an event.
*
* @event VideoTrack#selectedchange
* @type {EventTarget~Event}
*/
this.trigger('selectedchange');
}
});

1
src/js/utils/browser.js
View File

@ -1,5 +1,6 @@
/**
* @file browser.js
* @module browser
*/
import document from 'global/document';
import window from 'global/window';

16
src/js/utils/buffer.js
View File

@ -1,16 +1,20 @@
/**
* @file buffer.js
* @module buffer
*/
import { createTimeRange } from './time-ranges.js';
/**
* Compute how much your video has been buffered
* Compute the percentage of the media that has been buffered.
*
* @param {Object} Buffered object
* @param {Number} Total duration
* @return {Number} Percent buffered of the total duration
* @private
* @function bufferedPercent
* @param {TimeRange} buffered
* The current `TimeRange` object representing buffered time ranges
*
* @param {number} duration
* Total duration of the media
*
* @return {number}
* Percent buffered of the total duration in decimal form.
*/
export function bufferedPercent(buffered, duration) {
let bufferedDuration = 0;

21
src/js/utils/computed-style.js
View File

@ -1,16 +1,23 @@
/**
* @file computed-style.js
* @module computed-style
*/
import window from 'global/window';
/**
* A safe getComputedStyle with an IE8 fallback.
*
* This is because in Firefox, if the player is loaded in an iframe with `display:none`,
* then `getComputedStyle` returns `null`, so, we do a null-check to make sure
* that the player doesn't break in these cases.
* See https://bugzilla.mozilla.org/show_bug.cgi?id=548397 for more details.
* This is needed because in Firefox, if the player is loaded in an iframe with
* `display:none`, then `getComputedStyle` returns `null`, so, we do a null-check to
* make sure that the player doesn't break in these cases.
*
* @function computedStyle
* @param el the element you want the computed style of
* @param prop the property name you want
* @param {Element} el
* The element you want the computed style of
*
* @param {string} prop
* The property name you want
*
* @see https://bugzilla.mozilla.org/show_bug.cgi?id=548397
*/
export default function computedStyle(el, prop) {
if (!el || !prop) {

18
src/js/utils/fn.js
View File

@ -1,18 +1,24 @@
/**
* @file fn.js
* @module fn
*/
import { newGUID } from './guid.js';
/**
* Bind (a.k.a proxy or Context). A simple method for changing the context of a function
* It also stores a unique id on the function so it can be easily removed from events
* It also stores a unique id on the function so it can be easily removed from events.
*
* @param {Mixed} context
* The object to bind as scope.
*
* @param {Function} fn
* The function to be bound to a scope.
*
* @param {number} [uid]
* An optional unique ID for the function to be set
*
* @param {*} context The object to bind as scope
* @param {Function} fn The function to be bound to a scope
* @param {Number=} uid An optional unique ID for the function to be set
* @return {Function}
* @private
* @method bind
* The new function that will be bound into the context given
*/
export const bind = function(context, fn, uid) {
// Make sure the function has a unique ID

21
src/js/utils/format-time.js
View File

@ -1,15 +1,20 @@
/**
* @file format-time.js
* @module Format-time
*/
/**
* Format seconds as a time string, H:MM:SS or M:SS. Supplying a guide (in seconds)
* will force a number of leading zeros to cover the length of the guide.
*
* Format seconds as a time string, H:MM:SS or M:SS
* Supplying a guide (in seconds) will force a number of leading zeros
* to cover the length of the guide
* @param {number} seconds
* Number of seconds to be turned into a string
*
* @param {Number} seconds Number of seconds to be turned into a string
* @param {Number} guide Number (in seconds) to model the string after
* @return {String} Time formatted as H:MM:SS or M:SS
* @private
* @function formatTime
* @param {number} guide
* Number (in seconds) to model the string after
*
* @return {string}
* Time formatted as H:MM:SS or M:SS
*/
function formatTime(seconds, guide = seconds) {
seconds = seconds < 0 ? 0 : seconds;

12
src/js/utils/guid.js
View File

@ -1,17 +1,19 @@
/**
* @file guid.js
*
* @module guid
*/
/**
* Unique ID for an element or function
* @type {Number}
* @private
*/
let _guid = 1;
/**
* Get the next unique ID
* Get a unique auto-incrementing ID by number that has not been returned before.
*
* @return {String}
* @function newGUID
* @return {number}
* A new unique ID.
*/
export function newGUID() {
return _guid++;

51
src/js/utils/obj.js
View File

@ -1,14 +1,42 @@
/**
* @file obj.js
* @module obj
*/
/**
* @callback obj:EachCallback
*
* @param {Mixed} value
* The current key for the object that is being iterated over.
*
* @param {string} key
* The current key-value for object that is being iterated over
*/
/**
* @callback obj:ReduceCallback
*
* @param {Mixed} accum
* The value that is accumulating over the reduce loop.
*
* @param {Mixed} value
* The current key for the object that is being iterated over.
*
* @param {string} key
* The current key-value for object that is being iterated over
*
* @return {Mixed}
* The new accumulated value.
*/
/**
* Array-like iteration for objects.
*
* @param {Object} object
* @param {Function} fn
* A callback function which is called for each key in the object. It
* receives the value and key as arguments.
* @param {Object} object
* The object to iterate over
*
* @param {obj:EachCallback} fn
* The callback function which is called for each key in the object.
*/
export function each(object, fn) {
Object.keys(object).forEach(key => fn(object[key], key));
@ -17,16 +45,21 @@ export function each(object, fn) {
/**
* Array-like reduce for objects.
*
* @param {Object} object
* @param {Function} fn
* @param {Object} object
* The Object that you want to reduce.
*
* @param {Function} fn
* A callback function which is called for each key in the object. It
* receives the accumulated value and the per-iteration value and key
* as arguments.
* @param {Mixed} [initial = 0]
*
* @param {Mixed} [initial = 0]
* Starting value
*
* @return {Mixed}
* The final accumulated value.
*/
export function reduce(object, fn, initial = 0) {
return Object.keys(object).reduce(
(accum, key) => fn(accum, object[key], key),
initial);
(accum, key) => fn(accum, object[key], key), initial);
}

22
src/js/utils/stylesheet.js
View File

@ -1,5 +1,18 @@
/**
* @file stylesheet.js
* @module stylesheet
*/
import document from 'global/document';
/**
* Create a DOM syle element given a className for it.
*
* @param {string} className
* The className to add to the created style element.
*
* @return {Element}
* The element that was created.
*/
export const createStyleElement = function(className) {
const style = document.createElement('style');
@ -8,6 +21,15 @@ export const createStyleElement = function(className) {
return style;
};
/**
* Add text to a DOM element.
*
* @param {Element} el
* The Element to add text content to.
*
* @param {string} content
* The text to add to the element.
*/
export const setTextContent = function(el, content) {
if (el.styleSheet) {
el.styleSheet.cssText = content;

92
src/js/utils/time-ranges.js
View File

@ -1,11 +1,83 @@
/**
* @file time-ranges.js
* @module time-ranges
*/
import log from './log.js';
/**
* Returns the time for the specified index at the start or end
* of a TimeRange object.
*
* @function time-ranges:indexFunction
*
* @param {number} [index=0]
* The range number to return the time for.
*
* @return {number}
* The time that offset at the specified index.
*
* @depricated index must be set to a value, in the future this will throw an error.
*/
/**
* An object that contains ranges of time for various reasons.
*
* @typedef {Object} TimeRange
*
* @property {number} length
* The number of time ranges represented by this Object
*
* @property {time-ranges:indexFunction} start
* Returns the time offset at which a specified time range begins.
*
* @property {time-ranges:indexFunction} end
* Returns the time offset at which a specified time range begins.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/TimeRanges
*/
/**
* Check if any of the time ranges are over the maximum index.
*
* @param {string} fnName
* The function name to use for logging
*
* @param {number} index
* The index to check
*
* @param {number} maxIndex
* The maximum possible index
*
* @throws {Error} if the timeRanges provided are over the maxIndex
*/
function rangeCheck(fnName, index, maxIndex) {
if (index < 0 || index > maxIndex) {
throw new Error(`Failed to execute '${fnName}' on 'TimeRanges': The index provided (${index}) is greater than or equal to the maximum bound (${maxIndex}).`);
}
}
/**
* Check if any of the time ranges are over the maximum index.
*
* @param {string} fnName
* The function name to use for logging
*
* @param {string} valueIndex
* The proprety that should be used to get the time. should be 'start' or 'end'
*
* @param {Array} ranges
* An array of time ranges
*
* @param {Array} [rangeIndex=0]
* The index to start the search at
*
* @return {number}
* The time that offset at the specified index.
*
*
* @depricated rangeIndex must be set to a value, in the future this will throw an error.
* @throws {Error} if rangeIndex is more than the length of ranges
*/
function getRange(fnName, valueIndex, ranges, rangeIndex) {
if (rangeIndex === undefined) {
log.warn(`DEPRECATED: Function '${fnName}' on 'TimeRanges' called without an index argument.`);
@ -15,6 +87,12 @@ function getRange(fnName, valueIndex, ranges, rangeIndex) {
return ranges[rangeIndex][valueIndex];
}
/**
* Create a time range object givent ranges of time.
*
* @param {Array} [ranges]
* An array of time ranges.
*/
function createTimeRangesObj(ranges) {
if (ranges === undefined || ranges.length === 0) {
return {
@ -35,17 +113,15 @@ function createTimeRangesObj(ranges) {
}
/**
* @file time-ranges.js
* Should create a fake `TimeRange` object which mimics an HTML5 time range instance.
*
* Should create a fake TimeRange object
* Mimics an HTML5 time range instance, which has functions that
* return the start and end times for a range
* TimeRanges are returned by the buffered() method
* @param {number|Array} start
* The start of a single range or an array of ranges
*
* @param {number} end
* The end of a single range.
*
* @param {(Number|Array)} Start of a single range or an array of ranges
* @param {Number} End of a single range
* @private
* @method createTimeRanges
*/
export function createTimeRanges(start, end) {
if (Array.isArray(start)) {

14
src/js/utils/to-title-case.js
View File

@ -1,12 +1,16 @@
/**
* @file to-title-case.js
* @module to-title-case
*/
/**
* Uppercase the first letter of a string.
*
* Uppercase the first letter of a string
* @param {string} string
* String to be uppercased
*
* @param {String} string String to be uppercased
* @return {String}
* @private
* @method toTitleCase
* @return {string}
* The string with an uppercased first letter
*/
function toTitleCase(string) {
if (typeof string !== 'string') {