Chromecast CAF3迁移求助：TTML+PNG字幕激活后无法显示

我之前帮朋友排查过类似的迁移问题，CAF3和v2在字幕渲染的底层逻辑差异确实挺坑的，给你几个实际验证过的排查方向：

• 先确认Shaka Player的字幕渲染配置是否适配CAF3
  旧版v2可能默认启用了TTML图片渲染，但CAF3环境下Shaka Player需要显式配置相关参数。试试在初始化播放器时加上这些配置：

  const player = new shaka.Player(videoElement);
  player.configure({
    // 确保使用内置的文本渲染工厂
    textDisplayFactory: shaka.text.TextDisplay.Factory,
    // 优先启用TTML解析器
    textParsers: ['ttml'],
    // 关闭不需要的字幕格式避免冲突
    enableWebVtt: false,
  });
  

  另外，检查TTML文件的格式是否符合CAF3的严格要求：比如<tt>标签必须带正确的命名空间xmlns="http://www.w3.org/ns/ttml"，<image>标签的xlink:href路径要确保是Chromecast能访问到的（绝对路径或者相对于媒体文件的正确相对路径）。

• 用远程调试工具深挖DOM渲染问题
  别只找隐藏div，用Chrome的chrome://inspect/#devices连接到你的Chromecast设备，直接看Elements面板：

  • 找带有shaka-text-container类的容器，确认它是否真的被插入到DOM中
  • 检查该容器的CSS属性：有没有被设置visibility: hidden、opacity: 0，或者z-index比视频层低导致被挡住？
  • 有时候CAF3的默认视频容器会加overflow: hidden，把超出视频区域的字幕裁剪掉，这时候可以调整字幕容器的position或者修改视频容器的overflow属性。

• 验证字幕轨道的识别和激活状态
  在播放器加载媒体后，在控制台打印player.getTextTracks()，看看输出的轨道信息：

  • 确认TTML轨道的active属性是true（你说能激活，这个大概率没问题，但还是要确认）
  • 检查轨道的kind、label是否正确，M3U8文件里的字幕轨道TYPE是否为SUBTITLES，CODECS是否指定为stpp（TTML的标准codec标识）。

• 排查资源加载和权限问题
  打开调试工具的Network面板，看看TTML文件和PNG图片是否成功加载：

  • 有没有CORS报错？CAF3对跨域资源的限制比v2严格，要确保服务器配置了正确的CORS头。
  • 有没有CSP（内容安全策略）阻止PNG加载？检查应用的CSP配置，是否允许加载data:或者外部域名的PNG资源。

• 尝试调整Shaka Player版本
  某些版本的Shaka Player和CAF3存在兼容性bug，比如我之前遇到过v4.2.x版本在CAF3下无法渲染TTML图片的情况，切换到v4.3.2就解决了。你可以试试降级到稳定版或者升级到最新版，同时看看Shaka Player的Release Notes里有没有针对CAF3字幕问题的修复。

如果以上方法都没解决，建议去Shaka Player的社区讨论区搜搜相关问题，很多开发者都分享过CAF3迁移的踩坑经验。

内容的提问来源于stack exchange，提问作者Franco Fantini