API osadzonego playera wideo

Możesz użyć naszego API JavaScript, żeby nasłuchiwać zdarzeń i sterować playerem osadzonym. Player w iframe jest zgodny ze standardem player.js API od Embedly.

1. Konfiguracja

Najpierw dołącz bibliotekę player.js na stronie:

CDN


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

Potem zainicjuj player z twoim 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
});

Zawsze czekaj na zdarzenie ready, zanim wywołasz metody playera. Player kolejkuje wiadomości do momentu wywołania ready.

2. Zdarzenia (metody)

To metody, które możesz wywołać na playerze, żeby sterować odtwarzaniem:

Sterowanie odtwarzaniem

play() — start odtwarzania


player.play();

pause() — wstrzymanie


player.pause();

Głośność

mute() — wyciszenie


player.mute();

unmute() — wyłączenie wyciszenia


player.unmute();

setVolume(volume) — ustawienie głośności (0–100)


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

Przewijanie

setCurrentTime(seconds) — skok do wybranego czasu


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

Zapytania o stan

getPaused(callback) — czy player jest wstrzymany


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

getMuted(callback) — czy player jest wyciszony


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

getVolume(callback) — aktualna głośność (0–100)


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

getDuration(callback) — długość wideo w sekundach


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

getCurrentTime(callback) — aktualny czas odtwarzania


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

Text tracks (napisy i captions)

Metody Text tracks nie są częścią wbudowanej biblioteki player.js, więc musisz powiązać je raz. Dodaj poniższą funkcję pomocniczą i wywołaj ją w swoim handlerze ready:


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

Udostępniane są tylko Text tracks typu napisy i napisy zamknięte (captions). Ścieżki rozdziałów są wykluczone. Każda ścieżka to obiekt z polami language, kind, label i mode.

getTextTracks(callback) — wszystkie dostępne Text tracks


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

getTextTrack(callback) — aktywny Text track lub null, gdy Text tracks są wyłączone


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

enableTextTrack(track, callback) — włącz Text track według języka lub według języka i rodzaju

Jeśli podasz tylko język i pasuje on do więcej niż jednej ścieżki, player preferuje dokładne dopasowanie języka, a następnie subtitles przed captions. Opcjonalny callback otrzymuje włączoną ścieżkę.


// 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() — wyłącz Text tracks


player.disableTextTrack();

3. Nasłuchiwanie (zdarzenia)

To zdarzenia, na które możesz nasłuchiwać przy zmianach stanu playera:

Podstawowe zdarzenia

ready — gdy player jest gotowy na komendy


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

play — gdy zaczyna się odtwarzanie


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

pause — gdy odtwarzanie jest wstrzymane


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

ended — gdy odtwarzanie się kończy


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

Zdarzenia postępu

timeupdate — podczas odtwarzania z aktualnym czasem i długością


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 — podczas ładowania z postępem buforowania


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

Zdarzenia Text track

texttrackchange — gdy zmienia się aktywny Text track, przez API lub elementy sterujące playera


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 — gdy enableTextTrack nie znajduje pasującej ścieżki


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

W przypadku transmisji na żywo ścieżki napisów są wykrywane w miarę ładowania manifestu i mogą nie być dostępne bezpośrednio po zdarzeniu ready. Po rozpoczęciu odtwarzania ponownie odpytaj getTextTracks, aby pobrać ścieżki pojawiające się później. Zdarzenie texttrackchange uruchamia się tylko wtedy, gdy zmienia się aktywna ścieżka, więc nie polegaj na nim przy wykrywaniu nowo znalezionych ścieżek.

Obsługa błędów

error — gdy wystąpi błąd


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

Pełny przykład

Kompletny przykład konfiguracji i użycia API playera:


// 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();
}

Jeśli na jednej stronie masz kilka playerów z tym samym src, mogą pojawić się niespójności. Żeby tego uniknąć, dopisz unikalny identyfikator (UUID lub znacznik czasu) do src każdego iframe.