hls.js初始化、钩子函数及执行关系超完全解析(附代码)

if (Hls.isSupported()) {
  // 1. 配置参数（官方常用配置，按需调整）
  const hlsConfig = {
    startLevel: -1, // 自动选择清晰度
    maxBufferLength: 30, // 视频最大缓冲时长（秒）
    enableWorker: true, // 启用 Web Worker 解析
    backBufferLength: 90 // 后台缓冲保留时长（秒）
  };

  // 2. 创建 hls 实例
  const hls = new Hls(hlsConfig);
  const video = document.getElementById('videoPlayer');

  // 3. 绑定媒体元素（触发 MEDIA_ATTACHING → MEDIA_ATTACHED）
  hls.attachMedia(video);

  // 4. 监听媒体绑定成功事件，加载资源
  hls.on(Hls.Events.MEDIA_ATTACHED, () => {
    console.log('媒体元素绑定成功，加载 HLS 流');
    hls.loadSource('https://example.com/stream/main.m3u8'); // 加载主 m3u8
  });

  // 5. 可选：监听初始化相关事件
  hls.on(Hls.Events.MANIFEST_PARSED, (event, data) => {
    console.log('主 m3u8 解析完成，可用清晰度：', data.levels.length);
    video.play().catch(err => console.log('自动播放失败：', err));
  });

  // 6. 错误处理（按官方错误参数结构）
  hls.on(Hls.Events.ERROR, (event, data) => {
    if (data.fatal) {
      switch (data.type) {
        case Hls.ErrorTypes.NETWORK_ERROR:
          console.log('网络错误：', data.details, data.url);
          hls.startLoad(); // 重试加载
          break;
        case Hls.ErrorTypes.MEDIA_ERROR:
          console.log('媒体错误：', data.details);
          hls.recoverMediaError(); // 恢复媒体错误
          break;
        default:
          hls.destroy();
          break;
      }
    }
  });
} else if (video.canPlayType('application/vnd.apple.mpegurl')) {
  // 降级：浏览器原生支持 HLS（如 Safari）
  video.src = 'https://example.com/stream/main.m3u8';
  video.play();
}

MEDIA_ATTACHING → MEDIA_ATTACHED → 
MANIFEST_LOADING → MANIFEST_LOADED → MANIFEST_PARSED → 
LEVEL_LOADING（首个清晰度） → LEVEL_LOADED → LEVEL_UPDATED → 
FRAG_LOADING（首个片段） → FRAG_LOADED → FRAG_DECRYPTED（加密片段） → 
FRAG_PARSING_INIT_SEGMENT → FRAG_PARSED → 
BUFFER_APPENDING → BUFFER_APPENDED → FRAG_BUFFERED → 
（播放开始）

LEVEL_SWITCHING → BUFFER_RESET → 
LEVEL_LOADING（新清晰度） → LEVEL_LOADED → LEVEL_UPDATED → 
FRAG_LOADING（新清晰度首个片段） → FRAG_LOADED → ...（片段处理流程） → 
LEVEL_SWITCHED → FRAG_BUFFERED → （继续播放）

FRAG_CHANGED → FRAG_LOADING → FRAG_LOADED → 
（加密片段触发 KEY_LOADING → KEY_LOADED → FRAG_DECRYPTED） → 
FRAG_PARSED → BUFFER_APPENDING → BUFFER_APPENDED → FRAG_BUFFERED → 
（循环直到播放结束或切换清晰度）

ERROR（fatal: true） → 
（根据错误类型分支）
  - 网络错误：MANIFEST_LOADING/FRAG_LOADING（重试）
  - 媒体错误：BUFFER_RESET → FRAG_LOADING（重新加载片段）
  - 帧率下降：FPS_DROP → FPS_DROP_LEVEL_CAPPING → LEVEL_SWITCHING（降清晰度）
→ 错误恢复 → 回到对应流程继续播放

destroy() → DESTROYING → MEDIA_DETACHING → MEDIA_DETACHED

hls.on(Hls.Events.FRAG_LOADING, (event, data) => {
  console.log('片段开始加载：');
  console.log('完整请求 URL：', data.frag.url); // 如 https://.../lhg_segment_000.ts
  console.log('片段原始路径（m3u8中定义）：', data.frag.rawUrl); // 如 lhg_segment_000.ts
  console.log('目标缓冲时间：', data.targetBufferTime);
  console.log('所属清晰度 ID：', data.frag.level); // 通过片段对象获取清晰度 ID
});

hls.on(Hls.Events.FRAG_LOADED, (event, data) => {
  console.log('片段加载完成，大小：', data.payload.byteLength + ' 字节');
  console.log('加载耗时：', data.stats.loadTime + ' 毫秒');
});

hls.on(Hls.Events.LEVEL_SWITCHING, (event, data) => {
  console.log('切换清晰度：目标 ID =', data.level);
  console.log('目标清晰度码率：', data.bitrate / 1000 + 'kbps');
});

hls.on(Hls.Events.LEVEL_SWITCHED, (event, data) => {
  console.log('清晰度切换完成，当前 ID =', data.level);
  const currentLevel = hls.levels[data.level];
  console.log('当前清晰度分辨率：', currentLevel.width + 'x' + currentLevel.height);
});

hls.on(Hls.Events.KEY_LOADING, (event, data) => {
  console.log('开始加载密钥，对应片段：', data.frag.url);
});

hls.on(Hls.Events.KEY_LOADED, (event, data) => {
  console.log('密钥加载完成，片段即将解密：', data.frag.url);
});

完整事件列表如下：

- `Hls.Events.MEDIA_ATTACHING` - 在 MediaSource 附加到媒体元素之前触发
  - 数据：{ media: 媒体元素 }
- `Hls.Events.MEDIA_ATTACHED` - 当 MediaSource 成功附加到媒体元素时触发
  - 数据：{ media: 媒体元素 }
- `Hls.Events.MEDIA_DETACHING` - 在 MediaSource 从媒体元素分离之前触发
  - 数据：{ }
- `Hls.Events.MEDIA_DETACHED` - 当 MediaSource 从媒体元素分离后触发
  - 数据：{ }
- `Hls.Events.BUFFER_RESET` - 当缓冲区即将重置时触发
  - 数据：{ }
- `Hls.Events.BUFFER_CODECS` - 当确定需要为其创建缓冲区以推入数据的编解码器时触发
  - 数据：{ audio? : `[轨道对象数组]`, video? : `[轨道对象数组]` }
- `Hls.Events.BUFFER_CREATED` - 当源缓冲区（SourceBuffer）创建完成时触发
  - 数据：{ tracks : { audio? : `[轨道对象数组]`, video? : `[轨道对象数组]`, audiovideo?: `[轨道对象数组]` } }
    接口 Track { id: 'audio' | 'main'（轨道类型标识）, buffer?: SourceBuffer（关联的源缓冲区）, container: string（容器格式）, codec?: string（编解码器类型）, initSegment?: Uint8Array（初始化片段数据）, levelCodec?: string（层级编解码器信息）, metadata?: any（元数据） }
- `Hls.Events.BUFFER_APPENDING` - 当向缓冲区追加片段时触发
  - 数据：{ parent（父对象）, type（类型）, frag（片段对象）, part（分片对象）, chunkMeta（分片元数据）, data（数据内容） }
- `Hls.Events.BUFFER_APPENDED` - 当媒体片段成功追加到缓冲区后触发
  - 数据：{ parent : 触发 `BUFFER_APPENDING` 的播放列表类型, type（类型）, frag（片段对象）, part（分片对象）, chunkMeta（分片元数据）, timeRanges : { video?: 视频时间范围, audio?: 音频时间范围, audiovideo?: 音视频合并时间范围 } }
- `Hls.Events.BUFFER_EOS` - 当流结束且需通知媒体缓冲区不再有新数据时触发
  - 数据：{ type: 源缓冲区名称（SourceBufferName） }
- `Hls.Events.BUFFER_FLUSHING` - 当媒体缓冲区需要刷新时触发
  - 数据：{ startOffset（起始偏移量）, endOffset（结束偏移量）, type: 源缓冲区名称（SourceBufferName） }
- `Hls.Events.BUFFER_FLUSHED` - 当媒体缓冲区刷新完成后触发
  - 数据：{ type: 源缓冲区名称（SourceBufferName） }
- `Hls.Events.BACK_BUFFER_REACHED` - 当达到 [backBufferLength](#backbufferlength) 配置项定义的后缓冲区阈值时触发
  - 数据：{ bufferEnd: number（缓冲区结束位置时间戳） }
- `Hls.Events.MANIFEST_LOADING` - 标识清单文件（manifest）开始加载
  - 数据：{ url : 清单文件URL }
- `Hls.Events.MANIFEST_LOADED` - 清单文件加载完成后触发
  - 数据：{ levels : [可用的质量等级列表], audioTracks : [可用的音轨列表], captions? [可用的隐藏字幕媒体列表], subtitles?: [可用的字幕轨道列表], url : 清单文件URL, stats : [加载统计信息（LoaderStats）], sessionData: [解析后的 #EXT-X-SESSION-DATA 数据], networkDetails: [用于调试的加载器特定对象（XMLHttpRequest 或 fetch 响应对象）]}
- `Hls.Events.MANIFEST_PARSED` - 清单文件解析完成后触发
  - 数据：{ levels : [可用的质量等级列表 ], firstLevel : 清单中首次出现的质量等级索引, audioTracks（音轨列表）, subtitleTracks（字幕轨道列表）, stats（加载统计信息）, audio: boolean（是否包含音频）, video: boolean（是否包含视频）, altAudio: boolean（是否包含备用音频） }
- `Hls.Events.LEVEL_SWITCHING` - 当请求切换质量等级时触发
  - 数据：{ `level` 及等级对象属性（详见 [下方](#level) 说明） }
- `Hls.Events.LEVEL_SWITCHED` - 当质量等级切换生效后触发
  - 数据：{ level : 新等级的ID }
- `Hls.Events.LEVEL_LOADING` - 当请求加载等级播放列表时触发（除非它是通过 `hls.loadSource()` 加载的唯一媒体播放列表）
  - 数据：{ url : 等级播放列表URL, level : 正在加载的等级ID, deliveryDirectives: 低延迟HLS（LL-HLS）传输指令，若不支持阻塞重载则为 `null` }
- `Hls.Events.LEVEL_LOADED` - 等级播放列表加载完成后触发
  - 数据：{ details : [等级详情（LevelDetails）], level : 已加载等级的ID, stats : [加载统计信息（LoadStats）] }
- `Hls.Events.LEVEL_UPDATED` - 当等级加载完成后，基于历史详情更新该等级信息时触发
  - 数据：{ details : [等级详情（LevelDetails）], level : 已更新等级的ID }
- `Hls.Events.LEVEL_PTS_UPDATED` - 当解析片段后更新等级的PTS（演示时间戳）信息时触发
  - 数据：{ details : [等级详情（LevelDetails）], level : 已更新等级的ID, drift: 解析最后一个片段时观察到的PTS偏移量, type（类型）, start（起始时间）, end（结束时间） }
- `Hls.Events.LEVELS_UPDATED` - 调用 `removeLevel()` 移除某个等级后触发
  - 数据：{ levels : [可用的质量等级列表 ] }
- `Hls.Events.AUDIO_TRACKS_UPDATED` - 通知音轨列表已更新时触发
  - 数据：{ audioTracks : 音轨列表 }
- `Hls.Events.AUDIO_TRACK_SWITCHING` - 当请求切换音轨时触发
  - 数据：{ id : 音轨ID, type : 播放列表类型 ('AUDIO' | 'main'), url : 音轨URL }
- `Hls.Events.AUDIO_TRACK_SWITCHED` - 当音轨实际切换完成后触发
  - 数据：{ id : 音轨ID }
- `Hls.Events.AUDIO_TRACK_LOADING` - 音轨开始加载时触发
  - 数据：{ url : 音轨URL, id : 音轨ID }
- `Hls.Events.AUDIO_TRACK_LOADED` - 音轨加载完成后触发
  - 数据：{ details : [等级详情（LevelDetails）], id : 音轨ID, stats : [加载统计信息（LoadStats）] }
- `Hls.Events.SUBTITLE_TRACKS_UPDATED` - 通知字幕轨道列表已更新时触发
  - 数据：{ subtitleTracks : 字幕轨道列表 }
- `Hls.Events.SUBTITLE_TRACK_SWITCH` - 当字幕轨道切换时触发
  - 数据：{ id : 字幕轨道ID, type? : 播放列表类型 ('SUBTITLES' | 'CLOSED-CAPTIONS'（隐藏字幕）), url? : 字幕轨道URL }
- `Hls.Events.SUBTITLE_TRACK_LOADING` - 字幕轨道开始加载时触发
  - 数据：{ url : 字幕轨道URL, id : 字幕轨道ID } （原文此处字段描述有误，已修正为字幕相关）
- `Hls.Events.SUBTITLE_TRACK_LOADED` - 字幕轨道加载完成后触发
  - 数据：{ details : [等级详情（LevelDetails）], id : 字幕轨道ID, stats : [加载统计信息（LoadStats）] }
- `Hls.Events.SUBTITLE_FRAG_PROCESSED` - 当字幕片段处理完成后触发
  - 数据：{ success : boolean（处理是否成功）, frag : [已处理的片段对象], error?: [字幕解析错误信息（若有）] }
- `Hls.Events.INIT_PTS_FOUND` - 当找到第一个时间戳时触发
  - 数据：{ d : 解复用器ID, initPTS: 初始演示时间戳, timescale: 时间刻度, frag : 片段对象 }
- `Hls.Events.FRAG_LOADING` - 片段开始加载时触发
  - 数据：{ frag : 片段对象, targetBufferTime: number | null [期望通过该片段填充的缓冲区空白时间] }
- `Hls.Events.FRAG_LOAD_PROGRESS` - [已废弃]
- `Hls.Events.FRAG_LOAD_EMERGENCY_ABORTED` - 标识因紧急降级切换而中止片段加载
  - 数据：{ frag : 片段对象 }
- `Hls.Events.FRAG_LOADED` - 片段加载完成后触发
  - 数据：{ frag : 片段对象, payload : 片段数据负载, stats : [加载统计信息（LoadStats）]}
- `Hls.Events.FRAG_DECRYPTED` - 片段解密完成后触发
  - 数据：{ id : 解复用器ID, frag : 片段对象, payload : 片段数据负载, stats : { tstart（开始时间）, tdecrypt（解密耗时）}}
- `Hls.Events.FRAG_PARSING_INIT_SEGMENT` - 当从片段中提取初始化片段（Init Segment）后触发
  - 数据：{ id: 解复用器ID, frag : 片段对象, moov : MP4的moov盒数据, codecs : 解析片段时发现的编解码器信息 }
- `Hls.Events.FRAG_PARSING_USERDATA` - 当SEI（补充增强信息）文本解析完成后触发
  - 数据：{ id : 解复用器ID, frag: 片段对象, samples : [ SEI样本PES包 ], details: [等级详情（LevelDetails）] }
- `Hls.Events.FRAG_PARSING_METADATA` - 当ID3元数据解析完成后触发
  - 数据：{ id: 解复用器ID, frag : 片段对象, samples : [ ID3 PES包 - PTS和DTS时间戳为相对时间，单位为秒], details: [等级详情（LevelDetails）] }
- `Hls.Events.FRAG_PARSING_DATA` - [已废弃]
- `Hls.Events.FRAG_PARSED` - 片段解析完成后触发
  - 数据：{ frag : 片段对象, partIndex（分片索引） }
- `Hls.Events.FRAG_BUFFERED` - 当片段重新封装后的MP4盒数据全部追加到SourceBuffer后触发
  - 数据：{ id: 解复用器ID, frag : 片段对象, stats : [加载统计信息（LoadStats）] }
- `Hls.Events.FRAG_CHANGED` - 当与当前视频播放位置匹配的片段发生变化时触发
  - 数据：{ id : 解复用器ID, frag : 片段对象 }
- `Hls.Events.FPS_DROP` - 当最近监控周期内的帧率下降超过设定阈值时触发
  - 数据：{ curentDropped : 最近监控周期内的丢帧数, currentDecoded : 最近监控周期内的解码帧数, totalDroppedFrames : 该视频元素的总丢帧数 }（原文curentDropped拼写有误，已保留原字段名）
- `Hls.Events.FPS_DROP_LEVEL_CAPPING` - 当帧率下降触发自动质量等级限制时触发
  - 数据：{ level: 帧率控制器建议的新自动等级限制值, droppedLevel : 因丢帧过多将被限制的等级 }
- `Hls.Events.ERROR` - 错误事件标识
  - 数据：{ type : 错误类型, details : 错误详情, fatal : 错误是否致命, 其他错误相关数据 }
- `Hls.Events.DESTROYING` - 当 hls.js 实例开始销毁时触发。与 `MEDIA_DETACHED` 的区别在于：例如为了处理插播广告（mid-rolls），可能需要分离并重新附加视频到 hls.js 实例
  - 数据：{ }
- `Hls.Events.KEY_LOADING` - 解密密钥开始加载时触发
  - 数据：{ frag : 片段对象 }
- `Hls.Events.KEY_LOADED` - 解密密钥加载完成后触发
  - 数据：{ frag : 片段对象 }
- `Hls.Events.STREAM_STATE_TRANSITION` - [已废弃]
- `Hls.Events.NON_NATIVE_TEXT_TRACKS_FOUND` - 当 `renderTextTracksNatively` 设为 `false` 时，发现新的隐藏字幕或字幕轨道时触发（替代向视频元素添加 TextTrack 的行为）
  - 数据：{ tracks: 轨道数组<{ label（轨道标签）, kind（轨道类型）, default（是否默认轨道）, subtitleTrack（字幕轨道对象）}> }
- `Hls.Events.CUES_PARSED` - 当 `renderTextTracksNatively` 设为 `false` 时，解析到新的隐藏字幕或字幕提示（cues）时触发
  - 数据：{ type（类型）, cues（提示信息列表）, track（所属轨道） }