Shaka Player v2.2 升级至 v2.4 完整指南API 迁移、配置变更与重试机制详解【免费下载链接】shaka-playerJavaScript player library / DASH HLS client / MSE-EME player项目地址: https://gitcode.com/GitHub_Trending/sh/shaka-player本文是面向应用开发者的 Shaka Player 从 v2.2 升级到 v2.4 的详细迁移指南覆盖 HLS 起始时间配置移除、文本解析/显示插件 API 重写、离线存储删除接口变更、流失败重试回调机制、语言与角色选择、网络层可中止操作IAbortableOperation以及 Manifest 解析器相关 API 调整等全部破坏性变更。读完本文你将掌握每个变更点的迁移步骤、可直接复制的升级代码示例以及对应的源码实现依据能够在升级后快速定位并修复自己的应用代码。v2.4 带来了哪些新能力相比 v2.2Shaka Player v2.4 引入了一系列播放能力与工程体验上的改进主要包括HLS 直播流支持并支持起始时间不为 t0 的 HLS VOD 流MPEG-2 TS 内容可被转封装transmux为 MP4从而在所有浏览器上播放字幕仅在显示时才被拉取流式传输Captions are not streamed until shown减少带宽浪费使用NetworkInformation API获取初始带宽估计官方 Demo 应用升级为渐进式 Web 应用PWA可离线使用支持 TS 内容中的CEA 字幕支持TTML 与 VTT 区域region的精确表示构造Player时不再强制要求传入 video 元素新增attach()与detach()方法管理播放器与 video 元素的绑定关系Fetch 优先于 XHR发起网络请求网络请求支持中止abort直播流可从偏离直播边缘的负偏移位置开始播放。这些能力中的多项如 TS 转封装、请求中止、字幕按需拉取都依赖下文要讲的 API 变更因此在升级时务必同步迁移应用代码。HLS 起始时间配置移除自动从分片提取v2.2 中对于起始时间不为 t0 的 HLS VOD 内容应用需要显式配置manifest.hls.defaultTimeOffset告知播放器正确的内容起始时间。该配置在 v2.4 中已被移除。v2.4 会自动从分片segments本身提取 HLS 内容的起始时间无需任何配置。如果你的应用仍在调用player.configure({manifest: {hls: {defaultTimeOffset: ...}}})请在升级时删除这段配置。这一能力背后的实现可参考 lib/media/presentation_timeline.js 中的setUserSeekStart(time)方法由 lib/player.js 在解析到播放范围起始时间后调用它设置用户可定义的 seek 范围起点并仅用于 VOD 内容与getSegmentAvailabilityStart()共同决定可用分片的起始边界。自动提取的起始时间最终会落到这一时间轴上。文本解析插件TextParserAPI 变更文本解析插件TextParser的 API 在 v2.4 中发生变化所有应用自定义的文本解析插件都必须更新v2.4 不提供向后兼容。核心变化是插件接收的数据类型由ArrayBuffer改为Uint8Array这一改动让库内部得以优化并避免缓冲区拷贝。// v2.2 /** * param {!ArrayBuffer} data * param {shakaExtern.TextParser.TimeContext} timeContext * return {!Array.!shaka.text.Cue} */ MyTextParser.prototype.parseMedia function(data, timeContext) {}; // v2.4 /** * param {!Uint8Array} data * param {shakaExtern.TextParser.TimeContext} timeContext * return {!Array.!shaka.text.Cue} */ MyTextParser.prototype.parseMedia function(data, timeContext) {};同时timeContext中的segmentStart字段变为可空nullable。当该信息不可用时——例如在 HLS 场景下——你的插件会收到null作为segmentStart需要做好空值处理MyTextParser.prototype.parseMedia function(data, timeContext) { if (timeContext.segmentStart null) { // HLS 场景下起始时间可能不可用走兜底逻辑 } // ... };产生区域region信息的文本解析插件还需要改用新的shaka.text.CueRegion类。新结构能够更精确地同时表示 TTML 与 VTT 的区域信息。接口细节可参考 externs/shaka/text.js 中的shakaExtern.TextParser.prototype.parseInit与shakaExtern.TextParser.prototype.parseMedia定义。文本显示插件TextDisplayerAPI 变更文本显示插件TextDisplayer的 API 同样发生了变更。所有应用自定义的 TextDisplayer 插件都必须更新v2.4 不提供向后兼容。插件需要适配shakaExtern.CueRegion结构的调整——新的结构支持更精确地表示 TTML 与 VTT 区域。例如区域单位目前支持shaka.text.CueRegion.units.LINES行单位与PERCENTAGE百分比单位两种取值CEA-708 窗口定位就是通过把锚点相关值映射到CueRegion实现的参见 lib/cea/cea708_window.js。如果你的自定义显示插件直接操作旧的区域字段需要按新结构重新实现。区域结构的完整定义可查看shakaExtern.CueRegion位于 externs/shaka/text.js。离线存储Offline StorageAPI 变更v2.2 中shaka.offline.Storage的remove()方法接收一个StoredContent实例作为参数v2.4 改为接收StoredContent中的offlineUri字段。// v2.2: storage.list().then(function(storedContentList) { var someContent storedContentList[someIndex]; storage.remove(someContent); }); // v2.4: storage.list().then(function(storedContentList) { var someContent storedContentList[someIndex]; storage.remove(someContent.offlineUri); });旧参数在 v2.3 中被标记废弃并在 v2.4 中正式移除。所有使用离线存储的应用都必须更新到新 API。从源码看新实现位于 lib/offline/storage.jsremove(contentUri)接收字符串形式的contentUri随后通过shaka.offline.OfflineUri.parse(contentUri)解析并校验若 URI 不合法或不是 manifest 类型会抛出MALFORMED_OFFLINE_URI错误。删除内容时还会尝试释放对应的 DRM license。流失败后的重试机制从配置项到回调函数v2.1.3 引入了streaming.infiniteRetriesForLiveStreams配置来控制直播流的重试行为v2.2 又增加了更灵活的回调机制来为所有类型的流指定重试策略。到 v2.4该配置已被移除v2.2 标记废弃、v2.3 正式删除取而代之的是streaming.failureCallback。// v2.1 —— 直播流无限重试默认行为 player.configure({ streaming: { infiniteRetriesForLiveStreams: true // the default } }); // v2.4 —— 等价写法回调里判断直播并重试 player.configure({ streaming: { failureCallback: function(error) { // Always retry live streams: if (player.isLive()) player.retryStreaming(); } } }); // v2.1 —— 直播流不重试 player.configure({ streaming: { infiniteRetriesForLiveStreams: false // do not retry live } }); // v2.4 —— 等价写法回调里什么都不做停止尝试继续流式传输 player.configure({ streaming: { failureCallback: function(error) { // Do nothing, and we will stop trying to stream the content. } } });灵活决策结合 isLive()、错误码与其他条件player.retryStreaming()可在失败后随时调用以重试。你可以基于player.isLive()、error.code或任何其他条件决定是否重试。由于retryStreaming()可在任意时刻调用你甚至可以把决策推迟到收到用户反馈、浏览器恢复联网等时机。几个典型回调示例function neverRetryCallback(error) {} function alwaysRetryCallback(error) { player.retryStreaming(); } function retryOnSpecificHttpErrorsCallback(error) { if (error.code shaka.util.Error.Code.BAD_HTTP_STATUS) { var statusCode error.data[1]; var retryCodes [ 502, 503, 504, 520 ]; if (retryCodes.indexOf(statusCode) 0) { player.retryStreaming(); } } }如果你选择响应error事件而不是 failure 回调可以通过event.preventDefault()完全绕过回调player.addEventListener(error, function(event) { // Custom logic for error events if (player.isLive() event.error.code shaka.util.Error.Code.BAD_HTTP_STATUS) { player.retryStreaming(); } // Do not invoke the failure callback for this event event.preventDefault(); });从源码看retryStreaming()定义于 lib/player.js其默认重试延迟为 0.1 秒并且只有在当前加载模式为MEDIA_SOURCE时才真正生效否则返回false。failure 回调的实际触发点位于 lib/media/streaming_engine.js即流媒体引擎在遭遇失败并经过退避等待backoff后会调用配置中的failureCallback并把错误对象传给它回调自身抛出的异常会被捕获并记入日志避免干扰播放器状态机。语言与角色选择在 v2.1 引入的语言选择方法基础上v2.4 新增了面向角色role的方法getAudioLanguagesAndRoles()与getTextLanguagesAndRoles()。它们以对象数组的形式返回语言/角色的组合并且语言选择方法支持用可选的第二个参数指定角色// v2.4: var languagesAndRoles player.getAudioLanguagesAndRoles(); for (var i 0; i languagesAndRoles.length; i) { var combo languagesAndRoles[i]; if (someSelector(combo)) { player.selectAudioLanguage(combo.language, combo.role); break; } }这种模式非常适合“根据某种偏好规则自动挑选一条带指定角色如注释音轨、导演评论的音轨或字幕轨”的场景例如在 UI 中列出所有可选项供用户勾选后调用selectAudioLanguage(language, role)/selectTextLanguage(language, role)完成切换。NetworkingEngine API 变更request() 返回可中止操作v2.2 中shaka.net.NetworkingEngine的request()方法直接返回一个 Promisev2.4 改为返回shakaExtern.IAbortableOperation实例该实例内含一个 Promise。所有通过NetworkingEngine发起应用级请求的代码 SHOULD 更新到新 API旧 API 的支持将在 v2.5 中移除// v2.2: player.getNetworkingEngine().request(type, request).then((response) { // ... }); // v2.4: let operation player.getNetworkingEngine().request(type, request); // Use operation.promise to get the response. operation.promise.then((response) { // ... }); // The operation can also be aborted on some condition. onSomeOtherCondition(() { operation.abort(); });为平滑过渡v2.4 的发布版本对request()的返回值额外提供了.then与.catch方法实现向后兼容。IAbortableOperation的推荐实现是工具类shaka.util.AbortableOperation见 lib/util/abortable_operation.js。它的构造函数接收底层操作的 Promise 与onAbort回调并对外暴露promise、aborted与abort()。其中abort()并非“取消”不撤销已完成的工作只是停止后续工作被中止的操作应以OPERATION_ABORTED错误码拒绝其 Promise。该工具类还提供了failed()、aborted()、completed()、notAbortable()等静态工厂方法与combine()、chain()等组合原语方便网络插件与上层逻辑复用。网络 scheme 插件 API 变更v2.4 同样调整了网络 scheme 插件负责特定 URI scheme 的请求的 API。所有应用级网络 scheme 插件 SHOULD 更新到新 API旧 API 支持将在 v2.5 中移除。变化有两处插件现在返回shakaExtern.IAbortableOperation实例推荐用shaka.util.AbortableOperation封装新增一个参数用于标识请求类型requestType。// v2.2 function fooPlugin(uri, request) { return new Promise((resolve, reject) { // ... }); } shaka.net.NetworkingEngine.registerScheme(foo, fooPlugin); // v2.4 function fooPlugin(uri, request, requestType) { let rejectCallback null; const promise new Promise((resolve, reject) { rejectCallback reject; // Use this if you have a need for it. Ignore it otherwise. if (requestType shaka.net.NetworkingEngine.RequestType.MANIFEST) { // ... } else { // ... } // ... }); const abort () { // Abort the operation. // ... // Reject the Promise. rejectCallback(new shaka.util.Error( shaka.util.Error.Severity.RECOVERABLE, shaka.util.Error.Category.NETWORK, shaka.util.Error.Code.OPERATION_ABORTED)); }; return new shaka.util.AbortableOperation(promise, abort); } shaka.net.NetworkingEngine.registerScheme(foo, fooPlugin);requestType的枚举值定义于 lib/net/networking_engine.js 的shaka.net.NetworkingEngine.RequestType覆盖MANIFEST、SEGMENT、LICENSE、TIMING等常用类型另有更细粒度的AdvancedRequestType。registerScheme(scheme, plugin, priority, progressSupport)也支持通过priority调整同一 scheme 下多个插件的优先级并在 v2.4 中增加了progressSupport参数以支持请求进度上报。Manifest 解析器插件 API 变更shaka.media.PresentationTimeline的 API 发生了变化使用以下方法的 ManifestParser 插件必须更新setAvailabilityStart()更名为setUserSeekStart()notifySegments()的参数由“周期起始时间 引用数组”改为“引用数组 布尔值isFirstPeriod”。其中setUserSeekStart(time)的当前实现位于 lib/media/presentation_timeline.js仅用于 VOD 内容其值会参与getSegmentAvailabilityStart()的计算取userSeekStart_与动态可用窗口起点中较大者直接影响播放器允许 seek 的最小时间点。升级自检清单对照下表逐项检查你的应用可避免在 v2.4 升级后踩坑变更点旧用法v2.2新用法v2.4是否破坏性HLS 起始时间manifest.hls.defaultTimeOffset配置自动从分片提取删除配置是TextParser 插件parseMedia(data /* ArrayBuffer */, timeContext)parseMedia(data /* Uint8Array */, timeContext)segmentStart可为null区域改用CueRegion是无兼容TextDisplayer 插件旧CueRegion结构新CueRegion结构支持 TTML/VTT 区域是无兼容离线存储删除storage.remove(storedContent)storage.remove(storedContent.offlineUri)是直播流重试streaming.infiniteRetriesForLiveStreamsstreaming.failureCallbackplayer.retryStreaming()是配置已移除语言/角色选择selectAudioLanguage(language)等新增getAudioLanguagesAndRoles()/getTextLanguagesAndRoles()选择方法支持 role 参数否新增NetworkingEngine.request返回 Promise返回IAbortableOperation含.promise可abort()建议更新v2.5 移除旧支持网络 scheme 插件(uri, request)返回 Promise(uri, request, requestType)返回AbortableOperation建议更新v2.5 移除旧支持Manifest 解析器setAvailabilityStart()、旧notifySegments()setUserSeekStart()、notifySegments(refs, isFirstPeriod)是解析器插件其中标注“无兼容”的两处TextParser 与 TextDisplayer 插件 API破坏性最强应用必须同步改写插件代码标注“建议更新”的两处NetworkingEngine 与网络 scheme 插件在 v2.4 中仍带过渡兼容层但需在 v2.5 之前完成迁移。按此清单逐项处理后你的应用即可平稳运行在 Shaka Player v2.4 之上。【免费下载链接】shaka-playerJavaScript player library / DASH HLS client / MSE-EME player项目地址: https://gitcode.com/GitHub_Trending/sh/shaka-player创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考