Getting Started

1. Install the package

   npm

   npm i @capgo/ivs-player

   pnpm

   pnpm add @capgo/ivs-player

   yarn

   yarn add @capgo/ivs-player

   bun

   bun add @capgo/ivs-player

2. Sync with native projects

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Configure the plugin

   import { IvsPlayer } from '@capgo/ivs-player';
   
   // Create a player
   const { playerId } = await IvsPlayer.create({
     url: 'https://your-ivs-playback-url.m3u8',
     autoplay: true
   });
   
   // Start playback
   await IvsPlayer.play({ playerId });

   // Pause playback
   await IvsPlayer.pause({ playerId });
   
   // Set volume
   await IvsPlayer.setVolume({
     playerId,
     volume: 0.5 // 0.0 to 1.0
   });
   
   // Seek to position
   await IvsPlayer.seekTo({
     playerId,
     position: 30 // seconds
   });

   iOS

   Add to your Info.plist:

   <key>NSAppTransportSecurity</key>
   <dict>
     <key>NSAllowsArbitraryLoads</key>
     <true/>
   </dict>

   Android

   Add to your AndroidManifest.xml:

   <uses-permission android:name="android.permission.INTERNET" />

4. Event handling

   import { IvsPlayer } from '@capgo/ivs-player';
   
   // Listen for player events
   IvsPlayer.addListener('onState', (event) => {
     console.log('Player state:', event.state);
     // States: idle, buffering, ready, playing, ended
   });
   
   IvsPlayer.addListener('onError', (event) => {
     console.error('Player error:', event.error);
   });
   
   IvsPlayer.addListener('onDuration', (event) => {
     console.log('Video duration:', event.duration);
   });
   
   IvsPlayer.addListener('onProgress', (event) => {
     console.log('Current position:', event.position);
   });
   
   // Listen for timed metadata
   IvsPlayer.addListener('onMetadata', (event) => {
     console.log('Timed metadata:', event.metadata);
   });

5. Advanced usage

   import { IvsPlayer } from '@capgo/ivs-player';
   
   export class StreamPlayer {
     private playerId: string | null = null;
     private listeners: any[] = [];
   
     async initialize(streamUrl: string) {
       // Create player with custom configuration
       const result = await IvsPlayer.create({
         url: streamUrl,
         autoplay: false,
         muted: true, // Start muted for autoplay policies
         controls: true
       });
   
       this.playerId = result.playerId;
       this.setupEventListeners();
     }
   
     private setupEventListeners() {
       // State changes
       const stateListener = IvsPlayer.addListener('onState', (event) => {
         this.handleStateChange(event.state);
       });
       this.listeners.push(stateListener);
   
       // Quality changes
       const qualityListener = IvsPlayer.addListener('onQuality', (event) => {
         console.log(`Quality changed to: ${event.quality.name}`);
       });
       this.listeners.push(qualityListener);
   
       // Buffer updates
       const bufferListener = IvsPlayer.addListener('onBuffer', (event) => {
         console.log(`Buffer: ${event.percentage}%`);
       });
       this.listeners.push(bufferListener);
     }
   
     private handleStateChange(state: string) {
       switch (state) {
         case 'playing':
           console.log('Stream is playing');
           break;
         case 'buffering':
           console.log('Stream is buffering');
           break;
         case 'ended':
           console.log('Stream ended');
           break;
       }
     }
   
     async play() {
       if (this.playerId) {
         await IvsPlayer.play({ playerId: this.playerId });
       }
     }
   
     async pause() {
       if (this.playerId) {
         await IvsPlayer.pause({ playerId: this.playerId });
       }
     }
   
     async setQuality(qualityName: string) {
       if (this.playerId) {
         await IvsPlayer.setQuality({
           playerId: this.playerId,
           quality: qualityName
         });
       }
     }
   
     async destroy() {
       // Remove listeners
       this.listeners.forEach(listener => listener.remove());
   
       // Destroy player
       if (this.playerId) {
         await IvsPlayer.destroy({ playerId: this.playerId });
       }
     }
   }

API Reference

Methods

create(options: CreateOptions)

Create a new IVS player instance.

Parameters:

• options: Player configuration
  • url: string - IVS playback URL
  • autoplay: boolean - Auto-start playback
  • muted: boolean - Start muted
  • controls: boolean - Show native controls

Returns: Promise<{ playerId: string }>

play(options: PlayerOptions)

Start playback.

pause(options: PlayerOptions)

Pause playback.

stop(options: PlayerOptions)

Stop playback and reset position.

seekTo(options: SeekOptions)

Seek to a specific position.

setVolume(options: VolumeOptions)

Set player volume (0.0 to 1.0).

setQuality(options: QualityOptions)

Set playback quality.

destroy(options: PlayerOptions)

Destroy the player instance.

Events

• onState: Player state changes
• onError: Playback errors
• onDuration: Video duration available
• onProgress: Playback progress updates
• onQuality: Quality changes
• onMetadata: Timed metadata events
• onBuffer: Buffer status updates

Interfaces

interface CreateOptions {
  url: string;
  autoplay?: boolean;
  muted?: boolean;
  controls?: boolean;
}

interface PlayerOptions {
  playerId: string;
}

interface SeekOptions extends PlayerOptions {
  position: number; // seconds
}

interface VolumeOptions extends PlayerOptions {
  volume: number; // 0.0 to 1.0
}

interface QualityOptions extends PlayerOptions {
  quality: string; // quality name
}

Platform Notes

iOS

• Requires iOS 12.0 or later
• Uses native AVPlayer with IVS extensions
• Supports Picture-in-Picture on iPads

Android

• Requires Android 5.0 (API level 21) or later
• Uses Amazon IVS Player SDK
• Hardware acceleration recommended

Common Use Cases

1. Live Streaming: Real-time events, sports, gaming
2. Interactive Streaming: Viewer polls, Q&A sessions
3. E-commerce: Live shopping with product highlights
4. Education: Live classes with timed content
5. Entertainment: Concerts, shows with audience interaction

Best Practices

1. Network Handling: Monitor connection quality

   IvsPlayer.addListener('onError', (event) => {
     if (event.error.includes('network')) {
       // Handle network errors
       showRetryButton();
     }
   });

2. Resource Management: Always destroy players when done

3. Autoplay Policies: Start muted for reliable autoplay

4. Quality Selection: Let IVS handle automatic quality switching

Troubleshooting

Stream not playing:

• Verify the IVS playback URL is valid
• Check network permissions
• Ensure the stream is live

High latency:

• IVS is optimized for low latency, check your encoder settings
• Verify you’re using the IVS-specific playback URL

Quality issues:

• Allow automatic quality switching
• Check network bandwidth requirements