Player

Player

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

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

Methods

getAllFolders() → {Promise.<Array.<Player~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>

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>

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>

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.

Events

FileEndEvent

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

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

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

The file end event type.
filename string

The name of the file.
folder Player~FolderInfo

The folder containing the file.

This event shall be registered using window.addEventListener() as defined by the DOM specification.

Type:
Example
window.addEventListener('idal-player-event', 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.

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

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

The file start event type.
filename string

The name of the file.
folder Player~FolderInfo

The folder containing the file.

This event shall be registered using window.addEventListener() as defined by the DOM specification.

Type:
Example
window.addEventListener('idal-player-event', 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.

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

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

The folder enter event type.
folder Player~FolderInfo

The entered folder.

This event shall be registered using window.addEventListener() as defined by the DOM specification.

Type:
Example
window.addEventListener('idal-player-event', 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.

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

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

The folder leave event type.
folder Player~FolderInfo

The leaved folder.

This event shall be registered using window.addEventListener() as defined by the DOM specification.

Type:
Example
window.addEventListener('idal-player-event', 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.

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

The custom 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 window.addEventListener() as defined by the DOM specification.

Type:
Example
window.addEventListener('idal-player-event', function(e) {
      if (e.detail.type == 'mute-change') {
          // Do something useful...
          console.log("Mute: " + e.detail.mute);
      }
});

VolumeChangeEvent

VolumeChangeEvent are fired when the audio volume is modified.

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

The custom 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 window.addEventListener() as defined by the DOM specification.

Type:
Example
window.addEventListener('idal-player-event', function(e) {
      if (e.detail.type == 'volume-change') {
          // Do something useful...
          console.log("Volume: " + e.detail.volume);
      }
});