@xiping/node-utils 1.0.64 → 1.0.65

package/lib/src/ffmpeg/getThumbnail.d.ts

@@ -1,7 +1,3 @@
-/**
- * 视频缩略图生成器
- * 使用 ffmpeg 提取视频帧，使用 sharp 合成缩略图
- */
 /** 进度信息，用于 onProgress 回调 */
 export interface ThumbnailProgress {
     /** 当前阶段 */
@@ -15,17 +11,26 @@ export interface ThumbnailProgress {
     /** 可读描述 */
     message?: string;
 }
-interface ThumbnailOptions {
+export interface ThumbnailOptions {
+    /** 参与合成的帧数（实际提取 frames - 1 张），默认 60 */
     frames?: number;
+    /** 输出图宽度，默认 3840 */
     outputWidth?: number;
+    /** 每行列数，默认 4 */
     columns?: number;
+    /** 输出文件名，默认 thumbnail.avif */
     outputFileName?: string;
+    /** 输出质量 1–100，默认 80 */
     quality?: number;
+    /** 输出格式，默认 avif */
     format?: 'avif' | 'webp' | 'jpeg' | 'png';
+    /** 批处理大小，默认 10 */
     batchSize?: number;
+    /** 最大并发数，默认 4 */
     maxConcurrency?: number;
+    /** 临时目录 */
     tempDir?: string;
-    /** 进度回调，按阶段与完成比例调用 */
+    /** 进度回调 */
     onProgress?: (progress: ThumbnailProgress) => void;
 }
 interface ProcessingResult {

package/lib/src/ffmpeg/getThumbnail.js

@@ -4,6 +4,12 @@ import * as fs from "fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import { checkFFmpegAvailability } from "./check.js";
+/**
+ * 视频缩略图生成器
+ * 使用 ffmpeg 提取视频帧，使用 sharp 合成缩略图
+ */
+/** HEIF/AVIF 编码器常见的单边最大像素数（libheif 安全限制） */
+const HEIF_MAX_DIMENSION = 16384;
 // 日志函数
 const log = (message, data) => {
     console.log(`[ThumbnailGenerator] ${message}`, data ? JSON.stringify(data, null, 2) : '');
@@ -77,11 +83,28 @@ async function createThumbnail(frameFiles, tempDir, options, progressCallbacks)
     log('Creating thumbnail', { frameCount: frameFiles.length, columns, outputWidth });
     // 计算尺寸
     const rows = Math.ceil(frameFiles.length / columns);
-    const singleWidth = Math.floor(outputWidth / columns);
+    let singleWidth = Math.floor(outputWidth / columns);
     // 获取第一帧的元数据来计算宽高比
     const firstFrame = await Sharp(path.join(tempDir, frameFiles[0])).metadata();
     const aspectRatio = (firstFrame.width || 1) / (firstFrame.height || 1);
-    const singleHeight = Math.floor(singleWidth / aspectRatio);
+    let singleHeight = Math.floor(singleWidth / aspectRatio);
+    let totalWidth = singleWidth * columns;
+    let totalHeight = singleHeight * rows;
+    // AVIF/HEIF 编码有单边尺寸上限，超过会在 macOS 等环境报 "Processed image is too large for the HEIF format"
+    if (totalWidth > HEIF_MAX_DIMENSION || totalHeight > HEIF_MAX_DIMENSION) {
+        const scale = Math.min(HEIF_MAX_DIMENSION / totalWidth, HEIF_MAX_DIMENSION / totalHeight);
+        singleWidth = Math.floor(singleWidth * scale);
+        singleHeight = Math.floor(singleHeight * scale);
+        totalWidth = singleWidth * columns;
+        totalHeight = singleHeight * rows;
+        log('Capped dimensions for HEIF/AVIF limit', {
+            scale: scale.toFixed(3),
+            totalWidth,
+            totalHeight,
+            singleWidth,
+            singleHeight
+        });
+    }
     log('Calculated dimensions', {
         rows,
         singleWidth,
@@ -91,8 +114,8 @@ async function createThumbnail(frameFiles, tempDir, options, progressCallbacks)
     // 创建合成图像
     const composite = Sharp({
         create: {
-            width: singleWidth * columns,
-            height: singleHeight * rows,
+            width: totalWidth,
+            height: totalHeight,
             channels: 3,
             background: { r: 0, g: 0, b: 0 },
         },

package/lib/src/ffmpeg/transcode.d.ts

@@ -1,3 +1,4 @@
+import { type ThumbnailOptions } from "./getThumbnail.js";
 /** 转码进度信息，用于 onProgress 回调 */
 export interface TranscodeProgress {
     /** 当前阶段 */
@@ -14,6 +15,8 @@ export interface TranscodeProgress {
 export interface TranscodingConfig {
     /** 是否生成缩略图，默认 true */
     generateThumbnail?: boolean;
+    /** 缩略图生成参数，不传则使用 getThumbnail 默认值（如 frames=60, outputWidth=3840, columns=4, format=avif 等） */
+    thumbnailOptions?: Partial<ThumbnailOptions>;
     /** 目标编码格式，默认 'hevc' */
     format?: "av1" | "hevc";
     /** 是否替换原文件（删除原文件并将输出重命名为原路径），默认 false */

package/lib/src/ffmpeg/transcode.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { runSync } from "./runSync.js";
 import { checkFFmpegAvailability } from "./check.js";
@@ -59,8 +60,24 @@ function parseTimeFromStderr(line) {
     const [, h, m, s] = match;
     return parseInt(h, 10) * 3600 + parseInt(m, 10) * 60 + parseFloat(s);
 }
-/** 根据格式与可用编码器构建 ffmpeg 参数数组 */
-function buildTranscodeArgs(inputPath, outputPath, format, encoders) {
+/** 从 -progress 文件内容中解析当前输出时间（秒）。out_time_ms/out_time_us 均为微秒。 */
+function parseOutTimeFromProgressFile(content) {
+    let lastUs = null;
+    for (const line of content.split(/\r?\n/)) {
+        const msMatch = line.match(/^out_time_ms=(\d+)/);
+        if (msMatch) {
+            lastUs = parseInt(msMatch[1], 10);
+            continue;
+        }
+        const usMatch = line.match(/^out_time_us=(\d+)/);
+        if (usMatch) {
+            lastUs = parseInt(usMatch[1], 10);
+        }
+    }
+    return lastUs != null ? lastUs / 1e6 : null;
+}
+/** 根据格式与可用编码器构建 ffmpeg 参数数组；progressPath 用于 -progress 以获取实时进度（避免 stderr 缓冲导致 0 直接跳到 99） */
+function buildTranscodeArgs(inputPath, outputPath, format, encoders, progressPath) {
     const args = ["-i", inputPath];
     if (format === "av1") {
         if (encoders.av1Nvenc) {
@@ -84,17 +101,23 @@ function buildTranscodeArgs(inputPath, outputPath, format, encoders) {
             throw new Error("没有可用的 HEVC 编码器");
         }
     }
+    if (progressPath) {
+        args.push("-progress", progressPath);
+    }
     args.push("-y", outputPath);
     return args;
 }
-/** 使用 spawn 执行 ffmpeg 转码，解析 stderr 并回调 onProgress */
+const PROGRESS_POLL_INTERVAL_MS = 400;
+/** 使用 spawn 执行 ffmpeg 转码。进度通过 -progress 文件轮询获取，避免 stderr 管道缓冲导致 0 直接跳到 99。 */
 function runTranscodeWithProgress(inputPath, outputPath, format, encoders, totalDuration, onProgress) {
     return new Promise((resolve, reject) => {
-        const args = buildTranscodeArgs(inputPath, outputPath, format, encoders);
-        log("ffmpeg spawn", { totalDuration, format, outputPath });
+        const progressPath = path.join(os.tmpdir(), `ffmpeg-progress-${process.pid}-${Date.now()}`);
+        const args = buildTranscodeArgs(inputPath, outputPath, format, encoders, progressPath);
+        log("ffmpeg spawn", { totalDuration, format, outputPath, progressPath });
         const child = spawn("ffmpeg", args, { stdio: ["ignore", "pipe", "pipe"] });
         let lastPercent = -1;
         let hasReportedProgress = false;
+        let hasReceivedStderrData = false;
         let loggedUnparsedTime = false;
         const report = (progress) => {
             if (progress.percent !== lastPercent) {
@@ -106,37 +129,62 @@ function runTranscodeWithProgress(inputPath, outputPath, format, encoders, total
                 onProgress(progress);
             }
         };
+        const pollProgress = () => {
+            try {
+                if (!fs.existsSync(progressPath))
+                    return;
+                const content = fs.readFileSync(progressPath, "utf8");
+                const currentTime = parseOutTimeFromProgressFile(content);
+                if (currentTime != null && totalDuration > 0) {
+                    const percent = Math.min(99, Math.round((currentTime / totalDuration) * 100));
+                    report({
+                        phase: "encoding",
+                        percent,
+                        message: "正在转码...",
+                        currentTime,
+                        duration: totalDuration,
+                    });
+                }
+            }
+            catch {
+                // 文件可能正在被 ffmpeg 写入，忽略读错误
+            }
+        };
+        const progressTimer = setInterval(pollProgress, PROGRESS_POLL_INTERVAL_MS);
         if (child.stderr) {
             let buffer = "";
             child.stderr.setEncoding("utf8");
             child.stderr.on("data", (chunk) => {
+                hasReceivedStderrData = true;
                 buffer += chunk;
                 const lines = buffer.split(/\r?\n/);
                 buffer = lines.pop() ?? "";
                 for (const line of lines) {
-                    const currentTime = parseTimeFromStderr(line);
-                    if (/time=\d/.test(line) && !loggedUnparsedTime && currentTime == null) {
+                    if (/time=\d/.test(line) && !loggedUnparsedTime && parseTimeFromStderr(line) == null) {
                         loggedUnparsedTime = true;
                         log("stderr time line not parsed (check locale/format)", { line: line.trim() });
                     }
-                    if (currentTime != null && totalDuration > 0) {
-                        const percent = Math.min(99, Math.round((currentTime / totalDuration) * 100));
-                        report({
-                            phase: "encoding",
-                            percent,
-                            message: "正在转码...",
-                            currentTime,
-                            duration: totalDuration,
-                        });
-                    }
                 }
             });
         }
+        else {
+            log("ffmpeg stderr is null");
+        }
         child.on("error", (err) => {
+            clearInterval(progressTimer);
+            try {
+                fs.unlinkSync(progressPath);
+            }
+            catch { /* ignore */ }
             log("ffmpeg error", err.message);
             reject(err);
         });
         child.on("close", (code, signal) => {
+            clearInterval(progressTimer);
+            try {
+                fs.unlinkSync(progressPath);
+            }
+            catch { /* ignore */ }
             log("ffmpeg close", { code, signal, hasReportedProgress });
             if (signal) {
                 reject(new Error(`FFmpeg killed by signal: ${signal}`));
@@ -146,8 +194,8 @@ function runTranscodeWithProgress(inputPath, outputPath, format, encoders, total
                 reject(new Error(`FFmpeg exited with code ${code}`));
                 return;
             }
-            if (!hasReportedProgress) {
-                log("no encoding progress was parsed from stderr (progress callbacks may not have fired)");
+            if (!hasReportedProgress && !child.stderr) {
+                log("no encoding progress: ffmpeg stderr was null");
             }
             report({
                 phase: "done",
@@ -187,8 +235,8 @@ export async function transcoding(inputPath, config = {}) {
     };
     await runTranscodeWithProgress(validatedPath, tempOutputPath, format, encoders, duration, reportProgress);
     if (finalConfig.generateThumbnail) {
-        log("generating thumbnail");
-        await getThumbnail(validatedPath);
+        log("generating thumbnail", finalConfig.thumbnailOptions ?? {});
+        await getThumbnail(validatedPath, finalConfig.thumbnailOptions ?? {});
     }
     let resultPath;
     if (finalConfig.replaceOriginal) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiping/node-utils",
-  "version": "1.0.64",
+  "version": "1.0.65",
   "description": "node-utils",
   "type": "module",
   "author": "The-End-Hero <527409987@qq.com>",
@@ -25,7 +25,7 @@
   "bugs": {
     "url": "https://github.com/The-End-Hero/xiping/issues"
   },
-  "gitHead": "483df3f50a54f6d66b461c64bf05c77c68d368ad",
+  "gitHead": "fca213dab54ebc6913dfe46030566a30d613f456",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"