使用VimeJs HLS播放m3u8视频时字幕无法显示的技术求助

问题描述 #

使用Vime.js的<Hls />组件播放m3u8流视频，同时从CDN加载VTT字幕文件时遇到以下问题：

• 同一VTT字幕搭配<Video />组件播放MP4时，视频正常播放且字幕可显示
• 同一VTT字幕搭配<Hls />组件播放m3u8时，视频可播放但字幕完全无法显示

怀疑是HLS时间戳同步问题，需要解决m3u8视频的VTT字幕显示问题。

相关代码 #

import React from "react";
import '@vime/core/themes/default.css';
import { Player, Ui, Video, Hls } from '@vime/react';

export default function App() {
  return (
    <Player controls>
      {/* Provider component is placed here. */}
      <FirstProvider />
      {/* <SecondProvider /> */}
      <Ui>{/* UI components are placed here. */}</Ui>
    </Player>
  );
}

const FirstProvider = () => (
  <Video crossOrigin="" poster="https://media.vimejs.com/poster.png">
    {/* These are passed directly to the underlying HTML5 `<video>` element. */}
    {/* Why `data-src`? Lazy loading, you can always use `src` if you prefer.  */}
    <source
      data-src="https://media.vimejs.com/720p.mp4"
      type="video/mp4"
    />

    <track
      default
      kind="subtitles"
      src="https://cc.2cdns.com/16/d6/16d6e74bf6ab3cc89cb80d523d0aea47/eng-2.vtt"
      srcLang="en"
      label="English"
    />
  </Video>
)

const SecondProvider = () => (
  <Hls crossOrigin="" poster="https://media.vimejs.com/poster.png">
    <source
      data-src="https://c-3.dokicloud.one/_v8/7e93e434d479b1e7d3468cb3859004cfceb53e8b4b8d625a2ed9b915c22bb21ececf7e991c74a3ab21ec244c564870dd9d62599850f1b17bd3bee2a52eef67e7667f713cdb84f7e4875c8168d43aa2ffe11da669f995a5ca61ee21475e66a307ae4c2a565adb930ee82922df63a5346e65480f90421c42c998808ab02bc7b760/playlist.m3u8"
      type="application/x-mpegURL"
    />
    <track
      default
      kind="subtitles"
      src="https://cc.2cdns.com/16/d6/16d6e74bf6ab3cc89cb80d523d0aea47/eng-2.vtt"
      srcLang="en"
      label="English"
    />
  </Hls>
)

问题原因 #

这确实和HLS的处理机制有关：Vime.js的<Hls />组件底层依赖hls.js库，原生<video>会直接读取<track>标签加载字幕，但hls.js不会自动识别<Hls />组件下的<track>标签，需要显式将字幕源注册到HLS实例中。时间戳同步问题仅在字幕加载后才可能出现，当前核心问题是字幕未被正确加载。

解决方案 #

方法1：手动注册字幕到HLS实例 #

通过useRef获取HLS组件实例，在组件挂载时手动添加字幕轨道：

import React, { useEffect, useRef } from "react";
import '@vime/core/themes/default.css';
import { Player, Ui, Hls } from '@vime/react';

export default function App() {
  return (
    <Player controls>
      <HlsWithSubtitles />
      <Ui></Ui>
    </Player>
  );
}

const HlsWithSubtitles = () => {
  const hlsRef = useRef(null);

  useEffect(() => {
    const hlsInstance = hlsRef.current?.hls;
    if (!hlsInstance) return;

    // 在HLS层级加载完成后添加字幕
    hlsInstance.addLevelLoadingListener(({ level }) => {
      if (level === -1) return;
      hlsInstance.addSubtitleTrack({
        url: "https://cc.2cdns.com/16/d6/16d6e74bf6ab3cc89cb80d523d0aea47/eng-2.vtt",
        type: 'vtt',
        lang: 'en',
        label: 'English',
        default: true
      });
    });

    // 组件卸载时销毁HLS实例
    return () => {
      hlsInstance?.destroy();
    };
  }, []);

  return (
    <Hls ref={hlsRef} crossOrigin="" poster="https://media.vimejs.com/poster.png">
      <source
        data-src="https://c-3.dokicloud.one/_v8/7e93e434d479b1e7d3468cb3859004cfceb53e8b4b8d625a2ed9b915c22bb21ececf7e991c74a3ab21ec244c564870dd9d62599850f1b17bd3bee2a52eef67e7667f713cdb84f7e4875c8168d43aa2ffe11da669f995a5ca61ee21475e66a307ae4c2a565adb930ee82922df63a5346e65480f90421c42c998808ab02bc7b760/playlist.m3u8"
        type="application/x-mpegURL"
      />
    </Hls>
  );
};

方法2：将字幕嵌入到HLS播放列表中 #

如果有权限修改m3u8文件，可以把VTT字幕作为字幕轨道添加到主播放列表，hls.js会自动识别加载。示例m3u8片段：

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="English",LANGUAGE="en",DEFAULT=YES,URI="你的VTT字幕地址"
#EXT-X-STREAM-INF:BANDWIDTH=1280000,RESOLUTION=1280x720,SUBTITLES="subs"
你的视频流地址.m3u8

方法3：检查跨域设置 #

确保VTT字幕的CDN服务器允许当前页面域名的跨域请求（响应头包含Access-Control-Allow-Origin）。虽然MP4能加载字幕说明跨域大概率没问题，但HLS加载字幕时的跨域检查可能更严格，建议确认。

内容的提问来源于stack exchange，提问作者Liam Anderson