@flow-player/test-streams 0.6.0

package/src/fixtures/catalog.ts

@@ -0,0 +1,99 @@
+// 读 manifest.json 并对外提供按 codec / format 维度的查询。
+// 不依赖 ffmpeg;generate.ts 负责写 manifest,catalog 负责读 + 过滤。
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { ALL_CODECS, ALL_FORMATS, type CodecId, type FormatId } from "../config.ts";
+
+export type ManifestEntry = {
+  path: string;
+  size: number;
+  sha256: string;
+};
+
+export type ManifestItem = {
+  codec: CodecId;
+  format: FormatId;
+  entries: ReadonlyArray<ManifestEntry>;
+};
+
+export type Manifest = {
+  version: 1;
+  generatedAt: string;
+  durationSeconds: number;
+  fixtures: ReadonlyArray<ManifestItem>;
+};
+
+export type FixtureLookup = {
+  files: ReadonlyArray<ManifestEntry>;
+  mainFile: ManifestEntry | null;
+  exists: boolean;
+};
+
+export function loadManifest(fixtureDir: string): Manifest | null {
+  const path = resolve(fixtureDir, "manifest.json");
+  if (!existsSync(path)) return null;
+  const raw = JSON.parse(readFileSync(path, "utf8")) as Manifest;
+  return raw;
+}
+
+export function lookupFixture(
+  manifest: Manifest | null,
+  codec: CodecId,
+  format: FormatId,
+): FixtureLookup {
+  if (!manifest) return { files: [], mainFile: null, exists: false };
+  const item = manifest.fixtures.find((f) => f.codec === codec && f.format === format);
+  if (!item) return { files: [], mainFile: null, exists: false };
+  // 主文件 = 第一个 entry(generate.ts 中 entries 顺序稳定:主文件优先)。
+  const mainFile = item.entries[0] ?? null;
+  return { files: item.entries, mainFile, exists: true };
+}
+
+export type CatalogSummary = {
+  codecs: ReadonlyArray<CodecId>;
+  formats: ReadonlyArray<FormatId>;
+  fixtureCount: number;
+  exists: boolean;
+  reason?: string;
+};
+
+export function summarizeCatalog(fixtureDir: string): CatalogSummary {
+  const manifest = loadManifest(fixtureDir);
+  if (!manifest) {
+    return {
+      codecs: ALL_CODECS,
+      formats: ALL_FORMATS,
+      fixtureCount: 0,
+      exists: false,
+      reason: `manifest.json not found at ${resolve(fixtureDir, "manifest.json")}`,
+    };
+  }
+  let total = 0;
+  for (const item of manifest.fixtures) total += item.entries.length;
+  return {
+    codecs: ALL_CODECS,
+    formats: ALL_FORMATS,
+    fixtureCount: total,
+    exists: true,
+  };
+}
+
+// 用 manifest 的 sha256 重新对磁盘文件做核对;供 generate.ts 写完磁盘后自检。
+export function verifyEntryOnDisk(
+  fixtureDir: string,
+  entry: ManifestEntry,
+): { ok: boolean; size: number; reason?: string } {
+  const abs = resolve(fixtureDir, entry.path);
+  if (!existsSync(abs)) {
+    return { ok: false, size: 0, reason: `missing file: ${entry.path}` };
+  }
+  const size = statSync(abs).size;
+  if (size !== entry.size) {
+    return {
+      ok: false,
+      size,
+      reason: `size mismatch for ${entry.path}: manifest=${entry.size} disk=${size}`,
+    };
+  }
+  return { ok: true, size };
+}

package/src/fixtures/codec.ts

@@ -0,0 +1,43 @@
+// Per-codec ffmpeg 参数集。Centralized so generate.ts and any future
+// probe code agree on a single source of truth。
+import type { CodecId } from "../config.ts";
+
+export type CodecSpec = {
+  codec: CodecId;
+  encoder: string;
+  // 通用视频参数(所有 format 都用)
+  videoArgs: ReadonlyArray<string>;
+  // 容器 tag(在 MP4 / fMP4 时需要 hvc1,FLV / TS 不需要)
+  audioArgs: ReadonlyArray<string>;
+  pixelFormat: string;
+};
+
+export const CODEC_SPEC: Record<CodecId, CodecSpec> = {
+  h264: {
+    codec: "h264",
+    encoder: "libx264",
+    videoArgs: ["-profile:v", "high", "-preset", "veryfast"],
+    audioArgs: ["-c:a", "aac", "-b:a", "128k"],
+    pixelFormat: "yuv420p",
+  },
+  hevc: {
+    codec: "hevc",
+    encoder: "libx265",
+    // 注意:FLV / TS 容器用 enhanced-rtmp 1cvh tag,不能强行写 hvc1;
+    // MP4 / fMP4 / HLS 走 hvc1。containerArgs 在 buildPlan 时按 format 决定。
+    videoArgs: ["-preset", "veryfast"],
+    audioArgs: ["-c:a", "aac", "-b:a", "128k"],
+    pixelFormat: "yuv420p",
+  },
+};
+
+export function containerExtraArgs(
+  format: "flv" | "hls" | "mp4" | "fmp4" | "ts",
+  codec: CodecId,
+): ReadonlyArray<string> {
+  if (codec !== "hevc") return [];
+  // HEVC + MP4 / fMP4 / HLS:fMP4/HLS 内部 ts 段走 mpegts 复用,不需要 tag;
+  // 单纯 MP4 文件需要 -tag:v hvc1 才会被 QuickTime/Safari 识别。
+  if (format === "mp4") return ["-tag:v", "hvc1"];
+  return [];
+}

package/src/fixtures/format.ts

@@ -0,0 +1,118 @@
+// Per-format output plan. ffmpeg 参数 + 相对 fixture 根的输出路径。
+// 单一事实源：matrix.ts 与 generate.ts 都从这份声明派生。
+// 文件布局约定:
+//   flv/mp4/ts  → {format}/{codec}.{format}      单文件,无 codec 子目录
+//   hls         → hls/{codec}/master.m3u8 + seg-NN.ts
+//   fmp4        → fmp4/{codec}/init.mp4 + seg-NN.m4s
+import { join } from "node:path";
+import type { CodecId, FormatId } from "../config.ts";
+
+export type FormatLayout = {
+  format: FormatId;
+  mime: string;
+  // 单文件格式:文件名(无父目录)。HLS/fMP4:目录内主文件名(master.m3u8/init.mp4)。
+  mainFileName: string;
+  // ffmpeg 参数,只描述容器层(不含 -c:v -c:a,见 codec.ts)。
+  containerArgs: ReadonlyArray<string>;
+  isContainerDirectory: boolean;
+  sideFiles: ReadonlyArray<string>;
+};
+
+function formatSpecific(format: FormatId): ReadonlyArray<string> {
+  if (format === "flv") return ["-f", "flv"];
+  if (format === "hls") {
+    return [
+      "-f",
+      "hls",
+      "-hls_time",
+      "2",
+      "-hls_playlist_type",
+      "vod",
+      "-hls_segment_type",
+      "mpegts",
+      "-hls_flags",
+      "independent_segments",
+    ];
+  }
+  if (format === "mp4") return ["-f", "mp4", "-movflags", "+faststart"];
+  if (format === "fmp4") {
+    return [
+      "-f",
+      "mp4",
+      "-movflags",
+      "frag_keyframe+empty_moov+default_base_moof",
+      "-frag_duration",
+      "2000000",
+    ];
+  }
+  if (format === "ts") return ["-f", "mpegts"];
+  throw new Error(`Unknown format: ${String(format)}`);
+}
+
+export function layoutFor(codec: CodecId, format: FormatId): FormatLayout {
+  if (format === "hls") {
+    return {
+      format,
+      mime: "application/vnd.apple.mpegurl",
+      mainFileName: "master.m3u8",
+      containerArgs: formatSpecific(format),
+      isContainerDirectory: true,
+      sideFiles: ["seg-00000.ts", "seg-00001.ts", "seg-00002.ts"],
+    };
+  }
+  if (format === "fmp4") {
+    return {
+      format,
+      mime: "video/iso.segment",
+      mainFileName: "init.mp4",
+      containerArgs: formatSpecific(format),
+      isContainerDirectory: true,
+      sideFiles: ["seg-00000.m4s", "seg-00001.m4s", "seg-00002.m4s"],
+    };
+  }
+  if (format === "flv") {
+    return {
+      format,
+      mime: "video/x-flv",
+      mainFileName: `${codec}.flv`,
+      containerArgs: formatSpecific(format),
+      isContainerDirectory: false,
+      sideFiles: [],
+    };
+  }
+  if (format === "mp4") {
+    return {
+      format,
+      mime: "video/mp4",
+      mainFileName: `${codec}.mp4`,
+      containerArgs: formatSpecific(format),
+      isContainerDirectory: false,
+      sideFiles: [],
+    };
+  }
+  if (format === "ts") {
+    return {
+      format,
+      mime: "video/mp2t",
+      mainFileName: `${codec}.ts`,
+      containerArgs: formatSpecific(format),
+      isContainerDirectory: false,
+      sideFiles: [],
+    };
+  }
+  throw new Error(`Unknown format: ${String(format)}`);
+}
+
+// 单文件格式的相对路径: {format}/{codec}.{format}
+export function singleFileRelative(codec: CodecId, format: FormatId): string {
+  return join(format, `${codec}.${format}`);
+}
+
+// HLS / fMP4 子目录的相对路径: {format}/{codec}/...
+export function containerRelativeDir(codec: CodecId, format: FormatId): string {
+  return join(format, codec);
+}
+
+export function containerRelativePath(codec: CodecId, format: FormatId, name: string): string {
+  return join(containerRelativeDir(codec, format), name);
+}

package/src/fixtures/generate.ts

@@ -0,0 +1,209 @@
+// ffmpeg 驱动的 fixture 生成器。按 codec × format 矩阵顺序执行 ffmpeg,
+// 把每个 plan 的输出写到 fixtureDir,写完后输出 manifest.json。
+// 设计:不引入 npm 依赖,直接 spawn ffmpeg 子进程。
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { spawn } from "node:child_process";
+import { join, resolve } from "node:path";
+import {
+  ALL_CODECS,
+  ALL_FORMATS,
+  DEFAULT_DURATION_SECONDS,
+  DEFAULT_FIXTURE_DIR,
+  type GenerateOptions,
+} from "../config.ts";
+import { type FixturePlan, expandMatrix, VOD_SAMPLE_RELATIVE } from "./matrix.ts";
+import { type Manifest, type ManifestEntry, type ManifestItem } from "./catalog.ts";
+
+export type GenerateResult = {
+  fixtureDir: string;
+  manifest: Manifest;
+  generated: number;
+  skipped: number;
+  ffmpegPath: string;
+  ffmpegMissing: boolean;
+};
+
+const FFMPEG_PROBE_ARGS = ["-version"] as const;
+
+export async function generateFixtures(opts: GenerateOptions = {}): Promise<GenerateResult> {
+  const ffmpegPath = opts.ffmpegPath ?? (await findFfmpeg());
+  if (!ffmpegPath) {
+    return {
+      fixtureDir: resolve(opts.fixtureDir ?? DEFAULT_FIXTURE_DIR),
+      manifest: emptyManifest(opts.durationSeconds ?? DEFAULT_DURATION_SECONDS),
+      generated: 0,
+      skipped: 0,
+      ffmpegPath: "ffmpeg",
+      ffmpegMissing: true,
+    };
+  }
+  const fixtureDir = resolve(opts.fixtureDir ?? DEFAULT_FIXTURE_DIR);
+  mkdirSync(fixtureDir, { recursive: true });
+  const duration = opts.durationSeconds ?? DEFAULT_DURATION_SECONDS;
+  const plans = expandMatrix({
+    codecs: opts.codecs ?? ALL_CODECS,
+    formats: opts.formats ?? ALL_FORMATS,
+    durationSeconds: duration,
+  });
+  const manifestItems: ManifestItem[] = [];
+  let generated = 0;
+  let skipped = 0;
+  for (const plan of plans) {
+    const item = await generateOne(
+      plan,
+      fixtureDir,
+      ffmpegPath,
+      opts.quiet ?? false,
+      opts.overwrite ?? false,
+    );
+    if (item) {
+      manifestItems.push(item);
+      generated += 1;
+    } else {
+      skipped += 1;
+    }
+  }
+  copyVodSamples(fixtureDir);
+  const manifest: Manifest = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    durationSeconds: duration,
+    fixtures: manifestItems,
+  };
+  writeFileSync(join(fixtureDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  return { fixtureDir, manifest, generated, skipped, ffmpegPath, ffmpegMissing: false };
+}
+
+async function generateOne(
+  plan: FixturePlan,
+  fixtureDir: string,
+  ffmpegPath: string,
+  quiet: boolean,
+  overwrite: boolean,
+): Promise<ManifestItem | null> {
+  const outDir = join(fixtureDir, plan.containerDir);
+  mkdirSync(outDir, { recursive: true });
+  const outFile = join(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(join(outDir, f));
+    }
+  }
+  const args = plan.ffmpegOutputArgs.concat([outFile]);
+  if (!quiet) {
+    process.stdout.write(`[generate] ${plan.codec}/${plan.format} -> ${plan.mainFile}\n`);
+  }
+  const code = await runFfmpeg(ffmpegPath, args, quiet);
+  if (code !== 0) {
+    throw new Error(`ffmpeg exited with code ${code} for ${plan.codec}/${plan.format}`);
+  }
+  return collectExisting(plan, fixtureDir);
+}
+
+function collectExisting(plan: FixturePlan, fixtureDir: string): ManifestItem {
+  const entries: ManifestEntry[] = [];
+  for (const rel of plan.files) {
+    const abs = join(fixtureDir, rel);
+    if (!existsSync(abs)) continue;
+    entries.push({ path: rel, size: statSync(abs).size, sha256: hashFile(abs) });
+  }
+  if (plan.layout.isContainerDirectory) {
+    // HLS / fMP4 容器目录内 ffmpeg 会按命名规则追加 segment(实际文件名不一定
+    // 等于 plan.files 预定义的 seg-00000.ts / seg-00000.m4s,可能形如 master0.ts)。
+    const absDir = join(fixtureDir, plan.containerDir);
+    if (existsSync(absDir)) {
+      for (const name of readdirSync(absDir).sort()) {
+        if (name === plan.layout.mainFileName) continue;
+        const rel = join(plan.containerDir, name);
+        if (entries.find((e) => e.path === rel)) continue;
+        const abs = join(absDir, name);
+        if (!statSync(abs).isFile()) continue;
+        entries.push({ path: rel, size: statSync(abs).size, sha256: hashFile(abs) });
+      }
+    }
+  }
+  return { codec: plan.codec, format: plan.format, entries };
+}
+
+function copyVodSamples(fixtureDir: string): void {
+  const src = join(fixtureDir, VOD_SAMPLE_RELATIVE);
+  if (!existsSync(src)) return;
+  const vodDir = join(fixtureDir, "vod");
+  mkdirSync(vodDir, { recursive: true });
+  for (const name of ["sample-1.mp4", "sample-2.mp4"]) {
+    const dst = join(vodDir, name);
+    writeFileSync(dst, readFileSync(src));
+  }
+}
+
+function rmIfExists(abs: string): void {
+  if (!existsSync(abs)) return;
+  try {
+    unlinkSync(abs);
+  } catch {
+    // ignore
+  }
+}
+
+function runFfmpeg(
+  ffmpegPath: string,
+  args: ReadonlyArray<string>,
+  quiet: boolean,
+): Promise<number> {
+  const { promise, resolve, reject } = Promise.withResolvers<number>();
+  const proc = spawn(ffmpegPath, args, {
+    stdio: quiet ? ["ignore", "ignore", "ignore"] : "inherit",
+  });
+  proc.once("error", reject);
+  proc.once("exit", (code) => resolve(code ?? 1));
+  return promise;
+}
+
+async function findFfmpeg(): Promise<string | null> {
+  const candidates = [
+    "ffmpeg",
+    "/opt/homebrew/bin/ffmpeg",
+    "/usr/local/bin/ffmpeg",
+    "/usr/bin/ffmpeg",
+  ];
+  for (const candidate of candidates) {
+    if (await canRun(candidate)) return candidate;
+  }
+  return null;
+}
+
+async function canRun(path: string): Promise<boolean> {
+  const { promise, resolve } = Promise.withResolvers<boolean>();
+  const proc = spawn(path, FFMPEG_PROBE_ARGS as unknown as string[], { stdio: "ignore" });
+  proc.once("error", () => resolve(false));
+  proc.once("exit", (code) => resolve(code === 0));
+  return promise;
+}
+
+function hashFile(abs: string): string {
+  const hash = createHash("sha256");
+  hash.update(readFileSync(abs));
+  return hash.digest("hex");
+}
+
+function emptyManifest(duration: number): Manifest {
+  return {
+    version: 1,
+    generatedAt: new Date(0).toISOString(),
+    durationSeconds: duration,
+    fixtures: [],
+  };
+}

package/src/fixtures/matrix.ts

@@ -0,0 +1,94 @@
+// 完整的 codec × format 矩阵 + 单条 fixture plan。
+// 仅依赖 codec.ts / format.ts / config.ts;不引入 ffmpeg,以便单测可脱机运行。
+import { join } from "node:path";
+import { ALL_CODECS, ALL_FORMATS, type CodecId, type FormatId } from "../config.ts";
+import { CODEC_SPEC, containerExtraArgs } from "./codec.ts";
+import {
+  containerRelativeDir,
+  containerRelativePath,
+  layoutFor,
+  singleFileRelative,
+  type FormatLayout,
+} from "./format.ts";
+
+export type FixturePlan = {
+  codec: CodecId;
+  format: FormatId;
+  layout: FormatLayout;
+  containerDir: string;
+  mainFile: string;
+  files: ReadonlyArray<string>;
+  ffmpegOutputArgs: ReadonlyArray<string>;
+};
+
+export function buildPlan(codec: CodecId, format: FormatId, durationSeconds: number): FixturePlan {
+  const layout = layoutFor(codec, format);
+  const spec = CODEC_SPEC[codec];
+  const gop = String(durationSeconds * 25);
+  const videoInput = `testsrc2=size=1280x720:rate=25,format=yuv420p`;
+  const audioInput = `sine=frequency=1000:sample_rate=44100`;
+
+  // 关键 GOP 锁:25 fps × duration,保证每个 fixture 至少一个 IDR。
+  const ffmpegOutputArgs = [
+    "-y",
+    "-f",
+    "lavfi",
+    "-i",
+    videoInput,
+    "-f",
+    "lavfi",
+    "-i",
+    audioInput,
+    "-t",
+    String(durationSeconds),
+    "-c:v",
+    spec.encoder,
+    ...spec.videoArgs,
+    "-pix_fmt",
+    spec.pixelFormat,
+    "-g",
+    gop,
+    "-keyint_min",
+    gop,
+    "-sc_threshold",
+    "0",
+    ...containerExtraArgs(format, codec),
+    ...spec.audioArgs,
+    ...layout.containerArgs,
+  ];
+
+  if (layout.isContainerDirectory) {
+    const containerDir = containerRelativeDir(codec, format);
+    const mainFile = containerRelativePath(codec, format, layout.mainFileName);
+    const files = [
+      mainFile,
+      ...layout.sideFiles.map((s) => containerRelativePath(codec, format, s)),
+    ];
+    return { codec, format, layout, containerDir, mainFile, files, ffmpegOutputArgs };
+  }
+  // 单文件格式
+  const mainFile = singleFileRelative(codec, format);
+  const containerDir = join(mainFile.split("/").slice(0, -1).join("/"));
+  return { codec, format, layout, containerDir, mainFile, files: [mainFile], ffmpegOutputArgs };
+}
+
+export function expandMatrix(opts?: {
+  codecs?: ReadonlyArray<CodecId>;
+  formats?: ReadonlyArray<FormatId>;
+  durationSeconds?: number;
+}): ReadonlyArray<FixturePlan> {
+  const codecs = opts?.codecs ?? ALL_CODECS;
+  const formats = opts?.formats ?? ALL_FORMATS;
+  const duration = opts?.durationSeconds ?? 5;
+  const plans: FixturePlan[] = [];
+  for (const codec of codecs) {
+    for (const format of formats) {
+      plans.push(buildPlan(codec, format, duration));
+    }
+  }
+  return plans;
+}
+
+// VOD 段默认从 mp4/h264.mp4 派生(同 fixture)。generate.ts 在生成结束后
+// 把真实 fileSize 写进 vodList.example.json;此处只描述派生约定。
+export const VOD_SAMPLE_RELATIVE = "mp4/h264.mp4";

package/src/index.ts

@@ -0,0 +1,41 @@
+// 公共 API 入口。generate / serve / catalog / server 各模块在此 re-export。
+export {
+  buildPlan,
+  expandMatrix,
+  VOD_SAMPLE_RELATIVE,
+  type FixturePlan,
+} from "./fixtures/matrix.ts";
+export {
+  loadManifest,
+  lookupFixture,
+  summarizeCatalog,
+  verifyEntryOnDisk,
+  type CatalogSummary,
+  type FixtureLookup,
+  type Manifest,
+  type ManifestEntry,
+  type ManifestItem,
+} from "./fixtures/catalog.ts";
+export { CODEC_SPEC, type CodecSpec } from "./fixtures/codec.ts";
+export {
+  layoutFor,
+  containerRelativeDir,
+  containerRelativePath,
+  type FormatLayout,
+} from "./fixtures/format.ts";
+export {
+  ALL_CODECS,
+  ALL_FORMATS,
+  DEFAULT_DURATION_SECONDS,
+  DEFAULT_FIXTURE_DIR,
+  DEFAULT_HLS_SEGMENT_SECONDS,
+  DEFAULT_HOST,
+  DEFAULT_PORT,
+  type CodecId,
+  type FormatId,
+  type GenerateOptions,
+  type ServeOptions,
+} from "./config.ts";
+export { createStreamsServer, type StreamsServerHandle } from "./server/server.ts";
+export { generateFixtures, type GenerateResult } from "./fixtures/generate.ts";
+export { handleLiveStream, matchLivePath, type LiveStreamOptions } from "./server/live.ts";