# Media: Native Media Player

The media player module provides an interface for applications to creat a media player instance. Through the media player, you can perform some operations on pictures, videos and other media.

Developers can determine whether this interface work in the EdgerOS mobile App environment through the following code:

edger.env().then(data => {
  if (data.env === 'edgerapp') {
    // We work in EdgerOS mobile App environment.
  }
}).catch(error => {
  console.error(error);
});

Every media player application starts by creating a new media player instance with the player function:

# edger.media.player(params)

The parameters of player method include:

• params {Object} Parameters for the media player.
• Returns: {Promise} Player instance object.

The params is an object, it can contain the following members:

• files {Array} Media files. Optional. The files attribute is a media file array, each media file item contains the following members:
  • id {String} Media file ID. Optional.
  • title {String} Media file title. Optional.
  • type {String} The type of media file. Optional values: video | livephoto | livephoto#mov | picture | file | directory.
  • url {String} The url of media file.
  • thumbnailUrl {String} The url of thumbnail. Optional.
  • livePhotoUrl {String} The url of live photo. Optional.
  • headers {Object} Media request headers. Optional.
  • edger-cache-enable {Boolean} Whether to enable Edger cache. When the value is true, the cache will be enabled. Default: false. Optional.
• position {Number} The focus position of media player. Optional.
• positionFileId {string} The currently displayed file ID of media player. Optional.
• toolbarItems {Array} The toolbar items of media player. Optional. It can contain the following members:
  • icon {String} Toolbar icon.
  • code {String} Toolbar type code. Optional values: drop | export | share | detail.
  • label {String} Toolbar title.
  • labelColor {String} Font color for toolbar items. Optional.
  • labelBgColor {String} Background color for toolbar items. Optional.
  • position {String} Toolbar items display position. Optional values: top | bottom. Default: bottom. Optional.
  • disabled {Boolean} Whether toolbar item is disabled. Optional.
• mode {string} The media player mode. Optional values: normal | caster. Default: normal. Optional.

# Example

const files = [
  {
    id: '001',
    type: 'video',
    url: 'https://www.w3school.com.cn/example/html5/mov_bbb.mp4',
    thumbnailUrl: 'https://edgeros-static-image.oss-cn-hangzhou.aliyuncs.com/vip_banner/v2_free.png',
    headers: {
      'edger-cache-enable': true;
    }
  },
  {
    id: '002',
    type: 'video',
    url: 'https://www.w3cschool.cn/statics/demosource/movie.mp4',
    thumbnailUrl: 'https://edgeros-static-image.oss-cn-hangzhou.aliyuncs.com/vip_banner/v2_free.png',
    headers: {
      'edger-cache-enable': true;
    }
  },
  {
    id: '003',
    type: 'video',
    url: 'https://media.w3.org/2010/05/sintel/trailer.mp4',
    thumbnailUrl: 'https://edgeros-static-image.oss-cn-hangzhou.aliyuncs.com/vip_banner/v2_free.png',
    headers: {
      'edger-cache-enable': true;
    }
  }
];
const position = 2;
const toolbarItems = [
  { icon: 'delete1', code: 'drop', label: '删除' },
  { icon: 'export', code: 'export', label: '导出' },
  { icon: 'share', code: 'share', label: '分享' },
  { icon: 'details', code: 'detail', label: '详情' }
];
const mode = 'normal'

// player instance object
const player = edger.media.player({ files, position, toolbarItems, mode })

# async / await

async function player(params) {
  try {
    const { files, position, toolbarItems, mode } = params;
    return await edger.media.player({ files, position, toolbarItems, mode });
  } catch (error) {
    console.error(error);
  }
}

Once instantiated, we can call methods or events on the instance, the instance methods are as follows:

# player.play(sourceFrame)

Open the media player.

• sourceFrame: {Object} Source frame.
• Returns: {Promise}.

The sourceFrame is an object, it can contain the following members:

• width {Number} Source frame width.
• height {Number} Source frame height.
• offsetX {Number} Source frame horizontal offset value.
• offsetY {Number} Source frame vertical offset value.

# Example

const sourceFrame = {
  width: 1000,
  height: 1000,
  offsetX: 10,
  offsetY: 10
};

player.play(sourceFrame)

# async / await

async function player(sourceFrame) {
  try {
    await player.play(sourceFrame);
  } catch (error) {
    console.error(error);
  }
}

# player.append(files, direction)

Add media files to the playlist of media player.

• files: {Array} Media files.
• direction: {String} Media append direction. Optional values: start | end.
• Returns: {Promise}.

The files are media files array, each item can contain the following members:

• id {String} Media file ID. Optional.
• title {String} Media file title. Optional.
• type {String} Media file types. Optional values: video | livephoto | livephoto#mov | picture | file | directory.
• url {String} The url of media file.
• thumbnailUrl {String} The url of thumbnail. Optional.
• livePhotoUrl {String} The url of live photo. Optional.
• headers {Object} Media request headers. Optional.
• edger-cache-enable {Boolean} Whether to enable Edger cache. When the value is true, the cache will be enabled. Default: false. Optional.

# Example

const files = [
  {
    id: '004',
    type: 'video',
    url: 'https://www.w3cschool.cn/statics/demosource/movie.mp4',
    thumbnailUrl: 'https://edgeros-static-image.oss-cn-hangzhou.aliyuncs.com/vip_banner/v2_free.png'
  },
  {
    id: '005',
    type: 'video',
    url: 'https://www.w3school.com.cn/example/html5/mov_bbb.mp4',
    thumbnailUrl: 'https://edgeros-static-image.oss-cn-hangzhou.aliyuncs.com/vip_banner/v2_free.png'
  }
];
const position = 'end';

const sourceFrame = {
  width: 1000,
  height: 1000,
  offsetX: 10,
  offsetY: 10
};

// play
player.play(sourceFrame);

// append files after 3 seconds
setTimeout(() => {
  player.append(files, position);
}, 3000)

# async / await

const delay = (time) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve();
    }, time)
  })
}

async function playAndAppend(sourceFrame, files, position) {
  try {
    await player.play(sourceFrame);
    await delay(3000);
    await player.append(files, position);
  } catch (error) {
    console.error(error);
  }
}

# player.update(index, file[, loading, showError])

Update the files, loading status, and error messages in the playlist of media player.

• index {Number} The index of media file needs to be updated.
• file {Object} Media file, it can contain the following members:
• loading {Number} The player shows the loading effect. Default: true. Optional.
• showError {Boolean} Whether to display pictures after loading failure. Default: true. Optional.
• Returns: {Promise}.

The file is an object, it can contain the following members:

• id {String} Media file ID. Optional.
• type {String} The type of media file (only optional value: 'picture').
• url {String} The url of media file.
• thumbnailUrl {String} The url of thumbnail. Optional.
• livePhotoUrl {String} The url of live photo. Optional.
• headers {Object} Media request headers. Optional.
• edger-cache-enable {Boolean} Whether to enable Edger cache. When the value is true, the cache will be enabled. Default: false. Optional.

# Example

const index = 0
const file = {
  id: '004',
  type: 'video',
  url: 'https://www.w3cschool.cn/statics/demosource/movie.mp4',
  thumbnailUrl: 'https://edgeros-static-image.oss-cn-hangzhou.aliyuncs.com/vip_banner/v2_free.png'
}
const loading = true
const showError = false

player.update(index, file, loading, showError);

# async / await

async function update(params) {
  try {
    const { index, file, loading, showError } = params;
    await player.update(index, file, loading, showError);
  } catch (error) {
    console.error(error);
  }
}

# player.layout(layout)

Update the layout configuration of the current media player, including the title, subtitle, playback animation, and other layout settings.

• layout {Object} The layout information of media player.
• Returns: {Promise}.

The layout is an object, it can contain the following members:

• title {String} The title of media player. Only supports players whose media file type is picture.
• subtitle {String} The subtitle of media player. Optional.
• alignment {String} The direction in which the title is displayed. Optional values: left | center | right. Default: left. Optional.
• animation {Object} Title animation configuration items. Optional. It can contain the following members:
  • mode {String} Animation mode of the title. when the value is marquee, it represents the scrolling mode. Optional values: none | marquee. Default: none. Optional.
  • config {Object} Animation specific configuration items, it can contain the following member:
    • speed {Number} Animation execution speed. Default: 60. Unit: Pixels per second.

# Example

const layout = {
  title: 'EdgerOS Media Player',
}
// play
player.play();

// update layout after 5 seconds
setTimeout(() => {
  player.layout(layout);
}, 5000);

# async / await

const delay = (time) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve();
    }, time)
  })
}

async function playAndLayout(layout) {
  try {
    await player.play();
    await delay(5000);
    await player.layout(layout);
  } catch (error) {
    console.error(error);
  }
}

# player.toolbar(toolbarItems)

Set the toolbar for media player.

• toolbarItems {Array} The toolbar items of media player.
• Returns: {Promise}.

The toolbarItems are toolbar items of the media player, each item can contain the following members:

• icon {String} Toolbar icon.
• code {String} Toolbar type code. Optional values: drop | export | share | detail.
• label {String} Toolbar title.
• labelColor {String} Font color for toolbar items. Optional.
• labelBgColor {String} Background color for toolbar items. Optional.
• position {String} Toolbar items display position. Optional values: top | bottom. Default: bottom. Optional.
• disabled {Boolean} Whether toolbar item is disabled. Optional.

The returned object can contain the following members:

• code {String} Toolbar code.
• id {String} File ID.

# Example

const toolbarItems = [
  { icon: 'caster', code: 'caster', label: '投屏', position: 'top', labelColor: '#f0f0f0', labelBgColor: '#0077fa' },
  { icon: 'delete1', code: 'drop', label: '删除' },
  { icon: 'share', code: 'share', label: '分享', disabled: true },
  { icon: 'details', code: 'detail', label: '详情' },
];

// play
player.play();

// update toolbar after 5 seconds
setTimeout(() => {
  player.toolbar(toolbarItems);
}, 5000);

# async / await

const delay = (time) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve();
    }, time)
  })
}

async function playAndToolbar(toolbarItems) {
  try {
    await player.play();
    await delay(5000);
    await player.toolbar(toolbarItems);
  } catch (error) {
    console.error(error);
  }
}

# player.drop(id)

Drop file in the media player.

• id {String} Media file ID.
• Returns: {Promise}.

# Example

const sourceFrame = {
  width: 1000,
  height: 1000,
  offsetX: 10,
  offsetY: 10
};
player.play(sourceFrame);

// drop files after 3 seconds
setTimeout(() => {
  player.drop('002');
}, 3000)

# async / await

const delay = (time) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve();
    }, time)
  })
}

async function playAndDrop(sourceFrame, id) {
  try {
    await player.play(sourceFrame);
    await delay(3000);
    await player.drop(id);
  } catch (error) {
    console.error(error);
  }
}

# player.scrollTo(params)

Scroll to the position on media player.

• params {Object} The attribute information of media player.
• Returns: {Promise}.

The params is an object, it can contain the following members:

• positionFileId {String} The media player scrolls to the current file ID location.

# Example

const params = {
  positionFileId: 'xxxxxx-xxxxxxxxxx-xxxxxx-xxxxxxxxxx'
};
player.scrollTo(params);

# async / await

async function scrollTo(params) {
  try {
    await player.scrollTo(params);
  } catch (error) {
    console.error(error);
  }
}

# player.updateAttributes(params)

Update the attributes of media player.

• params {Object} The layout information of media player.
• Returns: {Promise}.

The params is an object, it can contain the following members:

• attributes {Array} The media player attributes, each item can contain the following members:
  • key {String} The media player attribute key.
  • value {any} The media player attribute value.

# Example

const params = {
  attributes: [
    { 
      key: 'sourceFrame', 
      value: {
        width: 1000,
        height: 1000,
        offsetX: 10,
        offsetY: 10
      }
    }
  ]
}

player.updateAttributes(params);

# async / await

async function updateAttributes(params) {
  try {
    await player.updateAttributes(params);
  } catch (error) {
    console.error(error);
  }
}

# player.close()

Close the entire player.

• Returns: {Promise}.

# Example

const sourceFrame = {
  width: 1000,
  height: 1000,
  offsetX: 10,
  offsetY: 10
};
player.play(sourceFrame);

// closed player after 6 seconds
setTimeout(() => {
  player.close();
}, 6000)

# async / await

const delay = (time) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve();
    }, time)
  })
}

async function playAndClose(sourceFrame) {
  try {
    await player.play(sourceFrame);
    await delay(6000);
    await player.close();
  } catch (error) {
    console.error(error);
  }
}

# player.setMode(mode)

Set the playback mode of media player.

• mode {string} The media player mode. Optional values: normal | caster .
• Returns: {Promise}.

# Example

const mode = 'caster';

player.setMode(mode).then(() => {
  console.log('set mode successful')
}).catch((err) => {
  console.log('set mode failed', err)
});

# async / await

async function setMode(mode) {
  try {
    await player.setMode(mode);
    console.log('set mode successful')
  } catch (err) {
    console.log('set mode failed', err)
  }
}

# player.setCasterControls(params)

Set the casting controller for media player.

• params {Object} Caster control.
• Returns: {Promise}.

The params is an object, it can contain the following members:

• status {String} The status of media player control buttons. Optional values: pause | play.
• duration {number} The total duration of media player screen casting. Unit: millisecond(ms). Optional.
• progress {number} The progress of media player screen casting. Unit: millisecond(ms). Optional.

# Example

const params = {
  status: 'pause',
  duration: 60000,
  progress: 12000
};

player.setCasterControls(params).then(() => {
  console.log('set caster controls successful')
}).catch((err) => {
  console.log('set caster controls failed', err)
});

# async / await

async function setCasterControls(params) {
  try {
    await player.setCasterControls(params);
    console.log('set caster controls successful')
  } catch (err) {
    console.log('set caster controls failed', err)
  }
}

# Events

The unified event listener provided by Web-SDK:

const listener = (payload) => {
  // Event handling...
}

// add listener
player.addEventListener('some-event', listener)

// or 
// onAction() is an alias of addEventListener().
player.onAction('some-event', listener)

// remove listener
player.removeEventListener('some-event', listener)

// remove all listeners
player.removeAllListeners()

# change

This event will be generated when the media player changes.

• Returns: {Object} A media object.

Get an object of result, the object includes:

• playerId {String} Player ID, the unique identifier of media player.
• previous {Number} Number of the previous media file.
• current {Number} Number of the current media file.
• total {Number} Total number of media files.

# Example

player.addEventListener('change', (payload) => {
  const { playerId, previous, current, total } = payload;
  console.log("player change result:", playerId, previous, current, total);
});

# close

This event will be generated when the media player closed.

• Returns: {Object} A media object.

Get an object of result, the object includes:

• playerId {String} Player ID, the unique identifier of media player.

# Example

player.addEventListener('close', (payload) => {
  console.log("closed player ID:", payload.playerId)
});

# action

This event will be generated when the media player actions.

• Returns: {Object} A media object.

Get an object of result, the object includes:

• id {String} Media file ID.
• code {String} Action type code. Optional values: drop | export | share | detail.
• playerId {String} Player ID, the unique identifier of media player.

# Example

player.addEventListener('action', (payload) => {
  console.log("action code:", payload.code, 'player ID', payload.playerId);
});

# status

This event is generated when the status of media player changes.

• Returns: {Object} A media object.

Get an object of result, the object includes:

• id {String} Media file ID.
• status {String} Current status of the media player. Optional values: loading | loaded | fail.
• playerId {String} Player ID, the unique identifier of media player.

# Example

player.addEventListener('status', (payload) => {
  console.log("layer status:", payload.status, 'player ID', payload.playerId, , 'File ID', payload.id)
});

# casterControls

This event is generated when the caster status of media player changes.

• Returns: {Object} A media object.

Get an object of result, the object includes:

• playerId {String} Player ID, the unique identifier of media player.
• status {String} Player caster status. Optional values: pause | play.
• progress {String} Player caster progress. Unit: millisecond(ms).

# Example

player.addEventListener('casterControls', (payload) => {
  console.log("casterControls status:", payload.status, 'casterControls progress', payload.playerId)
});