Référence API
Référence complète de l'API du Lecteur M3U8 en Ligne.
API du Lecteur
Initialisation
Constructeur Player
const player = new M3U8Player(options);
Paramètres:
options
(Object): Options de configuration du lecteur
Options de configuration:
const options = {
container: '#player', // Sélecteur du conteneur du lecteur
autoplay: false, // Lecture automatique
muted: true, // État muet
preload: 'metadata', // Configuration de préchargement
width: '100%', // Largeur du lecteur
height: 'auto', // Hauteur du lecteur
controls: true, // Afficher les contrôles
fluid: true, // Responsive
responsive: true, // Support responsive
playbackRates: [0.5, 1, 1.25, 1.5, 2], // Vitesses de lecture
defaultPlaybackRate: 1, // Vitesse de lecture par défaut
language: 'fr', // Configuration de langue
techOrder: ['html5'], // Ordre de priorité des technologies
html5: {
vhs: {
overrideNative: true, // Remplacer HLS natif
enableLowInitialPlaylist: true,
smoothQualityChange: true,
handlePartialData: true,
},
},
};
Méthodes
load()
Charge un stream.
player.load(url);
Paramètres:
url
(String): URL du stream M3U8
Valeur de retour:
Promise
: Promise de chargement terminé
Exemple:
try {
await player.load('https://example.com/stream.m3u8');
console.log('Stream chargé avec succès');
} catch (error) {
console.error('Erreur lors du chargement du stream:', error);
}
play()
Démarre la lecture.
player.play();
Valeur de retour:
Promise
: Promise de démarrage de lecture
pause()
Met en pause la lecture.
player.pause();
currentTime()
Obtient ou définit le temps de lecture actuel.
// Obtenir le temps actuel
const currentTime = player.currentTime();
// Définir le temps
player.currentTime(120); // Définir à 2 minutes
duration()
Obtient la durée totale du stream.
const duration = player.duration();
volume()
Obtient ou définit le volume.
// Obtenir le volume (0.0 - 1.0)
const volume = player.volume();
// Définir le volume
player.volume(0.5); // Définir à 50%
muted()
Obtient ou définit l'état muet.
// Obtenir l'état muet
const isMuted = player.muted();
// Définir l'état muet
player.muted(true); // Couper le son
player.muted(false); // Remettre le son
paused()
Obtient l'état de pause.
const isPaused = player.paused();
ended()
Obtient l'état de fin.
const isEnded = player.ended();
readyState()
Obtient l'état de préparation du lecteur.
const readyState = player.readyState();
Valeurs de retour:
0
: HAVE_NOTHING - Aucune information1
: HAVE_METADATA - Avec métadonnées2
: HAVE_CURRENT_DATA - Avec données de frame actuelle3
: HAVE_FUTURE_DATA - Avec données de frame future4
: HAVE_ENOUGH_DATA - Avec données suffisantes
networkState()
Obtient l'état du réseau.
const networkState = player.networkState();
Valeurs de retour:
0
: NETWORK_EMPTY - État initial1
: NETWORK_IDLE - État inactif2
: NETWORK_LOADING - Chargement3
: NETWORK_NO_SOURCE - Aucune source
Événements
loadstart
Se déclenche quand le chargement du stream commence.
player.on('loadstart', () => {
console.log('Début du chargement du stream');
});
loadedmetadata
Se déclenche quand les métadonnées sont chargées.
player.on('loadedmetadata', () => {
console.log('Métadonnées chargées');
console.log('Durée:', player.duration());
});
loadeddata
Se déclenche quand le premier frame est chargé.
player.on('loadeddata', () => {
console.log('Premier frame chargé');
});
canplay
Se déclenche quand la lecture est possible.
player.on('canplay', () => {
console.log('Prêt à lire');
});
canplaythrough
Se déclenche quand le buffering est complet et qu'il est possible de lire jusqu'à la fin.
player.on('canplaythrough', () => {
console.log("Prêt à lire jusqu'à la fin");
});
play
Se déclenche quand la lecture commence.
player.on('play', () => {
console.log('Lecture démarrée');
});
pause
Se déclenche quand la lecture est mise en pause.
player.on('pause', () => {
console.log('Lecture en pause');
});
ended
Se déclenche quand la lecture se termine.
player.on('ended', () => {
console.log('Lecture terminée');
});
timeupdate
Se déclenche quand le temps de lecture est mis à jour.
player.on('timeupdate', () => {
const currentTime = player.currentTime();
const duration = player.duration();
const progress = (currentTime / duration) * 100;
console.log(`Progression: ${progress.toFixed(1)}%`);
});
volumechange
Se déclenche quand le volume change.
player.on('volumechange', () => {
console.log('Volume:', player.volume());
console.log('Muet:', player.muted());
});
error
Se déclenche quand une erreur se produit.
player.on('error', (error) => {
console.error('Erreur du lecteur:', error);
});
API HLS
Propriétés
hls
Accède à l'instance HLS.
const hls = player.hls;
hls.levels
Obtient les niveaux de qualité disponibles.
const levels = player.hls.levels;
console.log('Niveaux de qualité disponibles:', levels);
hls.currentLevel
Obtient ou définit le niveau de qualité actuel.
// Obtenir le niveau actuel
const currentLevel = player.hls.currentLevel;
// Définir le niveau
player.hls.currentLevel = 2; // Définir au troisième niveau
hls.nextLevel
Obtient ou définit le niveau de qualité suivant.
const nextLevel = player.hls.nextLevel;
hls.loadLevel
Obtient le niveau de qualité en cours de chargement.
const loadLevel = player.hls.loadLevel;
hls.bandwidth
Obtient la bande passante estimée.
const bandwidth = player.hls.bandwidth;
console.log('Bande passante estimée:', bandwidth, 'bps');
hls.startLevel
Obtient ou définit le niveau de qualité initial.
// Définir le niveau initial
player.hls.startLevel = 1;
Méthodes
hls.startLoad()
Démarre le chargement HLS.
player.hls.startLoad();
hls.stopLoad()
Arrête le chargement HLS.
player.hls.stopLoad();
hls.swapAudioCodec()
Échange le codec audio.
player.hls.swapAudioCodec();
hls.recoverMediaError()
Tente de récupérer d'une erreur de média.
player.hls.recoverMediaError();
Événements
hlsEvent
Surveille les événements liés à HLS.
player.on('hlsEvent', (event, data) => {
console.log('Événement HLS:', event, data);
});
levelLoaded
Se déclenche quand un niveau de qualité est chargé.
player.on('levelLoaded', (event, data) => {
console.log('Niveau de qualité chargé:', data);
});
levelSwitched
Se déclenche quand le niveau de qualité change.
player.on('levelSwitched', (event, data) => {
console.log('Niveau de qualité changé:', data);
});
fragLoaded
Se déclenche quand un fragment est chargé.
player.on('fragLoaded', (event, data) => {
console.log('Fragment chargé:', data);
});
API d'Événements
Ajouter des Écouteurs d'Événements
on()
Ajoute un écouteur d'événement.
player.on('eventName', callback);
Paramètres:
eventName
(String): Nom de l'événementcallback
(Function): Fonction de callback
off()
Supprime un écouteur d'événement.
player.off('eventName', callback);
one()
Ajoute un écouteur d'événement qui s'exécute une seule fois.
player.one('eventName', callback);
trigger()
Déclenche un événement manuellement.
player.trigger('customEvent', data);
Événements Personnalisés
qualitychange
Se déclenche quand la qualité change.
player.on('qualitychange', (event, data) => {
console.log('Changement de qualité:', {
from: data.from,
to: data.to,
reason: data.reason,
});
});
bufferwarning
Se déclenche quand le buffer est faible.
player.on('bufferwarning', (event, data) => {
console.log('Avertissement de buffer:', data);
});
Gestion des Erreurs
Types d'Erreur
MediaError
Erreur liée aux médias.
player.on('error', (error) => {
if (error.code === 1) {
console.log('Erreur de média: Abandonné');
} else if (error.code === 2) {
console.log('Erreur de média: Réseau');
} else if (error.code === 3) {
console.log('Erreur de média: Décodage');
} else if (error.code === 4) {
console.log('Erreur de média: Source non supportée');
}
});
HlsError
Erreur liée à HLS.
player.on('error', (error) => {
if (error.type === 'networkError') {
console.log('Erreur de réseau');
} else if (error.type === 'mediaError') {
console.log('Erreur de média');
}
});
Récupération d'Erreurs
Récupération Automatique
Le lecteur tente automatiquement de récupérer des erreurs.
player.on('error', (error) => {
console.log('Erreur survenue:', error);
// Le lecteur tente automatiquement de récupérer
});
Récupération Manuelle
Vous pouvez tenter de récupérer manuellement des erreurs.
player.on('error', (error) => {
if (error.type === 'mediaError') {
// Pour les erreurs de média, tenter une récupération manuelle
player.hls.recoverMediaError();
}
});
Fonctions Utilitaires
Format de Temps
formatTime()
Convertit les secondes en format de temps.
function formatTime(seconds) {
const hours = Math.floor(seconds / 3600);
const minutes = Math.floor((seconds % 3600) / 60);
const secs = Math.floor(seconds % 60);
if (hours > 0) {
return `${hours}:${minutes.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
} else {
return `${minutes}:${secs.toString().padStart(2, '0')}`;
}
}
// Exemple d'utilisation
const currentTime = player.currentTime();
console.log('Temps actuel:', formatTime(currentTime));
Gestion des Niveaux de Qualité
getQualityLevels()
Obtient les niveaux de qualité disponibles.
function getQualityLevels() {
return player.hls.levels.map((level, index) => ({
index: index,
height: level.height,
width: level.width,
bitrate: level.bitrate,
name: `${level.height}p`,
}));
}
const qualityLevels = getQualityLevels();
console.log('Niveaux de qualité disponibles:', qualityLevels);
setQualityLevel()
Définit le niveau de qualité.
function setQualityLevel(levelIndex) {
if (levelIndex >= 0 && levelIndex < player.hls.levels.length) {
player.hls.currentLevel = levelIndex;
console.log(`Niveau de qualité défini à ${levelIndex}`);
} else {
console.error('Niveau de qualité invalide');
}
}
Cette référence API vous permet d'exploiter toutes les fonctionnalités du Lecteur M3U8 en Ligne.