@gumlet/player.js 2.0.16 → 3.0.1

package/README.md

@@ -6,67 +6,105 @@ Player.js
 )](https://www.npmjs.com/package/@gumlet/player.js)
 
 
-A JavaScript library for interacting with iframes that support Player.js
-spec.
+A JavaScript library for interacting with iframes that support Player.js spec.
 
 ```js
 const player = new playerjs.Player('iframe');
 
-player.on('ready', () => {
+player.on('ready', async () => {
   player.on('play', () => {
     console.log('play');
   });
 
-  player.getDuration(duration => console.log(duration));
+  const duration = await player.getDuration();
+  console.log(duration);
 
   if (player.supports('method', 'mute')) {
-    player.mute();
+    await player.mute();
   }
 
-  player.play();
+  await player.play();
 });
 ```
 
 Install
 -------
 
-Player.js is hosted on JSDelivr's CDN. :
+Player.js is hosted on JSDelivr's CDN:
 
 ```html
-<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@gumlet/player.js@2.0/dist/player.min.js"></script>
+<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@gumlet/player.js@3.0/dist/main.global.js"></script>
 ```
 
-install via npm :
+Install via npm:
 
 ```sh
 npm install @gumlet/player.js
 ```
 
+TypeScript Support
+------------------
+
+Player.js v3.0.0+ includes full TypeScript support with type definitions included. The library is written in TypeScript and provides comprehensive type safety:
+
+```typescript
+import playerjs from '@gumlet/player.js';
+
+const player = new playerjs.Player('iframe');
+
+player.on('ready', async () => {
+  try {
+    const duration = await player.getDuration();
+    console.log(`Duration: ${duration} seconds`);
+    
+    if (player.supports('method', 'mute')) {
+      await player.mute();
+    }
+    
+    await player.play();
+  } catch (error) {
+    console.error('Player error:', error);
+  }
+});
+```
+
+### Promise-Based API
+
+All player methods return promises, making it easier to work with async/await patterns:
+
+```typescript
+// Get multiple values concurrently
+const [duration, currentTime, volume] = await Promise.all([
+  player.getDuration(),
+  player.getCurrentTime(),
+  player.getVolume()
+]);
+
+// Chain operations
+await player.setCurrentTime(10);
+await player.setVolume(75);
+await player.play();
+```
+
 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. :
+Because of the dance that we need to do between both iframes, you should always wait till the `ready` event fires before interacting with the player object. However, the player will internally queue messages until ready is called:
 
 ```js
 const player = new playerjs.Player('iframe');
 
-player.on(playerjs.Events.PLAY, () => console.log('play'));
-
-player.on('ready', () => player.setCurrentTime(20));
+player.on('ready', async () => {
+  await 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 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.
+The best way is to do one of the following:
 
 ### Create the iframe via JavaScript
 
@@ -78,355 +116,393 @@ 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.
+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.
+### Wait for the document to be ready
 
 ```html
 <iframe src="//example.com/iframe"></iframe>
 
 <script>
   $(document).on('ready', () => {
-    $('iframes').each(() => {
+    $('iframes').each(async () => {
       const player = new playerjs.Player(this);
-      player.on('ready', () => player.play());
+      player.on('ready', async () => {
+        await 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.
+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
+All methods return promises for modern async/await patterns:
+
+### `play(): Promise<void>`
 Play the media:
 
 ```js
-player.play();
+await player.play();
 ```
 
-`pause`: void
+### `pause(): Promise<void>`
 Pause the media:
 
 ```js
-player.pause();
+await player.pause();
 ```
 
-`getPaused`: boolean
+### `getPaused(): Promise<boolean>`
 Determine if the media is paused:
 
 ```js
-player.getPaused(function(value){
-  console.log('paused:', value);
-});
+const isPaused = await player.getPaused();
+console.log('paused:', isPaused);
 ```
 
-`mute`: void
+### `mute(): Promise<void>`
 Mute the media:
 
 ```js
-player.mute();
+await player.mute();
 ```
 
-`unmute`: void
+### `unmute(): Promise<void>`
 Unmute the media:
 
 ```js
-player.unmute();
+await player.unmute();
 ```
 
-`getMuted`: boolean
+### `getMuted(): Promise<boolean>`
 Determine if the media is muted:
 
 ```js
-player.getMuted(value => console.log('muted:', value));
+const isMuted = await player.getMuted();
+console.log('muted:', isMuted);
 ```
 
-`setVolume`: void
+### `setVolume(volume: number): Promise<void>`
 Set the volume. Value needs to be between 0-100:
 
-```
-player.setVolume(50);
+```js
+await player.setVolume(50);
 ```
 
-`getVolume`: number
+### `getVolume(): Promise<number>`
 Get the volume. Value will be between 0-100:
 
 ```js
-player.getVolume(value => console.log('getVolume:', value));
+const volume = await player.getVolume();
+console.log('volume:', volume);
 ```
 
-`getDuration`: number
-Get the duration of the media is seconds:
+### `getDuration(): Promise<number>`
+Get the duration of the media in seconds:
 
 ```js
-player.getDuration(value => console.log('getDuration:', value));
+const duration = await player.getDuration();
+console.log('duration:', duration);
 ```
 
-`setCurrentTime`: number
+### `setCurrentTime(time: number): Promise<void>`
 Perform a seek to a particular time in seconds:
 
 ```js
-player.setCurrentTime(50);
+await player.setCurrentTime(50);
 ```
 
-`getCurrentTime`: number
+### `getCurrentTime(): Promise<number>`
 Get the current time in seconds of the video:
 
 ```js
-player.getCurrentTime(value => console.log('getCurrentTime:', value));
+const currentTime = await player.getCurrentTime();
+console.log('currentTime:', currentTime);
 ```
 
-`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. 
+### `setPlaybackRate(rate: number): Promise<void>`
+Set the playback rate which are available in the player. Doesn't return an error if the passed playback rate is not available:
 
 ```js
-player.setPlaybackRate(0.5);
+await player.setPlaybackRate(0.5);
 ```
 
-`getPlaybackRate`: number
+### `getPlaybackRate(): Promise<number>`
 Get the current playback rate of the player:
 
 ```js
-player.getPlaybackRate(value => console.log('getPlaybackRate:', value));
+const rate = await player.getPlaybackRate();
+console.log('playbackRate:', rate);
 ```
 
-`off`: void
-Remove an event listener. If the listener is specified it should remove
-only that listener, otherwise remove all listeners:
+### `setLoop(loop: boolean): Promise<void>`
+Set whether the media should loop:
 
 ```js
-player.off('play');
+await player.setLoop(true);
+```
+
+### `getLoop(): Promise<boolean>`
+Get whether the media is set to loop:
+
+```js
+const isLooping = await player.getLoop();
+console.log('looping:', isLooping);
+```
+
+### `off(event: string, callback?: Function): void`
+Remove an event listener. If the listener is specified it should remove only that listener, otherwise remove all listeners:
 
+```js
+player.off('play');
 player.off('play', playCallback);
 ```
 
-`on`: void
+### `on(event: string, callback: Function): void`
 Add an event listener:
 
 ```js
 player.on('play', () => console.log('play'));
 ```
 
-`supports`: \['method', 'event'\], methodOrEventName
-Determines if the player supports a given event or method.
+### `supports(type: 'method' | 'event', name: string | string[]): boolean`
+Determines if the player supports a given event or method:
 
 ```js
 player.supports('method', 'getDuration');
 player.supports('event', 'ended');
+player.supports('method', ['play', 'pause']);
 ```
 
 Events
 ------
 
-Events that can be listened to.
+Player.js provides comprehensive event handling to monitor playback state and user interactions. All events can be listened to using the `on()` method.
 
-`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`.
+### Core Events
 
-`progress`
-fires when the media is loading additional media for playback:
+#### `ready`
+Fired when the media is ready to receive commands. Always wait for this event before calling player methods.
 
 ```js
-{
-  percent: 0.8,
-}
+player.on('ready', async () => {
+  console.log('Player is ready!');
+  // Safe to call player methods now
+  await player.play();
+});
 ```
 
-`timeupdate`
-fires during playback:
+**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 avoid this, append a UUID or timestamp to the iframe's src.
+
+#### `play`
+Fired when playback starts.
 
 ```js
-{
-  seconds: 10,
-  duration: 40
-}
+player.on('play', () => {
+  console.log('Video started playing');
+});
 ```
 
-`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:
+#### `pause`
+Fired when playback is paused.
 
 ```js
-{
-  isFullScreen: true // or false
-}
+player.on('pause', () => {
+  console.log('Video paused');
+});
 ```
 
-`pipChange`
-fires when the video is put to or brought back from picture-in-picture.
+#### `ended`
+Fired when playback reaches the end of the media.
 
 ```js
-{
-  isPIP: true // or false
-}
+player.on('ended', async () => {
+  console.log('Video finished');
+  // Reset to beginning if needed
+  await player.setCurrentTime(0);
+});
 ```
 
-`playbackRateChange`
-fires when the video playback rate is changed by user.
-
-`audioChange`
-fires when the audio track of video is changed.
+### Progress Events
 
-`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.
+#### `timeupdate`
+Fired regularly during playback with current time information.
 
 ```js
-{
-  quality: '720p'
+player.on('timeupdate', (data) => {
+  const { seconds, duration } = data;
+  const progress = (seconds / duration) * 100;
+  
+  console.log(`Progress: ${progress.toFixed(1)}%`);
+  console.log(`Current time: ${formatTime(seconds)} / ${formatTime(duration)}`);
+});
+
+function formatTime(seconds) {
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.floor(seconds % 60);
+  return `${mins}:${secs.toString().padStart(2, '0')}`;
 }
 ```
 
-`seeked`
-fires when the video has been seeked by the user. Gives seeked to time in seconds and total duration of video.
+#### `progress`
+Fired when the media is buffering/loading additional content.
 
 ```js
-{
-  seconds: 10
-  duration: 50
-}
+player.on('progress', (data) => {
+  const { percent } = data;
+  console.log(`Buffered: ${(percent * 100).toFixed(1)}%`);
+});
 ```
 
-`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.
+#### `seeked`
+Fired when the user seeks to a different time position.
 
 ```js
-const receiver = new playerjs.Receiver();
-
-receiver.on('play', () => {
-  video.play();
-  receiver.emit('play');
-});
-
-receiver.on('pause', () => {
-  video.pause();
-  receiver.emit('pause');
+player.on('seeked', (data) => {
+  const { seconds, duration } = data;
+  console.log(`Seeked to ${seconds}s of ${duration}s`);
 });
+```
 
-receiver.on('getDuration', callback => callback(video.duration));
+### Audio/Video Control Events
 
-receiver.on('getVolume', callback => callback(video.volume*100));
+#### `volumeChange`
+Fired when the volume level changes, including mute/unmute actions.
 
-receiver.on('setVolume', value => video.volume = (value/100));
+```js
+player.on('volumeChange', async () => {
+  const volume = await player.getVolume();
+  const isMuted = await player.getMuted();
+  
+  console.log(`Volume: ${volume}%, Muted: ${isMuted}`);
+});
+```
 
-receiver.on('mute', () => video.mute = true)
+#### `playbackRateChange`
+Fired when playback speed is changed.
 
-receiver.on('unmute', () => video.mute = false);
+```js
+player.on('playbackRateChange', async () => {
+  const rate = await player.getPlaybackRate();
+  console.log(`Playback rate: ${rate}x`);
+});
+```
 
-receiver.on('getMuted', callback => callback(video.mute));
+### Display Events
 
-receiver.on('getLoop', callback => callback(video.loop));
+#### `fullscreenChange`
+Fired when fullscreen mode is toggled.
 
-receiver.on('setLoop', value => video.loop = value);
+```js
+player.on('fullscreenChange', (data) => {
+  const { isFullScreen } = data;
+  console.log(`Fullscreen: ${isFullScreen}`);
+});
+```
 
-video.addEventListener('ended', () => receiver.emit('ended'));
+#### `pipChange`
+Fired when Picture-in-Picture mode is toggled.
 
-video.addEventListener('timeupdate', () => {
-  receiver.emit('timeupdate', {
-    seconds: video.currentTime,
-    duration: video.duration
-  });
+```js
+player.on('pipChange', (data) => {
+  const { isPIP } = data;
+  console.log(`Picture-in-Picture: ${isPIP}`);
 });
-
-receiver.ready();
 ```
 
-Methods
--------
+### Quality Events
 
-`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:
+#### `qualityChange`
+Fired when video quality/resolution is changed.
 
 ```js
-receiver.on('getDuration', callback => callback(video.duration));
+player.on('qualityChange', (data) => {
+  const { quality } = data;
+  console.log(`Quality changed to: ${quality}`);
+});
 ```
 
-Otherwise you can safely ignore any inputs:
+#### `audioChange`
+Fired when the audio track is changed.
 
 ```js
-receiver.on('play', callback => video.play());
+player.on('audioChange', (data) => {
+  console.log('Audio track changed:', data);
+});
 ```
 
-`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:
+### Error Handling
 
-    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`:
+#### `error`
+Fired when an error occurs during playback.
 
 ```js
-receiver.ready();
+player.on('error', (error) => {
+  console.error('Playback error:', error);
+  // Handle error appropriately for your application
+});
 ```
-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](http://www.videojs.com/),
-[JWPlayer](https://www.jwplayer.com/) and [HTML5
-Video](http://dev.w3.org/html5/spec-author-view/video.html). An Adapter
-wraps the Receiver and wires up all the events so your iframe is
-Player.js compatible.
 
-### VideoJSAdapter
+### Complete Example
 
-An adapter for [Video.js](http://www.videojs.com/). :
+Here's a comprehensive example showing how to listen to multiple events:
 
 ```js
-videojs("video", {}, () => {
-  const adapter = new playerjs.VideoJSAdapter(this);
-  // ... Do other things to initialize your video.
+const player = new playerjs.Player('video-iframe');
+
+player.on('ready', async () => {
+  console.log('Player is ready!');
+  
+  // Get initial player state
+  const duration = await player.getDuration();
+  const volume = await player.getVolume();
+  const isPaused = await player.getPaused();
+  
+  console.log(`Duration: ${duration}s, Volume: ${volume}%, Paused: ${isPaused}`);
+});
+
+// Listen to playback events
+player.on('play', () => console.log('Started playing'));
+player.on('pause', () => console.log('Paused'));
+player.on('ended', () => console.log('Playback finished'));
 
-  // Start accepting events
-  adapter.ready();
+// Listen to progress events
+player.on('timeupdate', (data) => {
+  const { seconds, duration } = data;
+  console.log(`${seconds.toFixed(1)}s / ${duration.toFixed(1)}s`);
 });
-```
-### HTML5Adapter
 
-An adapter for [HTML5
-Video](http://dev.w3.org/html5/spec-author-view/video.html). :
+// Listen to user interaction events
+player.on('volumeChange', async () => {
+  const volume = await player.getVolume();
+  const muted = await player.getMuted();
+  console.log(`Volume: ${volume}%, Muted: ${muted}`);
+});
 
-```js
-const video = document.getElementById('video');
-video.load();
+player.on('seeked', (data) => {
+  console.log(`Seeked to: ${data.seconds}s`);
+});
+
+// Listen to display events
+player.on('fullscreenChange', (data) => {
+  console.log(`Fullscreen: ${data.isFullScreen}`);
+});
 
-const adapter = playerjs.HTML5Adapter(video);
+player.on('pipChange', (data) => {
+  console.log(`Picture-in-Picture: ${data.isPIP}`);
+});
 
-// Start accepting events
-adapter.ready();
+// Handle errors
+player.on('error', (error) => {
+  console.error('Player error:', error);
+});
 ```
+
+## Related Documentation
+
+- [Receiver Implementation Guide](./RECEIVER.md) - For implementing the Player.js spec in your video player
+- [Legacy Callback API](./CALLBACK_API.md) - Documentation for backward-compatible callback-based methods