Video-Embed-Player-API

Mit unserer JavaScript-API kannst du den Embed-Player abhören und steuern. Unser iFrame-Player ist mit dem player.js-API-Standard von Embedly kompatibel.

1. Einrichtung

Binde zuerst die Bibliothek player.js in deine Seite ein:

CDN


<script type="text/javascript" src="//cdn.embed.ly/player-0.1.0.min.js"></script>

Initialisiere als Nächstes den Player mit deinem iframe:


// Get reference to your iframe element
const iframe = document.getElementById('your-iframe-id');
 
// Create player instance
const player = new playerjs.Player(iframe);
 
// Wait for player to be ready before interacting
player.on('ready', () => {
  console.log('Player is ready!');
  // Now you can safely use player methods
});

Warte immer auf das ready-Event, bevor du Player-Methoden aufrufst. Der Player reiht Nachrichten ein, bis ready ausgelöst wurde.

2. Events (Methoden)

Das sind die Methoden, die du am Player aufrufen kannst, um die Wiedergabe zu steuern:

Wiedergabe steuern

play() — Wiedergabe starten


player.play();

pause() — Wiedergabe pausieren


player.pause();

Lautstärke

mute() — Player stumm schalten


player.mute();

unmute() — Stummschaltung aufheben


player.unmute();

setVolume(volume) — Lautstärke setzen (0–100)


player.setVolume(50); // Set to 50%

Springen

setCurrentTime(seconds) — Zu einer bestimmten Zeit springen


player.setCurrentTime(30); // Seek to 30 seconds

Status abfragen

getPaused(callback) — Prüfen, ob der Player pausiert ist


player.getPaused((paused) => {
  console.log('Player is paused:', paused);
});

getMuted(callback) — Prüfen, ob der Player stumm ist


player.getMuted((muted) => {
  console.log('Player is muted:', muted);
});

getVolume(callback) — Aktuelle Lautstärke abrufen (0–100)


player.getVolume((volume) => {
  console.log('Current volume:', volume);
});

getDuration(callback) — Videodauer in Sekunden abrufen


player.getDuration((duration) => {
  console.log('Video duration:', duration, 'seconds');
});

getCurrentTime(callback) — Aktuelle Wiedergabezeit abrufen


player.getCurrentTime((time) => {
  console.log('Current time:', time, 'seconds');
});

Text tracks (Untertitel und Captions)

Die Methoden für Text tracks sind nicht Teil der integrierten player.js-Bibliothek. Du musst sie deshalb einmalig binden. Füge die folgende Hilfsfunktion hinzu und rufe sie in deinem ready-Handler auf:


function bindTextTrackMethods(player) {
  player.enableTextTrack = (value, callback) =>
    player.send({ method: 'enableTextTrack', value }, callback);
  player.disableTextTrack = () => player.send({ method: 'disableTextTrack' });
  player.getTextTracks = (callback) => player.send({ method: 'getTextTracks' }, callback);
  player.getTextTrack = (callback) => player.send({ method: 'getTextTrack' }, callback);
}
 
player.on('ready', () => {
  bindTextTrackMethods(player);
});

Es werden nur Text tracks der Typen Untertitel und Captions bereitgestellt. Kapitelspuren sind ausgeschlossen. Jede Spur ist ein Objekt mit den Feldern language, kind, label und mode.

getTextTracks(callback) — Alle verfügbaren Text tracks abrufen


player.getTextTracks((tracks) => {
  // [{ language, kind, label, mode }, ...]
  console.log('Available text tracks:', tracks);
});

getTextTrack(callback) — Aktiven Text track abrufen, oder null, wenn Text tracks aus sind


player.getTextTrack((track) => {
  console.log('Active text track:', track);
});

enableTextTrack(track, callback) — Einen Text track nach Sprache oder nach Sprache und Art aktivieren

Wenn du nur eine Sprache übergibst und diese auf mehrere Spuren passt, bevorzugt der Player eine exakte Sprachübereinstimmung und dann subtitles vor captions. Der optionale Callback erhält die aktivierte Spur.


// Enable by language
player.enableTextTrack('en');
 
// Enable by language and kind (when both exist for the same language)
player.enableTextTrack({ language: 'en', kind: 'captions' });
 
// Read the enabled track from the optional callback
player.enableTextTrack('en', (track) => {
  console.log('Enabled text track:', track);
});

disableTextTrack() — Text tracks ausschalten


player.disableTextTrack();

3. Listener (Events)

Das sind die Events, auf die du hören kannst, um Änderungen am Player-Status zu erkennen:

Basis-Events

ready — Wird ausgelöst, wenn der Player Befehle entgegennehmen kann


player.on('ready', () => {
  console.log('Player is ready for interaction');
});

play — Wird ausgelöst, wenn die Wiedergabe startet


player.on('play', () => {
  console.log('Playback started');
});

pause — Wird ausgelöst, wenn die Wiedergabe pausiert wird


player.on('pause', () => {
  console.log('Playback paused');
});

ended — Wird ausgelöst, wenn die Wiedergabe endet


player.on('ended', () => {
  console.log('Playback finished');
});

Fortschritt

timeupdate — Wird während der Wiedergabe mit aktueller Zeit und Dauer ausgelöst


player.on('timeupdate', (data) => {
  console.log('Current time:', data.seconds);
  console.log('Duration:', data.duration);
  
  // Calculate progress percentage
  const progress = (data.seconds / data.duration) * 100;
  console.log('Progress:', progress + '%');
});

progress — Wird beim Laden mit Puffer-Fortschritt ausgelöst


player.on('progress', (data) => {
  console.log('Buffering progress:', data.percent * 100 + '%');
});

Text-track-Events

texttrackchange — Wird ausgelöst, wenn sich der aktive Text track ändert, entweder über die API oder die Steuerelemente im Player


player.on('texttrackchange', (track) => {
  // `track` is the active track object, or null when text tracks are off
  console.log('Active text track:', track ? track.language : 'off');
});

texttrackerror — Wird ausgelöst, wenn enableTextTrack keine passende Spur findet


player.on('texttrackerror', (error) => {
  // error.name: 'InvalidTrackLanguageError' | 'InvalidTrackError'
  console.error('Text track error:', error.name);
});

Bei Livestreams werden Text tracks erst beim Laden des Manifests erkannt und sind direkt nach ready möglicherweise noch nicht verfügbar. Frage getTextTracks erneut ab, sobald die Wiedergabe gestartet ist, um später hinzukommende Spuren zu erfassen. Das texttrackchange-Event wird nur ausgelöst, wenn sich die aktive Spur ändert – verlass dich also nicht darauf, um neu erkannte Spuren zu finden.

Fehlerbehandlung

error — Wird ausgelöst, wenn ein Fehler auftritt


player.on('error', (error) => {
  console.error('Player error:', error);
});

Vollständiges Beispiel

Hier ein vollständiges Beispiel, wie du die Player-API einrichtest und nutzt:


// Initialize player
const iframe = document.getElementById('video-player');
const player = new playerjs.Player(iframe);
 
// Bind the text track methods (not part of the built-in player.js library)
function bindTextTrackMethods(player) {
  player.enableTextTrack = (value, callback) =>
    player.send({ method: 'enableTextTrack', value }, callback);
  player.disableTextTrack = () => player.send({ method: 'disableTextTrack' });
  player.getTextTracks = (callback) => player.send({ method: 'getTextTracks' }, callback);
  player.getTextTrack = (callback) => player.send({ method: 'getTextTrack' }, callback);
}
 
// Set up event listeners
player.on('ready', () => {
  console.log('Player ready!');
 
  bindTextTrackMethods(player);
 
  // Get initial state
  player.getDuration((duration) => {
    console.log('Video duration:', duration);
  });
  
  player.getVolume((volume) => {
    console.log('Current volume:', volume);
  });
 
  // List available text tracks
  player.getTextTracks((tracks) => {
    console.log('Text tracks:', tracks);
  });
});
 
player.on('play', () => {
  console.log('Started playing');
});
 
player.on('pause', () => {
  console.log('Paused');
});
 
player.on('timeupdate', (data) => {
  // Update progress bar
  const progress = (data.seconds / data.duration) * 100;
  document.getElementById('progress-bar').style.width = progress + '%';
});
 
player.on('ended', () => {
  console.log('Video finished');
});
 
player.on('texttrackchange', (track) => {
  console.log('Active text track:', track ? track.language : 'off');
});
 
player.on('texttrackerror', (error) => {
  console.error('Text track error:', error.name);
});
 
player.on('error', (error) => {
  console.error('Error:', error);
});
 
// Example control functions
function playVideo() {
  player.play();
}
 
function pauseVideo() {
  player.pause();
}
 
function setVolume(volume) {
  player.setVolume(volume);
}
 
function seekTo(seconds) {
  player.setCurrentTime(seconds);
}
 
function enableSubtitles(language) {
  player.enableTextTrack(language);
}
 
function disableSubtitles() {
  player.disableTextTrack();
}

Wenn du mehrere Player auf derselben Seite mit derselben src hast, kann es zu Inkonsistenzen kommen. Hänge deshalb an die src jedes iframes eine eindeutige Kennung (UUID oder Zeitstempel) an.