@flow-player/test-streams 0.14.2 → 0.15.0

package/README.md

@@ -50,6 +50,69 @@ npm 发布产物由 `scripts/build-package.ts` 生成：esbuild 编译出 `dist/
 1. 先跑 `test-streams-generate` 生成完整矩阵 + `manifest.json`（系统需有 ffmpeg；建议用 `--fixture-dir` 指到项目内目录，避免写入 `node_modules`）；或
 2. 用 `--fixture-dir <path>` 显式指向一个已有 fixture 目录。
 
+## P3-H 烧录窗序列（window/）
+
+P3 窗口测试与 P5 容量测试用的合成 MP4 序列：`window/<id>.mp4`（16 段，
+规格见 `src/fixtures/window.ts` 的 `WINDOW_SPECS`）。每段画面经 drawtext
+烧录帧号与媒体时间（`n=<frame_num> t=<hms>`，左上白字黑底），供视觉核对；
+manifest 的 `windowFixtures` 数组为每段记录 `entries`（单文件，
+size/sha256，与存量条目同契约）+ `encode`（codec/GOP/B 帧/首 PTS/稀疏标记
+等编码参数）。
+
+参数矩阵（`moov` 全段为 trailing，即关闭 faststart；`delayedTail` 为 true
+的段用 B 帧回吐延迟考察尾部 delayed 帧）：
+
+| id | codec | GOP | B 帧 | 首 PTS(s) | 稀疏 | 用途 P3 | 用途 P5 |
+|----|-------|-----|------|-----------|------|---------|---------|
+| h264-shortgop-bframes | h264 | 短 25f/1s | 3 | 5 | 否 | 短 GOP 有 B 帧基线：窗口逐 GOP 前进对齐 | 常规解码负载基线 |
+| h264-shortgop-nobframes | h264 | 短 25f/1s | 0 | 5 | 否 | 无 B 帧对照：PTS 单调性 | 低延迟容量对照 |
+| hevc-shortgop-bframes | hevc | 短 25f/1s | 3 | 5 | 否 | HEVC 短 GOP 基线（hvc1） | HEVC 解码基线 |
+| hevc-shortgop-nobframes | hevc | 短 25f/1s | 0 | 5 | 否 | HEVC 无 B 帧对照 | HEVC 低延迟对照 |
+| h264-longgop-bframes | h264 | 长 125f/5s | 3 | 10 | 否 | 长 GOP 跨窗 seek 回跳距离 | 长 GOP 容量档 |
+| hevc-longgop-bframes | hevc | 长 125f/5s | 3 | 10 | 否 | HEVC 长 GOP 对照 | HEVC 长 GOP 容量档 |
+| h264-singlegop | h264 | 单 200f/8s | 3 | 20 | 否 | 单 GOP 极限：任意 seek 回段首 IDR | 极低码率容量档 |
+| hevc-singlegop | hevc | 单 200f/8s | 3 | 20 | 否 | HEVC 单 GOP 对照 | HEVC 单 GOP 容量档 |
+| h264-sparse-1fps | h264 | 短 4f | 0 | 30 | 是 | 1fps 稀疏：秒步进帧号/时间对应 | 稀疏流容量档 |
+| hevc-sparse-1fps | hevc | 短 4f | 0 | 30 | 是 | HEVC 稀疏对照 | HEVC 稀疏容量档 |
+| h264-gap-a / h264-gap-b | h264 | 短 25f | 0 | 100 / 108 | 否 | gap 双段：2s 空洞展示 | 空洞占比模型输入 |
+| h264-overlap-a / h264-overlap-b | h264 | 短 25f | 0 | 200 / 204 | 否 | overlap 双段：2s 重叠去重 | 重叠占比模型输入 |
+| h264-size-720p / h264-size-360p | h264 | 短 25f | 0 | 300 / 300 | 否 | 同起点尺寸+配置切换（high→baseline） | 切换瞬时峰值 |
+
+生成（默认连带烧录窗；`--skip-window` 跳过以加速反馈）：
+
+```bash
+# 全量（含烧录窗）
+node src/cli/generate.ts --fixture-dir ./fixtures
+# 快速反馈（跳过烧录窗）
+node src/cli/generate.ts --fixture-dir ./fixtures --skip-window
+# 仅看烧录窗计划（不跑 ffmpeg，离线可执行）
+node --test test/window.test.ts
+```
+
+单段 canonical 命令（以 h264-shortgop-bframes 为例，`<font>` 取本机存在字体，
+`DRAWTEXT_FONT_CANDIDATES` 顺序探测；HEVC 段追加 `-tag:v hvc1`）：
+
+```bash
+ffmpeg -y -f lavfi -i "testsrc2=size=1280x720:rate=25" \
+  -f lavfi -i "sine=frequency=1000:sample_rate=44100" -t 6 \
+  -vf "format=yuv420p,drawtext=fontfile=<font>:text='n=%{frame_num} t=%{pts\:hms}':fontsize=28:fontcolor=white:box=1:boxcolor=black@0.6:x=16:y=16" \
+  -r 25 -c:v libx264 -profile:v high -preset veryfast -pix_fmt yuv420p \
+  -bf 3 -g 25 -keyint_min 25 -sc_threshold 0 \
+  -c:a aac -b:a 128k -output_ts_offset 5 -f mp4 -movflags -faststart \
+  window/h264-shortgop-bframes.mp4
+```
+
+注意：
+
+- brew 版 ffmpeg 默认缺 libfreetype（无 drawtext 滤镜）时，生成器自动降级为
+  裸 testsrc2（画面无烧录文字，但 GOP/B 帧/PTS/稀疏/moov 参数不变），并在
+  stdout 提示；Linux CI（带 libfreetype）走完整 drawtext 链路。
+- 烧录窗 fixture 为文件级产物（`window/*.mp4` + manifest `windowFixtures`），
+  供 P3/P5 测试 harness 直接读取或 ffprobe 校验；`/streams/<format>/<codec>`
+  等 VOD 路由语义不变，不新增路由。
+- `/streams/list` 原样返回 manifest（含 `windowFixtures`），`summarizeCatalog`
+  的 fixtures 计数包含烧录窗条目。
+
 ## 注意
 
 - 内置矩阵、CLI 参数与路径语义与 [仓库文档](../../docs/reference/test-stream.md) 保持一致；**不要在业务代码里硬编码流地址**——demo 侧经 `VITE_FLOW_PLAYER_DEMO_STREAMS_BASE` 切换基址。

package/dist/cli/generate.js

@@ -22,7 +22,7 @@ import {
   writeFileSync
 } from "node:fs";
 import { spawn } from "node:child_process";
-import { join as join3, resolve } from "node:path";
+import { join as join4, resolve } from "node:path";
 
 // src/fixtures/matrix.ts
 import { join as join2 } from "node:path";
@@ -208,6 +208,372 @@ function expandMatrix(opts) {
 }
 var VOD_SAMPLE_RELATIVE = "mp4/h264.mp4";
 
+// src/fixtures/window.ts
+import { join as join3 } from "node:path";
+var DEFAULT_DRAWTEXT_FONT = "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf";
+var DRAWTEXT_FONT_CANDIDATES = [
+  "/System/Library/Fonts/Supplemental/Verdana.ttf",
+  "/System/Library/Fonts/Hiragino Sans GB.ttc",
+  "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+  "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf"
+];
+var WINDOW_CONTAINER_DIR = "window";
+var WINDOW_SPECS = [
+  {
+    id: "h264-shortgop-bframes",
+    codec: "h264",
+    width: 1280,
+    height: 720,
+    fps: 25,
+    durationSeconds: 6,
+    gopFrames: 25,
+    gopMode: "short",
+    bframes: 3,
+    startPtsSeconds: 5,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: true,
+    usageP3: "\u77ED GOP \u6709 B \u5E27\u57FA\u7EBF\uFF1A\u7A97\u53E3\u9010 GOP \u524D\u8FDB\u65F6\u7684\u89E3\u7801\u8D77\u70B9\u5BF9\u9F50",
+    usageP5: "\u591A\u8DEF\u5E76\u53D1\u4E0B\u7684\u5E38\u89C4\u89E3\u7801\u8D1F\u8F7D\u57FA\u7EBF"
+  },
+  {
+    id: "h264-shortgop-nobframes",
+    codec: "h264",
+    width: 1280,
+    height: 720,
+    fps: 25,
+    durationSeconds: 6,
+    gopFrames: 25,
+    gopMode: "short",
+    bframes: 0,
+    startPtsSeconds: 5,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: false,
+    usageP3: "\u65E0 B \u5E27\u5BF9\u7167\uFF1A\u5E27\u8F93\u51FA\u65E0\u91CD\u6392\u5EF6\u8FDF\uFF0C\u6821\u9A8C PTS \u5355\u8C03\u6027",
+    usageP5: "\u4F4E\u5EF6\u8FDF\u94FE\u8DEF\u7684\u5BB9\u91CF\u5BF9\u7167\u7EC4"
+  },
+  {
+    id: "hevc-shortgop-bframes",
+    codec: "hevc",
+    width: 1280,
+    height: 720,
+    fps: 25,
+    durationSeconds: 6,
+    gopFrames: 25,
+    gopMode: "short",
+    bframes: 3,
+    startPtsSeconds: 5,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: true,
+    usageP3: "HEVC \u77ED GOP \u6709 B \u5E27\u57FA\u7EBF\uFF1Ahvc1 \u5C01\u88C5\u4E0B\u7A97\u53E3\u63A8\u8FDB",
+    usageP5: "HEVC \u8F6F\u89E3 / \u786C\u89E3\u5BB9\u91CF\u57FA\u7EBF"
+  },
+  {
+    id: "hevc-shortgop-nobframes",
+    codec: "hevc",
+    width: 1280,
+    height: 720,
+    fps: 25,
+    durationSeconds: 6,
+    gopFrames: 25,
+    gopMode: "short",
+    bframes: 0,
+    startPtsSeconds: 5,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: false,
+    usageP3: "HEVC \u65E0 B \u5E27\u5BF9\u7167\uFF1A\u91CD\u6392\u5173\u95ED\u65F6\u7684\u7A97\u53E3\u884C\u4E3A",
+    usageP5: "HEVC \u4F4E\u5EF6\u8FDF\u5BB9\u91CF\u5BF9\u7167\u7EC4"
+  },
+  {
+    id: "h264-longgop-bframes",
+    codec: "h264",
+    width: 1280,
+    height: 720,
+    fps: 25,
+    durationSeconds: 10,
+    gopFrames: 125,
+    gopMode: "long",
+    bframes: 3,
+    startPtsSeconds: 10,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: true,
+    usageP3: "\u957F GOP\uFF085s\uFF09\u8DE8\u7A97 seek\uFF1A\u7A97\u53E3\u843D\u5728 GOP \u4E2D\u90E8\u65F6\u7684\u56DE\u8DF3\u8DDD\u79BB",
+    usageP5: "\u957F GOP \u4F4E\u7801\u7387\u6863\u7684\u89E3\u7801\u5BB9\u91CF"
+  },
+  {
+    id: "hevc-longgop-bframes",
+    codec: "hevc",
+    width: 1280,
+    height: 720,
+    fps: 25,
+    durationSeconds: 10,
+    gopFrames: 125,
+    gopMode: "long",
+    bframes: 3,
+    startPtsSeconds: 10,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: true,
+    usageP3: "HEVC \u957F GOP \u8DE8\u7A97 seek \u5BF9\u7167",
+    usageP5: "HEVC \u957F GOP \u5BB9\u91CF\u6863"
+  },
+  {
+    id: "h264-singlegop",
+    codec: "h264",
+    width: 1280,
+    height: 720,
+    fps: 25,
+    durationSeconds: 8,
+    gopFrames: 200,
+    gopMode: "single",
+    bframes: 3,
+    startPtsSeconds: 20,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: true,
+    usageP3: "\u5355 GOP \u6781\u9650\uFF1A\u7A97\u53E3\u4EFB\u610F\u70B9 seek \u5FC5\u987B\u56DE\u8DF3\u5230\u6BB5\u9996 IDR",
+    usageP5: "\u5355 GOP \u6781\u4F4E\u7801\u7387\u6863\u5BB9\u91CF"
+  },
+  {
+    id: "hevc-singlegop",
+    codec: "hevc",
+    width: 1280,
+    height: 720,
+    fps: 25,
+    durationSeconds: 8,
+    gopFrames: 200,
+    gopMode: "single",
+    bframes: 3,
+    startPtsSeconds: 20,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: true,
+    usageP3: "HEVC \u5355 GOP \u6781\u9650\u5BF9\u7167",
+    usageP5: "HEVC \u5355 GOP \u5BB9\u91CF\u6863"
+  },
+  {
+    id: "h264-sparse-1fps",
+    codec: "h264",
+    width: 1280,
+    height: 720,
+    fps: 1,
+    durationSeconds: 8,
+    gopFrames: 4,
+    gopMode: "short",
+    bframes: 0,
+    startPtsSeconds: 30,
+    sparse: true,
+    moovTrailing: true,
+    delayedTail: false,
+    usageP3: "1fps \u7A00\u758F\u6D41\uFF1A\u7A97\u53E3\u6309\u79D2\u6B65\u8FDB\u65F6\u7684\u5E27\u53F7 / \u5A92\u4F53\u65F6\u95F4\u5BF9\u5E94",
+    usageP5: "\u7A00\u758F\u6D41\u6781\u4F4E\u5E27\u7387\u5BB9\u91CF\uFF08\u7F29\u7565\u56FE\u5F0F\u62C9\u6D41\uFF09"
+  },
+  {
+    id: "hevc-sparse-1fps",
+    codec: "hevc",
+    width: 1280,
+    height: 720,
+    fps: 1,
+    durationSeconds: 8,
+    gopFrames: 4,
+    gopMode: "short",
+    bframes: 0,
+    startPtsSeconds: 30,
+    sparse: true,
+    moovTrailing: true,
+    delayedTail: false,
+    usageP3: "HEVC 1fps \u7A00\u758F\u5BF9\u7167",
+    usageP5: "HEVC \u7A00\u758F\u6D41\u5BB9\u91CF\u6863"
+  },
+  {
+    id: "h264-gap-a",
+    codec: "h264",
+    width: 1280,
+    height: 720,
+    fps: 25,
+    durationSeconds: 6,
+    gopFrames: 25,
+    gopMode: "short",
+    bframes: 0,
+    startPtsSeconds: 100,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: false,
+    pairKind: "gap",
+    pairRole: "a",
+    usageP3: "gap \u53CC\u6BB5\u9996\u6BB5\uFF1A\u4E0E gap-b \u4E4B\u95F4\u7559 2s \u7A7A\u6D1E\uFF0C\u6D4B\u7A97\u53E3\u7A7A\u6D1E\u5C55\u793A",
+    usageP5: "\u65AD\u6D41\u7A7A\u6D1E\u573A\u666F\u7684\u5BB9\u91CF\u5360\u6BD4\u6A21\u578B\u8F93\u5165"
+  },
+  {
+    id: "h264-gap-b",
+    codec: "h264",
+    width: 1280,
+    height: 720,
+    fps: 25,
+    durationSeconds: 6,
+    gopFrames: 25,
+    gopMode: "short",
+    bframes: 0,
+    startPtsSeconds: 108,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: false,
+    pairKind: "gap",
+    pairRole: "b",
+    usageP3: "gap \u53CC\u6BB5\u6B21\u6BB5\uFF1A\u9996 PTS \u665A\u4E8E\u9996\u6BB5\u5C3E 2s\uFF0C\u7A97\u53E3\u5E94\u5448\u73B0\u7A7A\u6D1E",
+    usageP5: "\u540C gap-a \u914D\u5BF9\u4F7F\u7528"
+  },
+  {
+    id: "h264-overlap-a",
+    codec: "h264",
+    width: 1280,
+    height: 720,
+    fps: 25,
+    durationSeconds: 6,
+    gopFrames: 25,
+    gopMode: "short",
+    bframes: 0,
+    startPtsSeconds: 200,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: false,
+    pairKind: "overlap",
+    pairRole: "a",
+    usageP3: "overlap \u53CC\u6BB5\u9996\u6BB5\uFF1A\u4E0E overlap-b \u91CD\u53E0 2s\uFF0C\u6D4B\u7A97\u53E3\u53BB\u91CD",
+    usageP5: "\u91CD\u53E0\u5F55\u50CF\u573A\u666F\u7684\u5BB9\u91CF\u5360\u6BD4\u6A21\u578B\u8F93\u5165"
+  },
+  {
+    id: "h264-overlap-b",
+    codec: "h264",
+    width: 1280,
+    height: 720,
+    fps: 25,
+    durationSeconds: 6,
+    gopFrames: 25,
+    gopMode: "short",
+    bframes: 0,
+    startPtsSeconds: 204,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: false,
+    pairKind: "overlap",
+    pairRole: "b",
+    usageP3: "overlap \u53CC\u6BB5\u6B21\u6BB5\uFF1A\u9996 PTS \u65E9\u4E8E\u9996\u6BB5\u5C3E 2s\uFF0C\u7A97\u53E3\u5E94\u53BB\u91CD\u5408\u5E76",
+    usageP5: "\u540C overlap-a \u914D\u5BF9\u4F7F\u7528"
+  },
+  {
+    id: "h264-size-720p",
+    codec: "h264",
+    width: 1280,
+    height: 720,
+    fps: 25,
+    durationSeconds: 6,
+    gopFrames: 25,
+    gopMode: "short",
+    bframes: 0,
+    startPtsSeconds: 300,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: false,
+    pairKind: "sizeSwitch",
+    pairRole: "a",
+    usageP3: "\u5C3A\u5BF8\u5207\u6362\u9996\u6BB5\uFF08720p high\uFF09\uFF1A\u4E0E 360p \u6BB5\u540C\u8D77\u70B9\uFF0C\u6D4B\u7A97\u53E3\u5185\u5206\u8FA8\u7387\u5207\u6362",
+    usageP5: "\u6E05\u6670\u5EA6\u5207\u6362\u65F6\u7684\u77AC\u65F6\u89E3\u7801\u5CF0\u503C"
+  },
+  {
+    id: "h264-size-360p",
+    codec: "h264",
+    width: 640,
+    height: 360,
+    fps: 25,
+    durationSeconds: 6,
+    gopFrames: 25,
+    gopMode: "short",
+    bframes: 0,
+    startPtsSeconds: 300,
+    sparse: false,
+    moovTrailing: true,
+    delayedTail: false,
+    pairKind: "sizeSwitch",
+    pairRole: "b",
+    usageP3: "\u5C3A\u5BF8\u5207\u6362\u6B21\u6BB5\uFF08360p baseline\uFF09\uFF1A\u7F16\u7801\u914D\u7F6E\u4E0E\u5206\u8FA8\u7387\u540C\u65F6\u53D8\u5316",
+    usageP5: "\u540C size-720p \u914D\u5BF9\u4F7F\u7528"
+  }
+];
+function drawtextFilter(fontfile) {
+  return `drawtext=fontfile=${fontfile}:text='n=%{frame_num} t=%{pts\\:hms}':fontsize=28:fontcolor=white:box=1:boxcolor=black@0.6:x=16:y=16`;
+}
+function buildWindowPlan(spec, opts) {
+  const useDrawtext = opts?.useDrawtext ?? true;
+  const fontfile = opts?.fontfile ?? DEFAULT_DRAWTEXT_FONT;
+  const specCodec = CODEC_SPEC[spec.codec];
+  const videoInput = `testsrc2=size=${spec.width}x${spec.height}:rate=${spec.fps}`;
+  const audioInput = `sine=frequency=1000:sample_rate=44100`;
+  const videoFilter = useDrawtext ? `format=yuv420p,${drawtextFilter(fontfile)}` : "format=yuv420p";
+  const outputFps = spec.sparse ? 1 : spec.fps;
+  const sizeSwitchBaseline = spec.pairKind === "sizeSwitch" && spec.pairRole === "b" ? ["-profile:v", "baseline"] : specCodec.videoArgs;
+  const ffmpegOutputArgs = [
+    "-y",
+    "-f",
+    "lavfi",
+    "-i",
+    videoInput,
+    "-f",
+    "lavfi",
+    "-i",
+    audioInput,
+    "-t",
+    String(spec.durationSeconds),
+    "-vf",
+    videoFilter,
+    "-r",
+    String(outputFps),
+    "-c:v",
+    specCodec.encoder,
+    ...sizeSwitchBaseline,
+    "-pix_fmt",
+    specCodec.pixelFormat,
+    "-bf",
+    String(spec.bframes),
+    "-g",
+    String(spec.gopFrames),
+    "-keyint_min",
+    String(spec.gopFrames),
+    "-sc_threshold",
+    "0",
+    ...containerExtraArgs("mp4", spec.codec),
+    "-c:a",
+    "aac",
+    "-b:a",
+    "128k",
+    "-output_ts_offset",
+    String(spec.startPtsSeconds),
+    "-f",
+    "mp4",
+    "-movflags",
+    "-faststart"
+  ];
+  const mainFile = join3(WINDOW_CONTAINER_DIR, `${spec.id}.mp4`);
+  const encode = {
+    codec: spec.codec,
+    gopFrames: spec.gopFrames,
+    gopMode: spec.gopMode,
+    bframes: spec.bframes,
+    startPtsSeconds: spec.startPtsSeconds,
+    sparse: spec.sparse,
+    moov: "trailing",
+    delayedTail: spec.delayedTail,
+    width: spec.width,
+    height: spec.height,
+    fps: outputFps
+  };
+  return { id: spec.id, spec, mainFile, files: [mainFile], ffmpegOutputArgs, encode };
+}
+
 // src/fixtures/generate.ts
 var FFMPEG_PROBE_ARGS = ["-version"];
 async function generateFixtures(opts = {}) {
@@ -249,26 +615,39 @@ async function generateFixtures(opts = {}) {
     }
   }
   copyVodSamples(fixtureDir);
+  let windowFixtures = [];
+  if (opts.includeWindow !== false) {
+    const windowResult = await generateWindowSet(
+      fixtureDir,
+      ffmpegPath,
+      opts.quiet ?? false,
+      opts.overwrite ?? false
+    );
+    windowFixtures = windowResult.items;
+    generated += windowResult.generated;
+    skipped += windowResult.skipped;
+  }
   const manifest = {
     version: 1,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     durationSeconds: duration,
-    fixtures: manifestItems
+    fixtures: manifestItems,
+    windowFixtures
   };
-  writeFileSync(join3(fixtureDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  writeFileSync(join4(fixtureDir, "manifest.json"), JSON.stringify(manifest, null, 2));
   return { fixtureDir, manifest, generated, skipped, ffmpegPath, ffmpegMissing: false };
 }
 async function generateOne(plan, fixtureDir, ffmpegPath, quiet, overwrite) {
-  const outDir = join3(fixtureDir, plan.containerDir);
+  const outDir = join4(fixtureDir, plan.containerDir);
   mkdirSync(outDir, { recursive: true });
-  const outFile = join3(fixtureDir, plan.mainFile);
+  const outFile = join4(fixtureDir, plan.mainFile);
   if (!overwrite && existsSync(outFile)) {
     return collectExisting(plan, fixtureDir);
   }
   if (plan.layout.isContainerDirectory) {
     for (const f of readdirSync(outDir)) {
       if (f === plan.layout.mainFileName) continue;
-      rmIfExists(join3(outDir, f));
+      rmIfExists(join4(outDir, f));
     }
   }
   const args = plan.ffmpegOutputArgs.concat([outFile]);
@@ -282,21 +661,89 @@ async function generateOne(plan, fixtureDir, ffmpegPath, quiet, overwrite) {
   }
   return collectExisting(plan, fixtureDir);
 }
+async function generateWindowSet(fixtureDir, ffmpegPath, quiet, overwrite) {
+  const outDir = join4(fixtureDir, WINDOW_CONTAINER_DIR);
+  mkdirSync(outDir, { recursive: true });
+  const useDrawtext = await supportsDrawtext(ffmpegPath);
+  const fontfile = useDrawtext ? pickFontfile() : void 0;
+  if (!useDrawtext && !quiet) {
+    process.stdout.write(
+      "[generate] drawtext \u6EE4\u955C\u7F3A\u5931\uFF0C\u70E7\u5F55\u7A97\u964D\u7EA7\u4E3A\u88F8 testsrc2\uFF08\u65E0\u70E7\u5F55\u6587\u5B57\uFF0C\u7F16\u7801\u53C2\u6570\u4E0D\u53D8\uFF1B\u5B8C\u6574\u547D\u4EE4\u89C1 README P3-H \u4E00\u8282\uFF09\n"
+    );
+  }
+  const items = [];
+  let generated = 0;
+  let skipped = 0;
+  for (const spec of WINDOW_SPECS) {
+    const plan = buildWindowPlan(spec, { useDrawtext, fontfile });
+    const outFile = join4(fixtureDir, plan.mainFile);
+    if (!overwrite && existsSync(outFile)) {
+      items.push(collectWindowExisting(plan, fixtureDir));
+      skipped += 1;
+      continue;
+    }
+    if (!quiet) {
+      process.stdout.write(`[generate] window/${plan.id} -> ${plan.mainFile}
+`);
+    }
+    const code = await runFfmpeg(ffmpegPath, plan.ffmpegOutputArgs.concat([outFile]), quiet);
+    if (code !== 0) {
+      throw new Error(`ffmpeg exited with code ${code} for window/${plan.id}`);
+    }
+    items.push(collectWindowExisting(plan, fixtureDir));
+    generated += 1;
+  }
+  return { items, generated, skipped };
+}
+function collectWindowExisting(plan, fixtureDir) {
+  const entries = [];
+  for (const rel of plan.files) {
+    const abs = join4(fixtureDir, rel);
+    if (!existsSync(abs)) continue;
+    entries.push({ path: rel, size: statSync(abs).size, sha256: hashFile(abs) });
+  }
+  return { id: plan.id, codec: plan.spec.codec, entries, encode: plan.encode };
+}
+async function supportsDrawtext(ffmpegPath) {
+  const { promise, resolve: resolve3 } = Promise.withResolvers();
+  const proc = spawn(ffmpegPath, ["-hide_banner", "-filters"], {
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  let out = "";
+  proc.stdout?.on("data", (chunk) => {
+    out += chunk.toString("utf8");
+  });
+  proc.once("error", () => resolve3(false));
+  proc.once("exit", (code) => {
+    if (code !== 0) {
+      resolve3(false);
+      return;
+    }
+    resolve3(/^\s*\S{2,3}\s+drawtext\s/m.test(out));
+  });
+  return promise;
+}
+function pickFontfile() {
+  for (const candidate of DRAWTEXT_FONT_CANDIDATES) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return DRAWTEXT_FONT_CANDIDATES[0] ?? "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf";
+}
 function collectExisting(plan, fixtureDir) {
   const entries = [];
   for (const rel of plan.files) {
-    const abs = join3(fixtureDir, rel);
+    const abs = join4(fixtureDir, rel);
     if (!existsSync(abs)) continue;
     entries.push({ path: rel, size: statSync(abs).size, sha256: hashFile(abs) });
   }
   if (plan.layout.isContainerDirectory) {
-    const absDir = join3(fixtureDir, plan.containerDir);
+    const absDir = join4(fixtureDir, plan.containerDir);
     if (existsSync(absDir)) {
       for (const name of readdirSync(absDir).sort()) {
         if (name === plan.layout.mainFileName) continue;
-        const rel = join3(plan.containerDir, name);
+        const rel = join4(plan.containerDir, name);
         if (entries.find((e) => e.path === rel)) continue;
-        const abs = join3(absDir, name);
+        const abs = join4(absDir, name);
         if (!statSync(abs).isFile()) continue;
         entries.push({ path: rel, size: statSync(abs).size, sha256: hashFile(abs) });
       }
@@ -305,12 +752,12 @@ function collectExisting(plan, fixtureDir) {
   return { codec: plan.codec, format: plan.format, entries };
 }
 function copyVodSamples(fixtureDir) {
-  const src = join3(fixtureDir, VOD_SAMPLE_RELATIVE);
+  const src = join4(fixtureDir, VOD_SAMPLE_RELATIVE);
   if (!existsSync(src)) return;
-  const vodDir = join3(fixtureDir, "vod");
+  const vodDir = join4(fixtureDir, "vod");
   mkdirSync(vodDir, { recursive: true });
   for (const name of ["sample-1.mp4", "sample-2.mp4"]) {
-    const dst = join3(vodDir, name);
+    const dst = join4(vodDir, name);
     writeFileSync(dst, readFileSync(src));
   }
 }
@@ -359,7 +806,8 @@ function emptyManifest(duration) {
     version: 1,
     generatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
     durationSeconds: duration,
-    fixtures: []
+    fixtures: [],
+    windowFixtures: []
   };
 }
 
@@ -374,6 +822,7 @@ function parseArgs(argv) {
     durationSeconds: DEFAULT_DURATION_SECONDS,
     fixtureDir: resolve2(here, "..", "..", DEFAULT_FIXTURE_DIR),
     overwrite: false,
+    includeWindow: true,
     help: false
   };
   for (let i = 0; i < argv.length; i += 1) {
@@ -410,6 +859,9 @@ function parseArgs(argv) {
       case "--overwrite":
         parsed.overwrite = true;
         break;
+      case "--skip-window":
+        parsed.includeWindow = false;
+        break;
       case "--help":
       case "-h":
         parsed.help = true;
@@ -431,6 +883,7 @@ Options:
   --fixture-dir <path>          Output directory (default: packages/test-streams/fixtures)
   --ffmpeg-path <path>          Explicit ffmpeg executable (default: auto-detect on PATH)
   --overwrite                   Re-run ffmpeg even if output exists
+  --skip-window                 Skip P3-H burned window sequence (window/<id>.mp4)
   --help, -h                    Show this help
 `;
 async function main() {
@@ -452,7 +905,8 @@ ${USAGE}`);
     durationSeconds: args.durationSeconds,
     fixtureDir: args.fixtureDir,
     overwrite: args.overwrite,
-    ffmpegPath: args.ffmpegPath
+    ffmpegPath: args.ffmpegPath,
+    includeWindow: args.includeWindow
   });
   if (result.ffmpegMissing) {
     process.stderr.write(

package/dist/cli/serve.js

@@ -45,6 +45,7 @@ function summarizeCatalog(fixtureDir) {
   }
   let total = 0;
   for (const item of manifest.fixtures) total += item.entries.length;
+  for (const item of manifest.windowFixtures ?? []) total += item.entries.length;
   return {
     codecs: ALL_CODECS,
     formats: ALL_FORMATS,
@@ -246,6 +247,12 @@ function parseChannelCount(raw) {
   if (!Number.isFinite(value) || value < 1) return MULTI_VOD_DEFAULT_CHANNELS;
   return Math.min(MULTI_VOD_MAX_CHANNELS, Math.floor(value));
 }
+function parseBoundedQueryInt(raw, min, max) {
+  if (raw == null || raw === "") return null;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < min || value > max) return null;
+  return value;
+}
 function handleVodListMulti(res, manifest, fixtureDir, channels) {
   const entriesSource = (() => {
     const vodListPath = join(fixtureDir, "vod", "vod-list.json");
@@ -565,7 +572,13 @@ function createStreamsServer(options) {
       }
       const liveMatch = matchLivePath(path);
       if (liveMatch) {
-        handleLiveStream(req, res, liveMatch.format, liveMatch.codec);
+        const liveQuery = (req.url ?? "").split("?", 2)[1] ?? "";
+        const liveParams = new URLSearchParams(liveQuery);
+        handleLiveStream(req, res, liveMatch.format, liveMatch.codec, {
+          width: parseBoundedQueryInt(liveParams.get("width"), 160, 3840) ?? void 0,
+          height: parseBoundedQueryInt(liveParams.get("height"), 160, 3840) ?? void 0,
+          fps: parseBoundedQueryInt(liveParams.get("fps"), 1, 60) ?? void 0
+        });
         return;
       }
       writeNotFound(res);

package/dist/config.d.ts

@@ -21,6 +21,8 @@ export type GenerateOptions = {
     /** ffmpeg 可执行文件路径；缺省自动探测 PATH 与常见安装位置。 */
     ffmpegPath?: string;
     quiet?: boolean;
+    /** 是否生成 P3-H 烧录窗序列（window/，默认 true；--skip-window 可关闭以加速反馈）。 */
+    includeWindow?: boolean;
 };
 /** createStreamsServer / serve CLI 的选项；fixtureDir 必填（server 侧）。 */
 export type ServeOptions = {