Class: SRGLetterbox

SRGLetterbox(options)

SRGLetterbox

The SRGLetterbox class provides a simple way to create a web player.

Constructor

new SRGLetterbox(options)

Parameters:
Name Type Description
options LetterboxConfiguration

Letterbox configuration object. The parameter object is merged with the default options.

Properties
Name Type Description
container String

query selector of the HTMLElement where the player will be created.
Source:
See:
  • SRGLetterbox.LETTERBOX_DEFAULT_OPTIONS and its documentation for available options.

Members

(static) BUILD

Object with detailed build information.

Source:

(static) LETTERBOX_DEFAULT_OPTIONS

Letterbox default options. Those options can be overridden in the constructor.

Source:

(static) LONG_VERSION

Long string with detailed version and build information.

Source:

(static) srgLetterboxComponents

Source:

(static) supportedDevices

SupportedDevices allows to detect browser's version and some features compatibilities.

Source:

(static) VERSION

Represents the Letterbox version.

Source:

Methods

(static) addInstance()

Add Letterbox instance.

Source:

(static) getInstances() → {Array}

Get Letterbox instances.

Source:
Returns:

array of SRGLetterbox instances

Type
Array

(static) removeInstance(instance)

Remove a specific Letterbox instance.

Parameters:
Name Type Description
instance SRGLetterbox
Source:

aspectRatio(ratioopt) → {string|undefined}

A getter/setter for the Player's aspect ratio.

Parameters:
Name Type Attributes Description
ratio string <optional>

The value to set the Player's aspect ratio to.
Source:
See:
Returns:
  • The current aspect ratio of the Player when getting. - undefined when setting
Type
string | undefined

audioTrackLanguage(value) → {object}

Get or set the audio track language. The value should be the language code of the audio track or an object containing at least the language property

Parameters:
Name Type Description
value undefined | string | object
Source:
Returns:
Type
object
Examples
audioTrackLanguage()
audioTrackLanguage('de')
audioTrackLanguage({language: 'de'})
audioTrackLanguage({language: 'de', description: true})
audioTrackLanguage({language: 'de', description: false})

audioTracks(safety) → {AudioTrackList}

Get the AudioTrackList.

Parameters:
Name Type Description
safety *

Anything passed in to silence the warning.
Source:
See:
Returns:

The current audio track list.

Type
AudioTrackList

autoplay(value)

Get or set the autoplay option.

  • true: autoplay using the browser behavior
  • false: do not autoplay
  • 'play': call play() on every loadstart
  • 'muted': call muted() then play() on every loadstart
  • 'any': call play() on every loadstart. if that fails call muted() then play().
  • *: values other than those listed here will be set autoplay to true
Parameters:
Name Type Description
value boolean | string
Source:
See:

currentDate(dateopt) → {Date}

Get or set the current date.

It allows to seek in a DVR live stream using a date as an absolute position.

Parameters:
Name Type Attributes Description
date Date <optional>

The date to seek to
Source:
Returns:

The current date when getting

Type
Date

currentTime(secondsopt) → {number}

Get or set the current time (in seconds)

Parameters:
Name Type Attributes Description
seconds number | string <optional>

The time to seek to in seconds
Source:
Returns:

The current time in seconds when getting

Type
number

disablePictureInPicture(value)

Disable Picture-in-Picture mode.

FYI: Firefox doesn't provide any PiP API at the moment.

Parameters:
Name Type Description
value boolean
  • true will disable Picture-in-Picture mode - false will enable Picture-in-Picture mode
Source:

dispose()

Destroys the video player and does any necessary cleanup. This is especially helpful if you are dynamically adding and removing videos to/from the DOM.

Source:
See:
Fires:
  • videojs#event:dispose

duration()

TODO: Investigate the use case : Why do we return duration from mediacomposition

Source:

error()

Get the value of the error from the media element. error indicates any MediaError that may have occurred during playback. If error returns null there is no current error.

FYI: video.js error method allows a MediaError object as a parameter, Letterbox don't.

Source:
See:
Returns:

MediaError | null

exitFullscreen()

Return the video to its normal size after having been in full screen mode

Source:
Fires:
  • Player#event:fullscreenchange

exitPictureInPicture() → {Promise}

Exit Picture-in-Picture mode.

FYI: Firefox doesn't provide any PiP API at the moment.

Source:
See:
Fires:
  • Player#event:leavepictureinpicture
Returns:

A promise.

Type
Promise

fill(boolopt) → {boolean|undefined}

A getter/setter/toggler for the vjs-fill className on the Player.

Turning this on will turn off fluid mode.

By default Letterbox uses the fill mode. This means the player will take all the available space in his container.

Parameters:
Name Type Attributes Description
bool boolean <optional>
  • A value of true adds the class. - A value of false removes the class. - No value will be a getter.
Source:
See:
Returns:
  • The value of fluid when getting. - undefined when setting.
Type
boolean | undefined

fluid(boolopt) → {boolean|undefined}

A getter/setter/toggler for the vjs-fluid className on the Player.

Turning this on will turn off fill mode.

Parameters:
Name Type Attributes Description
bool boolean <optional>
  • A value of true adds the class. - A value of false removes the class. - No value will be a getter.
Source:
See:
Returns:
  • The value of fluid when getting. - undefined when setting.
Type
boolean | undefined

getConfiguration() → {PlayerConfiguration}

Get the current player configuration object

Source:
See:
  • SRGLetterboxConfiguration.getPlayerConfiguration
Returns:

SRG player configuration

Type
PlayerConfiguration

getDebugInformation() → {Object}

Get the debug information.

Source:
Returns:
Type
Object

getMediaComposition() → {MediaComposition}

Get the currently playing Media Composition.

Source:
Returns:
Type
MediaComposition

getPlaybackSettings() → {Object}

Get the current playback settings.

Source:
Returns:

TODO: Check playbackSettings that shouldn't be merged in the mediaComposition in the middleware

Type
Object

getUrn() → {String}

Source:
Returns:

currently playing URN

Type
String

hasSubdivisions() → {Boolean}

Check if the MediaComposition has subdivisions.

Source:
Returns:
Type
Boolean

isFullscreen() → {Boolean}

Check if the player is in fullscreen mode or tell the player that it is or is not in fullscreen mode.

Source:
See:
Returns:
Type
Boolean

isInPictureInPicture(isPiPopt) → {boolean}

Check if the player is in Picture-in-Picture mode or tell the player that it is or is not in Picture-in-Picture mode.

FYI: Firefox doesn't provide any PiP API at the moment.

Parameters:
Name Type Attributes Description
isPiP boolean <optional>

Set the players current Picture-in-Picture state
Source:
Returns:
  • true if Picture-in-Picture is on and getting - false if Picture-in-Picture is off and getting
Type
boolean

loadMediaComposition(mediaComposition, param1)

Load a media provided as a mediacomposition.

Parameters:
Name Type Description
mediaComposition Object

data or mediaComposition object
param1 Object
Properties
Name Type Attributes Description
pendingSeek Number <optional>

position to play at in seconds or undefined to play at stream default position
playbackSettings Object <optional>

options to be stored with the playback context, can be used for application specific information they can be read back in getPlaybackSettings
autoplay boolean | string <optional>

value
Source:
See:
  • autoplay autoplay value
  • getPlaybackSettings
  • getMediaComposition

loadUrn(urn, param1)

Load an URN.

Parameters:
Name Type Description
urn String

string
param1 Object
Properties
Name Type Attributes Default Description
pendingSeek Number <optional>

position to play at in seconds or undefined to play at stream default position
playbackSettings Object <optional>

options to be stored with the playback context, can be used for application specific information they can be read back in getPlaybackSettings
autoplay boolean | string <optional>

value
standalone bolean <optional>
 false

allow to switch between onlyChapters true/false. The default value is false.
Source:
See:
  • autoplay autoplay value
  • getPlaybackSettings
  • getMediaComposition

loop(valueopt) → {boolean}

Get or set the loop attribute on the video element.

Parameters:
Name Type Attributes Description
value boolean <optional>
  • true means that we should loop the video - false means that we should not loop the video
Source:
See:
Returns:

The current value of loop when getting

Type
boolean

muted(mutedopt) → {boolean}

Get the current muted state, or turn mute on or off

Parameters:
Name Type Attributes Description
muted boolean <optional>
  • true to mute - false to unmute
Source:
See:
Returns:
  • true if mute is on and getting - false if mute is off and getting
Type
boolean

off(targetOrTypeopt, typeOrListeneropt, listeneropt)

Removes listener(s) from event(s) on an evented object.

Parameters:
Name Type Attributes Description
targetOrType string | Array | Element | Object <optional>

If this is a string or array, it represents the event type(s).

    Another evented object can be passed here instead, in which case
    ALL 3 arguments are _required_.
typeOrListener string | Array | function <optional>

If the first argument was a string or array, this may be the listener function. Otherwise, this is a string or array of event type(s).
listener function <optional>

If the first argument was another evented object, this will be the listener function; otherwise, all listeners bound to the event type(s) will be removed.
Source:
See:

on(targetOrType, typeOrListener, listeneropt)

Add a listener to an event (or events) on this object or another evented object.

Parameters:
Name Type Attributes Description
targetOrType string | Array | Element | Object

If this is a string or array, it represents the event type(s) that will trigger the listener.

    Another evented object can be passed here instead, which will
    cause the listener to listen for events on _that_ object.

    In either case, the listener's `this` value will be bound to
    this object.
typeOrListener string | Array | function

If the first argument was a string or array, this should be the listener function. Otherwise, this is a string or array of event type(s).
listener function <optional>

If the first argument was another evented object, this will be the listener function.
Source:
See:

one(targetOrType, typeOrListener, listeneropt)

Add a listener to an event (or events) on this object or another evented object. The listener will be called once per event and then removed.

Parameters:
Name Type Attributes Description
targetOrType string | Array | Element | Object

If this is a string or array, it represents the event type(s) that will trigger the listener.

    Another evented object can be passed here instead, which will
    cause the listener to listen for events on _that_ object.

    In either case, the listener's `this` value will be bound to
    this object.
typeOrListener string | Array | function

If the first argument was a string or array, this should be the listener function. Otherwise, this is a string or array of event type(s).
listener function <optional>

If the first argument was another evented object, this will be the listener function.
Source:
See:

pause()

Pause the video playback.

Source:
See:

paused() → {Boolean}

Check if the player is paused.

Source:
See:
Returns:
Type
Boolean

play() → {Promise|undefined}

Attempt to begin playback.

Source:
See:
Returns:
Type
Promise | undefined

playbackRate(rateopt) → {Number}

Gets or sets the current playback rate. A playback rate of 1.0 represents normal speed and 0.5 would indicate half-speed playback, for instance.

Parameters:
Name Type Description
rateopt Number

New playback rate to set.
Source:
See:
Returns:

The current playback rate when getting or 1.0

Type
Number

requestFullscreen(fullscreenOptionsopt)

Increase the size of the video to full screen In some browsers, full screen is not supported natively, so it enters "full window mode", where the video fills the browser window. In browsers and devices that support native full screen, sometimes the browser's default controls will be shown, and not the Video.js custom skin. This includes most mobile devices (iOS, Android) and older versions of Safari.

FYI: Be aware of the potential error "Request for fullscreen was denied because Element.requestFullscreen() was not called from inside a short running user-generated event handler."

Parameters:
Name Type Attributes Description
fullscreenOptions Object <optional>

Override the player fullscreen options
Source:
See:
Fires:
  • Player#event:fullscreenchange

requestPictureInPicture() → {Promise}

Create a floating video window always on top of other windows so that users may continue consuming media while they interact with other content sites, or applications on their device.

FYI: Firefox doesn't provide any PiP API at the moment.

Source:
See:
Fires:
  • Player#event:enterpictureinpicture
Returns:

A promise with a Picture-in-Picture window.

Type
Promise

restart(autoplay)

Restart the playback session.

Parameters:
Name Type Default Description
autoplay true

autoplay property
Source:
See:
  • autoplay

switchToUrn(urn)

Switch URN. Play a different URN in the same context.

  • Switch to segment if urn is within segment list of the current mediacomposition (e.g.: full DVR highlight or live). Will start at the beginning of the segment, or at the edge of live for live.
  • Switch to chapter if urn is within chapter list of the current mediacomposition (e.g.: limited DVR highlight or live). Will start at the beginning of the segment, or at the edge of live for live.

This will start playing if player is not currently playing.

Parameters:
Name Type Description
urn String

to play
Source:

textTrackLanguage(value) → {object}

Get or set the text track language. The value should be the language code of the text track Or an object containing at least the language property

Parameters:
Name Type Description
value undefined | string | object
Source:
Returns:
Type
object
Examples
textTrackLanguage()
textTrackLanguage('de')
textTrackLanguage({language: 'de'})
textTrackLanguage({language: 'de', caption: true})
textTrackLanguage({language: 'de', caption: false})

textTracks(safety) → {TextTrackList}

Get the TextTrackList.

Parameters:
Name Type Description
safety *

Anything passed in to silence the warning.
Source:
See:
Returns:

The current text track list.

Type
TextTrackList
Example
//Allows to filter the metadata type tracks
Array.from(letterboxInstance.textTracks()).filter(({kind}) => kind !== 'metadata');

textTrackSizeLevel(sizeLevel) → {Number|undefined}

Get or set the text track font size.

Parameters:
Name Type Description
sizeLevel Number

is a size level between 1 and 8.
Source:
Returns:

The font size in percent.

Type
Number | undefined

trigger(event, hashopt) → {boolean}

Fire an event on this evented object, causing its listeners to be called.

Parameters:
Name Type Attributes Description
event string | Object

An event type or an object with a type property.
hash Object <optional>

An additional object to pass along to listeners.
Source:
See:
Returns:

Whether or not the default behavior was prevented.

Type
boolean

updateConfiguration(configuration)

Update the current player configration object.

Parameters:
Name Type Description
configuration object
Source:
Examples
// Set the continuousPlayback with a default value set to true and disable the local storage.
letterboxInstance.updateConfiguration({
   continuousPlayback : {
     default: true,
     storage : false,
   }
});
// Set the continuousPlayback with a default value set to false and enable the local storage.
letterboxInstance.updateConfiguration({
   continuousPlayback : {
     default: false,
     storage : true,
   }
});
// Activates the continuousPlayback but removes the UI component so that the user can't change it
letterboxInstance.updateConfiguration({
   continuousPlayback : true
});

volume(percentAsDecimalopt) → {number}

Get or set the current volume of the media

Parameters:
Name Type Attributes Description
percentAsDecimal number <optional>

The new volume as a decimal percent: - 0 is muted/0%/off - 1.0 is 100%/full - 0.5 is half volume or 50%
Source:
See:
Returns:

The current volume as a percent when getting

Type
number

Events

events

Aggregates all available event properties

Type:
  • Object
Source:
See:

playerEvents

Standard player events.

Type:
  • Object
Source:
See:

srgEvents

SRG events.

Type:
  • Object
Source:
See:

videojsEvents

Video.js events.

FYI: Not all Video.js are exposed.

Type:
  • Object
Source:
See: