@xiping/node-utils 1.0.62 → 1.0.64

package/lib/src/ffmpeg/README.md

@@ -12,6 +12,7 @@
 | 缩略图生成 | 多帧合成预览图（AVIF/WebP/JPEG/PNG） | ffmpeg + sharp |
 | 视频截取   | 按时间范围截取，流复制不重编码 | ffmpeg     |
 | 提取音频   | 从视频中提取音轨为 mp3/m4a/wav | ffmpeg     |
+| 视频转码   | HEVC/AV1 转码，支持转换进度回调 | ffmpeg     |
 | 环境检查   | 检测 ffmpeg/ffprobe 是否可用 | -          |
 
 ## 安装要求
@@ -307,7 +308,79 @@ const result = await extractAudio('/path/to/video.mp4', {
 
 ---
 
-## 5. 环境检查（check）
+## 5. 视频转码（transcoding）
+
+将视频转码为 HEVC 或 AV1，不依赖 shelljs，仅使用 Node 内置 `child_process`（spawn）与 `fs`。默认生成新文件（如 `{原名}_hevc.mp4` 或 `{原名}_av1.mp4`），不替换原文件；可选开启“替换原文件”。支持转换进度回调。
+
+### 基本使用
+
+```typescript
+import { transcoding, getAvailableEncoders } from '@xiping/node-utils';
+
+// 转码为 HEVC（默认），生成新文件
+const result = await transcoding('/path/to/video.mp4');
+console.log(result.outputPath); // 如 /path/to/video_hevc.mp4
+
+// 指定 AV1、不生成缩略图
+const r2 = await transcoding('/path/to/video.mp4', {
+  format: 'av1',
+  generateThumbnail: false,
+});
+
+// 替换原文件（删除原文件并将输出重命名为原路径）
+const r3 = await transcoding('/path/to/video.mp4', {
+  format: 'hevc',
+  replaceOriginal: true,
+});
+```
+
+### 转换进度（onProgress）
+
+```typescript
+const result = await transcoding('/path/to/video.mp4', {
+  onProgress(progress) {
+    console.log(progress.phase, progress.percent, progress.message);
+    // phase: 'encoding' | 'done'
+    if (progress.currentTime != null && progress.duration != null) {
+      console.log(`已处理 ${progress.currentTime}/${progress.duration} 秒`);
+    }
+  },
+});
+```
+
+### TranscodingConfig
+
+| 选项               | 类型     | 默认值   | 说明 |
+|--------------------|----------|----------|------|
+| format             | string   | 'hevc'   | 目标编码：'hevc' \| 'av1' |
+| generateThumbnail  | boolean  | true     | 是否生成缩略图 |
+| replaceOriginal    | boolean  | false    | 是否替换原文件（删除原文件并将输出重命名为原路径） |
+| onProgress         | function | -        | 转换进度回调 |
+
+### TranscodeProgress（onProgress 回调参数）
+
+| 字段        | 类型   | 说明 |
+|-------------|--------|------|
+| phase       | string | 阶段：'encoding' \| 'done' |
+| percent     | number | 总进度 0–100 |
+| message     | string | 可读描述 |
+| currentTime | number | 当前已处理时长（秒） |
+| duration    | number | 视频总时长（秒） |
+
+### 编码器检测
+
+```typescript
+import { getAvailableEncoders } from '@xiping/node-utils';
+
+const encoders = getAvailableEncoders();
+// { av1Nvenc, libaomAv1, hevcNvenc, libx265 }
+```
+
+HEVC 优先使用 hevc_nvenc（NVIDIA），否则使用 libx265；AV1 优先使用 av1_nvenc，否则使用 libaom-av1。输入路径需为**绝对路径**。
+
+---
+
+## 6. 环境检查（check）
 
 ```typescript
 import { checkFFmpegAvailability, isFfprobeAvailable } from '@xiping/node-utils';
@@ -320,7 +393,7 @@ if (isFfprobeAvailable()) {
 }
 ```
 
-- **checkFFmpegAvailability()**：用于缩略图、视频截取、提取音频前检查。
+- **checkFFmpegAvailability()**：用于缩略图、视频截取、提取音频、视频转码前检查。
 - **isFfprobeAvailable()**：用于视频信息接口前检查。
 
 ---
@@ -366,5 +439,7 @@ ffprobe/ffmpeg 支持常见容器与编码，例如：
 | `cutVideoByDuration(path, start, duration, options)` | 按起始+时长截取 |
 | `cutVideoFromStart(path, durationSeconds, options)`   | 从开头截取 N 秒 |
 | `extractAudio(path, options)` | 从视频提取音频（异步） |
+| `transcoding(path, options)` | 视频转码为 HEVC/AV1（异步，支持进度） |
+| `getAvailableEncoders()`      | 检测可用编码器（av1_nvenc、libaom-av1、hevc_nvenc、libx265） |
 | `isFfprobeAvailable()`   | 检测 ffprobe 是否可用 |
 | `checkFFmpegAvailability()` | 检测 ffmpeg 是否可用 |

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

@@ -3,3 +3,4 @@ export * from "./check.js";
 export * from "./cutVideo.js";
 export * from "./getVideoInfo.js";
 export * from "./extractAudio.js";
+export * from "./transcode.js";

package/lib/src/ffmpeg/index.js

@@ -3,3 +3,4 @@ export * from "./check.js";
 export * from "./cutVideo.js";
 export * from "./getVideoInfo.js";
 export * from "./extractAudio.js";
+export * from "./transcode.js";

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

@@ -0,0 +1,40 @@
+/** 转码进度信息，用于 onProgress 回调 */
+export interface TranscodeProgress {
+    /** 当前阶段 */
+    phase: "encoding" | "done";
+    /** 总进度 0–100 */
+    percent: number;
+    /** 可读描述 */
+    message?: string;
+    /** 当前已处理时长（秒） */
+    currentTime?: number;
+    /** 视频总时长（秒） */
+    duration?: number;
+}
+export interface TranscodingConfig {
+    /** 是否生成缩略图，默认 true */
+    generateThumbnail?: boolean;
+    /** 目标编码格式，默认 'hevc' */
+    format?: "av1" | "hevc";
+    /** 是否替换原文件（删除原文件并将输出重命名为原路径），默认 false */
+    replaceOriginal?: boolean;
+    /** 转换进度回调 */
+    onProgress?: (progress: TranscodeProgress) => void;
+}
+export interface AvailableEncoders {
+    av1Nvenc: boolean;
+    libaomAv1: boolean;
+    hevcNvenc: boolean;
+    libx265: boolean;
+}
+/** 同步检测可用编码器 */
+export declare function getAvailableEncoders(): AvailableEncoders;
+export interface TranscodingResult {
+    /** 转码输出文件路径（替换原文件时为原路径，否则为 {base}_hevc.mp4 或 {base}_av1.mp4） */
+    outputPath: string;
+}
+/**
+ * 将视频转码为 HEVC 或 AV1，不依赖 shelljs，使用 Node 内置 child_process 与 fs。
+ * 支持转换进度回调；默认生成新文件，不替换原文件。
+ */
+export declare function transcoding(inputPath: string, config?: TranscodingConfig): Promise<TranscodingResult>;

package/lib/src/ffmpeg/transcode.js

@@ -0,0 +1,205 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { runSync } from "./runSync.js";
+import { checkFFmpegAvailability } from "./check.js";
+import { getThumbnail } from "./getThumbnail.js";
+const log = (message, data) => {
+    console.log("[Transcode]", message, data !== undefined ? data : "");
+};
+const defaultConfig = {
+    generateThumbnail: true,
+    format: "hevc",
+    replaceOriginal: false,
+};
+/** 同步检测可用编码器 */
+export function getAvailableEncoders() {
+    const result = runSync("ffmpeg", ["-encoders"]);
+    const stdout = result.code === 0 ? result.stdout : "";
+    return {
+        av1Nvenc: stdout.includes("av1_nvenc"),
+        libaomAv1: stdout.includes("libaom-av1"),
+        hevcNvenc: stdout.includes("hevc_nvenc"),
+        libx265: stdout.includes("libx265"),
+    };
+}
+function validateAndSanitizePath(inputPath) {
+    if (!inputPath || typeof inputPath !== "string") {
+        throw new Error("Invalid path provided");
+    }
+    if (!path.isAbsolute(inputPath)) {
+        throw new Error("Path must be absolute");
+    }
+    return inputPath;
+}
+function getDurationInSeconds(videoPath) {
+    const result = runSync("ffprobe", [
+        "-v",
+        "error",
+        "-show_entries",
+        "format=duration",
+        "-of",
+        "default=noprint_wrappers=1:nokey=1",
+        videoPath,
+    ]);
+    if (result.code !== 0) {
+        throw new Error(`FFprobe failed to get duration: ${result.stderr}`);
+    }
+    const duration = parseFloat(result.stdout);
+    if (isNaN(duration) || duration <= 0) {
+        throw new Error("Invalid video duration");
+    }
+    return duration;
+}
+/** 解析 ffmpeg stderr 中的 time=HH:MM:SS.xx 为秒数 */
+function parseTimeFromStderr(line) {
+    const match = line.match(/time=(\d{2}):(\d{2}):(\d{2}\.\d+)/);
+    if (!match)
+        return null;
+    const [, h, m, s] = match;
+    return parseInt(h, 10) * 3600 + parseInt(m, 10) * 60 + parseFloat(s);
+}
+/** 根据格式与可用编码器构建 ffmpeg 参数数组 */
+function buildTranscodeArgs(inputPath, outputPath, format, encoders) {
+    const args = ["-i", inputPath];
+    if (format === "av1") {
+        if (encoders.av1Nvenc) {
+            args.push("-c:v", "av1_nvenc", "-preset", "slow", "-rc", "constqp", "-qp", "28");
+        }
+        else if (encoders.libaomAv1) {
+            args.push("-c:v", "libaom-av1", "-crf", "30", "-b:v", "0");
+        }
+        else {
+            throw new Error("没有可用的 AV1 编码器");
+        }
+    }
+    else {
+        if (encoders.hevcNvenc) {
+            args.push("-c:v", "hevc_nvenc", "-preset", "slow", "-rc", "constqp", "-qp", "28");
+        }
+        else if (encoders.libx265) {
+            args.push("-c:v", "libx265", "-crf", "28");
+        }
+        else {
+            throw new Error("没有可用的 HEVC 编码器");
+        }
+    }
+    args.push("-y", outputPath);
+    return args;
+}
+/** 使用 spawn 执行 ffmpeg 转码，解析 stderr 并回调 onProgress */
+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 child = spawn("ffmpeg", args, { stdio: ["ignore", "pipe", "pipe"] });
+        let lastPercent = -1;
+        let hasReportedProgress = false;
+        let loggedUnparsedTime = false;
+        const report = (progress) => {
+            if (progress.percent !== lastPercent) {
+                lastPercent = progress.percent;
+                hasReportedProgress = true;
+                if (progress.percent === 0 || progress.percent === 50 || progress.percent === 99 || progress.phase === "done") {
+                    log("progress", { phase: progress.phase, percent: progress.percent, currentTime: progress.currentTime, duration: progress.duration });
+                }
+                onProgress(progress);
+            }
+        };
+        if (child.stderr) {
+            let buffer = "";
+            child.stderr.setEncoding("utf8");
+            child.stderr.on("data", (chunk) => {
+                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) {
+                        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,
+                        });
+                    }
+                }
+            });
+        }
+        child.on("error", (err) => {
+            log("ffmpeg error", err.message);
+            reject(err);
+        });
+        child.on("close", (code, signal) => {
+            log("ffmpeg close", { code, signal, hasReportedProgress });
+            if (signal) {
+                reject(new Error(`FFmpeg killed by signal: ${signal}`));
+                return;
+            }
+            if (code !== 0) {
+                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)");
+            }
+            report({
+                phase: "done",
+                percent: 100,
+                message: "完成",
+                currentTime: totalDuration,
+                duration: totalDuration,
+            });
+            resolve();
+        });
+    });
+}
+/**
+ * 将视频转码为 HEVC 或 AV1，不依赖 shelljs，使用 Node 内置 child_process 与 fs。
+ * 支持转换进度回调；默认生成新文件，不替换原文件。
+ */
+export async function transcoding(inputPath, config = {}) {
+    const finalConfig = { ...defaultConfig, ...config };
+    if (!checkFFmpegAvailability()) {
+        throw new Error("FFmpeg is not available. Please install FFmpeg first.");
+    }
+    const validatedPath = validateAndSanitizePath(inputPath);
+    if (!fs.existsSync(validatedPath)) {
+        throw new Error(`Video file not found: ${validatedPath}`);
+    }
+    const encoders = getAvailableEncoders();
+    const format = finalConfig.format;
+    const duration = getDurationInSeconds(validatedPath);
+    log("start", { inputPath: validatedPath, format, durationSeconds: duration, hasOnProgress: !!finalConfig.onProgress });
+    const dir = path.dirname(validatedPath);
+    const baseName = path.basename(validatedPath, path.extname(validatedPath));
+    const suffix = format === "av1" ? "_av1" : "_hevc";
+    const outputFileName = `${baseName}${suffix}.mp4`;
+    const tempOutputPath = path.join(dir, outputFileName);
+    const reportProgress = (progress) => {
+        finalConfig.onProgress?.(progress);
+    };
+    await runTranscodeWithProgress(validatedPath, tempOutputPath, format, encoders, duration, reportProgress);
+    if (finalConfig.generateThumbnail) {
+        log("generating thumbnail");
+        await getThumbnail(validatedPath);
+    }
+    let resultPath;
+    if (finalConfig.replaceOriginal) {
+        fs.unlinkSync(validatedPath);
+        const originalPath = path.join(dir, path.basename(validatedPath));
+        fs.renameSync(tempOutputPath, originalPath);
+        resultPath = originalPath;
+    }
+    else {
+        resultPath = tempOutputPath;
+    }
+    log("done", { outputPath: resultPath });
+    return { outputPath: resultPath };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiping/node-utils",
-  "version": "1.0.62",
+  "version": "1.0.64",
   "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": "83ac9cffc81c4bbd5b78e1ecf621029630c98c20",
+  "gitHead": "483df3f50a54f6d66b461c64bf05c77c68d368ad",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"