@flow-player/software-decoder-ffmpeg 0.14.2 → 0.15.0

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

@@ -40,6 +40,13 @@ var FfmpegSimdSoftwareDecoder = class {
   #acquireFrameBuffers;
   #viewFrames;
   #pendingTimestamps = [];
+  /** hvcC 的 NALU 长度前缀字节数（lengthSizeMinusOne + 1）；0 表示非 hvcC 契约
+   *  （描述为 Annex B 或空），decode 不做包格式改写。 */
+  #mp4NalLengthSize = 0;
+  /** hvcC 转出的 Annex B 参数集（VPS/SPS/PPS 起始码拼接）。FFmpeg 的 Annex B
+   *  契约下参数集必须物理存在于流中（extradata 预载不可靠——hvcC 转出的文件
+   *  GOP 关键帧常不带内联参数集，出首帧后即停摆），按关键帧前置注入。 */
+  #annexbParams = null;
   /** 创建实例并立即构建原生解码句柄（尚未配置 codec，configure 前不可 decode）。 */
   constructor(module, options) {
     this.#module = module;
@@ -55,8 +62,8 @@ var FfmpegSimdSoftwareDecoder = class {
         this.#width = width;
         this.#height = height;
       },
-      draw: (_nativeTimestamp, yPointer, uPointer, vPointer, yStride, uStride, vStride) => {
-        this.#emitFrame(yPointer, uPointer, vPointer, yStride, uStride, vStride);
+      draw: (ptsUs, yPointer, uPointer, vPointer, yStride, uStride, vStride) => {
+        this.#emitFrame(ptsUs, yPointer, uPointer, vPointer, yStride, uStride, vStride);
       }
     });
   }
@@ -86,7 +93,10 @@ var FfmpegSimdSoftwareDecoder = class {
       this.#configured = false;
     }
     const decoder = this.#decoder ??= this.#createNativeDecoder();
-    const result = decoder.setCodec("hvc", description);
+    const isHvcC = description.length >= 23 && description[0] === 1;
+    this.#mp4NalLengthSize = isHvcC ? (description[21] & 3) + 1 : 0;
+    this.#annexbParams = isHvcC ? hevcHvcCToAnnexB(description) : null;
+    const result = decoder.setCodec("hvc", isHvcC ? hevcHvcCToAnnexB(description) : description);
     if (result !== 0) throw new Error(`FFmpeg setCodec failed: ${result}`);
     this.#configured = true;
   }
@@ -94,11 +104,11 @@ var FfmpegSimdSoftwareDecoder = class {
    * 解码一个视频包；FFmpeg 解出帧时在本次调用内同步触发 onFrame（可能一次
    * 吐出积压的有序帧，也可能本次无输出）。
    *
-   * 输出帧时间戳取毫秒，回退链为 `timestampMs ?? ptsMs ?? timestamp / 1000`：
-   * 优先用包携带的 timestampMs；缺失时回退 ptsMs（同为毫秒）；再缺失则以
-   * timestamp / 1000 兜底（timestamp 为微秒，与 WebCodecs EncodedVideoChunk
-   * 的 timestamp 同单位）。回退结果与 timestamp 原值一起进入 pending 队列，
-   * 输出帧按"最早 pending"取出，保证 B 帧重排下时间戳与画面对齐。
+   * 时间戳直通：包的 `timestamp`（微秒，不截断）经 `submitPacket` 以微秒 timebase
+   * 送入 FFmpeg，输出帧 pts 由 C++ 侧换算为微秒后经 draw 首参回传，adapter 直接
+   * 采用为 onFrame 的 timestamp（timestampMs = ptsUs / 1000）。pending 账本只做
+   * 提交记账（pendingCount 可观测），不再参与画面时间配对。句柄无 submitPacket
+   * 的旧构建回退 legacy 路径并打 console.warn。
    *
    * @throws 已 close（"decoder closed"）或尚未 configure（"decoder is not configured"）
    * @throws ffdecoder 输入暂存分配失败 / 解码失败（非零返回码）；错误先经
@@ -108,43 +118,78 @@ var FfmpegSimdSoftwareDecoder = class {
     if (this.#closed) throw new Error("decoder closed");
     const decoder = this.#decoder;
     if (!this.#configured || !decoder) throw new Error("decoder is not configured");
+    if (packet.payload.byteLength === 0) return;
     const pending = {
       timestamp: packet.timestamp,
       timestampMs: packet.timestampMs ?? packet.ptsMs ?? packet.timestamp / 1e3
     };
     this.#pendingTimestamps.push(pending);
     try {
-      const result = this.#decodePacket(decoder, packet.payload, packet.timestamp >>> 0);
+      const result = this.#decodePacket(
+        decoder,
+        packet.payload,
+        packet.timestamp,
+        packet.isKeyframe === true ? this.#annexbParams : null
+      );
       if (result !== 0) throw new Error(`FFmpeg decode failed: ${result}`);
     } catch (error) {
-      this.#removePendingTimestamp(pending);
+      const index = this.#pendingTimestamps.indexOf(pending);
+      if (index >= 0) {
+        const lastIndex = this.#pendingTimestamps.length - 1;
+        this.#pendingTimestamps[index] = this.#pendingTimestamps[lastIndex];
+        this.#pendingTimestamps.length = lastIndex;
+      }
       this.#onError(error);
       throw error;
     }
   }
-  #decodePacket(decoder, payload, timestamp) {
+  #decodePacket(decoder, payload, timestamp, prependParams) {
+    const annexb = this.#mp4NalLengthSize > 0 ? hevcLengthPrefixedToAnnexB(payload, this.#mp4NalLengthSize) : payload;
+    const fed = prependParams && prependParams.length > 0 ? concatUint8Arrays(prependParams, annexb) : annexb;
+    if (decoder.submitPacket) {
+      if (!decoder.reserveInput) {
+        throw new Error("FFmpeg decoder does not expose reserveInput()");
+      }
+      const pointer = decoder.reserveInput(fed.byteLength);
+      if (fed.byteLength > 0 && (!Number.isInteger(pointer) || pointer <= 0)) {
+        throw new Error(`FFmpeg input allocation failed: ${fed.byteLength} bytes`);
+      }
+      this.#module.HEAPU8.set(fed, pointer);
+      return decoder.submitPacket(fed.byteLength, timestamp, -1, 1, 1e6);
+    }
+    console.warn("[ffmpeg-simd] submitPacket unavailable, falling back to legacy decodeInput");
     if (decoder.reserveInput && decoder.decodeInput) {
-      const pointer = decoder.reserveInput(payload.byteLength);
-      if (payload.byteLength > 0 && (!Number.isInteger(pointer) || pointer <= 0)) {
-        throw new Error(`FFmpeg input allocation failed: ${payload.byteLength} bytes`);
+      const pointer = decoder.reserveInput(fed.byteLength);
+      if (fed.byteLength > 0 && (!Number.isInteger(pointer) || pointer <= 0)) {
+        throw new Error(`FFmpeg input allocation failed: ${fed.byteLength} bytes`);
       }
-      this.#module.HEAPU8.set(payload, pointer);
-      return decoder.decodeInput(payload.byteLength, timestamp);
+      this.#module.HEAPU8.set(fed, pointer);
+      return decoder.decodeInput(fed.byteLength, timestamp);
     }
     if (!decoder.decode) {
       throw new Error("FFmpeg decoder does not expose decodeInput() or decode()");
     }
-    return decoder.decode(payload, timestamp);
+    return decoder.decode(fed, 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 约束），故这里保持空实现。
+   * 排空解码器内延迟帧：调 ffdecoder 句柄 `drain()`（发空包刷出），同步回调内
+   * 吐出的帧照常走 onFrame；返回本次刷出的帧数。
+   *
+   * @returns drain 刷出的帧数（0 表示无延迟帧）
+   * @throws 已 close（"decoder closed"）或尚未 configure（"decoder is not configured"）
+   * @throws 句柄无 drain 原语（旧构建缺 P2 胶水，要求重建 wasm 产物）
+   * @throws drain 返回负值（FFmpeg 错误码）时抛 `FFmpeg drain failed: <码>`
    */
   flush() {
+    if (this.#closed) throw new Error("decoder closed");
+    const decoder = this.#decoder;
+    if (!this.#configured || !decoder) throw new Error("decoder is not configured");
+    if (!decoder.drain) {
+      throw new Error("FFmpeg decoder does not expose drain() (requires P2 decoder build)");
+    }
+    const result = decoder.drain();
+    if (result < 0) throw new Error(`FFmpeg drain failed: ${result}`);
+    return result;
   }
   /**
    * 软复位：丢弃 pending 时间戳并调用 ffdecoder seek() 清空解码器内部状态
@@ -189,7 +234,7 @@ var FfmpegSimdSoftwareDecoder = class {
       console.warn("[ffmpeg-simd] decoder delete failed during release", error);
     }
   }
-  #emitFrame(yPointer, uPointer, vPointer, yStride = this.#width, uStride = Math.ceil(this.#width / 2), vStride = Math.ceil(this.#width / 2)) {
+  #emitFrame(ptsUs, yPointer, uPointer, vPointer, yStride = this.#width, uStride = Math.ceil(this.#width / 2), vStride = Math.ceil(this.#width / 2)) {
     const width = this.#width;
     const height = this.#height;
     if (width <= 0 || height <= 0) {
@@ -208,12 +253,11 @@ var FfmpegSimdSoftwareDecoder = class {
     const y = this.#planeData(yPointer, width, height, yStride, pooled?.[0]);
     const u = this.#planeData(uPointer, chromaWidth, chromaHeight, uStride, pooled?.[1]);
     const v = this.#planeData(vPointer, chromaWidth, chromaHeight, vStride, pooled?.[2]);
-    const outputTimestamp = this.#takeOutputTimestamp();
     this.#onFrame({
       width,
       height,
-      timestamp: outputTimestamp.timestamp,
-      timestampMs: outputTimestamp.timestampMs,
+      timestamp: ptsUs,
+      timestampMs: ptsUs / 1e3,
       format: "I420",
       planes: [
         { data: y, stride: this.#viewFrames ? yStride : width },
@@ -252,26 +296,12 @@ var FfmpegSimdSoftwareDecoder = class {
   getWasmMemoryBytes() {
     return this.#module.HEAPU8.buffer.byteLength;
   }
-  #takeOutputTimestamp() {
-    if (this.#pendingTimestamps.length === 0) return { timestamp: 0, timestampMs: 0 };
-    let earliestIndex = 0;
-    for (let i = 1; i < this.#pendingTimestamps.length; i++) {
-      if (this.#pendingTimestamps[i].timestamp < this.#pendingTimestamps[earliestIndex].timestamp) {
-        earliestIndex = i;
-      }
-    }
-    const lastIndex = this.#pendingTimestamps.length - 1;
-    const timestamp = this.#pendingTimestamps[earliestIndex];
-    this.#pendingTimestamps[earliestIndex] = this.#pendingTimestamps[lastIndex];
-    this.#pendingTimestamps.length = lastIndex;
-    return timestamp;
-  }
-  #removePendingTimestamp(timestamp) {
-    const index = this.#pendingTimestamps.indexOf(timestamp);
-    if (index < 0) return;
-    const lastIndex = this.#pendingTimestamps.length - 1;
-    this.#pendingTimestamps[index] = this.#pendingTimestamps[lastIndex];
-    this.#pendingTimestamps.length = lastIndex;
+  /**
+   * 提交记账数（诊断用）：自上次 configure/reset/close 以来 decode 提交的包数
+   * （失败提交已剔除）。只做任务/资源记账，不参与画面时间戳配对。
+   */
+  get pendingCount() {
+    return this.#pendingTimestamps.length;
   }
 };
 async function loadFfmpegAssets() {
@@ -365,6 +395,86 @@ return module.exports;`
   }
   return module;
 }
+function hevcLengthPrefixedToAnnexB(payload, lengthSize) {
+  if (lengthSize < 1 || lengthSize > 4) {
+    throw new Error(`invalid HEVC NALU length size: ${lengthSize}`);
+  }
+  const nalus = [];
+  let pos = 0;
+  while (pos + lengthSize <= payload.length) {
+    let length = 0;
+    for (let k = 0; k < lengthSize; k += 1) {
+      length = length << 8 | payload[pos + k];
+    }
+    pos += lengthSize;
+    if (length <= 0 || pos + length > payload.length) {
+      throw new Error(`HEVC payload NALU length prefix out of bounds at ${pos - lengthSize}`);
+    }
+    nalus.push([pos, length]);
+    pos += length;
+  }
+  if (pos !== payload.length || nalus.length === 0) {
+    throw new Error(`HEVC payload trailing bytes after last NALU at ${pos}`);
+  }
+  const output = new Uint8Array(nalus.reduce((sum, [, length]) => sum + 4 + length, 0));
+  let offset = 0;
+  for (const [start, length] of nalus) {
+    output[offset] = 0;
+    output[offset + 1] = 0;
+    output[offset + 2] = 0;
+    output[offset + 3] = 1;
+    output.set(payload.subarray(start, start + length), offset + 4);
+    offset += 4 + length;
+  }
+  return output;
+}
+function concatUint8Arrays(a, b) {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+function hevcHvcCToAnnexB(description) {
+  if (description.length < 23 || description[0] !== 1) return description;
+  const numOfArrays = description[22];
+  const nalus = [];
+  let pos = 23;
+  let valid = true;
+  scan: for (let i = 0; i < numOfArrays; i += 1) {
+    if (pos + 3 > description.length) {
+      valid = false;
+      break;
+    }
+    const numNalus = description[pos + 1] << 8 | description[pos + 2];
+    pos += 3;
+    for (let j = 0; j < numNalus; j += 1) {
+      if (pos + 2 > description.length) {
+        valid = false;
+        break scan;
+      }
+      const nalLength = description[pos] << 8 | description[pos + 1];
+      pos += 2;
+      if (pos + nalLength > description.length) {
+        valid = false;
+        break scan;
+      }
+      nalus.push([pos, nalLength]);
+      pos += nalLength;
+    }
+  }
+  if (!valid || nalus.length === 0) return description;
+  const output = new Uint8Array(nalus.reduce((sum, [, length]) => sum + 4 + length, 0));
+  let offset = 0;
+  for (const [start, length] of nalus) {
+    output[offset] = 0;
+    output[offset + 1] = 0;
+    output[offset + 2] = 0;
+    output[offset + 3] = 1;
+    output.set(description.subarray(start, start + length), offset + 4);
+    offset += 4 + length;
+  }
+  return output;
+}
 async function createSoftwareVideoDecoder(options) {
   const module = await loadFfmpegSimdModule(options);
   return new FfmpegSimdSoftwareDecoder(module, options);
@@ -374,5 +484,7 @@ export {
   FfmpegSimdSoftwareDecoder,
   createSoftwareVideoDecoder,
   ffmpeg_software_decoder_adapter_default as default,
+  hevcHvcCToAnnexB,
+  hevcLengthPrefixedToAnnexB,
   resolveSoftwareDecoderWasmUrl
 };

package/dist/software-decode-worker.js

@@ -54,6 +54,8 @@ var SOFTWARE_DECODE_WORKER_MESSAGE = Object.freeze({
   Packet: "packet",
   /** in: adapter.reset（ack: ResetDone）。 */
   Reset: "reset",
+  /** in: adapter.drain 刷滞留延迟帧（ack: DrainDone，载荷 frames 为刷出帧数）。 */
+  Drain: "drain",
   /** in: adapter.close。 */
   Close: "close",
   /** in: 归还已消费 I420 帧的 y/u/v ArrayBuffer（transfer），供帧缓冲池复用。 */
@@ -65,6 +67,8 @@ var SOFTWARE_DECODE_WORKER_MESSAGE = Object.freeze({
   DecodeDone: "decode-done",
   ConfigureDone: "configure-done",
   ResetDone: "reset-done",
+  /** out: Drain 的响应（payload: frames 刷出帧数）。 */
+  DrainDone: "drain-done",
   Error: "error",
   /** out: 定期上报解码器 wasm heap 字节数（payload: bytes）。 */
   WasmMemory: "wasm-memory",
@@ -202,6 +206,16 @@ self.onmessage = (event) => {
         post({ type: SOFTWARE_DECODE_WORKER_MESSAGE.ResetDone, id: message.id });
         break;
       }
+      case SOFTWARE_DECODE_WORKER_MESSAGE.Drain: {
+        if (!decoder) throw new Error("decoder not ready");
+        const drain = decoder.drain;
+        if (typeof drain !== "function") {
+          throw new Error("software decoder does not implement drain()");
+        }
+        const frames = await drain.call(decoder);
+        post({ type: SOFTWARE_DECODE_WORKER_MESSAGE.DrainDone, id: message.id, frames });
+        break;
+      }
       case SOFTWARE_DECODE_WORKER_MESSAGE.Close: {
         stopWasmMemoryReporting();
         await decoder?.close?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-player/software-decoder-ffmpeg",
-  "version": "0.14.2",
+  "version": "0.15.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.14.2"
+    "@flow-player/browser-runtime": "^0.15.0"
   }
 }