@flow-player/test-streams 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flow Player contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @flow-player/test-streams
+
+Flow Player 集成本地验收用的测试流服务：spawn 系统 ffmpeg 生成 H.264/HEVC × HTTP-FLV / HLS / fMP4 / MP4 / MPEG-TS fixture，经本地 HTTPS server（默认 `127.0.0.1:4177`）提供两类流：
+
+1. **`/streams/live/<format>/<codec>`** — 无限循环 live 流（`-stream_loop -1 -re -fflags +genpts`，HTTP 永不 EOF），模拟 NVR 长期监控场景；格式 `flv|hls|mp4|fmp4|ts`，编码 `h264|hevc`。
+2. **`/streams/<format>/<codec>`** — 5s 预生成 VOD 风格 fixture，适合短链路验收与范围请求验证。
+
+## 要求
+
+- Node ≥ 24（本包直接发布 TypeScript 源码，依赖原生 type stripping 运行）
+- 系统 `ffmpeg` 在 PATH 上（fixture 生成时按需 spawn；缺失时脚本给出提示）
+
+## 接入
+
+```bash
+npm install -D @flow-player/test-streams
+```
+
+启动 streams server（HTTPS 需自备证书，`--cert/--key` 可省略走 HTTP）：
+
+```bash
+node node_modules/@flow-player/test-streams/src/cli/serve.ts --cert ./local.pem --key ./local-key.pem
+# 或经包 exports 编程式接入：
+#   import { ... } from "@flow-player/test-streams"
+#   import { createStreamsServer } from "@flow-player/test-streams/server"
+```
+
+健康检查：
+
+```bash
+curl -ksSf https://127.0.0.1:4177/streams/health
+```
+
+Vite 项目可加包提供的 dev 插件（仅 serve 生效：健康检查失败时自动后台拉起 streams server，日志 `/tmp/test-streams.log`）：
+
+```ts
+import { testStreamsVitePlugin } from "@flow-player/test-streams/vite-plugin";
+
+export default {
+  plugins: [
+    testStreamsVitePlugin({ cert: "./local.pem", key: "./local-key.pem" }),
+  ],
+};
+```
+
+## 注意
+
+- 内置矩阵、CLI 参数与路径语义与 [仓库文档](../../docs/reference/test-stream.md) 保持一致；**不要在业务代码里硬编码流地址**——demo 侧经 `VITE_FLOW_PLAYER_DEMO_STREAMS_BASE` 切换基址。
+- 本包是测试/验收工具，不是生产代理服务；生成码流质量只服务于接入验收（低码率、短 GOP）。
+
+## License
+
+MIT。

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@flow-player/test-streams",
+  "version": "0.6.0",
+  "description": "ffmpeg-driven local test stream service for Flow Player integration testing: generates and serves H.264/HEVC × HTTP-FLV / HLS / fMP4 / MP4 / MPEG-TS fixtures on 127.0.0.1:4177 (live infinite-loop + 5s VOD fixtures).",
+  "keywords": [
+    "esm",
+    "flow-player",
+    "test-streams",
+    "flv",
+    "hls",
+    "h264",
+    "h265",
+    "hevc",
+    "fixture"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server/server.ts",
+    "./fixtures/generate": "./src/fixtures/generate.ts",
+    "./fixtures/catalog": "./src/fixtures/catalog.ts",
+    "./vite-plugin": {
+      "types": "./src/vite-plugin.d.ts",
+      "default": "./src/vite-plugin.ts"
+    }
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  }
+}

package/src/cli/extend-vod.ts

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+// 单独生成 30s/段、1s GOP 的 H.264 + AAC LC MP4 fixture,
+// 复制到 vod/sample-1.mp4 与 vod/sample-2.mp4,
+// 并把 vod 段总时长写进 manifest.json(供 /streams/vod-list 端点使用)。
+//
+// 跟 generate.ts 解耦:不重跑 codec × format 矩阵,只补充 VOD 段。
+// 不改 fixture 矩阵(gop=5*25 锁单 GOP,保持 fast feedback),只让 VOD 段足够长
+// 供 e2e / 人工验证多 GOP 倒放语义。每段 30s、GOP=1s,30 段共 15 分钟素材。
+// 倒放 1s GOP 间隔保留:每段 30 GOP,跨段 GOP 序号连续,worker gopBuffer
+// 30 GOP 窗口下足以验证任意点倒放回跳。
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { join, resolve } from "node:path";
+import { DEFAULT_FIXTURE_DIR, type Manifest } from "../index.ts";
+
+type Options = {
+  fixtureDir: string;
+  segmentSeconds: number;
+  segmentCount: number;
+  gopSeconds: number;
+  width: number;
+  height: number;
+  fps: number;
+};
+
+function parseArgs(argv: ReadonlyArray<string>): Options & { help: boolean } {
+  const opts: Options = {
+    fixtureDir: DEFAULT_FIXTURE_DIR,
+    segmentSeconds: 30,
+    segmentCount: 20,
+    gopSeconds: 1,
+    width: 1280,
+    height: 720,
+    fps: 25,
+  };
+  let help = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") help = true;
+    else if (a === "--fixture-dir") {
+      opts.fixtureDir = argv[++i];
+    } else if (a === "--segment-seconds") {
+      opts.segmentSeconds = Number(argv[++i]);
+    } else if (a === "--segment-count") {
+      opts.segmentCount = Number(argv[++i]);
+    } else if (a === "--gop") {
+      opts.gopSeconds = Number(argv[++i]);
+    } else if (a === "--width") {
+      opts.width = Number(argv[++i]);
+    } else if (a === "--height") {
+      opts.height = Number(argv[++i]);
+    } else if (a === "--fps") {
+      opts.fps = Number(argv[++i]);
+    }
+  }
+  return { ...opts, help };
+}
+
+const USAGE = `Usage:
+  pnpm --filter @flow-player/test-streams run extend-vod [-- <args>]
+
+Options:
+  --fixture-dir <path>      Fixture root (default: packages/test-streams/fixtures)
+  --segment-seconds <sec>  Per-segment duration (default: 30)
+  --segment-count <n>      Number of segments per VOD (default: 30; total VOD = seconds * count)
+  --gop <seconds>          GOP interval (default: 1)
+  --width <px>             Video width (default: 1280)
+  --height <px>            Video height (default: 720)
+ `;
+
+function hashFile(abs: string): string {
+  return createHash("sha256").update(readFileSync(abs)).digest("hex");
+}
+
+async function runFfmpeg(ffmpegPath: string, args: ReadonlyArray<string>): Promise<number> {
+  return await new Promise<number>((resolveRun, rejectRun) => {
+    const child = spawn(ffmpegPath, args, { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (b) => {
+      stderr += b.toString("utf8");
+    });
+    child.on("error", rejectRun);
+    child.on("close", (code) => {
+      if (code !== 0) {
+        process.stderr.write(stderr);
+      }
+      resolveRun(code ?? 1);
+    });
+  });
+}
+
+async function findFfmpeg(): Promise<string | null> {
+  const candidates = ["ffmpeg", "/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg"];
+  for (const path of candidates) {
+    const code = await runFfmpeg(path, ["-version"]);
+    if (code === 0) return path;
+  }
+  return null;
+}
+
+async function main(): Promise<number> {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const ffmpegPath = await findFfmpeg();
+  if (!ffmpegPath) {
+    process.stderr.write("[extend-vod] ffmpeg not found in PATH\n");
+    return 1;
+  }
+  const fixtureDir = resolve(args.fixtureDir);
+  const vodDir = join(fixtureDir, "vod");
+  mkdirSync(vodDir, { recursive: true });
+  const gop = String(args.gopSeconds * args.fps);
+  process.stdout.write(
+    `[extend-vod] generating ${args.segmentCount} segments x ${args.segmentSeconds}s ` +
+      `${args.width}x${args.height}@${args.fps} mp4 h264+aac, gop=${gop} frames ` +
+      `(${args.gopSeconds}s); total VOD=${args.segmentCount * args.segmentSeconds}s\n`,
+  );
+  const segments: Array<{ index: number; path: string; size: number; sha256: string }> = [];
+  for (let i = 0; i < args.segmentCount; i += 1) {
+    const index = i + 1;
+    const file = join(vodDir, `seg-${String(index).padStart(3, "0")}.mp4`);
+    // 每段用不同音高 + 起始时间偏移,让相邻段可视/可听差异化,便于人工验证
+    // 段间的 monotonic start time 让 GOP / 帧序号跨越段连续
+    const startSec = i * args.segmentSeconds;
+    const frequency = 220 + i * 40;
+    // D 轨: 输出 fragmented MP4 (fMP4) 让 MSE 模式可直接 appendBuffer。
+    // 非 fragmented MP4 的 mdat 偏移依赖 stco, MSE 的 SourceBuffer demuxer 解析时会失败
+    // (典型症状: video.error = "PIPELINE_ERROR_DECODE: Failed to send audio packet for decoding")。
+    // +empty_moov 把 moov 写到开头; +frag_keyframe 在每个关键帧边界开 fragment。
+    const ffmpegArgs = [
+      "-y",
+      "-f",
+      "lavfi",
+      "-i",
+      `testsrc2=size=${args.width}x${args.height}:rate=${args.fps},format=yuv420p`,
+      "-f",
+      "lavfi",
+      "-i",
+      `sine=frequency=${frequency}:sample_rate=44100`,
+      "-t",
+      String(args.segmentSeconds),
+      "-c:v",
+      "libx264",
+      "-profile:v",
+      "high",
+      "-bf",
+      "0",
+      "-preset",
+      "veryfast",
+      "-pix_fmt",
+      "yuv420p",
+      "-g",
+      gop,
+      "-keyint_min",
+      gop,
+      "-sc_threshold",
+      "0",
+      "-c:a",
+      "aac",
+      "-b:a",
+      "128k",
+      "-ar",
+      "44100",
+      "-ac",
+      "2",
+      "-movflags",
+      "+faststart",
+      "-metadata",
+      `start_time=${startSec}`,
+      file,
+    ];
+    const code = await runFfmpeg(ffmpegPath, ffmpegArgs);
+    const size = statSync(file).size;
+    const sha256 = hashFile(file);
+    segments.push({ index, path: `vod/seg-${String(index).padStart(3, "0")}.mp4`, size, sha256 });
+  }
+  // 写 vod-list.json 让 handleVodList 端点能返回 N 段
+  const vodList = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    segmentSeconds: args.segmentSeconds,
+    segmentCount: args.segmentCount,
+    gopSeconds: args.gopSeconds,
+    entries: segments,
+  };
+  const vodListPath = join(vodDir, "vod-list.json");
+  writeFileSync(vodListPath, JSON.stringify(vodList, null, 2));
+  process.stdout.write(`[extend-vod] wrote ${vodListPath}\n`);
+  // 更新 manifest.json 的 durationSeconds 为 "per-segment duration",
+  // 并附带 segmentCount 字段,让 handleVodList 知道总段数。
+  const manifestPath = join(fixtureDir, "manifest.json");
+  if (existsSync(manifestPath)) {
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as Manifest;
+    manifest.durationSeconds = args.segmentSeconds;
+    manifest.generatedAt = new Date().toISOString();
+    (manifest as Manifest & { segmentCount?: number }).segmentCount = args.segmentCount;
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    process.stdout.write(
+      `[extend-vod] updated ${manifestPath} durationSeconds=${args.segmentSeconds} ` +
+        `segmentCount=${args.segmentCount}\n`,
+    );
+  } else {
+    process.stdout.write(
+      `[extend-vod] ${manifestPath} not found; skipping manifest update ` +
+        `(run pnpm run generate first)\n`,
+    );
+  }
+  return 0;
+}
+
+void main().then(
+  (code) => process.exit(code),
+  (err: unknown) => {
+    process.stderr.write(`[extend-vod] unexpected error: ${String(err)}\n`);
+    process.exit(2);
+  },
+);

package/src/cli/generate.ts

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  ALL_CODECS,
+  ALL_FORMATS,
+  DEFAULT_DURATION_SECONDS,
+  DEFAULT_FIXTURE_DIR,
+  type CodecId,
+  type FormatId,
+} from "../config.ts";
+import { generateFixtures } from "../fixtures/generate.ts";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, "..", "..", "..");
+
+const CODEC_SET: Record<string, true> = { h264: true, hevc: true };
+const FORMAT_SET: Record<string, true> = { flv: true, hls: true, mp4: true, fmp4: true, ts: true };
+
+type ParsedArgs = {
+  codecs: ReadonlyArray<CodecId>;
+  formats: ReadonlyArray<FormatId>;
+  durationSeconds: number;
+  fixtureDir: string;
+  overwrite: boolean;
+  help: boolean;
+};
+
+function parseArgs(argv: ReadonlyArray<string>): ParsedArgs {
+  const parsed: ParsedArgs = {
+    codecs: ALL_CODECS,
+    formats: ALL_FORMATS,
+    durationSeconds: DEFAULT_DURATION_SECONDS,
+    fixtureDir: resolve(here, "..", "..", DEFAULT_FIXTURE_DIR),
+    overwrite: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--codecs": {
+        const value = argv[++i] ?? "";
+        const list = value
+          .split(",")
+          .map((s) => s.trim())
+          .filter((s): s is CodecId => CODEC_SET[s] === true);
+        if (list.length === 0) throw new Error(`--codecs invalid: ${value}`);
+        parsed.codecs = list;
+        break;
+      }
+      case "--formats": {
+        const value = argv[++i] ?? "";
+        const list = value
+          .split(",")
+          .map((s) => s.trim())
+          .filter((s): s is FormatId => FORMAT_SET[s] === true);
+        if (list.length === 0) throw new Error(`--formats invalid: ${value}`);
+        parsed.formats = list;
+        break;
+      }
+      case "--duration": {
+        const value = Number(argv[++i]);
+        if (!Number.isFinite(value) || value <= 0)
+          throw new Error(`--duration must be positive, got ${argv[i]}`);
+        parsed.durationSeconds = value;
+        break;
+      }
+      case "--fixture-dir": {
+        parsed.fixtureDir = resolve(argv[++i] ?? "");
+        break;
+      }
+      case "--overwrite":
+        parsed.overwrite = true;
+        break;
+      case "--help":
+      case "-h":
+        parsed.help = true;
+        break;
+      default:
+        throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+  return parsed;
+}
+
+const USAGE = `Usage:
+  pnpm --filter @flow-player/test-streams run generate [-- <args>]
+
+Options:
+  --codecs <h264,hevc>          Codecs to generate (default: h264,hevc)
+  --formats <flv,hls,mp4,fmp4,ts>
+                                Container formats to generate (default: all 5)
+  --duration <seconds>          Per-fixture duration (default: 5)
+  --fixture-dir <path>          Output directory (default: packages/test-streams/fixtures)
+  --overwrite                   Re-run ffmpeg even if output exists
+  --help, -h                    Show this help
+`;
+
+async function main(): Promise<number> {
+  let args: ParsedArgs;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`${(err as Error).message}\n${USAGE}`);
+    return 1;
+  }
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const result = await generateFixtures({
+    codecs: args.codecs,
+    formats: args.formats,
+    durationSeconds: args.durationSeconds,
+    fixtureDir: args.fixtureDir,
+    overwrite: args.overwrite,
+  });
+  if (result.ffmpegMissing) {
+    process.stderr.write(
+      "ffmpeg not found in PATH. Install ffmpeg (brew install ffmpeg) and re-run.\n",
+    );
+    return 0;
+  }
+  process.stdout.write(
+    `Generated ${result.generated} fixture(s) under ${result.fixtureDir}\n` +
+      `Manifest: ${resolve(result.fixtureDir, "manifest.json")}\n`,
+  );
+  return 0;
+}
+
+void repoRoot;
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(`${(err as Error).message}\n`);
+    process.exit(1);
+  },
+);

package/src/cli/serve.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_FIXTURE_DIR, DEFAULT_PORT, type ServeOptions } from "../config.ts";
+import { createStreamsServer, listen } from "../server/server.ts";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+type ParsedArgs = ServeOptions & { help: boolean };
+
+function parseArgs(argv: ReadonlyArray<string>): ParsedArgs {
+  const parsed: ParsedArgs = {
+    port: DEFAULT_PORT,
+    fixtureDir: resolve(here, "..", "..", DEFAULT_FIXTURE_DIR),
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--port": {
+        const v = Number(argv[++i]);
+        if (!Number.isInteger(v) || v < 1 || v > 65_535)
+          throw new Error(`--port invalid: ${argv[i]}`);
+        parsed.port = v;
+        break;
+      }
+      case "--host":
+        parsed.host = argv[++i];
+        break;
+      case "--fixture-dir":
+        parsed.fixtureDir = resolve(argv[++i] ?? "");
+        break;
+      case "--cert":
+        parsed.cert = argv[++i];
+        break;
+      case "--key":
+        parsed.key = argv[++i];
+        break;
+      case "--help":
+      case "-h":
+        parsed.help = true;
+        break;
+      default:
+        throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+  return parsed;
+}
+
+const USAGE = `Usage:
+  pnpm --filter @flow-player/test-streams run serve [-- <args>]
+
+Options:
+  --port <port>                 Listen port (default: 4177)
+  --host <host>                 Bind host (default: 127.0.0.1)
+  --fixture-dir <path>          Fixture root (default: packages/test-streams/fixtures)
+  --cert <path>                 TLS cert (with --key, enables HTTPS)
+  --key <path>                  TLS private key (with --cert, enables HTTPS)
+  --help, -h                    Show this help
+`;
+
+async function main(): Promise<number> {
+  let args: ParsedArgs;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`${(err as Error).message}\n${USAGE}`);
+    return 1;
+  }
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const server = createStreamsServer({
+    port: args.port,
+    host: args.host,
+    // parseArgs guarantees a default; treat as string.
+    fixtureDir: args.fixtureDir as string,
+    cert: args.cert,
+    key: args.key,
+  });
+  const listening = await listen(server);
+  const protocol = args.cert && args.key ? "https" : "http";
+  process.stdout.write(
+    `streams server listening on ${protocol}://${listening.host}:${listening.port}\n`,
+  );
+  process.stdout.write(
+    `  health:  ${protocol}://${listening.host}:${listening.port}/streams/health\n`,
+  );
+  process.stdout.write(`  fixture: ${resolve(args.fixtureDir ?? "")}\n`);
+  // 等待 SIGINT / SIGTERM 或未捕获异常,再决定是否 exit。
+  const { promise, resolve: resolveWait } = Promise.withResolvers<number>();
+  const shutdown = (code: number): void => {
+    process.stdout.write("\nshutting down streams server...\n");
+    listening.close().finally(() => resolveWait(code));
+  };
+  process.once("SIGINT", () => shutdown(0));
+  process.once("SIGTERM", () => shutdown(0));
+  process.once("uncaughtException", (err) => {
+    process.stderr.write(`uncaught: ${err.stack ?? err.message}\n`);
+    shutdown(1);
+  });
+  return promise;
+}
+
+void main().then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(`${(err as Error).message}\n`);
+    process.exit(1);
+  },
+);

package/src/config.ts

@@ -0,0 +1,34 @@
+// Streams server / fixture defaults. Override per call when needed.
+export const DEFAULT_PORT = 4177;
+export const DEFAULT_HOST = "127.0.0.1";
+export const DEFAULT_FIXTURE_DIR = "fixtures";
+export const DEFAULT_DURATION_SECONDS = 5;
+export const DEFAULT_VIDEO_WIDTH = 1280;
+export const DEFAULT_VIDEO_HEIGHT = 720;
+export const DEFAULT_VIDEO_FPS = 25;
+export const DEFAULT_GOP_SECONDS = 1;
+export const DEFAULT_HLS_SEGMENT_SECONDS = 2;
+
+export type GenerateOptions = {
+  codecs?: ReadonlyArray<CodecId>;
+  formats?: ReadonlyArray<FormatId>;
+  durationSeconds?: number;
+  fixtureDir?: string;
+  overwrite?: boolean;
+  ffmpegPath?: string;
+  quiet?: boolean;
+};
+
+export type ServeOptions = {
+  port?: number;
+  host?: string;
+  fixtureDir?: string;
+  cert?: string;
+  key?: string;
+};
+
+export type CodecId = "h264" | "hevc";
+export type FormatId = "flv" | "hls" | "mp4" | "fmp4" | "ts";
+
+export const ALL_CODECS: ReadonlyArray<CodecId> = ["h264", "hevc"];
+export const ALL_FORMATS: ReadonlyArray<FormatId> = ["flv", "hls", "mp4", "fmp4", "ts"];