API 參考

M3U8 線上播放器的完整 API 參考。

播放器 API

初始化

Player 建構函式

const player = new M3U8Player(options);

參數:

options (Object): 播放器配置選項

配置選項:

const options = {
  container: '#player', // 播放器容器選擇器
  autoplay: false, // 自動播放
  muted: true, // 靜音狀態
  preload: 'metadata', // 預載設定
  width: '100%', // 播放器寬度
  height: 'auto', // 播放器高度
  controls: true, // 顯示控制項
  fluid: true, // 響應式
  responsive: true, // 響應式支援
  playbackRates: [0.5, 1, 1.25, 1.5, 2], // 播放速度
  defaultPlaybackRate: 1, // 預設播放速度
  language: 'zh-Hant', // 語言設定
  techOrder: ['html5'], // 技術優先順序
  html5: {
    vhs: {
      overrideNative: true, // 覆蓋原生 HLS
      enableLowInitialPlaylist: true,
      smoothQualityChange: true,
      handlePartialData: true,
    },
  },
};

方法

load()

載入串流。

player.load(url);

參數:

url (String): M3U8 串流的 URL

返回值:

Promise: 載入完成的 Promise

範例:

try {
  await player.load('https://example.com/stream.m3u8');
  console.log('串流載入成功');
} catch (error) {
  console.error('串流載入錯誤:', error);
}

play()

開始播放。

player.play();

返回值:

Promise: 播放開始的 Promise

pause()

暫停播放。

player.pause();

currentTime()

取得或設定當前播放時間。

// 取得當前時間
const currentTime = player.currentTime();

// 設定時間
player.currentTime(120); // 設定為 2 分鐘

duration()

取得串流的總時間。

const duration = player.duration();

volume()

取得或設定音量。

// 取得音量 (0.0 - 1.0)
const volume = player.volume();

// 設定音量
player.volume(0.5); // 設定為 50%

muted()

取得或設定靜音狀態。

// 取得靜音狀態
const isMuted = player.muted();

// 設定靜音狀態
player.muted(true); // 靜音
player.muted(false); // 取消靜音

paused()

取得暫停狀態。

const isPaused = player.paused();

ended()

取得播放結束狀態。

const isEnded = player.ended();

readyState()

取得播放器的準備狀態。

const readyState = player.readyState();

返回值:

0: HAVE_NOTHING - 無資訊
1: HAVE_METADATA - 有元數據
2: HAVE_CURRENT_DATA - 有當前幀數據
3: HAVE_FUTURE_DATA - 有未來幀數據
4: HAVE_ENOUGH_DATA - 有足夠數據

networkState()

取得網路狀態。

const networkState = player.networkState();

返回值:

0: NETWORK_EMPTY - 初始狀態
1: NETWORK_IDLE - 閒置狀態
2: NETWORK_LOADING - 載入中
3: NETWORK_NO_SOURCE - 無來源

事件

loadstart

串流載入開始時觸發。

player.on('loadstart', () => {
  console.log('串流載入開始');
});

loadedmetadata

元數據載入時觸發。

player.on('loadedmetadata', () => {
  console.log('元數據載入完成');
  console.log('總時間:', player.duration());
});

loadeddata

第一個幀載入時觸發。

player.on('loadeddata', () => {
  console.log('第一個幀載入完成');
});

canplay

可以播放時觸發。

player.on('canplay', () => {
  console.log('準備播放');
});

canplaythrough

緩衝完成且可以播放到結束時觸發。

player.on('canplaythrough', () => {
  console.log('準備播放到結束');
});

play

播放開始時觸發。

player.on('play', () => {
  console.log('播放開始');
});

pause

播放暫停時觸發。

player.on('pause', () => {
  console.log('播放暫停');
});

ended

播放結束時觸發。

player.on('ended', () => {
  console.log('播放結束');
});

timeupdate

播放時間更新時觸發。

player.on('timeupdate', () => {
  const currentTime = player.currentTime();
  const duration = player.duration();
  const progress = (currentTime / duration) * 100;
  console.log(`進度: ${progress.toFixed(1)}%`);
});

volumechange

音量變更時觸發。

player.on('volumechange', () => {
  console.log('音量:', player.volume());
  console.log('靜音:', player.muted());
});

error

發生錯誤時觸發。

player.on('error', (error) => {
  console.error('播放器錯誤:', error);
});

HLS API

屬性

hls

存取 HLS 實例。

const hls = player.hls;

hls.levels

取得可用的品質等級。

const levels = player.hls.levels;
console.log('可用品質等級:', levels);

hls.currentLevel

取得或設定當前品質等級。

// 取得當前等級
const currentLevel = player.hls.currentLevel;

// 設定等級
player.hls.currentLevel = 2; // 設定為第三個等級

hls.nextLevel

取得或設定下一個品質等級。

const nextLevel = player.hls.nextLevel;

hls.loadLevel

取得正在載入的品質等級。

const loadLevel = player.hls.loadLevel;

hls.bandwidth

取得預估頻寬。

const bandwidth = player.hls.bandwidth;
console.log('預估頻寬:', bandwidth, 'bps');

hls.startLevel

取得或設定開始品質等級。

// 設定開始等級
player.hls.startLevel = 1;

方法

hls.startLoad()

開始 HLS 載入。

player.hls.startLoad();

hls.stopLoad()

停止 HLS 載入。

player.hls.stopLoad();

hls.swapAudioCodec()

交換音頻編解碼器。

player.hls.swapAudioCodec();

hls.recoverMediaError()

嘗試從媒體錯誤中恢復。

player.hls.recoverMediaError();

事件

hlsEvent

監控 HLS 相關事件。

player.on('hlsEvent', (event, data) => {
  console.log('HLS 事件:', event, data);
});

levelLoaded

品質等級載入時觸發。

player.on('levelLoaded', (event, data) => {
  console.log('品質等級載入:', data);
});

levelSwitched

品質等級切換時觸發。

player.on('levelSwitched', (event, data) => {
  console.log('品質等級切換:', data);
});

fragLoaded

片段載入時觸發。

player.on('fragLoaded', (event, data) => {
  console.log('片段載入:', data);
});

事件 API

新增事件監聽器

on()

新增事件監聽器。

player.on('eventName', callback);

參數:

eventName (String): 事件名稱
callback (Function): 回調函式

off()

移除事件監聽器。

player.off('eventName', callback);

one()

新增只執行一次的事件監聽器。

player.one('eventName', callback);

trigger()

手動觸發事件。

player.trigger('customEvent', data);

自訂事件

qualitychange

品質變更時觸發。

player.on('qualitychange', (event, data) => {
  console.log('品質變更:', {
    from: data.from,
    to: data.to,
    reason: data.reason,
  });
});

bufferwarning

緩衝不足時觸發。

player.on('bufferwarning', (event, data) => {
  console.log('緩衝警告:', data);
});

錯誤處理

錯誤類型

MediaError

媒體相關錯誤。

player.on('error', (error) => {
  if (error.code === 1) {
    console.log('媒體錯誤: 中止');
  } else if (error.code === 2) {
    console.log('媒體錯誤: 網路');
  } else if (error.code === 3) {
    console.log('媒體錯誤: 解碼');
  } else if (error.code === 4) {
    console.log('媒體錯誤: 不支援的來源');
  }
});

HlsError

HLS 相關錯誤。

player.on('error', (error) => {
  if (error.type === 'networkError') {
    console.log('網路錯誤');
  } else if (error.type === 'mediaError') {
    console.log('媒體錯誤');
  }
});

錯誤恢復

自動恢復

播放器會自動嘗試從錯誤中恢復。

player.on('error', (error) => {
  console.log('發生錯誤:', error);
  // 播放器會自動嘗試恢復
});

手動恢復

可以手動嘗試從錯誤中恢復。

player.on('error', (error) => {
  if (error.type === 'mediaError') {
    // 媒體錯誤時嘗試手動恢復
    player.hls.recoverMediaError();
  }
});

工具函式

時間格式化

formatTime()

將秒數轉換為時間格式。

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

// 使用範例
const currentTime = player.currentTime();
console.log('當前時間:', formatTime(currentTime));

品質等級管理

getQualityLevels()

取得可用的品質等級。

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('可用品質等級:', qualityLevels);

setQualityLevel()

設定品質等級。

function setQualityLevel(levelIndex) {
  if (levelIndex >= 0 && levelIndex < player.hls.levels.length) {
    player.hls.currentLevel = levelIndex;
    console.log(`品質等級設定為 ${levelIndex}`);
  } else {
    console.error('無效的品質等級');
  }
}

這個 API 參考讓您能夠充分利用 M3U8 線上播放器的所有功能。

這個頁面對您有幫助嗎？

On this page

播放器 API HLS API 事件 API 錯誤處理工具函式