Saltar al contenido
Capgo - Live Updates for Capacitor Apps Capgo

Empezando

  1. Instalar el paquete

    Ventana de terminal
    npm i @capgo/capacitor-youtube-player

  2. Sincronización con proyectos nativos

    Ventana de terminal
    npx cap sync

Uso básico

Section titled “Uso básico”
import { YoutubePlayer } from '@capgo/capacitor-youtube-player';


// Initialize the player
const result = await YoutubePlayer.initialize({
  playerId: 'youtube-player',
  playerSize: { width: 640, height: 360 },
  videoId: 'dQw4w9WgXcQ',
  fullscreen: false,
  playerVars: {
    autoplay: 1,
    controls: 1
  }
});


// Play video
await YoutubePlayer.playVideo(result.player);


// Pause video
await YoutubePlayer.pauseVideo(result.player);


// Listen to player events
YoutubePlayer.addEventListener(result.player, 'onStateChange', (event) => {
  console.log('Player state:', event.data);
});

API Referencia

Section titled “API Referencia”

inicializar (opciones)

Section titled “inicializar (opciones)”

Inicialice una instancia del reproductor de YouTube.

const { player, playerReady } = await YoutubePlayer.initialize({
  playerId: 'my-player',
  playerSize: { width: 1280, height: 720 },
  videoId: 'VIDEO_ID',
  fullscreen: false,
  playerVars: {
    autoplay: 0,
    controls: 1,
    rel: 0
  }
});

Métodos de control de vídeo

Section titled “Métodos de control de vídeo”
// Play
await YoutubePlayer.playVideo(playerId);


// Pause
await YoutubePlayer.pauseVideo(playerId);


// Stop
await YoutubePlayer.stopVideo(playerId);


// Seek to time
await YoutubePlayer.seekTo(playerId, seconds, allowSeekAhead);


// Load video by ID
await YoutubePlayer.loadVideoById(playerId, { videoId: 'VIDEO_ID' });


// Cue video (load without playing)
await YoutubePlayer.cueVideoById(playerId, { videoId: 'VIDEO_ID' });

Control de lista de reproducción

Section titled “Control de lista de reproducción”
// Load playlist
await YoutubePlayer.loadPlaylist(playerId, {
  listType: 'playlist',
  list: 'PLAYLIST_ID'
});


// Cue playlist
await YoutubePlayer.cuePlaylist(playerId, {
  playlist: ['VIDEO_ID_1', 'VIDEO_ID_2'],
  index: 0
});


// Navigate playlist
await YoutubePlayer.nextVideo(playerId);
await YoutubePlayer.previousVideo(playerId);
await YoutubePlayer.playVideoAt(playerId, index);

Control de audio

Section titled “Control de audio”
// Mute/Unmute
await YoutubePlayer.mute(playerId);
await YoutubePlayer.unMute(playerId);


const { result } = await YoutubePlayer.isMuted(playerId);
console.log('Muted:', result.value);


// Volume (0-100)
await YoutubePlayer.setVolume(playerId, 50);
const { result } = await YoutubePlayer.getVolume(playerId);

Control de reproducción

Section titled “Control de reproducción”
// Playback rate
await YoutubePlayer.setPlaybackRate(playerId, 1.5);
const { result } = await YoutubePlayer.getPlaybackRate(playerId);


// Available rates
const { result } = await YoutubePlayer.getAvailablePlaybackRates(playerId);
console.log('Available rates:', result.value);


// Loop and shuffle
await YoutubePlayer.setLoop(playerId, true);
await YoutubePlayer.setShuffle(playerId, true);

Control de calidad

Section titled “Control de calidad”
// Set quality
await YoutubePlayer.setPlaybackQuality(playerId, 'hd720');


// Get current quality
const { result } = await YoutubePlayer.getPlaybackQuality(playerId);


// Get available qualities
const { result } = await YoutubePlayer.getAvailableQualityLevels(playerId);

Información del jugador

Section titled “Información del jugador”
// Duration
const { result } = await YoutubePlayer.getDuration(playerId);


// Current time
const { result } = await YoutubePlayer.getCurrentTime(playerId);


// Loaded fraction
const { result } = await YoutubePlayer.getVideoLoadedFraction(playerId);


// Player state
const { result } = await YoutubePlayer.getPlayerState(playerId);


// Video URL
const { result } = await YoutubePlayer.getVideoUrl(playerId);

Oyentes de eventos

Section titled “Oyentes de eventos”
// State change
YoutubePlayer.addEventListener(playerId, 'onStateChange', (event) => {
  console.log('State:', event.data); // -1, 0, 1, 2, 3, 5
});


// Ready
YoutubePlayer.addEventListener(playerId, 'onReady', (event) => {
  console.log('Player ready');
});


// Error
YoutubePlayer.addEventListener(playerId, 'onError', (event) => {
  console.error('Player error:', event.data);
});


// Quality change
YoutubePlayer.addEventListener(playerId, 'onPlaybackQualityChange', (event) => {
  console.log('Quality:', event.data);
});


// Rate change
YoutubePlayer.addEventListener(playerId, 'onPlaybackRateChange', (event) => {
  console.log('Rate:', event.data);
});


// Remove listener
YoutubePlayer.removeEventListener(playerId, 'onStateChange', callback);

Ejemplo completo

Section titled “Ejemplo completo”
import { YoutubePlayer } from '@capgo/capacitor-youtube-player';


export class YouTubeService {
  private playerId: string | null = null;


  async initPlayer(videoId: string) {
    try {
      const { player, playerReady } = await YoutubePlayer.initialize({
        playerId: 'main-player',
        playerSize: { width: 1280, height: 720 },
        videoId,
        fullscreen: false,
        playerVars: {
          autoplay: 0,
          controls: 1,
          modestbranding: 1,
          rel: 0
        }
      });


      this.playerId = player;


      // Set up event listeners
      YoutubePlayer.addEventListener(player, 'onReady', () => {
        console.log('Player is ready');
      });


      YoutubePlayer.addEventListener(player, 'onStateChange', (event) => {
        this.handleStateChange(event.data);
      });


      YoutubePlayer.addEventListener(player, 'onError', (event) => {
        console.error('YouTube error:', event.data);
      });


      return player;
    } catch (error) {
      console.error('Failed to initialize player:', error);
      throw error;
    }
  }


  private handleStateChange(state: number) {
    switch (state) {
      case -1:
        console.log('Unstarted');
        break;
      case 0:
        console.log('Ended');
        break;
      case 1:
        console.log('Playing');
        break;
      case 2:
        console.log('Paused');
        break;
      case 3:
        console.log('Buffering');
        break;
      case 5:
        console.log('Video cued');
        break;
    }
  }


  async play() {
    if (!this.playerId) return;
    await YoutubePlayer.playVideo(this.playerId);
  }


  async pause() {
    if (!this.playerId) return;
    await YoutubePlayer.pauseVideo(this.playerId);
  }


  async loadVideo(videoId: string) {
    if (!this.playerId) return;
    await YoutubePlayer.loadVideoById(this.playerId, { videoId });
  }


  async loadPlaylist(playlistId: string) {
    if (!this.playerId) return;
    await YoutubePlayer.loadPlaylist(this.playerId, {
      listType: 'playlist',
      list: playlistId,
      index: 0
    });
  }


  async setQuality(quality: 'small' | 'medium' | 'large' | 'hd720' | 'hd1080') {
    if (!this.playerId) return;
    await YoutubePlayer.setPlaybackQuality(this.playerId, quality);
  }


  async getProgress() {
    if (!this.playerId) return { current: 0, duration: 0 };


    const current = await YoutubePlayer.getCurrentTime(this.playerId);
    const duration = await YoutubePlayer.getDuration(this.playerId);


    return {
      current: current.result.value,
      duration: duration.result.value
    };
  }


  async destroy() {
    if (!this.playerId) return;
    await YoutubePlayer.destroy(this.playerId);
    this.playerId = null;
  }
}

Estados del jugador

Section titled “Estados del jugador”
EstadoValorDescripción
SIN COMENZAR-1Vídeo no iniciado
TERMINADO0El vídeo ha finalizado
JUGANDO1El vídeo se está reproduciendo
EN PAUSA2El vídeo está en pausa
BÚFER3El vídeo se está almacenando en búfer
CUED5El vídeo tiene indicaciones

Niveles de calidad

Section titled “Niveles de calidad”
  • small: 240p
  • medium: 360p
  • large: 480p
  • hd720: 720p
  • hd1080: 1080p
  • highres: >1080p
  • default: Calidad automática

Mejores prácticas

Section titled “Mejores prácticas”

  1. Inicializar una vez Cree una instancia de jugador una vez y reutilícela:

    let player = await YoutubePlayer.initialize(options);
    // Reuse player for different videos
    await YoutubePlayer.loadVideoById(player, { videoId: 'NEW_ID' });

  2. Maneja los errores con elegancia

    YoutubePlayer.addEventListener(playerId, 'onError', (event) => {
      switch (event.data) {
        case 2:
          console.error('Invalid parameter');
          break;
        case 100:
          console.error('Video not found');
          break;
        case 101:
        case 150:
          console.error('Embedding not allowed');
          break;
      }
    });

  3. Limpiar Destruye al jugador cuando el componente se desmonta:

    useEffect(() => {
      return () => {
        if (playerId) {
          YoutubePlayer.destroy(playerId);
        }
      };
    }, []);

  4. Respeta las preferencias del usuario

    // Don't autoplay unless user initiated
    playerVars: {
      autoplay: 0
    }

  5. Monitorizar reproducción

    setInterval(async () => {
      const time = await YoutubePlayer.getCurrentTime(playerId);
      updateProgressBar(time.result.value);
    }, 1000);

Notas de plataforma

Section titled “Notas de plataforma”

iOS

Section titled “iOS”
  • Funciona en iOS 9.0+
  • Utiliza WKWebView con iframe de YouTube API
  • Compatible con pantalla completa

Android

Section titled “Android”
  • Funciona en Android 5.0 (API 21)+
  • Utiliza WebView con iframe de YouTube API
  • Compatible con pantalla completa

Web

Section titled “Web”
  • Integración directa de iframe de YouTube
  • Soporte completo para API
  • Mejor rendimiento

Solución de problemas

Section titled “Solución de problemas”

El reproductor no carga:

  • Verifique que la identificación del video sea válida
  • Verificar la conexión a Internet
  • Asegúrese de que se permita la incrustación de YouTube para el video.

Eventos que no se activan:

  • Asegúrese de que se agreguen oyentes después de la inicialización
  • Verifique que el reproductor esté listo antes de agregar oyentes

Problemas de calidad:

  • Verifique primero los niveles de calidad disponibles
  • Algunos videos no admiten todas las calidades.
  • Los cambios de calidad pueden no ser inmediatos