Player

Player

The Player control interface is used to control playback on the video player.

The following API is asynchronous and is using Promise to return values.
To use this API, you first need to retrieve the player control interface thanks to IDAL.getControlInterfaces().

Methods

addListener(listener): Promise.<boolean>

Attach an event handler to the Player control interface.

Since:
  • firmware v1.08

This method was introduced with firmware version v1.08 to make it possible to run the same code on the player or on a remote browser using IDAL.getRemoteControlInterfaces().
When running on the video player, this method is equivalent to window.addEventListener('idal-player-event', function(e) {}).

Example
var player = ... // Get the Player interface
player.addListener(function(event) {
      // Here the value of event.type is always 'idal-player-event'
      switch (event.detail.type) {
          case 'folder-enter':
              console.log("Enter folder: " + event.detail.folder.name);
              break;

          case 'file-start':
              console.log("File start: " + event.detail.filename);
              break;

          // and so on...
      }
});
Parameters
Name Type Description
listener Listener

The function to run when a player event occurs.
Returns

A promise resolved with a boolean value.

Type
Promise.<boolean>

getAllFolders(): Promise.<Array.<FolderInfo>> | Promise.<ErrorStatus>

Get the list of all the media folders available on the current storage.

Returns

getDuration(): Promise.<number> | Promise.<ErrorStatus>

Get the playback duration.

The returned duration is 0 when the playback is not started.

Returns

  • A promise resolved with the total duration expressed in seconds (decimal number).

    Type
    Promise.<number>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

getFileName(): Promise.<string> | Promise.<ErrorStatus>

Get the name of the file currently playing.

Returns

  • A promise resolved with the filename as a string.

    Type
    Promise.<string>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

getFolderName(): Promise.<string> | Promise.<ErrorStatus>

Get the name of the current folder.

Returns

  • A promise resolved with the folder name as a string.

    Type
    Promise.<string>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

getFolderNumber(): Promise.<number> | Promise.<ErrorStatus>

Get the current folder identifier.

Returns

  • A promise resolved with the folder number (-1 if there is no folder).

    Type
    Promise.<number>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

getMute(): Promise.<boolean> | Promise.<ErrorStatus>

Get the audio mute state.

Returns

  • A promise resolved with the mute state (true = mute).

    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

getPosition(): Promise.<number> | Promise.<ErrorStatus>

Get the playback position.

The returned position is 0 when the playback is not started.

Returns

  • A promise resolved with the current playback position expressed in seconds (decimal number).

    Type
    Promise.<number>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

getRemainingTime(): Promise.<number> | Promise.<ErrorStatus>

Get the remaining playback time.

The returned time is 0 when the playback is not started.

Returns

  • A promise resolved with the remaining time expressed in seconds (decimal number).

    Type
    Promise.<number>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

getState(): Promise.<('stopped'|'paused'|'playing'|'maintenance')> | Promise.<ErrorStatus>

Get the video player state.

Returns

  • A promise resolved with a player state as a string.

    Type
    Promise.<('stopped'|'paused'|'playing'|'maintenance')>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

getStorageDevice(): Promise.<string> | Promise.<ErrorStatus>

Get the name of the current storage device.

Returns

  • A promise resolved with the storage device as a string.

    Type
    Promise.<string>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

getSubtitles(): Promise.<SubtitleInfo> | Promise.<ErrorStatus>

Get subtitles information:

  • the list of subtitle tracks available in the current video file,
  • the currently selected track,
  • the current selection parameters.

Since:
  • firmware v1.08
Returns

getVolume(): Promise.<number> | Promise.<ErrorStatus>

Get the audio volume.

Returns

  • A promise resolved with the audio volume value (integer between 0 and 100).

    Type
    Promise.<number>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

mute(): Promise.<boolean> | Promise.<ErrorStatus>

Mute the audio volume.

Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

nextFile(): Promise.<boolean> | Promise.<ErrorStatus>

Start playing the next file.

The next file is the one following the current file when processing tags on files and folders ([Jxxx], [LOOP]...). The next file may be therefore located in another folder.

Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    • There is no next file.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

nextFolder(): Promise.<boolean> | Promise.<ErrorStatus>

Start playing the next folder.

The next folder is the folder having an number greater than the current folder number.

Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    • There is no next folder.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

pause(): Promise.<boolean> | Promise.<ErrorStatus>

Pause the playback.

This method is relevant when the player is in playing state.

Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    • The player is not in playing state.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

play(): Promise.<boolean> | Promise.<ErrorStatus>

Start the playback.

The playback is started in the current folder. This command is intended to be used after calling stop() or after a pause command.

Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    • There is no audio or video file to resume (stop(). has not been previously called).
    • The player is not in paused state.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

playFolder(folder): Promise.<boolean> | Promise.<ErrorStatus>

Start playing a given folder.

Parameters
Name Type Description
folder number

The folder number.
Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    • The requested folder does not exist.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

playPause(): Promise.<boolean> | Promise.<ErrorStatus>

Pause, resume or start the playback.

If the player is in stopped state, the playback is started as of play().
If the player is in paused state, the playback is resumed as of resume().
If the player in in playing state, the playback is paused as of pause().

Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    • The current state is invalid (nothing to play or pause).
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

previousFile(): Promise.<boolean> | Promise.<ErrorStatus>

Start playing the previous media file.

The previous file is one preceding the current file in the current folder.

Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    • There is no previous file.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

previousFolder(): Promise.<boolean> | Promise.<ErrorStatus>

Start playing the previous folder.

The previous folder is the folder having an id number less than the current folder.

Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    • There is no previous folder.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

removeListener(listener): Promise.<boolean>

Removes an event handler that has been attached to the Player interface.

Since:
  • firmware v1.08
Parameters
Name Type Description
listener Listener

The function previously attached with addListener()
Returns

A promise resolved with a boolean value.

Type
Promise.<boolean>

resume(): Promise.<boolean> | Promise.<ErrorStatus>

Resume the playback.

This method is relevant when the player is in paused state.

Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    • The player is not in paused state.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

seek(position, relativeopt): Promise.<boolean> | Promise.<ErrorStatus>

Seek in the current audio/video file.

Parameters
Name Type Attributes Default Description
position number

The number of milliseconds to seek (can be negative in case of relative seek, positive otherwise)
relative boolean <optional>
 false

Is true when the position is relative to the current position, false when it is absolute.
Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    • The parameters are invalid (invalid absolute position).
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

selectSubtitle(settings): Promise.<boolean> | Promise.<ErrorStatus>

Change the subtitle selection mode.

Since:
  • firmware v1.08

By default, the player select the subtitle tracks as defined by the system settings (preferred languages, track type).
This method makes it possible to override the system settings in order to select a given track, a given language or to disable subtitles. Of course, it is also possible to revert to the default selection mode.

The selected track language is used as a reference to select the subtitles in the subsequent video files.

About next and previous track selection:

  • if there isn't any currently selected track, the first track is selected.
  • it is possible to wrap around to jump from the first track to the last track (and vice versa).
Examples

Select french subtitles

var player = ... // Get the Player interface
player.selectSubtitle({
    selection: "language",
    language: "fra"
});

Select the second subtitle track

var player = ... // Get the Player interface
player.selectSubtitle({
    selection: "index",
    index: 1
});

Select the next subtitle using wrap around

var player = ... // Get the Player interface
player.selectSubtitle({
    selection: "next",
    wrap: true
});

Disable subtitles

var player = ... // Get the Player interface
player.selectSubtitle({
    selection: "none",
});
Parameters
Name Type Description
settings Object

The selection settings.

Properties
Name Type Attributes Default Description
selection 'automatic' | 'none' | 'language' | 'index' | 'id' | 'next' | 'previous'

The selection method to execute.

It must be set to:

  • 'automatic' to let the player select the tracks using the system settings,
  • 'none' to fully disable the subtitles,
  • 'language' to select the tracks based on a given language (requires a language parameter),
  • 'index' to select a track based on its index in the current track list (requires an index parameter),
  • 'id' to select a track based on its identifier in the current track list (requires an id parameter),
  • 'next' to select the next track (wrap parameter optional),
  • 'previous' to select the previous track (wrap parameter optional).
language string <optional>

An ISO 639-1, 639-2 or 639-3 code defining the language to be selected.

Mandatory when selection is 'language'.

The player will select an appropriate track having the given language.
If the current video file does not provide any track for this language, no subtitles are displayed. Subtitles may however be displayed later when playing subsequent video files providing this language...
It is possible to call this method even when the player is in stop mode.
id string <optional>

Track identifier.

Mandatory when selection is 'id'.

The player will select the track identified by id in the current video file, therefore it must be in playing state.
Each subtitle track has its own identifier with its own private syntax. Don't try to craft identifiers nor hardcode them in your code!
You can have a look at Player.getSubtitles() to retrieve the track identifiers.
index number <optional>

Zero-based track index.

Mandatory when selection is 'index'.

The player will select the track having the given index within the track list of the current video file, therefore it must be in playing state.
You can have a look at Player.getSubtitles() to retrieve the track list.
wrap boolean <optional>
 false

Must be true to wrap around.

Can be used when selection is 'next' or 'previous'.
Returns

  • A promise resolved with a boolean.

    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

setVolume(volume, relativeopt): Promise.<boolean> | Promise.<ErrorStatus>

Set the audio volume (absolute or relative).

When the volume is set, the audio mute is automatically disabled.

Parameters
Name Type Attributes Default Description
volume number

The volume level (integer between 0 and 100 for absolute volume, between -100 and 100 for relative volume).
relative boolean <optional>
 false

Whether the volume level is relative to the current volume (increase or decrease volume).
Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    • The volume was already at the minimum and a decrease was requested or an increase was requested but the volume is at its highest level.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

stop(): Promise.<boolean> | Promise.<ErrorStatus>

Stop the current playback.

This method is relevant when the player is in playing or paused state. The current file and folder are saved to makes it possible to start playing again using play() or playPause().

Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    • The player is not in paused or playing state.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

toggleMute(): Promise.<boolean> | Promise.<ErrorStatus>

Mute or unmute the audio volume.

Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

togglePause(): Promise.<boolean> | Promise.<ErrorStatus>

Pause or resume the playback.

This method is relevant when the player is in paused or playing state.

Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    • The player is not in paused or playing state.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

unmute(): Promise.<boolean> | Promise.<ErrorStatus>

Unmute the audio volume.

Returns

  • A promise resolved with a boolean value that may be false in the following cases:

    • The operation is not allowed.
    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

Type Definitions

FolderInfo

A FolderInfo gives contains folder details.

Properties
Name Type Description
number number

The folder number (identifier).
name string

The folder name.

SubtitleInfo

A SubtitleInfo contains information about the subtitle selection.

Properties
Name Type Description
tracks Array.<Object>

The available subtitle tracks.

Properties
Name Type Attributes Default Description
language string

An ISO 639 language code.
id string

The track identifier.
default boolean <optional>
 false

Is true when the track is a default track.
forced boolean <optional>
 false

Is true when the track is a forced track.
current number

Index of the selected track or -1 when no track selected.
override Object

Manual selection settings.

Properties
Name Type Description
enabled boolean

Is true when the system settings for track selection are overridden (the automatic selection is disabled).
language string

Is the selected ISO 639 language code, can be null when subtitles are disabled.

It is possible to retrieve SubtitleInfo using Player.getSubtitles().

Example

Manual subtitle selection has been requested to select french subtitles, therefore the track at index 1 is selected.

{
    "override": {
        "enabled": true,
        "language": "fra"
    },
    "current": 1,
    "tracks": [
        {
            "id": "id-0",
            "language": "eng",
            "default": true
        },
        {
            "id": "id-1",
            "language": "fra"
        }
    ]
}

Events

FileEndEvent

FileEndEvent are fired when the video player stops playing a file.

Tutorials:
Properties
Name Type Description
type 'idal-player-event'

The player event type.
detail Object
Properties
Name Type Description
type 'file-end'

The file end event type.
filename string

The name of the file.
folder FolderInfo

The folder containing the file.

This event shall be registered using Player.addListener().
It can also be registered using window.addEventListener() as defined by the DOM specification.
if you plan to use the remote control interfaces, the later method must be avoided.

Type
Example
// Preferred method: registration using Player.addListener()
var player = ... // Get the Player control interface
player.addListener(function(e) {
      if (e.detail.type == 'file-end') {
          // Do something useful...
          console.log("File end: " + e.detail.filename);
      }
});

FileStartEvent

FileStartEvent are fired when the video player starts playing a file.

Tutorials:
Properties
Name Type Description
type 'idal-player-event'

The player event type.
detail Object
Properties
Name Type Description
type 'file-start'

The file start event type.
filename string

The name of the file.
folder FolderInfo

The folder containing the file.

This event shall be registered using Player.addListener().
It can also be registered using window.addEventListener() as defined by the DOM specification.
if you plan to use the remote control interfaces, the later method must be avoided.

Type
Example
// Preferred method: registration using Player.addListener()
var player = ... // Get the Player control interface
player.addListener(function(e) {
      if (e.detail.type == 'file-start') {
          // Do something useful...
          console.log("File start: " + e.detail.filename);
      }
});

FolderEnterEvent

FolderEnterEvent are fired when the video player start playing a folder.

Tutorials:
Properties
Name Type Description
type 'idal-player-event'

The player event type.
detail Object
Properties
Name Type Description
type 'folder-enter'

The folder enter event type.
folder FolderInfo

The entered folder.

This event shall be registered using Player.addListener().
It can also be registered using window.addEventListener() as defined by the DOM specification.
if you plan to use the remote control interfaces, the later method must be avoided.

Type
Example
// Preferred method: registration using Player.addListener()
var player = ... // Get the Player control interface
player.addListener(function(e) {
      if (e.detail.type == 'folder-enter') {
          // Do something useful...
          console.log("Enter folder: " + e.detail.folder.name);
      }
});

FolderLeaveEvent

FolderLeaveEvent are fired when the video player leaves a folder.

Tutorials:
Properties
Name Type Description
type 'idal-player-event'

The player event type.
detail Object
Properties
Name Type Description
type 'folder-leave'

The folder leave event type.
folder FolderInfo

The leaved folder.

This event shall be registered using Player.addListener().
It can also be registered using window.addEventListener() as defined by the DOM specification.
if you plan to use the remote control interfaces, the later method must be avoided.

Type
Example
// Preferred method: registration using Player.addListener()
var player = ... // Get the Player control interface
player.addListener(function(e) {
      if (e.detail.type == 'folder-leave') {
          // Do something useful...
          console.log("Leave folder: " + e.detail.folder.name);
      }
});

MuteChangeEvent

MuteChangeEvent are fired when the audio mute is modified.

Tutorials:
Properties
Name Type Description
type 'idal-player-event'

The player event type.
detail Object
Properties
Name Type Description
type 'mute-change'

The mute change event type.
mute boolean

Whether the audio mute is activated.

This event shall be registered using Player.addListener().
It can also be registered using window.addEventListener() as defined by the DOM specification.
if you plan to use the remote control interfaces, the later method must be avoided.

Type
Example
// Preferred method: registration using Player.addListener()
var player = ... // Get the Player control interface
player.addListener(function(e) {
      if (e.detail.type == 'mute-change') {
          // Do something useful...
          console.log("Mute: " + e.detail.mute);
      }
});

StateChangeEvent

StateChangeEvent are fired when the playback engine state changes.

Since:
  • firmware v1.08
Tutorials:
Properties
Name Type Description
type 'idal-player-event'

The player event type.
detail Object
Properties
Name Type Description
type 'state-change'

State change event type.
state 'playing' | 'paused' | 'stopped' | 'maintenance'

Playback engine state.

This event shall be registered using Player.addListener().
It can also be registered using window.addEventListener() as defined by the DOM specification.
if you plan to use the remote control interfaces, the later method must be avoided.

Type
Example
// Preferred method: registration using Player.addListener()
var player = ... // Get the Player control interface
player.addListener(function(e) {
      if (e.detail.type == 'state-change') {
          console.log("New state: " + e.detail.state);
      }
});

TimeUpdateEvent

TimeUpdateEvent are fired periodically to indicate the playback position.

Since:
  • firmware v1.08
Tutorials:
Properties
Name Type Description
type 'idal-player-event'

The player event type.
detail Object
Properties
Name Type Description
type 'time-update'

Time update event type.
position number

Position in the file playback (seconds).
duration number

Duration of the file (seconds).

This event shall be registered using Player.addListener().
It can also be registered using window.addEventListener() as defined by the DOM specification.
if you plan to use the remote control interfaces, the later method must be avoided.

Type
Example
// Preferred method: registration using Player.addListener()
var player = ... // Get the Player control interface
player.addListener(function(e) {
      if (e.detail.type == 'time-update') {
          console.log("Position: " + e.detail.position + " / " + e.detail.duration);
      }
});

TrackSelectionEvent

TrackSelectionEvent are received when the video player selects the audio, video or subtitle tracks.
It happen at the beginning of the media playback or when a track is explicitly selected, for example after changing the subtitle language.

For now, this event only contains the subtitle track information.

Since:
  • firmware v1.08
Tutorials:
Properties
Name Type Description
type 'idal-player-event'

The player event type.
detail Object
Properties
Name Type Attributes Description
type 'track-selection'

The track selection event type.
subtitle Object <optional>

The selected subtitle track information, can be null.

Properties
Name Type Attributes Default Description
id string

The track identifier.
language string

An ISO 639-1, 639-2 or 639-3 language code.
default boolean <optional>
 false

Is true when the track is a default track.
forced boolean <optional>
 false

Is true when the track is a forced track.

This event shall be registered using Player.addListener().
It can also be registered using window.addEventListener() as defined by the DOM specification.
if you plan to use the remote control interfaces, the later method must be avoided.

Type
Example
// Preferred method: registration using Player.addListener()
var player = ... // Get the Player control interface
player.addListener(function(e) {
      if (e.detail.type == 'track-selection') {
          console.log("Subtitle: " + JSON.stringify(e.detail.subtitle));
      }
});

VolumeChangeEvent

VolumeChangeEvent are fired when the audio volume is modified.

Tutorials:
Properties
Name Type Description
type 'idal-player-event'

The player event type.
detail Object
Properties
Name Type Description
type 'volume-change'

The volume change event type.
volume number

The audio volume value.

This event shall be registered using Player.addListener().
It can also be registered using window.addEventListener() as defined by the DOM specification.
if you plan to use the remote control interfaces, the later method must be avoided.

Type
Example
// Preferred method: registration using Player.addListener()
var player = ... // Get the Player control interface
player.addListener(function(e) {
      if (e.detail.type == 'volume-change') {
          // Do something useful...
          console.log("Volume: " + e.detail.volume);
      }
});