dsh-pf-stream 0.0.0-stage → 0.1.2

package/lib/stage0/decoder.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Stage 0 —— 双模解码调度（契约 3）。
+ *
+ * - seek_points（定点寻址）：目标 PTS 排序去重后逐点 `ffmpeg -ss <pts> -i <file> -frames:v 1`
+ *   关键帧跳跃 + 精解码，全分辨率（保障 OCR 级细节）；
+ * - 批量退化：目标数 ≥32 且平均间隔 ≤2s 时，排序后单遍区间解码摊薄寻址开销；
+ * - 空帧回退：解码端空输出时回退复用最后一个有效解码帧（契约 3）；
+ * - 解码输出天然处于显示坐标系（ffmpeg 默认 autorotate）。
+ *
+ * decodeRangeStreaming 为单遍流式消费（契约 3：每帧解码后同步派生感知图，
+ * 当场裁剪缩放入队并释放原图；await onFrame 期间 stdout 异步迭代自动背压）。
+ */
+import type { RgbImage } from '../utils/image.js';
+export interface DecodePointOptions {
+    ffmpegPath: string;
+    displayWidth: number;
+    displayHeight: number;
+    signal?: AbortSignal | undefined;
+}
+export type DecodePointFn = typeof decodePoint;
+/** 单点定点解码。返回 null 表示该 PTS 无帧输出（空帧）。 */
+export declare function decodePoint(videoPath: string, ptsMs: number, options: DecodePointOptions): Promise<RgbImage | null>;
+export interface PtsIndexEntry {
+    frameIndex: number;
+    ptsMs: number;
+}
+/** 窗口帧 PTS 索引（ffprobe -show_frames，VFR 安全）。 */
+export declare function probePtsIndex(ffprobePath: string, videoPath: string, window0Ms: number, window1Ms: number, signal?: AbortSignal | undefined): Promise<PtsIndexEntry[]>;
+export interface RangeDecodeOptions extends DecodePointOptions {
+    workMaxEdge?: number | undefined;
+    /** 每次 ffmpeg 解码进程启动时回调（argv 快照），供单遍解码断言计数。 */
+    onFfmpegSpawn?: ((argv: string[]) => void) | undefined;
+}
+/**
+ * 区间单遍解码（批量定点退化路径与流式共用骨架）。
+ * 返回帧序列（display 坐标系，全分辨率或受 workMaxEdge 上限的等比缩放）。
+ */
+export declare function decodeRange(videoPath: string, window0Ms: number, window1Ms: number, options: RangeDecodeOptions, onFrame?: (frame: RgbImage, ptsMs: number) => void | Promise<void>): Promise<Array<{
+    ptsMs: number;
+    image: RgbImage;
+}>>;
+export interface StreamDecodeResult {
+    frameCount: number;
+    /** 帧序号超出 PTS 索引长度时按最近 PTS 钳制的帧数。 */
+    realigned: number;
+}
+/**
+ * 单遍流式区间解码：stdout 逐帧切片回调，原始字节不整体驻留。
+ * onFrame 抛错时终止子进程并向上传播。
+ */
+export declare function decodeRangeStreaming(videoPath: string, window0Ms: number, window1Ms: number, options: RangeDecodeOptions, onFrame: (image: RgbImage, ptsMs: number) => Promise<void> | void): Promise<StreamDecodeResult>;
+/**
+ * 空帧回退解码（契约 3）：优先目标 PTS，空帧依次回退
+ * 调用方最后有效帧 → lastPtsMs → 半帧回退（PTS 毫秒取整进位会把
+ * -ss 目标推到末帧之后，回退 4ms 覆盖至 120fps 栅格），仍空则报错。
+ */
+export declare function decodePointWithFallback(videoPath: string, ptsMs: number, lastPtsMs: number, options: DecodePointOptions, lastValid?: RgbImage | null): Promise<RgbImage>;

package/lib/stage0/decoder.js

@@ -0,0 +1,229 @@
+/**
+ * Stage 0 —— 双模解码调度（契约 3）。
+ *
+ * - seek_points（定点寻址）：目标 PTS 排序去重后逐点 `ffmpeg -ss <pts> -i <file> -frames:v 1`
+ *   关键帧跳跃 + 精解码，全分辨率（保障 OCR 级细节）；
+ * - 批量退化：目标数 ≥32 且平均间隔 ≤2s 时，排序后单遍区间解码摊薄寻址开销；
+ * - 空帧回退：解码端空输出时回退复用最后一个有效解码帧（契约 3）；
+ * - 解码输出天然处于显示坐标系（ffmpeg 默认 autorotate）。
+ *
+ * decodeRangeStreaming 为单遍流式消费（契约 3：每帧解码后同步派生感知图，
+ * 当场裁剪缩放入队并释放原图；await onFrame 期间 stdout 异步迭代自动背压）。
+ */
+import { spawn } from 'node:child_process';
+import { PfStreamError } from '../errors.js';
+import { execFile } from './ffmpeg.js';
+/** 单点定点解码。返回 null 表示该 PTS 无帧输出（空帧）。 */
+export async function decodePoint(videoPath, ptsMs, options) {
+    const sec = (ptsMs / 1000).toFixed(3);
+    const argv = [
+        '-hide_banner',
+        '-loglevel', 'error',
+        '-ss', sec,
+        '-i', videoPath,
+        '-frames:v', '1',
+        '-an', '-sn', '-dn',
+        '-f', 'rawvideo',
+        '-pix_fmt', 'rgb24',
+        'pipe:1',
+    ];
+    const { stdout } = await execFile(options.ffmpegPath, argv, {
+        signal: options.signal,
+        encoding: 'buffer',
+    });
+    const frameBytes = options.displayWidth * options.displayHeight * 3;
+    if (stdout.length === 0)
+        return null;
+    return { width: options.displayWidth, height: options.displayHeight, data: stdout.subarray(0, frameBytes) };
+}
+/** 窗口帧 PTS 索引（ffprobe -show_frames，VFR 安全）。 */
+export async function probePtsIndex(ffprobePath, videoPath, window0Ms, window1Ms, signal) {
+    const interval = `${(window0Ms / 1000).toFixed(3)}%${(window1Ms / 1000).toFixed(3)}`;
+    const argv = [
+        '-v', 'error',
+        '-select_streams', 'v:0',
+        '-read_intervals', interval,
+        '-show_entries', 'frame=pts_time',
+        '-of', 'json',
+        videoPath,
+    ];
+    const { stdout } = await execFile(ffprobePath, argv, { signal, encoding: 'utf8' });
+    const parsed = JSON.parse(stdout);
+    const entries = [];
+    for (const f of parsed.frames ?? []) {
+        const t = f.pts_time;
+        if (t == null)
+            continue;
+        const ms = Number.parseFloat(t) * 1000;
+        // read_intervals 起点为关键帧回卷（pre-roll）：丢弃窗口外条目，
+        // 保证与 ffmpeg 精确 -ss 的首帧对齐（VFR 安全，亚毫秒精度）。
+        if (ms < window0Ms - 0.5 || ms > window1Ms + 0.5)
+            continue;
+        entries.push({ frameIndex: entries.length, ptsMs: ms });
+    }
+    return entries;
+}
+/**
+ * 区间单遍解码（批量定点退化路径与流式共用骨架）。
+ * 返回帧序列（display 坐标系，全分辨率或受 workMaxEdge 上限的等比缩放）。
+ */
+export async function decodeRange(videoPath, window0Ms, window1Ms, options, onFrame) {
+    const index = await probePtsIndexExec(options, videoPath, window0Ms, window1Ms);
+    if (index.length === 0)
+        return [];
+    const geometry = rangeOutputGeometry(options);
+    const argv = rangeArgv(videoPath, window0Ms, window1Ms, geometry);
+    const { stdout } = await execFile(options.ffmpegPath, argv, {
+        signal: options.signal,
+        encoding: 'buffer',
+    });
+    const frameBytes = geometry.outW * geometry.outH * 3;
+    const frameCount = Math.floor(stdout.length / frameBytes);
+    const frames = [];
+    for (let i = 0; i < frameCount; i++) {
+        const ptsMs = index[Math.min(i, index.length - 1)].ptsMs;
+        const image = {
+            width: geometry.outW,
+            height: geometry.outH,
+            data: stdout.subarray(i * frameBytes, (i + 1) * frameBytes),
+        };
+        frames.push({ ptsMs, image });
+        await onFrame?.(image, ptsMs);
+    }
+    return frames;
+}
+async function probePtsIndexExec(options, videoPath, w0, w1) {
+    // ffprobe 路径与 ffmpeg 同目录约定：入口适配层保证成对解析
+    const ffprobe = options.ffmpegPath.replace(/ffmpeg(\.exe)?$/i, 'ffprobe$1');
+    return probePtsIndex(ffprobe, videoPath, w0, w1, options.signal);
+}
+/** 区间解码输出几何（workMaxEdge 等比上限）。 */
+function rangeOutputGeometry(options) {
+    const vf = [];
+    let outW = options.displayWidth;
+    let outH = options.displayHeight;
+    const maxEdge = options.workMaxEdge ?? 0;
+    if (maxEdge > 0 && Math.max(options.displayWidth, options.displayHeight) > maxEdge) {
+        const k = maxEdge / Math.max(options.displayWidth, options.displayHeight);
+        outW = Math.max(2, Math.round(options.displayWidth * k) & ~1);
+        outH = Math.max(2, Math.round(options.displayHeight * k) & ~1);
+        vf.push(`scale=${outW}:${outH}`);
+    }
+    return { outW, outH, vf };
+}
+function rangeArgv(videoPath, window0Ms, window1Ms, geometry) {
+    const durationSec = ((window1Ms - window0Ms) / 1000 + 1.0).toFixed(3);
+    return [
+        '-hide_banner',
+        '-loglevel', 'error',
+        '-ss', (window0Ms / 1000).toFixed(3),
+        '-i', videoPath,
+        '-t', durationSec,
+        '-an', '-sn', '-dn',
+        '-fps_mode', 'passthrough',
+        ...(geometry.vf.length > 0 ? ['-vf', geometry.vf.join(',')] : []),
+        '-f', 'rawvideo',
+        '-pix_fmt', 'rgb24',
+        'pipe:1',
+    ];
+}
+/**
+ * 单遍流式区间解码：stdout 逐帧切片回调，原始字节不整体驻留。
+ * onFrame 抛错时终止子进程并向上传播。
+ */
+export async function decodeRangeStreaming(videoPath, window0Ms, window1Ms, options, onFrame) {
+    const index = await probePtsIndexExec(options, videoPath, window0Ms, window1Ms);
+    if (index.length === 0)
+        return { frameCount: 0, realigned: 0 };
+    const geometry = rangeOutputGeometry(options);
+    const argv = rangeArgv(videoPath, window0Ms, window1Ms, geometry);
+    const frameBytes = geometry.outW * geometry.outH * 3;
+    const child = spawn(options.ffmpegPath, argv, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    options.onFfmpegSpawn?.(argv);
+    const stderrChunks = [];
+    let stderrBytes = 0;
+    child.stderr?.on('data', (chunk) => {
+        if (stderrBytes < 64 * 1024) {
+            stderrChunks.push(chunk);
+            stderrBytes += chunk.length;
+        }
+    });
+    let pending = null;
+    let frameIndex = 0;
+    let realigned = 0;
+    let killed = false;
+    let indexExhausted = false;
+    const exited = new Promise((resolveExit, rejectExit) => {
+        child.once('error', rejectExit);
+        child.once('close', (code) => resolveExit(code));
+    });
+    try {
+        for await (const chunk of child.stdout) {
+            pending = pending ? Buffer.concat([pending, chunk]) : chunk;
+            while (pending && pending.length >= frameBytes) {
+                if (frameIndex >= index.length) {
+                    // 索引耗尽：解码裕量产出的 surplus 帧位于窗口之外，丢弃并终止解码。
+                    indexExhausted = true;
+                    break;
+                }
+                const image = {
+                    width: geometry.outW,
+                    height: geometry.outH,
+                    data: pending.subarray(0, frameBytes),
+                };
+                await onFrame(image, index[frameIndex].ptsMs);
+                pending = pending.length > frameBytes ? pending.subarray(frameBytes) : null;
+                frameIndex++;
+            }
+            if (indexExhausted) {
+                killed = true;
+                child.kill();
+                break;
+            }
+            if (options.signal?.aborted)
+                break;
+        }
+    }
+    catch (error) {
+        killed = true;
+        child.kill();
+        throw error;
+    }
+    if (options.signal?.aborted && !killed) {
+        child.kill();
+        await exited;
+        throw new PfStreamError('PFSTREAM_EXEC_ABORT', '解码已被调用方取消');
+    }
+    const code = await exited;
+    if (code !== 0 && !killed) {
+        const stderrTail = Buffer.concat(stderrChunks)
+            .subarray(Math.max(0, stderrBytes - 2048))
+            .toString('utf8');
+        throw new PfStreamError('PFSTREAM_EXEC_NONZERO', `ffmpeg 流式解码退出码 ${code}\nstderr 尾部：\n${stderrTail}`);
+    }
+    return { frameCount: frameIndex, realigned };
+}
+/**
+ * 空帧回退解码（契约 3）：优先目标 PTS，空帧依次回退
+ * 调用方最后有效帧 → lastPtsMs → 半帧回退（PTS 毫秒取整进位会把
+ * -ss 目标推到末帧之后，回退 4ms 覆盖至 120fps 栅格），仍空则报错。
+ */
+export async function decodePointWithFallback(videoPath, ptsMs, lastPtsMs, options, lastValid) {
+    const direct = await decodePoint(videoPath, ptsMs, options);
+    if (direct)
+        return direct;
+    if (lastValid)
+        return lastValid;
+    if (ptsMs !== lastPtsMs) {
+        const fallback = await decodePoint(videoPath, lastPtsMs, options);
+        if (fallback)
+            return fallback;
+    }
+    if (ptsMs > 0) {
+        const nudge = await decodePoint(videoPath, ptsMs - 4, options);
+        if (nudge)
+            return nudge;
+    }
+    throw new PfStreamError('PFSTREAM_DECODE_EMPTY', `时间点 ${ptsMs}ms 无可解码帧`);
+}
+//# sourceMappingURL=decoder.js.map

package/lib/stage0/decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder.js","sourceRoot":"","sources":["../../src/stage0/decoder.ts"],"names":[],"mappings":"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"}

package/lib/stage0/ffmpeg.d.ts

@@ -0,0 +1,34 @@
+/**
+ * ffmpeg / ffprobe 子进程封装。
+ *
+ * 约束（技术方案 §4.7 交互协议）：
+ * - argv 数组直接传给 spawn，不经 shell 拼接；
+ * - stdout / stderr 分别累计，超上限截断（防失控输出撑爆内存）；
+ * - 超时与调用方 AbortSignal 协作终止进程，退出码非 0 时抛参数化错误；
+ * - Windows 沙箱下管道捕获受限时优先 spawn stdio:'ignore' 形态（由调用方选择）。
+ */
+export interface ExecOptions {
+    /** 毫秒；缺省不限时。 */
+    timeoutMs?: number | undefined;
+    /** 调用方取消信号。 */
+    signal?: AbortSignal | undefined;
+    /** stdout 编码：'utf8' 返回 string，'buffer' 返回 Buffer。 */
+    encoding?: 'utf8' | 'buffer' | undefined;
+}
+export interface ExecTextResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface ExecBufferResult {
+    stdout: Buffer;
+    stderr: string;
+    exitCode: number;
+}
+export type ExecResult = ExecTextResult | ExecBufferResult;
+export declare function execFile(file: string, args: string[], options: ExecOptions & {
+    encoding?: 'utf8';
+}): Promise<ExecTextResult>;
+export declare function execFile(file: string, args: string[], options: ExecOptions & {
+    encoding: 'buffer';
+}): Promise<ExecBufferResult>;

package/lib/stage0/ffmpeg.js

@@ -0,0 +1,90 @@
+/**
+ * ffmpeg / ffprobe 子进程封装。
+ *
+ * 约束（技术方案 §4.7 交互协议）：
+ * - argv 数组直接传给 spawn，不经 shell 拼接；
+ * - stdout / stderr 分别累计，超上限截断（防失控输出撑爆内存）；
+ * - 超时与调用方 AbortSignal 协作终止进程，退出码非 0 时抛参数化错误；
+ * - Windows 沙箱下管道捕获受限时优先 spawn stdio:'ignore' 形态（由调用方选择）。
+ */
+import { spawn } from 'node:child_process';
+import { PfStreamError } from '../errors.js';
+const MAX_STDOUT_BYTES = 64 * 1024 * 1024;
+const MAX_STDERR_BYTES = 256 * 1024;
+export function execFile(file, args, options = {}) {
+    const { timeoutMs, signal, encoding = 'utf8' } = options;
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(file, args, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                windowsHide: true,
+            });
+        }
+        catch (error) {
+            reject(new PfStreamError('PFSTREAM_SPAWN_FAILED', `无法启动 ${file}：${error.message}`));
+            return;
+        }
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let settled = false;
+        const tail = (chunks, bytes) => Buffer.concat(chunks.length > 8 ? chunks.slice(-8) : chunks).subarray(Math.max(0, bytes - 2048)).toString('utf8');
+        const onKill = (code, message) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new PfStreamError(code, `${message}\nstderr 尾部：\n${tail(stderrChunks, stderrBytes)}`));
+        };
+        child.stdout.on('data', (chunk) => {
+            if (stdoutBytes < MAX_STDOUT_BYTES) {
+                stdoutChunks.push(chunk);
+                stdoutBytes += chunk.length;
+            }
+        });
+        child.stderr.on('data', (chunk) => {
+            if (stderrBytes < MAX_STDERR_BYTES) {
+                stderrChunks.push(chunk);
+                stderrBytes += chunk.length;
+            }
+        });
+        const timer = timeoutMs !== undefined
+            ? setTimeout(() => {
+                child.kill();
+                onKill('PFSTREAM_EXEC_TIMEOUT', `${file} 执行超过 ${timeoutMs}ms`);
+            }, timeoutMs)
+            : undefined;
+        const onAbort = () => {
+            child.kill();
+            onKill('PFSTREAM_EXEC_ABORT', `${file} 被调用方取消`);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        child.on('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            reject(new PfStreamError('PFSTREAM_SPAWN_FAILED', `无法启动 ${file}：${error.message}`));
+        });
+        child.on('close', (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            const stdout = encoding === 'buffer' ? Buffer.concat(stdoutChunks) : Buffer.concat(stdoutChunks).toString('utf8');
+            const stderr = Buffer.concat(stderrChunks).toString('utf8');
+            if (exitCode === 0) {
+                resolve({ stdout, stderr, exitCode });
+            }
+            else {
+                reject(new PfStreamError('PFSTREAM_EXEC_NONZERO', `${file} 退出码 ${exitCode}\nstderr 尾部：\n${tail(stderrChunks, stderrBytes)}`));
+            }
+        });
+    });
+}
+//# sourceMappingURL=ffmpeg.js.map

package/lib/stage0/ffmpeg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg.js","sourceRoot":"","sources":["../../src/stage0/ffmpeg.ts"],"names":[],"mappings":"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"}

package/lib/stage0/probe.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Stage 0 媒体探测：元数据 + 旋转归一化 + 末帧 PTS 双路径（契约 2 / 契约 3）。
+ *
+ * - 旋转双源：side_data_list[].rotation（Display Matrix，ffprobe 归一化到
+ *   [-90,180] 区间，如 270° 报告 -90）与旧式 tags.rotate；统一归一到
+ *   {0,90,180,270}，90°/270° 时在元数据层交换宽高建立显示坐标系。
+ * - last_pts_ms：优先 ffprobe 尾段逐帧探测（O(0.6s)），无帧输出时按
+ *   duration_ms − 2×(1000/avg_fps) 保守估算（VFR 末帧间隔覆盖）。
+ */
+import type { ProbeResult } from '../types.js';
+/** ffprobe -show_format -show_streams 的 JSON 形状（仅声明消费的字段）。 */
+export interface FfprobeJson {
+    streams?: Array<{
+        index?: number;
+        codec_type?: string;
+        codec_name?: string;
+        width?: number;
+        height?: number;
+        avg_frame_rate?: string;
+        r_frame_rate?: string;
+        duration?: string;
+        channels?: number;
+        tags?: Record<string, string>;
+        side_data_list?: Array<{
+            side_data_type?: string;
+            rotation?: number;
+        }>;
+    }>;
+    format?: {
+        duration?: string;
+        tags?: Record<string, string>;
+    };
+}
+export interface ProbeVideoOptions {
+    ffprobePath: string;
+    signal?: AbortSignal | undefined;
+}
+/** 旋转角归一化到 {0, 90, 180, 270}；非法输入按 0 处理。 */
+export declare function normalizeRotation(degrees: number | undefined | null): 0 | 90 | 180 | 270;
+/** 双源解析旋转角：Display Matrix 优先，旧式 tags.rotate 次之。 */
+export declare function extractRotation(stream: NonNullable<FfprobeJson['streams']>[number]): 0 | 90 | 180 | 270;
+/**
+ * 由 ffprobe JSON 构造 ProbeResult（纯函数，供单测直接覆盖 tags.rotate 等合成输入）。
+ * duration 优先级：format.duration > 视频流 duration > format.tags.DURATION。
+ */
+export declare function buildProbeResult(raw: FfprobeJson): ProbeResult;
+export declare function probeVideo(videoPath: string, options: ProbeVideoOptions): Promise<ProbeResult>;

package/lib/stage0/probe.js

@@ -0,0 +1,150 @@
+/**
+ * Stage 0 媒体探测：元数据 + 旋转归一化 + 末帧 PTS 双路径（契约 2 / 契约 3）。
+ *
+ * - 旋转双源：side_data_list[].rotation（Display Matrix，ffprobe 归一化到
+ *   [-90,180] 区间，如 270° 报告 -90）与旧式 tags.rotate；统一归一到
+ *   {0,90,180,270}，90°/270° 时在元数据层交换宽高建立显示坐标系。
+ * - last_pts_ms：优先 ffprobe 尾段逐帧探测（O(0.6s)），无帧输出时按
+ *   duration_ms − 2×(1000/avg_fps) 保守估算（VFR 末帧间隔覆盖）。
+ */
+import { stat } from 'node:fs/promises';
+import { PfStreamError } from '../errors.js';
+import { execFile } from './ffmpeg.js';
+import { clamp, estimateLastPtsMs, parseRational, secondsToMs } from '../utils/pts.js';
+const PROBE_TIMEOUT_MS = 60_000;
+/** 旋转角归一化到 {0, 90, 180, 270}；非法输入按 0 处理。 */
+export function normalizeRotation(degrees) {
+    if (typeof degrees !== 'number' || !Number.isFinite(degrees))
+        return 0;
+    const normalized = ((Math.round(degrees) % 360) + 360) % 360;
+    if (normalized === 90)
+        return 90;
+    if (normalized === 180)
+        return 180;
+    if (normalized === 270)
+        return 270;
+    return 0;
+}
+/** 双源解析旋转角：Display Matrix 优先，旧式 tags.rotate 次之。 */
+export function extractRotation(stream) {
+    const displayMatrix = (stream.side_data_list ?? []).find((side) => side.side_data_type === 'Display Matrix' && typeof side.rotation === 'number');
+    if (displayMatrix)
+        return normalizeRotation(displayMatrix.rotation);
+    const rotateTag = stream.tags?.['rotate'];
+    if (rotateTag !== undefined)
+        return normalizeRotation(Number.parseFloat(rotateTag));
+    return 0;
+}
+/**
+ * 由 ffprobe JSON 构造 ProbeResult（纯函数，供单测直接覆盖 tags.rotate 等合成输入）。
+ * duration 优先级：format.duration > 视频流 duration > format.tags.DURATION。
+ */
+export function buildProbeResult(raw) {
+    const video = raw.streams?.find((stream) => stream.codec_type === 'video');
+    if (!video) {
+        throw new PfStreamError('PFSTREAM_PROBE_NO_VIDEO', '容器内不存在视频流');
+    }
+    const codedWidth = video.width ?? 0;
+    const codedHeight = video.height ?? 0;
+    const rotation = extractRotation(video);
+    const swap = rotation === 90 || rotation === 270;
+    const avgFps = parseRational(video.avg_frame_rate) > 0
+        ? parseRational(video.avg_frame_rate)
+        : parseRational(video.r_frame_rate);
+    const durationMs = secondsToMs(raw.format?.duration) ||
+        secondsToMs(video.duration) ||
+        secondsToMs(raw.format?.tags?.['DURATION']);
+    const audioStreams = (raw.streams ?? [])
+        .filter((stream) => stream.codec_type === 'audio')
+        .map((stream) => ({
+        index: stream.index ?? 0,
+        codec: stream.codec_name ?? 'unknown',
+        ...(stream.channels !== undefined ? { channels: stream.channels } : {}),
+    }));
+    const subtitleStreams = (raw.streams ?? [])
+        .filter((stream) => stream.codec_type === 'subtitle')
+        .map((stream) => ({
+        index: stream.index ?? 0,
+        codec: stream.codec_name ?? 'unknown',
+        ...(stream.tags?.['language'] !== undefined ? { language: stream.tags['language'] } : {}),
+    }));
+    return {
+        codedWidth,
+        codedHeight,
+        displayWidth: swap ? codedHeight : codedWidth,
+        displayHeight: swap ? codedWidth : codedHeight,
+        rotation,
+        durationMs,
+        lastPtsMs: estimateLastPtsMs(durationMs, avgFps),
+        avgFps,
+        codec: video.codec_name ?? 'unknown',
+        audioStreams,
+        subtitleStreams,
+    };
+}
+/**
+ * 末帧 PTS 逐帧探测：只读容器尾段（0.6s 起读窗口 + 5s 余量）。
+ * 返回末帧 pts_time 毫秒；无帧输出或探测失败返回 null（调用方回退估算路径）。
+ */
+async function probeLastFramePtsMs(options, durationMs, videoPath) {
+    const startSec = Math.max(0, (durationMs - 600) / 1000);
+    const argv = [
+        '-v', 'error',
+        '-select_streams', 'v:0',
+        '-show_frames',
+        '-show_entries', 'frame=pts_time',
+        '-of', 'json',
+        '-read_intervals', `${startSec.toFixed(3)}%+5`,
+        '-i', videoPath,
+    ];
+    let parsed;
+    try {
+        const { stdout } = await execFile(options.ffprobePath, argv, {
+            timeoutMs: PROBE_TIMEOUT_MS,
+            signal: options.signal,
+        });
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    const frames = parsed.frames ?? [];
+    for (let i = frames.length - 1; i >= 0; i -= 1) {
+        const ptsTime = frames[i]?.pts_time;
+        if (ptsTime !== undefined) {
+            const ms = secondsToMs(ptsTime);
+            if (ms >= 0)
+                return clamp(ms, 0, Math.max(durationMs, ms));
+        }
+    }
+    return null;
+}
+export async function probeVideo(videoPath, options) {
+    try {
+        const info = await stat(videoPath);
+        if (!info.isFile()) {
+            throw new PfStreamError('PFSTREAM_PROBE_NOT_FOUND', `路径不是常规文件：${videoPath}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof PfStreamError)
+            throw error;
+        throw new PfStreamError('PFSTREAM_PROBE_NOT_FOUND', `文件不存在或不可访问：${videoPath}`);
+    }
+    let raw;
+    try {
+        const { stdout } = await execFile(options.ffprobePath, ['-v', 'error', '-print_format', 'json', '-show_format', '-show_streams', videoPath], { timeoutMs: PROBE_TIMEOUT_MS, signal: options.signal });
+        raw = JSON.parse(stdout);
+    }
+    catch (error) {
+        if (error instanceof PfStreamError && error.code === 'PFSTREAM_SPAWN_FAILED')
+            throw error;
+        throw new PfStreamError('PFSTREAM_PROBE_FAILED', error.message);
+    }
+    const result = buildProbeResult(raw);
+    const lastFramePtsMs = await probeLastFramePtsMs(options, result.durationMs, videoPath);
+    if (lastFramePtsMs !== null)
+        result.lastPtsMs = lastFramePtsMs;
+    return result;
+}
+//# sourceMappingURL=probe.js.map

package/lib/stage0/probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../../src/stage0/probe.ts"],"names":[],"mappings":"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"}