@gumlet/player.js v2.0.6

Player.js

A JavaScript library for interacting with iframes that support Player.js spec.

const player = new playerjs.Player('iframe');

player.on('ready', () => {
  player.on('play', () => {
    console.log('play');
  });

  player.getDuration(duration => console.log(duration));

  if (player.supports('method', 'mute')) {
    player.mute();
  }

  player.play();
});

Install

Player.js is hosted on JSDelivr's CDN. :

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@gumlet/player.js@2.0/dist/player.min.js"></script>

install via npm :

npm install @gumlet/player.js

Ready

Because of the dance that we need to do between both iframes, you should always wait till the ready events to fire before interacting with the player object. However, the player will internally queue messages until ready is called. :

const player = new playerjs.Player('iframe');

player.on(playerjs.Events.PLAY, () => console.log('play'));

player.on('ready', () => player.setCurrentTime(20));

Timing

The timing between when the iframe is added and when the ready event is fired is important. Sadly we cannot fire the ready event till the iframe is loaded, but there is no concrete way of telling when postmessage is available to us.

The best way is to do one of the following.

Create the iframe via JavaScript

const iframe = document.createElement('iframe');
iframe.src = 'https://example.com/iframe';
document.body.appendChild(iframe);

const player = new playerjs.Player(iframe);

In this case, Player.js will listen to the onload event of the iframe and only try to communicate when ready.

Wait for the document to be ready.

<iframe src="//example.com/iframe"></iframe>

<script>
  $(document).on('ready', () => {
    $('iframes').each(() => {
      const player = new playerjs.Player(this);
      player.on('ready', () => player.play());
    });
  });
</script>

At this point we can reasonably assume that the iframe's been loaded and the ready. Player.js will take care of listening for ready events that were fired before the player is set up.

Methods

play: void Play the media:

player.play();

pause: void Pause the media:

player.pause();

getPaused: boolean Determine if the media is paused:

player.getPaused(function(value){
  console.log('paused:', value);
});

mute: void Mute the media:

player.mute();

unmute: void Unmute the media:

player.unmute();

getMuted: boolean Determine if the media is muted:

player.getMuted(value => console.log('muted:', value));

setVolume: void Set the volume. Value needs to be between 0-100:

player.setVolume(50);

getVolume: number Get the volume. Value will be between 0-100:

player.getVolume(value => console.log('getVolume:', value));

getDuration: number Get the duration of the media is seconds:

player.getDuration(value => console.log('getDuration:', value));

setCurrentTime: number Perform a seek to a particular time in seconds:

player.setCurrentTime(50);

getCurrentTime: number Get the current time in seconds of the video:

player.getCurrentTime(value => console.log('getCurrentTime:', value));

setPlaybackRate: number Set the playback rate which are available in the player. Doesn't returns an error if the passed playback rate is not available.

player.setPlaybackRate(0.5);

getPlaybackRate: number Get the current playback rate of the player:

player.getPlaybackRate(value => console.log('getPlaybackRate:', value));

off: void Remove an event listener. If the listener is specified it should remove only that listener, otherwise remove all listeners:

player.off('play');

player.off('play', playCallback);

on: void Add an event listener:

player.on('play', () => console.log('play'));

supports: ['method', 'event'], methodOrEventName Determines if the player supports a given event or method.

player.supports('method', 'getDuration');
player.supports('event', 'ended');

Events

Events that can be listened to.

ready fired when the media is ready to receive commands. This is fired regardless of listening to the event. Note: As outlined in the PlayerJs Spec, you may run into inconsistencies if you have multiple players on the page with the same src. To get around this, simply append a UUID or a timestamp to the iframe's src to guarantee that all players on the page have a unique src.

progress fires when the media is loading additional media for playback:

{
  percent: 0.8,
}

timeupdate fires during playback:

{
  seconds: 10,
  duration: 40
}

play fires when the video starts to play.

pause fires when the video is paused.

ended fires when the video is finished.

fullscreenChange fires when the video fullscreen is changed:

{
  isFullScreen: true // or false
}

pipChange fires when the video is put to or brought back from picture-in-picture.

{
  isPIP: true // or false
}

playbackRateChange fires when the video playback rate is changed by user.

audioChange fires when the audio track of video is changed.

qualityChange fires when the video quality is changed.

volumeChange fires when the volume level of the player is changed. It also gets fired when the player is muted or unmuted, along with muted and unmuted events respectively.

{
  quality: '720p'
}

seeked fires when the video has been seeked by the user. Gives seeked to time in seconds and total duration of video.

{
  seconds: 10
  duration: 50
}

error fires when an error occurs.

Receiver

If you are looking to implement the Player.js spec, we include a Receiver that will allow you to easily listen to events and takes care of the house keeping.

const receiver = new playerjs.Receiver();

receiver.on('play', () => {
  video.play();
  receiver.emit('play');
});

receiver.on('pause', () => {
  video.pause();
  receiver.emit('pause');
});

receiver.on('getDuration', callback => callback(video.duration));

receiver.on('getVolume', callback => callback(video.volume*100));

receiver.on('setVolume', value => video.volume = (value/100));

receiver.on('mute', () => video.mute = true)

receiver.on('unmute', () => video.mute = false);

receiver.on('getMuted', callback => callback(video.mute));

receiver.on('getLoop', callback => callback(video.loop));

receiver.on('setLoop', value => video.loop = value);

video.addEventListener('ended', () => receiver.emit('ended'));

video.addEventListener('timeupdate', () => {
  receiver.emit('timeupdate', {
    seconds: video.currentTime,
    duration: video.duration
  });
});

receiver.ready();

Methods

on Requests an event from the video. The above player methods should be implemented. If the event expects a return value a callback will be passed into the function call:

receiver.on('getDuration', callback => callback(video.duration));

Otherwise you can safely ignore any inputs:

receiver.on('play', callback => video.play());

emit Sends events to the parent as long as someone is listing. The above player events should be implemented. If a value is expected, it should be passed in as the second argument:

receiver.emit('timeupdate', { seconds:20, duration: 40 });

ready Once everything is in place and you are ready to start responding to events, call this method. It performs some house keeping, along with emitting ready:

receiver.ready();

Adapters

In order to make it super easy to add Player.js to any embed, we have written adapters for common video libraries. We currently have adapters for Video.js, JWPlayer and HTML5 Video. An Adapter wraps the Receiver and wires up all the events so your iframe is Player.js compatible.

VideoJSAdapter

An adapter for Video.js. :

videojs("video", {}, () => {
  const adapter = new playerjs.VideoJSAdapter(this);
  // ... Do other things to initialize your video.

  // Start accepting events
  adapter.ready();
});

HTML5Adapter

An adapter for HTML5 Video. :

const video = document.getElementById('video');
video.load();

const adapter = playerjs.HTML5Adapter(video);

// Start accepting events
adapter.ready();