API 参考

M3U8 在线播放器的完整 API 参考文档。

播放器 API

播放器实例

创建播放器

// 创建播放器实例
const player = new M3U8Player(container, options);

参数:

container (HTMLElement): 播放器容器元素
options (Object): 播放器配置选项

返回值:

M3U8Player: 播放器实例

播放器配置选项

interface PlayerOptions {
  // 基本配置
  autoplay?: boolean; // 自动播放，默认 false
  muted?: boolean; // 静音状态，默认 false
  volume?: number; // 音量 (0-1)，默认 1
  controls?: boolean; // 显示控制条，默认 true
  preload?: 'none' | 'metadata' | 'auto'; // 预加载策略，默认 'metadata'
  loop?: boolean; // 循环播放，默认 false
  poster?: string; // 封面图片 URL
  width?: string | number; // 播放器宽度
  height?: string | number; // 播放器高度

  // HLS 配置
  hls?: HLSConfig; // HLS 特定配置

  // 事件回调
  onLoadStart?: () => void; // 开始加载回调
  onLoadedMetadata?: () => void; // 元数据加载完成回调
  onCanPlay?: () => void; // 可以播放回调
  onPlay?: () => void; // 开始播放回调
  onPause?: () => void; // 暂停播放回调
  onEnded?: () => void; // 播放结束回调
  onError?: (error: Error) => void; // 错误回调
  onTimeUpdate?: (time: number) => void; // 时间更新回调
  onVolumeChange?: (volume: number) => void; // 音量变化回调
}

播放器方法

load(url: string): Promise

加载 M3U8 流。

// 加载流
await player.load('https://example.com/stream.m3u8');

参数:

url (string): M3U8 流 URL

返回值:

Promise<void>: 加载完成的 Promise

异常:

LoadError: 加载失败时抛出

play(): Promise

开始播放。

// 开始播放
await player.play();

返回值:

Promise<void>: 播放开始的 Promise

异常:

PlayError: 播放失败时抛出

pause(): void

暂停播放。

// 暂停播放
player.pause();

stop(): void

停止播放并重置播放器。

// 停止播放
player.stop();

seek(time: number): void

跳转到指定时间。

// 跳转到 30 秒
player.seek(30);

参数:

time (number): 目标时间（秒）

setVolume(volume: number): void

设置音量。

// 设置音量为 50%
player.setVolume(0.5);

参数:

volume (number): 音量值 (0-1)

mute(): void

静音。

// 静音
player.mute();

unmute(): void

取消静音。

// 取消静音
player.unmute();

toggleMute(): void

切换静音状态。

// 切换静音状态
player.toggleMute();

enterFullscreen(): Promise

进入全屏模式。

// 进入全屏
await player.enterFullscreen();

返回值:

Promise<void>: 全屏模式进入完成的 Promise

exitFullscreen(): Promise

退出全屏模式。

// 退出全屏
await player.exitFullscreen();

返回值:

Promise<void>: 全屏模式退出完成的 Promise

toggleFullscreen(): Promise

切换全屏状态。

// 切换全屏状态
await player.toggleFullscreen();

返回值:

Promise<void>: 全屏状态切换完成的 Promise

播放器属性

currentTime: number

当前播放时间（秒）。

// 获取当前时间
const time = player.currentTime;
console.log(`当前时间: ${time} 秒`);

duration: number

媒体总时长（秒）。

// 获取总时长
const duration = player.duration;
console.log(`总时长: ${duration} 秒`);

paused: boolean

是否处于暂停状态。

// 检查暂停状态
if (player.paused) {
  console.log('播放器已暂停');
}

muted: boolean

是否处于静音状态。

// 检查静音状态
if (player.muted) {
  console.log('播放器已静音');
}

volume: number

当前音量 (0-1)。

// 获取当前音量
const volume = player.volume;
console.log(`当前音量: ${volume * 100}%`);

readyState: number

媒体就绪状态。

// 检查就绪状态
const readyState = player.readyState;
switch (readyState) {
  case 0:
    console.log('没有数据');
    break;
  case 1:
    console.log('有元数据');
    break;
  case 2:
    console.log('有当前数据');
    break;
  case 3:
    console.log('有未来数据');
    break;
  case 4:
    console.log('有足够数据');
    break;
}

networkState: number

网络状态。

// 检查网络状态
const networkState = player.networkState;
switch (networkState) {
  case 0:
    console.log('空闲');
    break;
  case 1:
    console.log('加载中');
    break;
  case 2:
    console.log('无数据');
    break;
  case 3:
    console.log('无源');
    break;
}

HLS API

HLS 实例

创建 HLS 实例

// 创建 HLS 实例
const hls = new Hls(config);

参数:

config (HLSConfig): HLS 配置选项

返回值:

Hls: HLS 实例

HLS 配置选项

interface HLSConfig {
  // 基本配置
  debug?: boolean; // 调试模式，默认 false
  enableWorker?: boolean; // 启用 Web Worker，默认 true
  lowLatencyMode?: boolean; // 低延迟模式，默认 false

  // 缓冲配置
  maxBufferLength?: number; // 最大缓冲长度（秒），默认 30
  maxMaxBufferLength?: number; // 最大缓冲上限（秒），默认 600
  backBufferLength?: number; // 后缓冲长度（秒），默认 90
  liveBackBufferLength?: number; // 直播后缓冲长度（秒），默认 0
  maxBufferHole?: number; // 最大缓冲空洞（秒），默认 0.5

  // 加载配置
  maxLoadingDelay?: number; // 最大加载延迟（秒），默认 4
  maxStarvationDelay?: number; // 最大饥饿延迟（秒），默认 4
  maxFragLookUpTolerance?: number; // 最大片段查找容差（秒），默认 0.25

  // 质量配置
  startLevel?: number; // 起始质量级别，默认 -1
  capLevelToPlayerSize?: boolean; // 根据播放器大小限制质量，默认 false
  capLevelOnFPSDrop?: boolean; // FPS 下降时限制质量，默认 false
  ignoreDevicePixelRatio?: boolean; // 忽略设备像素比，默认 false

  // 直播配置
  liveSyncDurationCount?: number; // 直播同步计数，默认 3
  liveMaxLatencyDurationCount?: number; // 最大延迟计数，默认 5
  maxLiveSyncPlaybackRate?: number; // 最大播放速率，默认 1.2
  liveDurationInfinity?: boolean; // 无限直播时长，默认 true

  // 其他配置
  highBufferWatchdogPeriod?: number; // 高缓冲监控周期（秒），默认 2
  nudgeOffset?: number; // 微调偏移（秒），默认 0.1
  nudgeMaxRetry?: number; // 最大微调重试次数，默认 3
  minAutoBitrate?: number; // 最小自动比特率，默认 0
  emeEnabled?: boolean; // 启用 EME，默认 false
  widevineLicenseUrl?: string; // Widevine 许可证 URL
  drmSystemOptions?: object; // DRM 系统选项
}

HLS 方法

loadSource(url: string): void

加载 HLS 源。

// 加载 HLS 源
hls.loadSource('https://example.com/stream.m3u8');

参数:

url (string): HLS 流 URL

attachMedia(media: HTMLMediaElement): void

将 HLS 实例附加到媒体元素。

// 附加到媒体元素
hls.attachMedia(videoElement);

参数:

media (HTMLMediaElement): 媒体元素

detachMedia(): void

从媒体元素分离 HLS 实例。

// 分离媒体元素
hls.detachMedia();

destroy(): void

销毁 HLS 实例。

// 销毁 HLS 实例
hls.destroy();

startLoad(): void

开始加载。

// 开始加载
hls.startLoad();

stopLoad(): void

停止加载。

// 停止加载
hls.stopLoad();

swapAudioCodec(): void

交换音频编解码器。

// 交换音频编解码器
hls.swapAudioCodec();

recoverMediaError(): void

恢复媒体错误。

// 恢复媒体错误
hls.recoverMediaError();

HLS 属性

levels: Level

可用的质量级别数组。

// 获取质量级别
const levels = hls.levels;
console.log('可用质量级别:', levels);

currentLevel: number

当前质量级别索引。

// 获取当前质量级别
const currentLevel = hls.currentLevel;
console.log('当前质量级别:', currentLevel);

loadLevel: number

加载的质量级别索引。

// 获取加载的质量级别
const loadLevel = hls.loadLevel;
console.log('加载的质量级别:', loadLevel);

nextLevel: number

下一个质量级别索引。

// 获取下一个质量级别
const nextLevel = hls.nextLevel;
console.log('下一个质量级别:', nextLevel);

startLevel: number

起始质量级别索引。

// 获取起始质量级别
const startLevel = hls.startLevel;
console.log('起始质量级别:', startLevel);

media: HTMLMediaElement

关联的媒体元素。

// 获取媒体元素
const media = hls.media;
console.log('媒体元素:', media);

url: string

当前加载的 URL。

// 获取当前 URL
const url = hls.url;
console.log('当前 URL:', url);

事件 API

播放器事件

事件监听

// 添加事件监听器
player.addEventListener('play', (event) => {
  console.log('开始播放');
});

// 移除事件监听器
player.removeEventListener('play', handler);

可用事件

// 播放器事件类型
type PlayerEventType =
  | 'loadstart' // 开始加载
  | 'loadedmetadata' // 元数据加载完成
  | 'loadeddata' // 数据加载完成
  | 'canplay' // 可以播放
  | 'canplaythrough' // 可以流畅播放
  | 'play' // 开始播放
  | 'pause' // 暂停播放
  | 'ended' // 播放结束
  | 'error' // 发生错误
  | 'timeupdate' // 时间更新
  | 'volumechange' // 音量变化
  | 'seeking' // 开始跳转
  | 'seeked' // 跳转完成
  | 'waiting' // 等待数据
  | 'playing' // 正在播放
  | 'ratechange' // 播放速率变化
  | 'durationchange' // 时长变化
  | 'progress' // 加载进度
  | 'abort' // 加载中止
  | 'emptied' // 媒体清空
  | 'stalled' // 加载停滞
  | 'suspend' // 加载暂停
  | 'loadstart' // 开始加载
  | 'loadedmetadata' // 元数据加载完成
  | 'loadeddata' // 数据加载完成
  | 'canplay' // 可以播放
  | 'canplaythrough' // 可以流畅播放
  | 'play' // 开始播放
  | 'pause' // 暂停播放
  | 'ended' // 播放结束
  | 'error' // 发生错误
  | 'timeupdate' // 时间更新
  | 'volumechange' // 音量变化
  | 'seeking' // 开始跳转
  | 'seeked' // 跳转完成
  | 'waiting' // 等待数据
  | 'playing' // 正在播放
  | 'ratechange' // 播放速率变化
  | 'durationchange' // 时长变化
  | 'progress' // 加载进度
  | 'abort' // 加载中止
  | 'emptied' // 媒体清空
  | 'stalled' // 加载停滞
  | 'suspend'; // 加载暂停

HLS 事件

HLS 事件监听

// 添加 HLS 事件监听器
hls.on(Hls.Events.MANIFEST_PARSED, (event, data) => {
  console.log('清单解析完成:', data);
});

可用 HLS 事件

// HLS 事件类型
type HLSEventType =
  | 'MANIFEST_LOADING' // 清单加载中
  | 'MANIFEST_LOADED' // 清单加载完成
  | 'MANIFEST_PARSED' // 清单解析完成
  | 'LEVEL_LOADING' // 级别加载中
  | 'LEVEL_LOADED' // 级别加载完成
  | 'LEVEL_UPDATED' // 级别更新
  | 'LEVEL_SWITCHED' // 级别切换
  | 'LEVEL_SWITCHING' // 级别切换中
  | 'FRAG_LOADING' // 片段加载中
  | 'FRAG_LOADED' // 片段加载完成
  | 'FRAG_PARSED' // 片段解析完成
  | 'FRAG_DECRYPTED' // 片段解密完成
  | 'FRAG_CHANGED' // 片段变化
  | 'FRAG_BUFFERED' // 片段缓冲完成
  | 'FRAG_INSERTED' // 片段插入
  | 'FRAG_DISCONTINUITY' // 片段不连续
  | 'FRAG_LOAD_EMERGENCY_ABORTED' // 片段加载紧急中止
  | 'ERROR' // 发生错误
  | 'DESTROYING' // 正在销毁
  | 'MEDIA_ATTACHED' // 媒体附加
  | 'MEDIA_DETACHED' // 媒体分离
  | 'BUFFER_APPENDED' // 缓冲追加
  | 'BUFFER_APPENDING' // 缓冲追加中
  | 'BUFFER_CODECS' // 缓冲编解码器
  | 'BUFFER_CREATED' // 缓冲创建
  | 'BUFFER_FLUSHED' // 缓冲刷新
  | 'BUFFER_FLUSHING' // 缓冲刷新中
  | 'BUFFER_RESET' // 缓冲重置
  | 'BUFFER_STALLED' // 缓冲停滞
  | 'BUFFER_STALLED_ERROR' // 缓冲停滞错误
  | 'BUFFER_STALLED_WARNING'; // 缓冲停滞警告

错误处理

错误类型

播放器错误

// 播放器错误类型
type PlayerErrorType =
  | 'MEDIA_ERR_ABORTED' // 媒体加载被中止
  | 'MEDIA_ERR_NETWORK' // 网络错误
  | 'MEDIA_ERR_DECODE' // 解码错误
  | 'MEDIA_ERR_SRC_NOT_SUPPORTED'; // 不支持的媒体源

HLS 错误

// HLS 错误类型
type HLSErrorType =
  | 'NETWORK_ERROR' // 网络错误
  | 'MEDIA_ERROR' // 媒体错误
  | 'MUX_ERROR' // 复用错误
  | 'OTHER_ERROR' // 其他错误
  | 'MANIFEST_LOAD_ERROR' // 清单加载错误
  | 'MANIFEST_LOAD_TIMEOUT' // 清单加载超时
  | 'MANIFEST_PARSING_ERROR' // 清单解析错误
  | 'LEVEL_LOAD_ERROR' // 级别加载错误
  | 'LEVEL_LOAD_TIMEOUT' // 级别加载超时
  | 'LEVEL_PARSING_ERROR' // 级别解析错误
  | 'FRAG_LOAD_ERROR' // 片段加载错误
  | 'FRAG_LOAD_TIMEOUT' // 片段加载超时
  | 'FRAG_DECRYPT_ERROR' // 片段解密错误
  | 'FRAG_PARSING_ERROR' // 片段解析错误
  | 'REMUX_ALLOC_ERROR' // 重复用分配错误
  | 'KEY_LOAD_ERROR' // 密钥加载错误
  | 'KEY_LOAD_TIMEOUT' // 密钥加载超时
  | 'KEY_SYSTEM_ERROR' // 密钥系统错误
  | 'BUFFER_ADD_CODEC_ERROR' // 缓冲添加编解码器错误
  | 'BUFFER_APPEND_ERROR' // 缓冲追加错误
  | 'BUFFER_APPENDING_ERROR' // 缓冲追加中错误
  | 'BUFFER_STALLED_ERROR' // 缓冲停滞错误
  | 'BUFFER_FULL_ERROR' // 缓冲满错误
  | 'BUFFER_SEEK_OVER_ERROR' // 缓冲跳转过错误
  | 'BUFFER_NUDGE_ON_STALL' // 缓冲停滞时微调
  | 'BUFFER_SEEK_OVER_BUFFER' // 缓冲跳转过缓冲
  | 'BUFFER_APPEND_OVER_BUFFER'; // 缓冲追加过缓冲

错误处理示例

// 播放器错误处理
player.addEventListener('error', (event) => {
  const error = event.error;
  console.error('播放器错误:', error);

  switch (error.code) {
    case 1: // MEDIA_ERR_ABORTED
      console.log('媒体加载被中止');
      break;
    case 2: // MEDIA_ERR_NETWORK
      console.log('网络错误');
      break;
    case 3: // MEDIA_ERR_DECODE
      console.log('解码错误');
      break;
    case 4: // MEDIA_ERR_SRC_NOT_SUPPORTED
      console.log('不支持的媒体源');
      break;
  }
});

// HLS 错误处理
hls.on(Hls.Events.ERROR, (event, data) => {
  console.error('HLS 错误:', data);

  if (data.fatal) {
    switch (data.type) {
      case Hls.ErrorTypes.NETWORK_ERROR:
        console.log('网络错误，尝试恢复...');
        hls.startLoad();
        break;
      case Hls.ErrorTypes.MEDIA_ERROR:
        console.log('媒体错误，尝试恢复...');
        hls.recoverMediaError();
        break;
      default:
        console.log('无法恢复的错误，销毁 HLS 实例');
        hls.destroy();
        break;
    }
  }
});

工具函数

时间格式化

// 时间格式化工具
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')}`;
  }
}

URL 验证

// URL 验证工具
function isValidM3U8URL(url) {
  try {
    const urlObj = new URL(url);
    return urlObj.protocol === 'http:' || urlObj.protocol === 'https:';
  } catch {
    return false;
  }
}

质量级别格式化

// 质量级别格式化工具
function formatQualityLevel(level) {
  if (level.height) {
    return `${level.height}p`;
  } else if (level.bitrate) {
    return `${Math.round(level.bitrate / 1000)}kbps`;
  } else {
    return `Level ${level.level}`;
  }
}

这个 API 参考文档提供了 M3U8 播放器的完整接口说明，包括所有可用的方法、属性、事件和配置选项。开发者可以根据这个参考文档来集成和使用播放器功能。

这个页面对您有帮助吗？

On this page

播放器 API HLS API 事件 API 错误处理工具函数