@flow-player/test-streams 0.6.0

package/src/visual/analyze.ts

@@ -0,0 +1,234 @@
+// 帧差 / 掉帧 / 倍速密度 / 倒放判定 — 纯 node，无依赖。
+// 输入：{ timestampMs, hash }[] 序列。
+// 输出：可序列化的 JSON 报告 + 人类可读 ASCII timeline。
+
+import { hammingDistance, isStaticFrame } from "./dhash.ts";
+
+export type FrameSample = {
+  timestampMs: number;
+  hash: string;
+};
+
+export type FrameDeltas = {
+  timestampMs: number;
+  distance: number;
+  moving: boolean;
+};
+
+export type StuckStreak = {
+  startMs: number;
+  endMs: number;
+  durationMs: number;
+  frames: number;
+};
+
+export type MovingWindow = {
+  windowStartMs: number;
+  windowEndMs: number;
+  movingCount: number;
+  total: number;
+  density: number; // moving/total
+};
+
+export type ReverseCheck = {
+  passed: boolean;
+  reason: string;
+  firstHash: string;
+  expectedAnchor: string;
+  observedAt: number;
+  distanceToAnchor: number;
+};
+
+export type AnalysisReport = {
+  totalFrames: number;
+  durationMs: number;
+  firstHash: string;
+  lastHash: string;
+  staticThreshold: number;
+  movingFrames: number;
+  movingRatio: number;
+  deltas: FrameDeltas[];
+  stuckStreaks: StuckStreak[];
+  longestStuckMs: number;
+  movingDensity: MovingWindow[];
+  averageMovingDensity: number;
+  reverse: ReverseCheck;
+};
+
+const DEFAULT_STATIC_THRESHOLD = 2; // dHash hamming distance ≤ 2 视为静止
+
+export function computeDeltas(
+  samples: ReadonlyArray<FrameSample>,
+  staticThreshold = DEFAULT_STATIC_THRESHOLD,
+): FrameDeltas[] {
+  const out: FrameDeltas[] = [];
+  for (let i = 1; i < samples.length; i += 1) {
+    const prev = samples[i - 1];
+    const cur = samples[i];
+    const distance = hammingDistance(prev.hash, cur.hash);
+    out.push({
+      timestampMs: cur.timestampMs,
+      distance,
+      moving: distance > staticThreshold,
+    });
+  }
+  return out;
+}
+
+export function findStuckStreaks(deltas: ReadonlyArray<FrameDeltas>): StuckStreak[] {
+  const streaks: StuckStreak[] = [];
+  let runStart: number | null = null;
+  for (let i = 0; i < deltas.length; i += 1) {
+    const d = deltas[i];
+    if (!d.moving) {
+      if (runStart === null) {
+        runStart = i;
+      }
+    } else if (runStart !== null) {
+      const start = deltas[runStart];
+      const end = deltas[i - 1];
+      streaks.push({
+        startMs: start.timestampMs,
+        endMs: end.timestampMs,
+        durationMs: end.timestampMs - start.timestampMs,
+        frames: i - runStart,
+      });
+      runStart = null;
+    }
+  }
+  if (runStart !== null && deltas.length > 0) {
+    const start = deltas[runStart];
+    const end = deltas[deltas.length - 1];
+    streaks.push({
+      startMs: start.timestampMs,
+      endMs: end.timestampMs,
+      durationMs: end.timestampMs - start.timestampMs,
+      frames: deltas.length - runStart,
+    });
+  }
+  return streaks;
+}
+
+export function movingDensityByWindow(
+  deltas: ReadonlyArray<FrameDeltas>,
+  windowMs = 1000,
+): MovingWindow[] {
+  if (deltas.length === 0) return [];
+  const out: MovingWindow[] = [];
+  let lo = 0;
+  for (let hi = 0; hi < deltas.length; hi += 1) {
+    while (deltas[hi].timestampMs - deltas[lo].timestampMs > windowMs) {
+      lo += 1;
+    }
+    const slice = deltas.slice(lo, hi + 1);
+    const movingCount = slice.reduce((acc, d) => acc + (d.moving ? 1 : 0), 0);
+    out.push({
+      windowStartMs: deltas[lo].timestampMs,
+      windowEndMs: deltas[hi].timestampMs,
+      movingCount,
+      total: slice.length,
+      density: slice.length === 0 ? 0 : movingCount / slice.length,
+    });
+  }
+  return out;
+}
+
+// 倒放开锚判定：倒放段首帧 hash 与正播段尾帧 hash 距离应在阈值内。
+// 阈值 6/64 ≈ 9% bit 差异，容纳 WebCodecs 解码噪声 + 截图重采样噪声。
+const REVERSE_ANCHOR_DISTANCE = 6;
+
+export function checkReverseAnchor(
+  forwardTail: FrameSample,
+  reverseHead: FrameSample,
+  tolerance = REVERSE_ANCHOR_DISTANCE,
+): ReverseCheck {
+  const distance = hammingDistance(forwardTail.hash, reverseHead.hash);
+  if (distance <= tolerance) {
+    return {
+      passed: true,
+      reason: `reverse head matches forward tail (distance=${distance})`,
+      firstHash: reverseHead.hash,
+      expectedAnchor: forwardTail.hash,
+      observedAt: reverseHead.timestampMs,
+      distanceToAnchor: distance,
+    };
+  }
+  return {
+    passed: false,
+    reason: `reverse head does NOT match forward tail (distance=${distance}, tolerance=${tolerance})`,
+    firstHash: reverseHead.hash,
+    expectedAnchor: forwardTail.hash,
+    observedAt: reverseHead.timestampMs,
+    distanceToAnchor: distance,
+  };
+}
+
+export function analyze(
+  samples: ReadonlyArray<FrameSample>,
+  options: {
+    staticThreshold?: number;
+    reverseAnchor?: FrameSample | null;
+  } = {},
+): AnalysisReport {
+  if (samples.length === 0) {
+    return {
+      totalFrames: 0,
+      durationMs: 0,
+      firstHash: "",
+      lastHash: "",
+      staticThreshold: options.staticThreshold ?? DEFAULT_STATIC_THRESHOLD,
+      movingFrames: 0,
+      movingRatio: 0,
+      deltas: [],
+      stuckStreaks: [],
+      longestStuckMs: 0,
+      movingDensity: [],
+      averageMovingDensity: 0,
+      reverse: {
+        passed: false,
+        reason: "no samples",
+        firstHash: "",
+        expectedAnchor: "",
+        observedAt: 0,
+        distanceToAnchor: 0,
+      },
+    };
+  }
+  const staticThreshold = options.staticThreshold ?? DEFAULT_STATIC_THRESHOLD;
+  const deltas = computeDeltas(samples, staticThreshold);
+  const streaks = findStuckStreaks(deltas);
+  const density = movingDensityByWindow(deltas);
+  const movingCount = deltas.reduce((acc, d) => acc + (d.moving ? 1 : 0), 0);
+  const last = samples[samples.length - 1];
+  const reverse: ReverseCheck = options.reverseAnchor
+    ? checkReverseAnchor(options.reverseAnchor, last, REVERSE_ANCHOR_DISTANCE)
+    : {
+        passed: false,
+        reason: "no reverse anchor provided",
+        firstHash: last.hash,
+        expectedAnchor: "",
+        observedAt: last.timestampMs,
+        distanceToAnchor: 0,
+      };
+  const longestStuck = streaks.reduce((acc, s) => Math.max(acc, s.durationMs), 0);
+  const avgDensity =
+    density.length === 0 ? 0 : density.reduce((acc, d) => acc + d.density, 0) / density.length;
+  return {
+    totalFrames: samples.length,
+    durationMs: last.timestampMs - samples[0].timestampMs,
+    firstHash: samples[0].hash,
+    lastHash: last.hash,
+    staticThreshold,
+    movingFrames: movingCount,
+    movingRatio: deltas.length === 0 ? 0 : movingCount / deltas.length,
+    deltas,
+    stuckStreaks: streaks,
+    longestStuckMs: longestStuck,
+    movingDensity: density,
+    averageMovingDensity: avgDensity,
+    reverse,
+  };
+}
+
+// 复用 dHash 的 isStaticFrame 给上层调用方，避免重复实现。
+export { isStaticFrame };

package/src/visual/dhash.ts

@@ -0,0 +1,76 @@
+// 8x8 difference hash (dHash) — 纯 node 实现，零依赖。
+// 输入：raw RGBA 字节序 buffer (Uint8Array) + 原始宽高。
+// 输出：16-char 十六进制字符串 (64 bit)，相同/近似画面 = 相同/近似 hash。
+//
+// 步骤：
+//   1. 9x8 cell 中心 1 像素采样 (nearest neighbor) — 不做 box-filter 平均
+//      因为 testsrc2 / 横向彩条在 1280x720 上 box-filter 会把 9x8 全部平均成
+//      相同值，hash 全 0。中心采样保留空间结构。
+//   2. Y = 0.299 R + 0.587 G + 0.114 B 灰度
+//   3. 横向相邻像素比较，8 行 × 8 列 = 64 bit
+//
+// 参考: https://www.hackerfactor.com/blog/index.php?/archives/529-Kind-of-Like-That.html
+// 故意不引 sharp/jimp/pngjs：30fps × 30s = 900 帧 × 4 字节 = 1.1MB 原始数据，
+// 缩放计算用纯 node 整数算，900 帧 < 50ms，远低于 sharp native startup 开销。
+
+export type RgbaBuffer = Uint8Array | Uint8ClampedArray | Buffer;
+
+const LUMA_R = 0.299;
+const LUMA_G = 0.587;
+const LUMA_B = 0.114;
+
+export function dHash8x8(rgba: RgbaBuffer, width: number, height: number): string {
+  if (rgba.length < width * height * 4) {
+    throw new Error(
+      `dHash8x8: buffer too small (${rgba.length} bytes) for ${width}x${height} RGBA`,
+    );
+  }
+  const cellW = width / 9;
+  const cellH = height / 8;
+  const gray = new Float64Array(9 * 8);
+  for (let y = 0; y < 8; y += 1) {
+    const cy = Math.min(height - 1, Math.floor((y + 0.5) * cellH));
+    for (let x = 0; x < 9; x += 1) {
+      const cx = Math.min(width - 1, Math.floor((x + 0.5) * cellW));
+      const off = (cy * width + cx) * 4;
+      gray[y * 9 + x] = LUMA_R * rgba[off] + LUMA_G * rgba[off + 1] + LUMA_B * rgba[off + 2];
+    }
+  }
+  const hexChars = "0123456789abcdef";
+  let out = "";
+  for (let bit = 0; bit < 64; bit += 1) {
+    const y = Math.floor(bit / 8);
+    const x = bit % 8;
+    const left = gray[y * 9 + x];
+    const right = gray[y * 9 + x + 1];
+    out += left > right ? "1" : "0";
+    if ((bit + 1) % 4 === 0) {
+      const nibble = parseInt(out.slice(out.length - 4), 2);
+      out = out.slice(0, out.length - 4) + hexChars[nibble];
+    }
+  }
+  return out;
+}
+
+export function hammingDistance(a: string, b: string): number {
+  if (a.length !== b.length) {
+    return Math.max(a.length, b.length) * 4;
+  }
+  let dist = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    const xa = parseInt(a[i], 16);
+    const xb = parseInt(b[i], 16);
+    let v = xa ^ xb;
+    while (v > 0) {
+      dist += v & 1;
+      v >>= 1;
+    }
+  }
+  return dist;
+}
+
+// 阈值 2/64 = 3% bit 差异，认为画面静止。testsrc2 + sine 视频在动时
+// 相邻帧至少 1 列变化 (8 bits) → distance ≥ 8。
+export function isStaticFrame(a: string, b: string, threshold = 2): boolean {
+  return hammingDistance(a, b) <= threshold;
+}

package/src/visual/index.ts

@@ -0,0 +1,18 @@
+// 视觉验证工具汇总导出。
+export { dHash8x8, hammingDistance, isStaticFrame, type RgbaBuffer } from "./dhash.ts";
+
+export {
+  analyze,
+  computeDeltas,
+  findStuckStreaks,
+  movingDensityByWindow,
+  checkReverseAnchor,
+  type AnalysisReport,
+  type FrameDeltas,
+  type FrameSample,
+  type MovingWindow,
+  type ReverseCheck,
+  type StuckStreak,
+} from "./analyze.ts";
+
+export { asciiTimeline, writeHumanReport, writeJsonReport } from "./report.ts";

package/src/visual/report.ts

@@ -0,0 +1,80 @@
+// 报告输出 — 纯 node，无依赖。
+// JSON：完整 AnalysisReport。
+// ASCII timeline：把 deltas 序列压缩到 80 列，用 ▁▂▃▄▅▆▇█ 标 distance 高度。
+
+import type { AnalysisReport, FrameDeltas } from "./analyze.ts";
+
+const BAR_CHARS = "▁▂▃▄▅▆▇█";
+
+export function writeJsonReport(report: AnalysisReport): string {
+  return JSON.stringify(report, null, 2);
+}
+
+// 把 deltas 序列压缩到 `width` 列，每列取窗口内最大 distance。
+export function asciiTimeline(
+  deltas: ReadonlyArray<FrameDeltas>,
+  options: { width?: number; maxDistance?: number } = {},
+): string {
+  const width = options.width ?? 80;
+  const maxDistance = options.maxDistance ?? 32; // dHash 0-64
+  if (deltas.length === 0) return "(no deltas)";
+  if (deltas.length <= width) {
+    return deltas
+      .map((d) => {
+        const idx = Math.min(
+          BAR_CHARS.length - 1,
+          Math.floor((d.distance / maxDistance) * BAR_CHARS.length),
+        );
+        return BAR_CHARS[idx];
+      })
+      .join("");
+  }
+  // 滑动窗口
+  const lines: string[] = [];
+  const bucketSize = Math.ceil(deltas.length / width);
+  for (let i = 0; i < deltas.length; i += bucketSize) {
+    const slice = deltas.slice(i, i + bucketSize);
+    const peak = slice.reduce((acc, d) => Math.max(acc, d.distance), 0);
+    const idx = Math.min(BAR_CHARS.length - 1, Math.floor((peak / maxDistance) * BAR_CHARS.length));
+    lines.push(BAR_CHARS[idx]);
+  }
+  return lines.join("");
+}
+
+export function writeHumanReport(report: AnalysisReport): string {
+  const lines: string[] = [];
+  lines.push(`# Visual Frame Analysis`);
+  lines.push("");
+  lines.push(`- Total frames:    ${report.totalFrames}`);
+  lines.push(`- Duration:        ${report.durationMs} ms`);
+  lines.push(`- Static threshold: distance <= ${report.staticThreshold}/64`);
+  lines.push(
+    `- Moving frames:   ${report.movingFrames} (${(report.movingRatio * 100).toFixed(1)}%)`,
+  );
+  lines.push(`- Longest stuck:   ${report.longestStuckMs} ms`);
+  lines.push(
+    `- Avg density:     ${(report.averageMovingDensity * 100).toFixed(1)}% moving/1s window`,
+  );
+  lines.push(`- Stuck streaks:   ${report.stuckStreaks.length}`);
+  lines.push(`- First hash:      ${report.firstHash}`);
+  lines.push(`- Last hash:       ${report.lastHash}`);
+  lines.push("");
+  lines.push(`## Reverse anchor check`);
+  lines.push(`- Passed:  ${report.reverse.passed}`);
+  lines.push(`- Reason:  ${report.reverse.reason}`);
+  lines.push(`- Distance: ${report.reverse.distanceToAnchor}/64`);
+  lines.push("");
+  lines.push(`## Timeline (deltas, max ${BAR_CHARS.length} levels)`);
+  lines.push("```");
+  lines.push(asciiTimeline(report.deltas));
+  lines.push("```");
+  if (report.stuckStreaks.length > 0) {
+    lines.push("");
+    lines.push(`## Top stuck streaks (longest 5)`);
+    const top = [...report.stuckStreaks].sort((a, b) => b.durationMs - a.durationMs).slice(0, 5);
+    for (const s of top) {
+      lines.push(`- [${s.startMs}ms → ${s.endMs}ms] ${s.durationMs}ms (${s.frames} frames)`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/vite-plugin.d.ts

@@ -0,0 +1,10 @@
+import type { Plugin } from "vite";
+
+export interface TestStreamsVitePluginOptions {
+  cert?: string;
+  key?: string;
+  healthUrl?: string;
+  logPath?: string;
+}
+
+export declare function testStreamsVitePlugin(options?: TestStreamsVitePluginOptions): Plugin;

package/src/vite-plugin.ts

@@ -0,0 +1,76 @@
+// 本地测试流服务的 dev 自准备插件（仅 serve 生效）：vite dev 启动时探测
+// streams server 健康状态，未就绪则后台拉起 `src/cli/serve.ts`（detached，
+// 日志写 /tmp/test-streams.log）。demo 等本地 consumer 无需再在 package.json
+// 里编排 streams 启动命令。
+import { spawn } from "node:child_process";
+import { openSync } from "node:fs";
+import https from "node:https";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Plugin } from "vite";
+
+export interface TestStreamsVitePluginOptions {
+  /** TLS 证书路径，传给 streams serve（默认 /tmp/flow-player-local.pem）。 */
+  cert?: string;
+  /** TLS 私钥路径，传给 streams serve（默认 /tmp/flow-player-local-key.pem）。 */
+  key?: string;
+  /** streams server 健康检查 URL（默认 https://127.0.0.1:4177/streams/health）。 */
+  healthUrl?: string;
+  /** streams server 日志文件（默认 /tmp/test-streams.log）。 */
+  logPath?: string;
+}
+
+const DEFAULT_CERT = "/tmp/flow-player-local.pem";
+const DEFAULT_KEY = "/tmp/flow-player-local-key.pem";
+const DEFAULT_HEALTH_URL = "https://127.0.0.1:4177/streams/health";
+const DEFAULT_LOG_PATH = "/tmp/test-streams.log";
+
+function streamsHealthy(healthUrl: string): Promise<boolean> {
+  return new Promise((resolveHealthy) => {
+    const req = https.get(
+      healthUrl,
+      { rejectUnauthorized: false, timeout: 2000 },
+      (res) => {
+        res.resume();
+        resolveHealthy(
+          res.statusCode !== undefined && res.statusCode >= 200 && res.statusCode < 300,
+        );
+      },
+    );
+    req.on("timeout", () => {
+      req.destroy();
+      resolveHealthy(false);
+    });
+    req.on("error", () => resolveHealthy(false));
+  });
+}
+
+export function testStreamsVitePlugin(options: TestStreamsVitePluginOptions = {}): Plugin {
+  const {
+    cert = DEFAULT_CERT,
+    key = DEFAULT_KEY,
+    healthUrl = DEFAULT_HEALTH_URL,
+    logPath = DEFAULT_LOG_PATH,
+  } = options;
+  const serveScript = resolve(dirname(fileURLToPath(import.meta.url)), "cli/serve.ts");
+
+  return {
+    name: "flow-player-test-streams",
+    apply: "serve",
+    configureServer() {
+      void (async () => {
+        if (await streamsHealthy(healthUrl)) {
+          return;
+        }
+        const logFd = openSync(logPath, "w");
+        const child = spawn(process.execPath, [serveScript, "--cert", cert, "--key", key], {
+          detached: true,
+          windowsHide: true,
+          stdio: ["ignore", logFd, logFd],
+        });
+        child.unref();
+        console.log(`[test-streams] 未就绪，已在后台启动，日志: ${logPath}`);
+      })();
+    },
+  };
+}