# MediaPlayer : Multi Media player

This module provides multimedia player functionality. This player supports a variety of multimedia formats:

Video media format: MP4, MKV, FLV, TS, ...
Image format: BMP, JPEG, PNG, HEIF, AVIF, TIFF, GIF, WebP, HDR, ...
Audio media format: MP3, MP4, M4A, FLAC, AIFF, AC3, AAC, OGG, APE, WAV, WMA, TS, OPUS, AMR, ...
Video codec: MPEG-4, AVC/H.264, HEVC/H.265, VP8, VP9, ...
Audio codec: MP3, AC3, VORBIS, FLAC, AAC, APE, WAV, WMA, OPUS, AMR, ...
Subtitle codec: LRC, ASS, ...

This module is available in EdgerOS 2.2.1 and above.

User can use the following code to import the MediaPlayer module.

var MediaPlayer = require('mediaplayer');

EdgerOS apps needs permission.display permission to use the printer. For details, please refer to permission.

# Support

The following shows MediaPlayer module APIs available for each permissions.

# MediaPlayer Class

# new MediaPlayer()

• Returns: {Player} MediaPlayer object.

Create a new MediaPlayer object.

var player = new MediaPlayer();

# MediaPlayer Object

# async player.setDisplay(channel[, canvasFixed])

• channel {Integer} Display channel. For related introduction, please refer to Display.
• canvasFixed {Boolean} Whether to use 1080P fixed virtual coordinates when drawing information. default: false.

Set the display channel for this player. Before loading media files, this function should be called first. If canvasFixed is true, it means that the additional information canvas uses 1920 X 1080 size coordinates for drawing, otherwise the current monitor size coordinates will be used.

The display channel is only allowed to be set once. After setting the display channel, the audio device id will be automatically set to the same value as the display channel.

await player.setDisplay(0);

When this function is called, this player will open the specified display channel until this player destroyed.

# async player.destroy()

Destroy the current player, this player will no longer occupy the display channel.

# player.state()

• Returns: {Integer} The state of this player.

Get the state of the current player. Possible state are as follows:

await player.pause();
console.log(player.state() === MediaPlayer.PAUSED); // true
await player.play();
console.log(player.state() === MediaPlayer.PLAYING); // true

# async player.open(url)

• url {String} Media source URL.

Open a specified media source. Supported protocols include:

// Open local file
await player.open('file://./demo.mp4');

// Open internet resource
await player.open('http://www.example.com/demo.mp4');

// Open internet resource with secure link (TLS)
await player.open('https://www.example.com/demo.mp4');

After normal opening, the state of this player is MediaPlayer.PAUSED.

# async player.open(source)

• source {Object} Media source.

Open a specified media source. The source object contains the following properties:

• video {Object} Video media source object. Optional.
• audio {Object} Audio media source object. Optional.
• subtitle {Object} Subtitle media source object. Optional.

Members video and audio cannot be empty at the same time. The video, audio, subtitle object contains the following members:

• url {String} The url of media source.
• type {String} The data type of media source. Optional.
• size {Integer} The size of media source data. Optional.
• opts {Object} The open options of media source. Optional.
  • timeout {Integer} Open timeout time, unit is milliseconds. Optional.
  • rtsptp {String} The transport protocol of RTSP, tcp or udp. Optional.
  • persistent {Boolean} Whether to use HTTP persistent links. Optional.
  • headers {Object} HTTP request headers. Optional.
• crypto {Object} The decrypt options of media source. Optional.
  • key {Buffer | String} The key of decrypt algorithm. Optional.
  • iv {Buffer | String} The iv of decrypt algorithm. Optional.
• tls TLS connect options.
  • rejectUnauthorized {Boolean} Whether the server certificate should be verified against the list of supplied CAs. default: false.
  • server Verify against a specific hostname. Optional.
  • ca CA certificate file path. Optional.
  • cert Private certificate file path. Optional.
  • key Private key file path. Optional.

If you use the ecache:// protocol, you need to manually fill in the media data. At this time, type and size must exist. The type can be:

// Open internet resource with local separate subtitle resource
await player.open({
  video: {
    url: 'http://www.example.com/demo.m3u8'
  },
  subtitle: {
    url: 'file://./local.ass'
  }
});

// Open MP3
await player.open({
  video: {
    url: 'http://www.example.com/cover.png'
  },
  audio: {
    url: 'http://www.example.com/demo.mp3'
  },
  subtitle: {
    url: 'http://www.example.com/lyrics.lrc'
  }
});

The opts.headers can define the http headers that need to be added to HTTP request:

await player.open({
  video: {
    url: 'http://www.example.com/demo.m3u8'.
    opts: {
      headers: { 'User-Agent': 'MediaPlayer/1.0.1 EdgerOS' }
    }
  }
});

If the multimedia resource is an encrypted resource, you can specify crypto for decryption.

Each resource link can specify secure connection certificate information. If not specified, the EdgerOS system default configuration will be used. The tls.ca can be used to add a specified CA certificate.

If tls.server is specified, tls.server will be used as hostname to verify the server certificate. Otherwise, the hostname specified by the URL will be used to verify the server certificate.

Client tls.cert and tls.key can be used for TLS two-way security verification.

// Open internet resource with secure link (TLS)
await player.open({
  video: {
    url: 'http://www.example.com/demo.m3u8',
    tls: { ca: './ca.cert' }
  }
});

# player.info()

• Returns: {Object} The information of media source which has been opened.

Get the information of media source which has been opened. The returns object contains the following members:

• duration {Integer} Media max durations, unit in milliseconds.
• video {Array} Video track information array.
• audio {Array} Audio track information array.
• subtitle {Array} Subtitle track information array.
• chapter {Array} Chapter information array.

The video track information object contains the following members:

• id {Integer} The id of video track.
• duration {Integer} Media durations, unit in milliseconds.
• codec {String} The codec name of video track, such as h264.
• lang {String} The language of video track.
• title {String} The title of video track.
• bitrate {Integer} The bitrate of video track, unit in Kbits/S.
• w {Integer} The width of video frame of video track.
• h {Integer} The height of video frame of video track.
• fps {Number} The fps of video frame of video track.

The audio track information object contains the following members:

• id {Integer} The id of audio track.
• duration {Integer} Media durations, unit in milliseconds.
• codec {String} The codec name of audio track, such as aac.
• lang {String} The language name of audio track.
• title {String} The title of audio track.
• bitrate {Integer} The bitrate of audio track, unit in Kbits/S.
• sampleRate {Integer} The sample rate of audio track, such as 44100.
• sampleBits {Integer} The sample bits of audio track, such as 16.
• channels {Integer} The channel number of audio track, such as 2.
• channelLayout {String} The channel layout of audio track, such as stereo.

channelLayout is a string, can be:

The subtitle track information object contains the following members:

• id {Integer} The id of subtitle track.
• duration {Integer} Media durations, unit in milliseconds.
• codec {String} The codec name of subtitle track, such as ass.
• lang {String} The language name of subtitle track.
• title {String} The title of subtitle track.
• bitrate {Integer} The bitrate of subtitle track, unit in Kbits/S.
• w {Integer} The width of canvas of subtitle track, only valid for graphic subtitles.
• h {Integer} The height of canvas of subtitle track. only valid for graphic subtitles.

The video, audio and subtitle track information object all have the following information:

• author {String} Author.
• album {String} Album.
• genre {String} Genre.
• composer {String} Composer.
• copyright {String} Copyright.
• comment {String} Comment.

The chapter information object contains the following members:

• id {Integer} The id of chapter.
• start {Integer} The start time of chapter, unit in milliseconds.
• end {Integer} The end time of chapter, unit in milliseconds.

duration is 0 which means player cannot obtain, for example it might be a live stream or picture.

console.log(JSON.stringify(player.info()));

# async player.close()

Close currently opened multimedia resources.

if (player.state() !== MediaPlayer.CLOSED) {
  await player.close();
}

# async player.play()

Play the currently opened multimedia resource.

# async player.pause()

Pause the currently playing multimedia resource.

# player.position()

• Returns: {Integer} The current position of media source, unit in milliseconds.

Get the position of the currently playing multimedia resource.

# async player.seek(position)

• position {Integer} The position of media source, unit in milliseconds.

Set the playback position of the current multimedia resource. This operation can be performed in the pause state and will not change the player state. If the seek position exceeds the media length, the actual set position is the end of the media resource.

// Go forward 15s
await player.seek(player.position() + 15000);

# async player.step()

• Returns: {Integer} The current position of media source, unit in milliseconds.

Step to the next display frame of media source.

The player.step() function is usually used to display pictures, because after opening the picture media source, the player is in the MediaPlayer.PAUSED state and will not display any picture. After calling the player.step(), the next frame of picture will be displayed, and remain in MediaPlayer.PAUSED state.

await player.open('file://./demo.mp4');
// Show the first frame of image.
await player.step();

# async player.hide(enable)

• enable {String} Whether to set to hidden mode.

Set whether it is hidden mode. You can use player.capture() to take screenshots in hidden mode. The initial hidden state is false.

# async player.capture()

• Returns: {Buffer} Screenshot content in JPEG format.

Currently displaying screenshots.

const screenshot = await player.capture();
fs.writeFile('./screenshot.jpg', screenshot);

# player.speed

• {Number} Range: 0.5 to 2.0, small values mean slow speed, 1 is normal speed.

This is a setter & getter function, used to set or get the current player play speed. Default speed is 1.

player.speed = 1.5;

# player.mute

• {Boolean} Whether the current player is in mute mode.

This is a setter & getter function, used to set or get the current player mute mode. Default mute is false.

# player.volume

• {Integer} Range: 0 to 100, small values mean low volume.

This is a setter & getter function, used to set or get the current player volume. Default volume is 100.

# player.isHidden()

• Returns: {Boolean} Whether it is currently in hidden mode.

Get whether the current mode is hidden.

# async player.switchVideoTrack(videoTrackId)

• videoTrackId {Integer} The id of video track.

Switch the video track of media source. The id of video track can be obtained through the player.info() function. Switch video tracks do not changing position.

# player.currentVideoTrack()

• Returns: {Integer} The id of current video track, -1 mean haven't video track.

Get the current video track of this player.

# async player.switchAudioTrack(audioTrackId)

• audioTrackId {Integer} The id of audio track.

Switch the audio track of media source. The id of audio track can be obtained through the player.info() function. Switch audio tracks do not changing position.

# player.currentAudioTrack()

• Returns: {Integer} The id of current audio track, -1 mean haven't audio track.

Get the current audio track of this player.

# async player.switchSubtitle(subtitleId)

• subtitleId {Integer} The id of subtitle track, -1 mean close subtitle.

Switch the subtitle track of media source. The id of subtitle track can be obtained through the player.info() function. Switch subtitle tracks do not changing position.

# player.currentSubtitle()

• Returns: {Integer} The id of current subtitle track, -1 mean subtitle track closed.

Get the id of current subtitle track.

# async player.addAssStyle(style)

• style {Object | String} ASS style object or string.

Add ASS style to this media player. ASS/SSA (Advanced Substation Alpha/Substation Alpha) is a popular subtitle format, MediaPlayer use ASS to implement player tips, real time barrage, and customize the style of text subtitles. Please refer to the ASS specificationsopen in new window.

The ASS style object contains the following members:

• name {String} The name of style, case-sensitive and cannot contain commas.
• fontname {String} The name of font.
• fontsize {Integer} The size of font.
• bold {Integer} Whether text is bold (true) or not (false). -1 is true, 0 is false.
• italic {Integer} Whether text is italic (true) or not (false). -1 is true, 0 is false.
• underline {Integer} Whether text is underline (true) or not (false). -1 is true, 0 is false.
• strikeOut {Integer} Whether text is strike out (true) or not (false). -1 is true, 0 is false.
• scaleX {Number} Modifies the width of the font.
• scaleY {Number} Modifies the height of the font.
• spacing {Integer} Extra space between characters.
• angle {Number} The origin of the rotation is defined by the alignment.
• borderStyle {Integer} 1=Outline + drop shadow, 3=Opaque box.
• outline {Integer} If borderStyle is 1, then this specifies the width of the outline around the text, in pixels. Values may be 0, 1, 2, 3 or 4.
• shadow {Integer} If borderStyle is 1, then this specifies the depth of the drop shadow behind the text, in pixels. Values may be 0, 1, 2, 3 or 4.
• alignment {Integer} This sets how text is "justified" within the Left/Right onscreen margins, and also the vertical placing. Values may be 1=Left, 2=Centered, 3=Right. Add 4 to the value for a "Toptitle". Add 8 to the value for a "Midtitle". eg. 5 = left-justified toptitle.
• marginL {Integer} The Left Margin in pixels.
• marginR {Integer} The Right Margin in pixels.
• marginV {Integer} The vertical Left Margin in pixels.
• encoding {Integer} The character set or encoding of the font.
• primaryColor {String} The fill color for normal display of subtitles.
• secondaryColor {String} This color may be used instead of the primary color when a subtitle is automatically shifted to prevent an onscreen collsion, to distinguish the different subtitles.
• outlineColor {String} This color may be used instead of the primary or secondary color when a subtitle is automatically shifted to prevent an onscreen collsion, to distinguish the different subtitles.
• backColor {String} This is the color of the subtitle outline or shadow, if these are used.

The player has built-in ASS style named 'Default'. Adding the same name will overwrite the previous one.

await player.addAssStyle({
  name: 'MyStyle',
  fontname: 'Source Han Sans SC Normal', fontsize: 32,
  bold: 1, italic: 0, underline: 0, strikeOut: 0,
  scaleX: 100, scaleY: 100,
  spacing: 0, angle: 0,
  borderStyle: 1, outline: 2, shadow: 0,
  alignment: 2,
  marginL: 20, marginR: 20, marginV: 2,
  encoding: 0,
  primaryColor: '&H66FFFFFF', secondaryColor: '&H66FFFFFF', outlineColor: '&H66000000', backColor: '&H66000000'
});

Styles can also be added via strings:

await player.addAssStyle('Style: MyStyle,Source Han Sans SC Normal,32,&H66FFFFFF,&H66FFFFFF,&H66000000,&H66000000,1,0,0,0,100,100,0,0,1,2,0,2,20,20,2,0');

# async player.addImage(name, buffer)

• name {String} Image resource name.
• buffer {Buffer} Image content buffer, support png, jpeg format image, recommended to use png images with alpha channel.

Add image resource to this media player. The added pictures can be used for graphical tips display. For example, add a image named 'PauseShow'. After calling the player.pause() function to pause player, application can call player.addTips() to display the 'PauseShow' picture on the screen.

// Add picture to player
await player.addImage('PauseShow', fs.readFile('./pic.png'));

// Pause player
await player.pause();

// Show picture
await player.addTips('player', {
  image: 'PauseShow', duration: 5000, x: ... y: ... w: ... h: ...
});

The added picture will always exist and can be displayed multiple times. Adding a picture with the same name will overwrite the picture added earlier.

# async player.addTips(level, event)

• level {String} Tips level.
• event {Object} ASS event object or string, or image event object.
• Returns: {Integer} The id of tips which been added.

Add designated level tips to this media player. The level of tips is a string, can be: 'user' or 'player'.

The ASS event object contains the following members:

• layer {Integer} Text display layer, higher numbered layers will be drawn over the lower numbered. default: 0
• duration {Integer} Text display durations, unit in millisecond. default: 0
• style {String} Style name. default: Default
• name {String} Character name. This is the name of the character who speaks the dialogue. default: ''
• marginL {Integer} 4-figure Left Margin override. The values are in pixels. All zeroes means the default margins defined by the style are used. default: ass style value
• marginR {Integer} 4-figure Right Margin override. The values are in pixels. All zeroes means the default margins defined by the style are used. default: ass style value
• marginV {Integer} 4-figure Bottom Margin override. The values are in pixels. All zeroes means the default margins defined by the style are used. default: ass style value
• effect {String} Transition Effect. This is either empty, or contains information for one of the three transition effects implemented in SSA v4.x. default: no effect
• text {String} Display text script. This is the actual text which will be displayed on screen.

// Object mode
var openTips = await player.addTips('player', {
  layer: 0,
  duration: 5000,
  style: 'MyStyle',
  marginL: 20, marginR: 20, marginV: 2,
  text: '{\\pos(960,540)\\c&H0203FE}Opened'
});

// String mode
var closeTips = await player.addTips('player', 'Dialogue: 0,0:00:05.00,MyStyle,,20,20,2,,{\\pos(960,540)\\c&H0203FE}Closed');

The image event object contains the following members:

• image {Integer} The name of image resource.
• duration {Integer} Image display durations, unit in millisecond.
• x {Integer} The x position of image in canvas.
• y {Integer} The y position of image in canvas.
• w {Integer} The width of image.
• h {Integer} The height of image.

var pauseTips = await player.addTips('player', {
  image: 'PauseShow', duration: 5000, x: 10 y: 10 w: 100 h: 100
});

# async player.clearTips(level[, id])

• level {String} Tips level.
• id {Integer} Tips id, negative number or undefined means clear all tips of designated level. Optional.

Clear designated level tips of media player. The level of tips is a string, can be: 'user' or 'player'.

// Add picture to player
await player.addImage('PauseShow', fs.readFile('./pic.png'));

// Pause player
await player.pause();

// Show ads
var pauseTips =await player.addTips('player', {
  image: 'PauseShow', duration: 5000, x: ... y: ... w: ... h: ...
});

// Sleep ...
await timer.delay(1000);

// Clear picture
await player.clearTips('player', pauseTips);

// Continue
await player.play();

# async player.addRtBarrage(event)

• event {Object} ASS event object or string.
• Returns: {Integer} The id of real time barrage which been added.

Add a real time barrage to media player. Similar to player.addTips().

# async player.clearRtBarrage([id])

• id {Integer} Real time barrage id, negative number or undefined means clear all real time barrages. Optional.

Clear the real time barrage of media player. Similar to player.clearTips().

# async player.openBarrage(buffer)

• buffer {Buffer} ASS format barrage content buffer.

Load barrage content. After successful loading, the barrage state is MediaPlayer.PAUSED.

const barrage = fs.readFile('./bar.ass');

await player.openBarrage(barrage);

# player.barrageState()

• Returns: {Integer} The state of barrage.

Get the state of the current player barrage. Possible state are as follows:

# player.playBarrage()

Play barrage.

# player.pauseBarrage()

Pause barrage.

# async player.closeBarrage()

Close barrage. Barrage can be loaded and played multiple times.

// Load barrage
await player.openBarrage(...);

// Play barrage
player.playBarrage();

// Clear barrage
await player.closeBarrage();

// Re load barrage
await player.openBarrage(...);

// Play barrage
player.playBarrage();

# async player.setSubtitleParam([style][, yPos])

• style {String} Subtitle ASS style name.
• yPos {Number} Ratio of subtitle position to screen height.

If subtitles exist, set the subtitle style and Y position ratio. This setting only valid for text subtitles and has no effect on graphic subtitles.

// Set style and position
await player.setSubtitleParam('MyStyle', 0.1);

// Only set position
await player.setSubtitleParam(0.1);

# player.getSubtitleParam()

• Returns: {Object} The current subtitle parameter.

The subitle parameter object contains the following members:

• style {String} Subtitle ASS style name.
• yPos {Number} Ratio of subtitle position to screen height.

# player.setBufferParam(lowLevel, recycleInterval, recyclePrecent, source)

• lowLevel {Integer} Low water level, unit in byte.
• recycleInterval {Integer} Internal buffer recycle interval, unit in millisecond.
• recyclePrecent {Number} Internal buffer recycle precent in a recycle period, range: 0 to 1.
• source {String} The type of media source.

Set the buffer parameter of this media player, only valid for ecache:// protocol. The source is a string, can be:

player.setBufferParam(512 * 1024, 5000, 0.2, 'media');

# player.currentBufferLength(source)

• source {String} The type of media source.
• Returns: {Integer} The internal buffer length after the current play point.

Get current internal buffer length. only valid for ecache:// protocol.

console.log('Current buffer length ' + player.currentBufferLength('video'));

# player.write(pos, buffer, source)

• pos {Integer} Media data position.
• buffer {Buffer} Media data.
• source {String} The type of media source.
• Returns: {Boolean} true mean media player need more data, false mean the internal buffer length after the current play point bigger than low water level, don't need more data.

Push data to the internal buffer of this media player, only valid for ecache:// protocol. This function can be used in conjunction with the data event. When the player needs data, a data event will be generated. Data can be provided to the player based on this event.

player.on('data', req => {
  // Get data
  get_data(req.source, req.expect, req.position)
  .then(buf => {
    // Put data to player
    player.write(req.position, buf, req.source);
  })
  .catch(...);
});

# MediaPlayer Events

The MediaPlayer class inherits from the EventEmitter class. The following events are thrown in some specific situations.

# eof

This event is generated when the player reaches the media resource end. Then the player will changed to MediaPlayer.PAUSED state, if application need to replay or implement cycle playback, application need to call player.seek() function to seek position to 0, and call player.play() function.

# error

• reason {Error} Error reason.

This event is generated when media player error occurs. When error occurs, media player will enter MediaPlayer.CLOSED state. Possible errors include:

# info

• info {Object} The information of media source.

This event will be generated when the player obtains the resource information. For detailed information, please refer to player.info().

# data

• req {Object} Media data request.
  • source {String} The type of media source.
  • position {Integer} Requested data position.
  • expect {Integer} Expected data length.

When we use the ecache:// protocol to open media resources, we need to manually fill in the data for the player. When the player needs data, this event will be generated. Under normal circumstances, we can fill the data based on the suggestions of this event.

Examples can be referred to player.write().