Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

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

Importer

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

Démarrage rapide

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

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

Erreurs courantes

• Écouteurs: supprimez les handles lors du démontage des écrans.
• Initialiser une seule fois: exécutez le setup lors du bootstrap de l'app.
• Source de vérité : fiez-vous src/definitions.ts au repo GitHub.

Corriger le blocage du referer YouTube dans la WebView principale

Si YouTube fonctionne dans le plugin mais échoue lorsque la même application charge des pages, des embeds ou des API YouTube via la WebView principale de Capacitor, activez patchRefererHeader dans votre configuration Capacitor.

Une fois activé, le plugin patche Capacitor lors de la synchro/mise à jour pour que les requêtes YouTube interceptées incluent un Referer header valide.

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

• Seules les youtube.com, youtube-nocookie.com, et youtu.be requêtes sont concernées.
• Les requêtes qui définissent déjà un Referer header conservent leur valeur d'origine.
• refererHeader est optionnel et vaut par défaut https://www.youtube.com.
• Pris en charge sur Capacitor 8.x pour les plateformes iOS et Android installées.

Aperçu de API

initialize

Initialiser une nouvelle instance du lecteur YouTube.

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

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

destroy

Détruire une instance du lecteur et libérer les ressources.

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

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

stopVideo

Arrête la lecture de la vidéo et annule le chargement. À utiliser avec parcimonie — pauseVideo() est généralement préférable.

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

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

playVideo

Lisez la vidéo actuellement en file d'attente ou chargée.\nL'état final du lecteur sera PLAYING (1).

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

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

pauseVideo

Mets en pause la vidéo en cours de lecture.\nL'état final du player sera PAUSED (2), sauf s'il est déjà en état ENDED (0).

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

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

seekTo

Accéder à un moment précis de la vidéo. Si le lecteur est en pause, il reste en pause. S'il est en lecture, la lecture continue.

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

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

loadVideoById

Charger et lire une vidéo à partir de son ID 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

Déclencher une vidéo par ID sans la lire. Charge la miniature et prépare le lecteur, sans demander la vidéo avant l’appel de 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

Charger et lire une vidéo à partir de son URL complète.

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

Préparer une vidéo par URL sans la lire.

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

Préparer une playlist sans la lancer. Charge la playlist et prépare la première vidéo.

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

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

loadPlaylist

Charger et lire une playlist.

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

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

nextVideo

Lire la vidéo suivante de la playlist.

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

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

previousVideo

Lire la vidéo précédente de la playlist.

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

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

playVideoAt

Lire une vidéo précise de la playlist par son index.

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

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

mute

Couper le son du lecteur.

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

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

unMute

Réactiver le son du lecteur.

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

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

isMuted

Vérifier si le son du lecteur est actuellement coupé.

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

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

setVolume

Définit le niveau de volume du lecteur.

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

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

getVolume

Renvoie le niveau de volume actuel du lecteur. Renvoie le volume même si le lecteur est en sourdine.

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

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

setSize

Définit les dimensions du lecteur en pixels.

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

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

getPlaybackRate

Récupère la vitesse de lecture actuelle.

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

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

setPlaybackRate

Régler la vitesse de lecture.

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

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

getAvailablePlaybackRates

Récupérer la liste des vitesses de lecture disponibles pour la vidéo actuelle.

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

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

setLoop

Activez ou désactivez la boucle de la playlist. Lorsqu’elle est activée, la playlist repart du début après la dernière vidéo.

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

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

setShuffle

Enable or disable playlist shuffle.

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

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

getVideoLoadedFraction

Récupérez la fraction de la vidéo mise en mémoire tampon. Plus fiable que les fonctions obsolètes getVideoBytesLoaded/getVideoBytesTotal.

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

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

getPlayerState

Récupérez l'état actuel du player.

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

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

getAllPlayersEventsState

Récupérez l'état des événements pour tous les players actifs. Utile pour suivre plusieurs instances de player.

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

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

getCurrentTime

Récupérez la position de lecture actuelle en secondes.

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

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

toggleFullScreen

Activer ou désactiver le mode plein écran.

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

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

getPlaybackQuality

Récupérer la qualité de lecture actuelle.

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

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

setPlaybackQuality

Définir la qualité de lecture suggérée. La qualité réelle peut varier selon les conditions réseau.

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

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

getAvailableQualityLevels

Récupérer la liste des niveaux de qualité disponibles pour la vidéo actuelle.

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

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

getDuration

Récupérer la durée en secondes de la vidéo en cours.

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

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

getVideoUrl

Récupérer l'URL YouTube.com de la vidéo en cours.

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

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

getVideoEmbedCode

Récupérer le code d'intégration pour la vidéo en cours. Retourne le code d'intégration iframe HTML.

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

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

getPlaylist

Récupérer le tableau des ID des vidéos de la playlist actuelle.

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

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

getPlaylistIndex

Récupérez l'index de la vidéo en cours de lecture dans la playlist.

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

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

getIframe

Récupérez l'élément DOM de l'iframe pour le lecteur. Plateforme Web uniquement.

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

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

addEventListener

Ajoutez un écouteur d'événement au lecteur. Plateforme Web uniquement.

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

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

removeEventListener

Supprimez un écouteur d'événement du lecteur. Plateforme Web uniquement.

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

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

Référence de type

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

Source de vérité

Cette page est générée à partir de src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier les opérations du dashboard et de API, connectez-l’avec Utiliser @capgo/capacitor-youtube-player pour la capacité native dans Utiliser @capgo/capacitor-youtube-player, Aperçu de API pour les détails d'implémentation dans « Vue d'ensemble de API », Introduction pour les détails d'implémentation dans l'introduction, Clés API pour les détails d'implémentation dans « Clés API », et Appareils pour les détails d'implémentation dans Devices.