Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Luego usa el siguiente prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-youtube-player` plugin in my project.

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

bun add @capgo/capacitor-youtube-player
bunx cap sync

Importar

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

Inicio rápido

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

await YoutubePlayer.initialize({
  playerId: 'my-player',
  videoId: 'dQw4w9WgXcQ',
  playerSize: { width: 640, height: 360 },
  privacyEnhanced: true
});

Errores comunes

• Listeners: elimina los handles cuando se desmonten las pantallas.
• Inicializa una vez: ejecuta setup durante el bootstrap de la app.
• Fuente de verdad: confianza src/definitions.ts en el repo de GitHub.

Soluciona el bloqueo de Referer de YouTube en la WebView principal

Si YouTube funciona dentro del plugin pero falla cuando la misma app carga páginas, embeds o APIs de YouTube a través del WebView principal de Capacitor, habilita patchRefererHeader en tu configuración de Capacitor.

Cuando está habilitado, el plugin parchea Capacitor durante la sincronización/actualización para que las solicitudes de YouTube interceptadas incluyan un Referer header.

{
  "plugins": {
    "YoutubePlayer": {
      "patchRefererHeader": true,
      "refererHeader": "https://www.youtube.com"
    }
  }
}

• Solo youtube.com, youtube-nocookie.com, y youtu.be las solicitudes están afectadas.
• Las peticiones que ya definen una Referer cabecera conservan su valor original.
• refererHeader es opcional y por defecto es https://www.youtube.com.
• Compatible con Capacitor 8.x en las plataformas iOS y Android instaladas.

Resumen de API

initialize

Inicializa una nueva instancia del reproductor de YouTube.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

await YoutubePlayer.initialize({
  playerId: 'my-player',
  videoId: 'dQw4w9WgXcQ',
  playerSize: { width: 640, height: 360 },
  privacyEnhanced: true
});

destroy

Destruye una instancia del reproductor y libera recursos.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.destroy({ playerId: 'player-id-123' });
console.log(result);

stopVideo

Detén la reproducción del video y cancela la carga. Úsalo con moderación; normalmente se prefiere pauseVideo().

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.stopVideo({ playerId: 'player-id-123' });
console.log(result);

playVideo

Reproduce el video actualmente preparado o cargado. El estado final del reproductor será PLAYING (1).

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.playVideo({ playerId: 'player-id-123' });
console.log(result);

pauseVideo

Pausa el video que se está reproduciendo. El estado final del reproductor será PAUSED (2), a menos que ya esté ENDED (0).

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.pauseVideo({ playerId: 'player-id-123' });
console.log(result);

seekTo

Salta a un momento específico del video. Si el reproductor está en pausa, sigue en pausa. Si se está reproduciendo, continúa reproduciéndose.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.seekTo({
  playerId: 'player-id-123',
  seconds: 10,
  allowSeekAhead: true,
});
console.log(result);

loadVideoById

Carga y reproduce un video por su ID de YouTube.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.loadVideoById({
  playerId: 'player-id-123',
  options: { videoId: 'video-id-123' },
});
console.log(result);

cueVideoById

Cuea un video por ID sin reproducirlo. Carga la miniatura y prepara el reproductor, pero no solicita el video hasta que se llame a playVideo().

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.cueVideoById({
  playerId: 'player-id-123',
  options: { videoId: 'video-id-123' },
});
console.log(result);

loadVideoByUrl

Carga y reproduce un video por su URL completa.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.loadVideoByUrl({
  playerId: 'player-id-123',
  options: { mediaContentUrl: 'https://example.com' },
});
console.log(result);

cueVideoByUrl

Prepara un video por URL sin reproducirlo.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.cueVideoByUrl({
  playerId: 'player-id-123',
  options: { mediaContentUrl: 'https://example.com' },
});
console.log(result);

cuePlaylist

Cuea una lista de reproducción sin reproducirla. Carga la lista y prepara el primer video.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.cuePlaylist({
  playerId: 'player-id-123',
  playlistOptions: { listType: 'playlist' },
});
console.log(result);

loadPlaylist

Carga y reproduce una playlist.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.loadPlaylist({
  playerId: 'player-id-123',
  playlistOptions: { listType: 'playlist' },
});
console.log(result);

nextVideo

Reproduce el siguiente video de la playlist.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.nextVideo({ playerId: 'player-id-123' });
console.log(result);

previousVideo

Reproduce el video anterior de la playlist.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.previousVideo({ playerId: 'player-id-123' });
console.log(result);

playVideoAt

Reproduce un video específico de la playlist por su índice.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.playVideoAt({
  playerId: 'player-id-123',
  index: 1,
});
console.log(result);

mute

Silencia el audio del reproductor.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.mute({ playerId: 'player-id-123' });
console.log(result);

unMute

Activa el audio del reproductor.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.unMute({ playerId: 'player-id-123' });
console.log(result);

isMuted

Comprueba si el reproductor está silenciado.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.isMuted({ playerId: 'player-id-123' });
console.log(result);

setVolume

Establece el nivel de volumen del reproductor.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.setVolume({
  playerId: 'player-id-123',
  volume: 0.5,
});
console.log(result);

getVolume

Obtiene el nivel de volumen actual del reproductor. Devuelve el volumen aunque el reproductor esté silenciado.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getVolume({ playerId: 'player-id-123' });
console.log(result);

setSize

Establece las dimensiones del reproductor en píxeles.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.setSize({
  playerId: 'player-id-123',
  width: 1080,
  height: 1920,
});
console.log(result);

getPlaybackRate

Obtiene la velocidad de reproducción actual.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getPlaybackRate({ playerId: 'player-id-123' });
console.log(result);

setPlaybackRate

Establece la velocidad de reproducción.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.setPlaybackRate({
  playerId: 'player-id-123',
  suggestedRate: 1,
});
console.log(result);

getAvailablePlaybackRates

Obtén la lista de velocidades de reproducción disponibles para el video actual.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getAvailablePlaybackRates({ playerId: 'player-id-123' });
console.log(result);

setLoop

Activa o desactiva el bucle de la lista de reproducción. Cuando está activado, la lista se reinicia desde el principio tras el último vídeo.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.setLoop({
  playerId: 'player-id-123',
  loopPlaylists: true,
});
console.log(result);

setShuffle

Activa o desactiva el modo aleatorio de la playlist.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.setShuffle({
  playerId: 'player-id-123',
  shufflePlaylist: true,
});
console.log(result);

getVideoLoadedFraction

Obtén la fracción del video que se ha almacenado en búfer. Más fiable que getVideoBytesLoaded/getVideoBytesTotal, que están en desuso.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getVideoLoadedFraction({ playerId: 'player-id-123' });
console.log(result);

getPlayerState

Obtén el estado actual del reproductor.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getPlayerState({ playerId: 'player-id-123' });
console.log(result);

getAllPlayersEventsState

Get event states for all active players. Useful for tracking multiple player instances.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getAllPlayersEventsState();
console.log(result);

getCurrentTime

Obtén la posición actual de reproducción en segundos.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getCurrentTime({ playerId: 'player-id-123' });
console.log(result);

toggleFullScreen

Activa o desactiva el modo de pantalla completa.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.toggleFullScreen({
  playerId: 'player-id-123',
  isFullScreen: true,
});
console.log(result);

getPlaybackQuality

Obtén la calidad de reproducción actual.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getPlaybackQuality({ playerId: 'player-id-123' });
console.log(result);

setPlaybackQuality

Establece la calidad de reproducción sugerida. La calidad real puede variar según las condiciones de la red.

import { YoutubePlayer, IPlaybackQuality } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.setPlaybackQuality({
  playerId: 'player-id-123',
  suggestedQuality: IPlaybackQuality.SMALL,
});
console.log(result);

getAvailableQualityLevels

Obtén la lista de niveles de calidad disponibles para el video actual.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getAvailableQualityLevels({ playerId: 'player-id-123' });
console.log(result);

getDuration

Obtén la duración del video actual en segundos.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getDuration({ playerId: 'player-id-123' });
console.log(result);

getVideoUrl

Obtén la URL de YouTube.com del video actual.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getVideoUrl({ playerId: 'player-id-123' });
console.log(result);

getVideoEmbedCode

Obtén el embed code del video actual. Devuelve el embed code en un iframe HTML.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getVideoEmbedCode({ playerId: 'player-id-123' });
console.log(result);

getPlaylist

Obtén el array de IDs de video de la playlist actual.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getPlaylist({ playerId: 'player-id-123' });
console.log(result);

getPlaylistIndex

Obtén el índice del video que se está reproduciendo en la playlist.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getPlaylistIndex({ playerId: 'player-id-123' });
console.log(result);

getIframe

Obtén el elemento DOM del iframe para el reproductor. Solo en plataforma web.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getIframe({ playerId: 'player-id-123' });
console.log(result);

addEventListener

Añade un event listener al reproductor. Solo en plataforma web.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

YoutubePlayer.addEventListener({
  playerId: 'my-player',
  eventName: 'onStateChange',
  listener: (event) => {
  console.log('Player state:', event.data);
  },
});

removeEventListener

Elimina un event listener del reproductor. Solo en plataforma web.

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

await YoutubePlayer.removeEventListener({
  playerId: 'player-id-123',
  eventName: 'onReady',
  listener: (event) => {
    console.log(event);
  },
});

Referencia de tipos

PlayerIdOptions

export interface PlayerIdOptions {
  playerId: string;
}

SeekToOptions

export interface SeekToOptions extends PlayerIdOptions {
  playerId: string;
  seconds: number;
  allowSeekAhead: boolean;
}

VideoByIdMethodOptions

export interface VideoByIdMethodOptions extends PlayerIdOptions {
  playerId: string;
  options: IVideoOptionsById;
}

VideoByUrlMethodOptions

export interface VideoByUrlMethodOptions extends PlayerIdOptions {
  playerId: string;
  options: IVideoOptionsByUrl;
}

PlaylistMethodOptions

export interface PlaylistMethodOptions extends PlayerIdOptions {
  playerId: string;
  playlistOptions: IPlaylistOptions;
}

PlayVideoAtOptions

export interface PlayVideoAtOptions extends PlayerIdOptions {
  playerId: string;
  index: number;
}

SetVolumeOptions

export interface SetVolumeOptions extends PlayerIdOptions {
  playerId: string;
  volume: number;
}

SetSizeOptions

export interface SetSizeOptions extends PlayerIdOptions {
  playerId: string;
  width: number;
  height: number;
}

SetPlaybackRateOptions

export interface SetPlaybackRateOptions extends PlayerIdOptions {
  playerId: string;
  suggestedRate: number;
}

SetLoopOptions

export interface SetLoopOptions extends PlayerIdOptions {
  playerId: string;
  loopPlaylists: boolean;
}

SetShuffleOptions

export interface SetShuffleOptions extends PlayerIdOptions {
  playerId: string;
  shufflePlaylist: boolean;
}

ToggleFullScreenOptions

export interface ToggleFullScreenOptions extends PlayerIdOptions {
  playerId: string;
  isFullScreen: boolean | null | undefined;
}

Fuente de verdad

Esta página se genera a partir del plugin src/definitions.ts. Vuelve a ejecutar el sync cuando el API público cambie en upstream.

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar las operaciones del dashboard y de API, conéctalo con Uso de @capgo/capacitor-youtube-player para la capacidad nativa en Uso de @capgo/capacitor-youtube-player, Resumen de API para los detalles de implementación en API Overview, Introducción para los detalles de implementación en la Introducción, Claves de API para los detalles de implementación en las claves de API, y Dispositivos para el detalle de implementación en Devices.