Jellyfin Android TV客户端SAMI字幕播放崩溃问题分析与解决方案

Jellyfin Android TV客户端SAMI字幕播放崩溃问题分析与解决方案

jellyfin-androidtv Android TV Client for Jellyfin 项目地址: https://gitcode.com/gh_mirrors/je/jellyfin-androidtv

问题现象

在Jellyfin Android TV客户端（版本0.18.2）中，当尝试播放带有SAMI格式字幕（*.smi文件）的视频时，内置播放器会出现崩溃现象。用户会连续收到两条提示信息："Player error encountered. Will re-try..."（播放器遇到错误，将重试）和"Too many errors. Giving up"（错误过多，放弃尝试）。该问题在Android TV 12系统的Chromecast设备上可稳定复现。

技术背景

SAMI（Synchronized Accessible Media Interchange）是微软开发的一种字幕格式，采用HTML-like的标记语言。与常见的SRT、ASS等字幕格式不同，SAMI支持更丰富的样式和排版控制，但在现代流媒体应用中已较少使用。

问题根源分析

通过技术排查发现问题的本质在于：

1. 字幕格式转换机制：Jellyfin服务端能正确识别SAMI格式不被客户端支持，会自动将其转换为WebVTT格式（通过/Videos/.../Subtitles/0/0/Stream.vtt接口提供）

2. 元数据标识错误：虽然服务端提供了转换后的WebVTT内容，但在媒体信息响应中仍将字幕流标记为原始格式（"Codec": "sami"），而非实际传输的WebVTT格式

3. 客户端处理逻辑：Android TV客户端根据元数据中的codec信息准备播放器配置，导致播放器尝试以SAMI格式解析实际为WebVTT的内容，最终引发解析失败

解决方案验证

测试表明以下两种方案可解决问题：

1. 服务端修复方案（推荐）：

   • 修改字幕流元数据返回逻辑，当进行格式转换时，应将Codec字段更新为目标格式（如WebVTT）
   • 保持Path字段记录原始文件路径即可

2. 客户端兼容方案：

   • 客户端可增加对转换后格式的识别逻辑
   • 当检测到DeliveryUrl包含".vtt"时，优先按WebVTT格式处理

临时应对措施

用户可采取以下临时解决方案：

1. 使用工具将SAMI字幕转换为SRT或ASS格式
2. 通过Jellyfin网页端预先转码视频（会生成兼容的字幕）
3. 在客户端设置中暂时禁用字幕显示

技术建议

对于多媒体应用开发，建议：

1. 实现格式转换时，元数据应与实际传输内容保持一致
2. 客户端应具备一定的格式自识别能力，作为元数据的补充验证
3. 对于老旧格式如SAMI，应考虑在服务端加入兼容性警告日志

该问题凸显了流媒体应用中元数据与内容一致性校验的重要性，特别是在格式转换场景下需要特别处理。通过修复服务端的元数据返回逻辑，可以最优雅地解决此类兼容性问题。

jellyfin-androidtv Android TV Client for Jellyfin 项目地址: https://gitcode.com/gh_mirrors/je/jellyfin-androidtv