Empezando

1. Instalar el paquete

   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. Sincronización con proyectos nativos

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Configurar el complemento

   Configuración básica del reproductor:

   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 });

   Controles del jugador:

   // 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

   Agregue a su Info.plist:

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

   Android

   Agregue a su AndroidManifest.xml:

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

4. Manejo de eventos

   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. Uso avanzado

   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 Referencia

Métodos

create(options: CreateOptions)

Cree una nueva instancia de reproductor IVS.

Parámetros:

• options: Configuración del reproductor
  • url: cadena - URL de reproducción de IVS
  • autoplay: booleano - Iniciar reproducción automáticamente
  • muted: booleano - Inicio silenciado
  • controls: booleano - Mostrar controles nativos

Devoluciones: Promise<{ playerId: string }>

play(options: PlayerOptions)

Inicie la reproducción.

pause(options: PlayerOptions)

Pausar la reproducción.

stop(options: PlayerOptions)

Detenga la reproducción y restablezca la posición.

seekTo(options: SeekOptions)

Buscar un puesto específico.

setVolume(options: VolumeOptions)

Establece el volumen del reproductor (0,0 a 1,0).

setQuality(options: QualityOptions)

Establece la calidad de reproducción.

destroy(options: PlayerOptions)

Destruye la instancia del jugador.

Eventos

• onState: Cambios de estado del jugador
• onError: Errores de reproducción
• onDuration: Duración del vídeo disponible
• onProgress: actualizaciones del progreso de la reproducción
• onQuality: Cambios de calidad
• onMetadata: Eventos de metadatos cronometrados
• onBuffer: Actualizaciones de estado del búfer

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
}

Notas de plataforma

iOS

• Requiere iOS 12.0 o posterior
• Utiliza AVPlayer nativo con extensiones IVS
• Admite imagen en imagen en iPads

Android

• Requiere Android 5.0 (API nivel 21) o posterior
• Utiliza el reproductor Amazon IVS SDK
• Se recomienda aceleración de hardware

Casos de uso comunes

1. Transmisión en vivo: eventos, deportes y juegos en tiempo real
2. Transmisión interactiva: encuestas de espectadores, sesiones de preguntas y respuestas
3. Comercio electrónico: compras en vivo con productos destacados
4. Educación: Clases en vivo con contenido cronometrado
5. Entretenimiento: Conciertos, espectáculos con interacción del público.

Mejores prácticas

1. Manejo de red: monitorear la calidad de la conexión

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

2. Gestión de recursos: Destruye siempre a los jugadores cuando hayas terminado

3. Políticas de reproducción automática: inicio silenciado para una reproducción automática confiable

4. Selección de calidad: deje que IVS se encargue del cambio automático de calidad

Solución de problemas

La transmisión no se reproduce:

• Verifique que la URL de reproducción de IVS sea válida
• Verificar permisos de red
• Asegúrate de que la transmisión esté en vivo.

Alta latencia:

• IVS está optimizado para baja latencia, verifique la configuración de su codificador
• Verifica que estás usando la URL de reproducción específica de IVS

Problemas de calidad:

• Permitir el cambio automático de calidad.
• Verifique los requisitos de ancho de banda de la red