Mpegts.js

Mpegts.js 是一個基於 HTML5 和 Media Source Extensions (MSE) 的 JavaScript 播放器，用於播放 MPEG-TS 格式的流媒體。該庫適用於原生不支援 MPEG-TS 的現代瀏覽器（如 Chrome、Firefox 等）。

testMpeg(player, channelName)

描述

testMpeg 是一個被動監聽方法，主要針對指定頻道（channelName）中的多條串流線路（lines）進行監控，收集播放相關數據（例如：緩衝情況和下載速度）。這些數據將被傳送至數據中心，用於進一步分析，從而協助系統判斷最佳線路，並通過 getResourceUrl 方法取得該頻道中性能最好的線路。

⚠️ 注意事項

1. Mpegts.js 支援性
   確保 Mpegts.js 和 Media Source Extensions (MSE) 支援的環境下執行，以正常處理 MPEG-TS 串流。

2. 數據中心配置
   確保已經 connect，能夠接收和處理傳送的數據，否則無法使用 getResourceUrl 方法取得最佳線路。

3. 動態切換
   在獲取最佳線路後，應根據播放需求及緩衝情況實現動態切換，以避免播放中斷。

4. 回傳值為空的處理
   當 getResourceUrl 回傳值為空時，請確保已實作預設線路處理機制或提示用戶。

---

語法

testMpeg(player, channelName);

參數

名稱	類型	描述
player	Mpegts JS Object	必填，Mpegts.js 的實例化物件，用於處理 MPEG-TS 流。
channelName	String	必填，頻道名稱，用於標記或追蹤當前測試的頻道。

---

功能與用途

1. 線路監控與數據收集

   • 測試和監控指定頻道的多條線路播放狀況。
   • 收集每條線路的緩衝狀態、下載速度和錯誤次數等數據，傳送至數據中心。

2. 動態線路選擇

   • 數據收集完成後，可通過 getResourceUrl 方法獲取當前頻道中性能最好的線路，以便自動切換至最佳線路。

---

使用範例

1. 初始化監控

以下程式碼展示如何使用 testMpegts 監控指定頻道的播放狀況：

// 引入 Mpegts.js 並創建實例
import Mpegts from 'mpegts.js';
import JBLWebSocket from '@/assets/js/jbl.es.js';

const authorizationKey = ${Product authorization key};
const channelName = "MovieChannel";

// 建立與 WebSocket 的連接
JBLWebSocket.connect(authorizationKey, channelName);

// 檢查瀏覽器是否支持 Mpegts.js
if (Mpegts.getFeatureList().mseLivePlayback) {
    const player = Mpegts.createPlayer({
        type: 'mse', // 使用 MSE 播放
        isLive: true,
        url: 'https://example.com/movie_channel/live.mpegts',
    });

    // 將播放器綁定到 video 元素
    const videoElement = document.getElementById('video');
    player.attachMediaElement(videoElement);
    player.load();
    player.play();

    // 開始監控該頻道的播放情況
    JBLWebSocket.testMpeg(player, channelName);
} else {
    console.error('您的瀏覽器不支援 Mpegts.js！');
}

2. 獲取最佳線路 getResourceUrl

當數據中心累積足夠的數據後，開發者可以使用 getResourceUrl 方法取得最佳線路：

const bestLine = JBLWebSocket.getResourceUrl();

if (bestLine) {
    console.log(`最佳線路為：${bestLine}`);
    // 切換到最佳線路
    player.unload();
    player.load({
        type: 'mse',
        isLive: true,
        url: bestLine,
    });
    player.play();
} else {
    console.error("最佳線路為空，請開發者自行處理，例如設置預設線路或提示用戶。");
}

---

監控機制

1. 播放事件監聽

   • 監控 MPEG-TS 播放過程中的關鍵事件，例如緩衝開始、緩衝完成、播放錯誤等。

2. 數據上傳

   • 針對每條線路的下載速度、緩衝情況、錯誤次數等數據進行收集，並上傳至數據中心。

3. 最佳線路選擇

   • 數據中心會根據收集到的數據進行分析，計算出性能最好的線路，供 getResourceUrl 方法返回。

sendMpegErrCode(url, errorCode)

描述

sendMpegErrCode 方法允許使用者自訂數字型錯誤代碼，並將其作為參數附加至指定的伺服器 URL，傳送錯誤資訊以標記錯誤發生的時間。該錯誤代碼將被伺服器記錄，供 Dashboard 呈現，便於錯誤的追蹤與分析。

優點

• 透過數字型錯誤代碼提升可讀性與標準化程度。
• Dashboard 可直接解析並呈現錯誤類型及發生時間，便於問題定位與處理。
• 支援擴展性，方便開發者針對不同錯誤場景添加對應的錯誤代碼。

⚠️ 注意事項

1. 錯誤代碼類型
   確保傳入的 errorCode 是數字類型，否則方法將拒絕執行並提示錯誤。

2. 請求頻率控制
   為避免頻繁錯誤導致伺服器負載過高，建議實現節流機制，限制每秒上傳的錯誤次數。

---

語法

sendMpegErrCode(url, errorCode);

參數

名稱	類型	描述
url	String	必填，伺服器的 API 基底 URL，用於接收錯誤數據（將附加錯誤代碼與時間參數）。
errorCode	Number	必填，自訂數字型錯誤代碼，用於標記具體的錯誤類型或情境。

---

功能與用途

1. 自訂錯誤代碼

   • 使用者可自訂一個數字型錯誤代碼（如 1001 或 2002），用於標記錯誤發生的原因或類型。

2. 錯誤追蹤與分析

   • 錯誤資訊（包括數字型錯誤代碼與時間戳）將被記錄在伺服器上，並顯示於 Dashboard 中，便於進行問題診斷與頻率分析。

3. 即時記錄錯誤

   • 方法會自動將當前時間戳記附加至請求中，確保每次錯誤發生的時間被準確標記。

---

使用範例

1. 傳送錯誤代碼到伺服器

import JBLWebSocket from '@/assets/js/jbl.es.js';

const authorizationKey = ${Product authorization key};
const channelName = "MovieChannel";

// 建立與 WebSocket 的連接
JBLWebSocket.connect(authorizationKey, channelName);

// 定義伺服器 URL 和錯誤代碼
const serverUrl = 'https://example.com/api/log-error';
const errorCode = 1001; // 自訂數字型錯誤代碼

// 發送錯誤代碼
JBLWebSocket.sendMpegErrCode(serverUrl, errorCode);

2. 在播放過程中自訂錯誤代碼

player.on(Mpegts.Events.ERROR, (type, details, data) => {
    console.error('播放錯誤:', type, details, data);

    // 自訂錯誤代碼，根據錯誤類型決定
    const errorCode = type === 'networkError' ? 1001 : 2001;

    // 傳送錯誤代碼到伺服器
    JBLWebSocket.sendMpegErrCode('https://example.com/api/log-error', errorCode);
});

getMpegBuffer()

描述

getMpegBuffer 方法用於獲取當前 MPEG 視頻播放的緩衝區數據資訊（如已緩衝數據大小、緩衝進度等），便於開發者進行調試或播放狀態監控。

⚠️ 注意事項

• 在播放器初始化並載入數據後才能正確調用此方法。
• 確保視頻緩衝區支持標準 API 接口來提供必要的數據。

---

語法

const bufferInfo = getMpegBuffer();

返回值

名稱	類型	描述
bufferInfo	Object	包含當前視頻緩衝資訊的物件，包括緩衝區範圍和已緩衝數據大小。

bufferInfo 返回物件結構

{
    buffered: Number, // 總緩衝數據大小（以秒計）
    newBuffer: Number, // 當前播放時間（以秒計）
    oldBuffer: Number, // 緩衝區範圍
}

---

使用範例

以下程式碼展示如何使用 getMpegBuffer 獲取緩衝區資訊：

// 獲取當前緩衝資訊
const bufferInfo = getMpegBuffer();

if (bufferInfo) {
    console.log('緩衝範圍:', bufferInfo.bufferedRanges);
    console.log('總緩衝數據:', bufferInfo.totalBuffered, '秒');
    console.log('當前播放時間:', bufferInfo.currentTime, '秒');
} else {
    console.error('無法獲取緩衝資訊，請檢查播放器狀態。');
}

---

功能與用途

1. 播放狀態監控

   • 獲取當前視頻緩衝數據，用於實時監控播放狀態（如卡頓或緩衝不足等問題）。

2. 性能調試

   • 用於開發或測試環境下的緩衝分析，協助定位性能瓶頸或優化播放體驗。

---

整體流程

1. 使用 testMpegts 方法開始監控頻道內的多條線路播放狀況。
2. 數據上傳至數據中心，進行分析與記錄。
3. 當需要更高效的播放性能時，通過 getResourceUrl 方法獲取最佳線路並切換。

透過這個流程，開發者可以實現對 MPEG-TS 流媒體的高效監控與動態調整，提升用戶體驗。