@flow-player/software-decoder-ffmpeg 0.8.0 → 0.10.0

package/dist/ffmpeg-software-decoder-adapter.js

@@ -40,6 +40,7 @@ var FfmpegSimdSoftwareDecoder = class {
   #acquireFrameBuffers;
   #viewFrames;
   #pendingTimestamps = [];
+  /** 创建实例并立即构建原生解码句柄（尚未配置 codec，configure 前不可 decode）。 */
   constructor(module, options) {
     this.#module = module;
     this.#onFrame = options.onFrame;
@@ -59,6 +60,18 @@ var FfmpegSimdSoftwareDecoder = class {
       }
     });
   }
+  /**
+   * 配置（或重配）解码器：把 codec 私有数据（HEVC extradata/hvcC）交给 ffdecoder。
+   * 可在已配置状态下再次调用——重配先释放旧句柄并降回未配置，再全新重建，
+   * 保证与全新 configure 的状态一致；重配中重建失败时状态一致回落，原始错误
+   * 原样上抛。
+   *
+   * @param config.codec 目标编码，本 adapter 仅支持 "h265"（HEVC）
+   * @param config.description codec 私有数据；缺省按空 description 配置
+   * @throws 已 close 后调用（"decoder closed"）
+   * @throws codec 不是 "h265"（`FFmpeg SIMD adapter only supports h265, got ...`）
+   * @throws ffdecoder setCodec 失败（`FFmpeg setCodec failed: <非零码>`）
+   */
   configure(config) {
     if (this.#closed) throw new Error("decoder closed");
     if (config.codec !== "h265") {
@@ -77,6 +90,20 @@ var FfmpegSimdSoftwareDecoder = class {
     if (result !== 0) throw new Error(`FFmpeg setCodec failed: ${result}`);
     this.#configured = true;
   }
+  /**
+   * 解码一个视频包；FFmpeg 解出帧时在本次调用内同步触发 onFrame（可能一次
+   * 吐出积压的有序帧，也可能本次无输出）。
+   *
+   * 输出帧时间戳取毫秒，回退链为 `timestampMs ?? ptsMs ?? timestamp / 1000`：
+   * 优先用包携带的 timestampMs；缺失时回退 ptsMs（同为毫秒）；再缺失则以
+   * timestamp / 1000 兜底（timestamp 为微秒，与 WebCodecs EncodedVideoChunk
+   * 的 timestamp 同单位）。回退结果与 timestamp 原值一起进入 pending 队列，
+   * 输出帧按"最早 pending"取出，保证 B 帧重排下时间戳与画面对齐。
+   *
+   * @throws 已 close（"decoder closed"）或尚未 configure（"decoder is not configured"）
+   * @throws ffdecoder 输入暂存分配失败 / 解码失败（非零返回码）；错误先经
+   *   onError 回调上报，再原样抛给调用方
+   */
   decode(packet) {
     if (this.#closed) throw new Error("decoder closed");
     const decoder = this.#decoder;
@@ -109,8 +136,22 @@ var FfmpegSimdSoftwareDecoder = class {
     }
     return decoder.decode(payload, timestamp);
   }
+  /**
+   * 有意的 no-op：协议里的 flush 面向"内部有异步输出队列"的解码器，而本 adapter
+   * 的帧在 decode() 调用内同步经 draw 回调吐出，flush 时没有可排空的在途输出；
+   * ffdecoder embind 句柄也没有 EOF/drain 原语（仅 setCodec/seek/clear/delete），
+   * 无法把 FFmpeg 内部帧缓冲显式排空。runtime 侧真正的解码器清理由 configure
+   * 全新重建句柄完成（seek 路径刻意不走 reset/flush，见 browser-runtime
+   * software-decode-controller 的 avcodec_flush_buffers 约束），故这里保持空实现。
+   */
   flush() {
   }
+  /**
+   * 软复位：丢弃 pending 时间戳并调用 ffdecoder seek() 清空解码器内部状态
+   * （不丢 codec 配置，之后可直接继续 decode）；已 close 时静默返回（幂等）。
+   *
+   * @throws ffdecoder seek 失败时抛 `FFmpeg seek failed: <非零码>`
+   */
   reset() {
     if (this.#closed) return;
     this.#pendingTimestamps = [];
@@ -119,6 +160,11 @@ var FfmpegSimdSoftwareDecoder = class {
     const result = decoder.seek();
     if (result !== 0) throw new Error(`FFmpeg seek failed: ${result}`);
   }
+  /**
+   * 终止解码器：置 closed 标记（此后 configure/decode 抛错）并释放原生句柄。
+   * 幂等：重复调用无副作用；句柄已随 wasm abort/重建失败失效时 teardown 也
+   * 不会抛错（见 #releaseNativeDecoder）。
+   */
   close() {
     if (this.#closed) return;
     this.#closed = true;
@@ -196,8 +242,13 @@ var FfmpegSimdSoftwareDecoder = class {
     }
     return output;
   }
-  // decode worker 每秒读取该值上报 decoderWasmMemoryPeakMb；ffdecoder WASM 堆
-  // 只涨不缩（ALLOW_MEMORY_GROWTH），缺失此方法的观测盲区会掩盖堆增长。
+  /**
+   * 返回 ffdecoder WASM 线性内存当前字节数（HEAPU8.buffer.byteLength）。
+   * decode worker 每秒读取该值上报 decoderWasmMemoryPeakMb；ffdecoder WASM 堆
+   * 只涨不缩（ALLOW_MEMORY_GROWTH），缺失此方法的观测盲区会掩盖堆增长。
+   * 协议签名保留 null（对齐 SoftwareVideoDecoder.getWasmMemoryBytes），当前实现
+   * 恒返回数值。
+   */
   getWasmMemoryBytes() {
     return this.#module.HEAPU8.buffer.byteLength;
   }
@@ -236,17 +287,29 @@ function resolveSoftwareDecoderWasmUrl(options) {
   return explicit;
 }
 async function instantiateFfmpegWasm(url, imports) {
+  let streamingError;
+  let streamingFailed = false;
   if (typeof WebAssembly.instantiateStreaming === "function") {
     try {
-      const { instance: instance2 } = await WebAssembly.instantiateStreaming(fetch(url), imports);
-      return instance2;
-    } catch {
+      const { instance } = await WebAssembly.instantiateStreaming(fetch(url), imports);
+      return instance;
+    } catch (error) {
+      streamingError = error;
+      streamingFailed = true;
     }
   }
-  const response = await fetch(url);
-  const bytes = await response.arrayBuffer();
-  const { instance } = await WebAssembly.instantiate(bytes, imports);
-  return instance;
+  try {
+    const response = await fetch(url);
+    const bytes = await response.arrayBuffer();
+    const { instance } = await WebAssembly.instantiate(bytes, imports);
+    return instance;
+  } catch (error) {
+    if (!streamingFailed) throw error;
+    throw new Error(
+      `FFmpeg wasm arrayBuffer fallback failed: ${String(error)}; instantiateStreaming first failed: ${String(streamingError)}`,
+      { cause: streamingError }
+    );
+  }
 }
 async function loadFfmpegSimdModule(options) {
   const { glueText: glueText2 } = await loadFfmpegAssets();

package/dist/index.d.ts

@@ -24,16 +24,59 @@
  * 传参，runtime R4 起使用）；未提供时 adapter 报错提示传入
  * `softwareDecoderWasmUrl`。
  */
-/** 软解 adapter 产物 URL（对应 FlowPlayerRuntimeOptions.softwareDecoderUrl）。 */
+/**
+ * 软解 adapter ESM 模块产物 URL（对应 FlowPlayerRuntimeOptions.softwareDecoderUrl）。
+ * runtime 仅在 decodeMode 非 "webcodecs" 时经该 URL 动态 import 模块（default 导出
+ * 为 `createSoftwareVideoDecoder` 工厂）。值为 `new URL(..., import.meta.url)`
+ * 字面量推导的绝对地址，由 consumer bundler 静态扫描改写为哈希资产。
+ */
 export declare const softwareDecoderUrl: string;
-/** 软解 decode worker 产物 URL（对应 FlowPlayerRuntimeOptions.softwareDecoderWorkerUrl）。 */
+/**
+ * 软解 decode worker 产物 URL（对应 FlowPlayerRuntimeOptions.softwareDecoderWorkerUrl）。
+ * runtime 以 module worker 拉起，worker 内部托管软解 adapter 与帧缓冲池，把解码
+ * 移出主线程。值为 `new URL(..., import.meta.url)` 字面量推导的绝对地址。
+ */
 export declare const softwareDecoderWorkerUrl: string;
-/** 软解 wasm 产物 URL（对应 FlowPlayerRuntimeOptions.softwareDecoderWasmUrl）。 */
+/**
+ * 软解 wasm 产物 URL（对应 FlowPlayerRuntimeOptions.softwareDecoderWasmUrl）。
+ * SIMD 版 ffdecoder（FFmpeg→WASM）二进制，adapter 经该 URL fetch 并实例化
+ * WASM（instantiateStreaming，MIME 不支持时回退 arrayBuffer）。值为
+ * `new URL(..., import.meta.url)` 字面量推导的绝对地址。
+ */
 export declare const softwareDecoderWasmUrl: string;
+/**
+ * 软解后端对接字段集合：展开进 `FlowPlayerRuntimeOptions`（即
+ * `FlowLivePlayerOptions` / `FlowVodPlayerOptions` 的公共软解可选字段）的同名字段。
+ *
+ * 三个值均为字符串形式的绝对 URL，由本入口模块内 `new URL(..., import.meta.url)`
+ * 字面量推导——入口被 consumer 静态 import，bundler 才能把三个相对路径识别为
+ * 静态资产并产出哈希产物地址；请勿在 adapter/worker 等动态加载模块内重新推导。
+ *
+ * 推荐不手工构造，直接使用 {@link ffmpegSoftwareDecoderOptions} 的返回值。
+ */
 export interface FfmpegSoftwareDecoderOptions {
+    /** 软解 adapter ESM 模块 URL（赋给 options.softwareDecoderUrl）。 */
     softwareDecoderUrl: string;
+    /** 软解 decode worker URL（赋给 options.softwareDecoderWorkerUrl）。 */
     softwareDecoderWorkerUrl: string;
+    /** 软解 wasm 资产 URL（赋给 options.softwareDecoderWasmUrl，最终传给 adapter 的 wasmUrl）。 */
     softwareDecoderWasmUrl: string;
 }
-/** 返回可直接展开进 FlowPlayerRuntimeOptions 的软解配置。 */
+/**
+ * 汇总软解后端三个 URL 字段，返回可直接展开进播放器 options 的软解配置：
+ *
+ * ```ts
+ * new FlowPlayerRuntime({
+ *   decodeMode: "software",
+ *   ...ffmpegSoftwareDecoderOptions(),
+ * });
+ * ```
+ *
+ * 同样适用于 `FlowLivePlayerOptions`（`flowVodPlayer` 之外的 Live 入口）与
+ * `FlowVodPlayerOptions`（`flowVodPlayer`）：三个字段名与各 options 的软解
+ * 可选字段一一同名，展开即完成对接。
+ *
+ * @returns {@link FfmpegSoftwareDecoderOptions}，三个值均为绝对 URL 字符串，
+ * 展开用法见包级 TSDoc 与上方示例。
+ */
 export declare function ffmpegSoftwareDecoderOptions(): FfmpegSoftwareDecoderOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-player/software-decoder-ffmpeg",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "FFmpeg (ffdecoder) WASM software decode backend for @flow-player/browser-runtime: prebuilt adapter + decode worker, drop-in HEVC software decoding.",
   "keywords": [
     "esm",
@@ -34,6 +34,6 @@
     "tag": "latest"
   },
   "dependencies": {
-    "@flow-player/browser-runtime": "^0.8.0"
+    "@flow-player/browser-runtime": "^0.10.0"
   }
 }