Commencer

Installation

npm

npm install @capgo/capacitor-jw-player
npx cap sync

yarn

yarn add @capgo/capacitor-jw-player
npx cap sync

pnpm

pnpm add @capgo/capacitor-jw-player
npx cap sync

bun

bun add @capgo/capacitor-jw-player
npx cap sync

Prérequis

Vous aurez besoin d’un compte JW Player et d’une clé de licence pour utiliser ce plugin. Inscrivez-vous sur JW Player si vous n’en avez pas.

Configuration de la plateforme

iOS

Ajoutez votre clé de licence JW Player à votre Info.plist :

<key>JWPlayerLicenseKey</key>
<string>VOTRE_CLE_DE_LICENCE</string>

Android

Ajoutez votre clé de licence JW Player à android/app/src/main/res/values/strings.xml :

<resources>
    <string name="jw_player_license_key">VOTRE_CLE_DE_LICENCE</string>
</resources>

Exemple d’utilisation

import { JWPlayer } from '@capgo/capacitor-jw-player';

// Lire une seule vidéo
await JWPlayer.playVideo({
  mediaUrl: 'https://example.com/video.mp4',
  title: 'Ma vidéo',
  description: 'Description de la vidéo',
  poster: 'https://example.com/poster.jpg'
});

// Lire une playlist
await JWPlayer.playPlaylist({
  playlistUrl: 'https://example.com/playlist.json'
});

// Écouter les événements du lecteur
JWPlayer.addListener('playerReady', () => {
  console.log('Le lecteur est prêt');
});

JWPlayer.addListener('play', (data) => {
  console.log('La vidéo a commencé à jouer');
});

JWPlayer.addListener('pause', (data) => {
  console.log('Vidéo mise en pause');
});

JWPlayer.addListener('complete', (data) => {
  console.log('Lecture de la vidéo terminée');
});

JWPlayer.addListener('error', (error) => {
  console.error('Erreur du lecteur:', error);
});

Référence API

playVideo(options)

playVideo(options: VideoOptions) => Promise<void>

Lire une seule vidéo en mode plein écran.

Param	Type
options	VideoOptions

playPlaylist(options)

playPlaylist(options: PlaylistOptions) => Promise<void>

Lire une playlist en mode plein écran.

Param	Type
options	PlaylistOptions

pause()

pause() => Promise<void>

Mettre en pause la vidéo actuelle.

play()

play() => Promise<void>

Reprendre la lecture de la vidéo.

seek(options)

seek(options: { position: number }) => Promise<void>

Aller à une position spécifique dans la vidéo.

Param	Type
options	{ position: number }

setPlaybackSpeed(options)

setPlaybackSpeed(options: { speed: number }) => Promise<void>

Définir la vitesse de lecture.

Param	Type
options	{ speed: number }

setVolume(options)

setVolume(options: { volume: number }) => Promise<void>

Définir le volume audio (0.0 à 1.0).

Param	Type
options	{ volume: number }

selectAudioTrack(options)

selectAudioTrack(options: { trackIndex: number }) => Promise<void>

Sélectionner une piste audio par index.

Param	Type
options	{ trackIndex: number }

selectCaptionTrack(options)

selectCaptionTrack(options: { trackIndex: number }) => Promise<void>

Sélectionner une piste de sous-titres par index.

Param	Type
options	{ trackIndex: number }

stop()

stop() => Promise<void>

Arrêter la lecture et fermer le lecteur.

Interfaces

VideoOptions

Prop	Type	Description
mediaUrl	string	URL du fichier vidéo
title	string	Titre de la vidéo (optionnel)
description	string	Description de la vidéo (optionnel)
poster	string	URL de l’affiche/miniature (optionnel)
autoStart	boolean	Démarrage automatique de la lecture (optionnel, par défaut : true)

PlaylistOptions

Prop	Type	Description
playlistUrl	string	URL du JSON de playlist JW
autoStart	boolean	Démarrage automatique de la lecture (optionnel)

Écouteurs d’événements

Événements disponibles

• playerReady - Le lecteur est initialisé et prêt
• play - La lecture de la vidéo a commencé
• pause - La lecture de la vidéo est mise en pause
• complete - La lecture de la vidéo est terminée
• error - Le lecteur a rencontré une erreur
• seek - L’utilisateur s’est déplacé à une position différente
• time - Le temps de lecture a été mis à jour
• bufferChange - L’état du buffer a changé

Exemple d’événement

// Écouter les mises à jour du temps
JWPlayer.addListener('time', (data) => {
  console.log('Temps actuel:', data.position);
  console.log('Durée:', data.duration);
});

// Écouter les changements de buffer
JWPlayer.addListener('bufferChange', (data) => {
  console.log('Buffering:', data.buffering);
});

// Supprimer l'écouteur lorsque terminé
const listener = await JWPlayer.addListener('play', (data) => {
  console.log('En lecture');
});

// Plus tard...
listener.remove();

Utilisation avancée

Lecture avec sous-titres

await JWPlayer.playVideo({
  mediaUrl: 'https://example.com/video.mp4',
  title: 'Vidéo avec sous-titres',
  poster: 'https://example.com/poster.jpg',
  tracks: [
    {
      file: 'https://example.com/captions-en.vtt',
      label: 'Anglais',
      kind: 'captions'
    },
    {
      file: 'https://example.com/captions-es.vtt',
      label: 'Espagnol',
      kind: 'captions'
    }
  ]
});

Contrôles de lecture personnalisés

import { JWPlayer } from '@capgo/capacitor-jw-player';

// Commencer la lecture
await JWPlayer.play();

// Mettre en pause après 10 secondes
setTimeout(() => {
  JWPlayer.pause();
}, 10000);

// Aller à 30 secondes
await JWPlayer.seek({ position: 30 });

// Définir la vitesse de lecture à 1.5x
await JWPlayer.setPlaybackSpeed({ speed: 1.5 });

// Définir le volume à 50%
await JWPlayer.setVolume({ volume: 0.5 });

Bonnes pratiques

• Fournissez toujours une image d’affiche pour une meilleure expérience utilisateur
• Gérez les erreurs du lecteur de manière élégante avec des messages d’erreur appropriés
• Nettoyez les écouteurs d’événements lorsque le composant se démonte
• Testez la lecture vidéo sur les appareils iOS et Android
• Utilisez des formats vidéo appropriés (MP4 recommandé)
• Implémentez des états de chargement pendant l’initialisation de la vidéo
• Considérez les conditions réseau lors du streaming

Dépannage

La vidéo ne se lit pas

• Vérifiez que votre clé de licence JW Player est correcte
• Vérifiez que l’URL de la vidéo est accessible et valide
• Assurez-vous des en-têtes CORS appropriés si vous utilisez un serveur personnalisé
• Testez avec différents formats vidéo

Problèmes de plein écran

• Le plugin lit toujours en mode plein écran
• Assurez-vous des permissions appropriées pour le plein écran dans votre application

Performance

• Utilisez une qualité vidéo appropriée pour les appareils cibles
• Considérez le streaming adaptatif pour de meilleures performances
• Implémentez des indicateurs de buffering appropriés