@xiping/node-utils 1.0.53 → 1.0.61

package/lib/src/ffmpeg/extractAudio.js

@@ -0,0 +1,186 @@
+import shell from "shelljs";
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { checkFFmpegAvailability } from "./check.js";
+import { getVideoInfo } from "./getVideoInfo.js";
+const log = (message, data) => {
+    console.log(`[ExtractAudio] ${message}`, data ? JSON.stringify(data, null, 2) : "");
+};
+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 = shell.exec(`ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "${videoPath}"`, { silent: true });
+    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 buildFfmpegArgs(outputPath, outputFormat, copyStream, audioCodec) {
+    const args = ["-i", ""]; // input 占位，调用方填入
+    args.push("-vn"); // 不要视频
+    if (outputFormat === "mp3") {
+        args.push("-acodec", "libmp3lame");
+    }
+    else if (outputFormat === "m4a") {
+        if (copyStream && (audioCodec === "aac" || audioCodec === "aac_latm")) {
+            args.push("-acodec", "copy");
+        }
+        else {
+            args.push("-acodec", "aac");
+        }
+    }
+    else if (outputFormat === "wav") {
+        args.push("-acodec", "pcm_s16le");
+    }
+    args.push("-y", outputPath);
+    return args;
+}
+/** 执行 ffmpeg（shell.exec），无进度 */
+function runFfmpegSync(inputPath, outputPath, outputFormat, copyStream, audioCodec) {
+    const args = buildFfmpegArgs(outputPath, outputFormat, copyStream, audioCodec);
+    args[1] = inputPath;
+    const command = `ffmpeg ${args.map((a) => (a.includes(" ") ? `"${a}"` : a)).join(" ")}`;
+    log("Executing FFmpeg command", { command });
+    const result = shell.exec(command, { silent: true });
+    if (result.code !== 0) {
+        throw new Error(`FFmpeg failed: ${result.stderr}`);
+    }
+}
+/** 执行 ffmpeg（spawn），解析 stderr 并回调 onProgress */
+function runFfmpegWithProgress(inputPath, outputPath, outputFormat, copyStream, audioCodec, totalDuration, onProgress) {
+    return new Promise((resolve, reject) => {
+        const args = buildFfmpegArgs(outputPath, outputFormat, copyStream, audioCodec);
+        args[1] = inputPath;
+        const child = spawn("ffmpeg", args, { stdio: ["ignore", "pipe", "pipe"] });
+        let lastPercent = -1;
+        const report = (progress) => {
+            if (progress.percent !== lastPercent) {
+                lastPercent = progress.percent;
+                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 (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) => reject(err));
+        child.on("close", (code, signal) => {
+            if (signal) {
+                reject(new Error(`FFmpeg killed by signal: ${signal}`));
+                return;
+            }
+            if (code !== 0) {
+                reject(new Error(`FFmpeg exited with code ${code}`));
+                return;
+            }
+            report({
+                phase: "done",
+                percent: 100,
+                message: "完成",
+                currentTime: totalDuration,
+                duration: totalDuration,
+            });
+            resolve();
+        });
+    });
+}
+export async function extractAudio(videoPath, options = {}) {
+    const startTime = Date.now();
+    const validatedPath = validateAndSanitizePath(videoPath);
+    if (!fs.existsSync(validatedPath)) {
+        throw new Error(`Video file not found: ${validatedPath}`);
+    }
+    if (!checkFFmpegAvailability()) {
+        throw new Error("FFmpeg is not available. Please install FFmpeg first.");
+    }
+    const { outputFileName, outputFormat = "mp3", overwrite = false, tempDir: customTempDir, copyStream = true, onProgress, } = options;
+    const videoInfo = getVideoInfo(validatedPath);
+    if (!videoInfo.audioCodec) {
+        throw new Error("Video has no audio stream.");
+    }
+    const duration = getDurationInSeconds(validatedPath);
+    const videoDir = path.dirname(validatedPath);
+    const baseName = path.basename(validatedPath, path.extname(validatedPath));
+    const defaultOutputName = `${baseName}.${outputFormat}`;
+    const outputFileNameFinal = outputFileName ?? defaultOutputName;
+    const outputPath = path.join(videoDir, outputFileNameFinal);
+    if (fs.existsSync(outputPath) && !overwrite) {
+        throw new Error(`Output file already exists: ${outputPath}. Use overwrite option to force overwrite.`);
+    }
+    const reportProgress = (progress) => {
+        onProgress?.(progress);
+    };
+    reportProgress({
+        phase: "preparing",
+        percent: 0,
+        message: "准备提取音频...",
+        duration,
+    });
+    const tempDir = customTempDir ?? fs.mkdtempSync(path.join(os.tmpdir(), "extract-audio-"));
+    const tempOutputPath = path.join(tempDir, `temp_audio.${outputFormat}`);
+    try {
+        if (onProgress) {
+            await runFfmpegWithProgress(validatedPath, tempOutputPath, outputFormat, copyStream, videoInfo.audioCodec, duration, reportProgress);
+        }
+        else {
+            runFfmpegSync(validatedPath, tempOutputPath, outputFormat, copyStream, videoInfo.audioCodec);
+        }
+        fs.copyFileSync(tempOutputPath, outputPath);
+        log("Extract audio complete", { outputPath });
+    }
+    finally {
+        if (!customTempDir && fs.existsSync(tempDir)) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    }
+    const outputStats = fs.statSync(outputPath);
+    const processingTime = Date.now() - startTime;
+    return {
+        outputPath,
+        metadata: {
+            duration,
+            fileSize: outputStats.size,
+            processingTime,
+        },
+    };
+}

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

@@ -2,6 +2,19 @@
  * 视频缩略图生成器
  * 使用 ffmpeg 提取视频帧，使用 sharp 合成缩略图
  */
+/** 进度信息，用于 onProgress 回调 */
+export interface ThumbnailProgress {
+    /** 当前阶段 */
+    phase: "analyzing" | "extracting" | "composing" | "encoding" | "done";
+    /** 总进度 0–100 */
+    percent: number;
+    /** 当前阶段已完成数（如已提取帧数） */
+    current?: number;
+    /** 当前阶段总数 */
+    total?: number;
+    /** 可读描述 */
+    message?: string;
+}
 interface ThumbnailOptions {
     frames?: number;
     outputWidth?: number;
@@ -12,6 +25,8 @@ interface ThumbnailOptions {
     batchSize?: number;
     maxConcurrency?: number;
     tempDir?: string;
+    /** 进度回调，按阶段与完成比例调用 */
+    onProgress?: (progress: ThumbnailProgress) => void;
 }
 interface ProcessingResult {
     buffer: Buffer;

package/lib/src/ffmpeg/getThumbnail.js

@@ -33,15 +33,16 @@ function getDurationInSeconds(videoPath) {
     return duration;
 }
 // 并行提取视频帧
-async function extractFrames(videoPath, tempDir, frames, interval, maxConcurrency = 4) {
+async function extractFrames(videoPath, tempDir, frames, interval, maxConcurrency = 4, onProgress) {
+    const total = frames - 1;
     log('Starting frame extraction', { frames, interval, maxConcurrency });
-    const framePromises = Array.from({ length: frames - 1 }, (_, i) => {
+    const framePromises = Array.from({ length: total }, (_, i) => {
         const t = interval * i;
         const framePath = path.join(tempDir, `frame-${t}.jpg`);
         return new Promise((resolve, reject) => {
             const result = shell.exec(`ffmpeg -ss ${t} -i "${videoPath}" -vframes 1 -q:v 10 -an -threads 4 "${framePath}"`, { silent: true });
             if (result.code === 0) {
-                log(`Frame ${i + 1}/${frames - 1} extracted`, { time: t });
+                log(`Frame ${i + 1}/${total} extracted`, { time: t });
                 resolve();
             }
             else {
@@ -49,14 +50,16 @@ async function extractFrames(videoPath, tempDir, frames, interval, maxConcurrenc
             }
         });
     });
-    // 分批执行以控制并发数
+    // 分批执行以控制并发数，每批完成后上报进度
     for (let i = 0; i < framePromises.length; i += maxConcurrency) {
         const batch = framePromises.slice(i, i + maxConcurrency);
         await Promise.all(batch);
+        const current = Math.min(i + maxConcurrency, total);
+        onProgress?.(current, total);
     }
 }
 // 创建缩略图
-async function createThumbnail(frameFiles, tempDir, options) {
+async function createThumbnail(frameFiles, tempDir, options, progressCallbacks) {
     const { columns = 4, outputWidth = 3840, format = 'avif', quality = 80 } = options;
     log('Creating thumbnail', { frameCount: frameFiles.length, columns, outputWidth });
     // 计算尺寸
@@ -84,6 +87,7 @@ async function createThumbnail(frameFiles, tempDir, options) {
     // 分批处理帧以避免内存问题
     const batchSize = options.batchSize || 10;
     const overlays = [];
+    const totalBatches = Math.ceil(frameFiles.length / batchSize);
     for (let i = 0; i < frameFiles.length; i += batchSize) {
         const batch = frameFiles.slice(i, i + batchSize);
         const batchOverlays = await Promise.all(batch.map(async (file, batchIndex) => {
@@ -100,7 +104,9 @@ async function createThumbnail(frameFiles, tempDir, options) {
             };
         }));
         overlays.push(...batchOverlays);
-        log(`Processed batch ${Math.floor(i / batchSize) + 1}/${Math.ceil(frameFiles.length / batchSize)}`);
+        const currentBatch = Math.floor(i / batchSize) + 1;
+        progressCallbacks?.onComposingProgress?.(currentBatch, totalBatches);
+        log(`Processed batch ${currentBatch}/${totalBatches}`);
     }
     // 生成最终图像
     let finalImage = composite.composite(overlays);
@@ -121,7 +127,10 @@ async function createThumbnail(frameFiles, tempDir, options) {
         default:
             finalImage = finalImage.avif({ quality });
     }
-    return await finalImage.toBuffer();
+    progressCallbacks?.onEncodingStart?.();
+    const buffer = await finalImage.toBuffer();
+    progressCallbacks?.onEncodingEnd?.();
+    return buffer;
 }
 // 临时目录管理
 async function withTempDir(fn, customTempDir) {
@@ -150,7 +159,7 @@ export const getThumbnail = async (videoPath, options = {}) => {
             throw new Error('FFmpeg is not available. Please install FFmpeg first.');
         }
         // 参数设置和验证
-        const { frames = 60, outputWidth = 3840, columns = 4, outputFileName = "thumbnail.avif", quality = 80, format = 'avif', batchSize = 10, maxConcurrency = 4, tempDir: customTempDir } = options;
+        const { frames = 60, outputWidth = 3840, columns = 4, outputFileName = "thumbnail.avif", quality = 80, format = 'avif', batchSize = 10, maxConcurrency = 4, tempDir: customTempDir, onProgress } = options;
         // 参数验证
         if (frames <= 0 || outputWidth <= 0 || columns <= 0) {
             throw new Error('Invalid parameters: frames, outputWidth, and columns must be positive');
@@ -158,14 +167,26 @@ export const getThumbnail = async (videoPath, options = {}) => {
         if (quality < 1 || quality > 100) {
             throw new Error('Quality must be between 1 and 100');
         }
+        const report = (progress) => {
+            onProgress?.(progress);
+        };
         log('Starting thumbnail generation', {
             videoPath: validatedPath,
             options: { frames, outputWidth, columns, format, quality }
         });
+        report({ phase: 'analyzing', percent: 0, message: '分析视频...' });
         // 获取视频信息
         const durationInSeconds = getDurationInSeconds(validatedPath);
         const interval = durationInSeconds / frames;
         log('Video analysis complete', { durationInSeconds, interval });
+        const extractTotal = frames - 1;
+        report({
+            phase: 'extracting',
+            percent: 5,
+            current: 0,
+            total: extractTotal,
+            message: `提取帧 0/${extractTotal}`
+        });
         // 准备输出路径
         const videoDir = path.dirname(validatedPath);
         const fileNameWithoutExt = path.basename(validatedPath, path.extname(validatedPath));
@@ -173,7 +194,16 @@ export const getThumbnail = async (videoPath, options = {}) => {
         // 使用临时目录处理
         const result = await withTempDir(async (tempDir) => {
             // 提取帧
-            await extractFrames(validatedPath, tempDir, frames, interval, maxConcurrency);
+            await extractFrames(validatedPath, tempDir, frames, interval, maxConcurrency, (current, total) => {
+                const percent = total > 0 ? 5 + 45 * (current / total) : 5;
+                report({
+                    phase: 'extracting',
+                    percent: Math.round(percent),
+                    current,
+                    total,
+                    message: `提取帧 ${current}/${total}`
+                });
+            });
             // 获取所有帧文件并排序
             const frameFiles = fs
                 .readdirSync(tempDir)
@@ -187,12 +217,36 @@ export const getThumbnail = async (videoPath, options = {}) => {
                 throw new Error('No frames were extracted from the video');
             }
             log('Frame extraction complete', { extractedFrames: frameFiles.length });
+            report({
+                phase: 'composing',
+                percent: 50,
+                message: '合成缩略图...'
+            });
             // 创建缩略图
-            const buffer = await createThumbnail(frameFiles, tempDir, options);
+            const totalComposeBatches = Math.ceil(frameFiles.length / (batchSize || 10));
+            const buffer = await createThumbnail(frameFiles, tempDir, options, {
+                onComposingProgress: (current, total) => {
+                    const percent = total > 0 ? 50 + 45 * (current / total) : 50;
+                    report({
+                        phase: 'composing',
+                        percent: Math.round(percent),
+                        current,
+                        total,
+                        message: `合成 ${current}/${total}`
+                    });
+                },
+                onEncodingStart: () => {
+                    report({ phase: 'encoding', percent: 95, message: '编码输出...' });
+                },
+                onEncodingEnd: () => {
+                    report({ phase: 'encoding', percent: 100, message: '编码完成' });
+                }
+            });
             return buffer;
         }, customTempDir);
         // 保存文件
         fs.writeFileSync(outputPath, result);
+        report({ phase: 'done', percent: 100, message: '完成' });
         const processingTime = Date.now() - startTime;
         log('Thumbnail generation complete', {
             outputPath,

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

@@ -0,0 +1,47 @@
+/**
+ * 获取视频信息的接口定义
+ */
+export interface VideoInfo {
+    /** 视频文件路径 */
+    path: string;
+    /** 视频时长（秒） */
+    duration: number;
+    /** 视频时长格式化字符串 */
+    durationFormatted: string;
+    /** 视频宽度 */
+    width: number;
+    /** 视频高度 */
+    height: number;
+    /** 视频编码格式 */
+    videoCodec: string;
+    /** 音频编码格式 */
+    audioCodec: string;
+    /** 视频比特率 */
+    bitrate: number;
+    /** 帧率 */
+    fps: number;
+    /** 文件大小（字节） */
+    fileSize: number;
+    /** 文件大小格式化字符串 */
+    fileSizeFormatted: string;
+    /** 原始 ffprobe 输出信息 */
+    rawInfo: string;
+}
+/**
+ * 获取视频信息（使用 ffprobe）
+ * @param videoPath 视频文件路径
+ * @returns 视频信息对象
+ */
+export declare function getVideoInfo(videoPath: string): VideoInfo;
+/**
+ * 批量获取视频信息
+ * @param videoPaths 视频文件路径数组
+ * @returns 视频信息对象数组
+ */
+export declare function getMultipleVideoInfo(videoPaths: string[]): VideoInfo[];
+/**
+ * 获取详细的视频信息（包含更多元数据）
+ * @param videoPath 视频文件路径
+ * @returns 详细的视频信息
+ */
+export declare function getDetailedVideoInfo(videoPath: string): any;

package/lib/src/ffmpeg/getVideoInfo.js

@@ -0,0 +1,109 @@
+import shell from "shelljs";
+/**
+ * 格式化文件大小
+ * @param bytes 字节数
+ * @returns 格式化后的文件大小字符串
+ */
+function formatFileSize(bytes) {
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let size = bytes;
+    let unitIndex = 0;
+    while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+    }
+    return `${size.toFixed(2)} ${units[unitIndex]}`;
+}
+/**
+ * 格式化时长
+ * @param seconds 秒数
+ * @returns 格式化后的时长字符串
+ */
+function formatDuration(seconds) {
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const secs = Math.floor(seconds % 60);
+    const ms = Math.floor((seconds % 1) * 100);
+    return `${hours.toString().padStart(2, "0")}:${minutes.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}.${ms.toString().padStart(2, "0")}`;
+}
+/**
+ * 获取视频信息（使用 ffprobe）
+ * @param videoPath 视频文件路径
+ * @returns 视频信息对象
+ */
+export function getVideoInfo(videoPath) {
+    // 检查文件是否存在
+    if (!shell.test("-f", videoPath)) {
+        throw new Error(`视频文件不存在: ${videoPath}`);
+    }
+    // 使用 ffprobe 获取 JSON 格式的视频信息
+    const result = shell.exec(`ffprobe -v quiet -print_format json -show_format -show_streams "${videoPath}"`, { silent: true });
+    if (result.code !== 0) {
+        throw new Error(`获取视频信息失败: ${result.stderr}`);
+    }
+    let probeData;
+    try {
+        probeData = JSON.parse(result.stdout);
+    }
+    catch (error) {
+        throw new Error(`解析 ffprobe 输出失败: ${error}`);
+    }
+    const info = {
+        path: videoPath,
+        rawInfo: JSON.stringify(probeData, null, 2),
+    };
+    // 从 format 信息中获取时长和文件大小
+    if (probeData.format) {
+        if (probeData.format.duration) {
+            info.duration = parseFloat(probeData.format.duration);
+            info.durationFormatted = formatDuration(info.duration);
+        }
+        if (probeData.format.size) {
+            info.fileSize = parseInt(probeData.format.size);
+            info.fileSizeFormatted = formatFileSize(info.fileSize);
+        }
+    }
+    // 从视频流中获取信息
+    const videoStream = probeData.streams?.find((stream) => stream.codec_type === "video");
+    if (videoStream) {
+        info.videoCodec = videoStream.codec_name || "unknown";
+        info.width = videoStream.width || 0;
+        info.height = videoStream.height || 0;
+        if (videoStream.r_frame_rate) {
+            const [num, den] = videoStream.r_frame_rate.split("/");
+            info.fps = parseInt(num) / parseInt(den);
+        }
+        if (videoStream.bit_rate) {
+            info.bitrate = parseInt(videoStream.bit_rate);
+        }
+    }
+    // 从音频流中获取信息
+    const audioStream = probeData.streams?.find((stream) => stream.codec_type === "audio");
+    if (audioStream) {
+        info.audioCodec = audioStream.codec_name || "unknown";
+    }
+    return info;
+}
+/**
+ * 批量获取视频信息
+ * @param videoPaths 视频文件路径数组
+ * @returns 视频信息对象数组
+ */
+export function getMultipleVideoInfo(videoPaths) {
+    return videoPaths.map((path) => getVideoInfo(path));
+}
+/**
+ * 获取详细的视频信息（包含更多元数据）
+ * @param videoPath 视频文件路径
+ * @returns 详细的视频信息
+ */
+export function getDetailedVideoInfo(videoPath) {
+    if (!shell.test("-f", videoPath)) {
+        throw new Error(`视频文件不存在: ${videoPath}`);
+    }
+    const result = shell.exec(`ffprobe -v quiet -print_format json -show_format -show_streams -show_chapters -show_private_data "${videoPath}"`, { silent: true });
+    if (result.code !== 0) {
+        throw new Error(`获取详细视频信息失败: ${result.stderr}`);
+    }
+    return JSON.parse(result.stdout);
+}

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

@@ -1,50 +1,5 @@
 export * from "./getThumbnail.js";
 export * from "./check.js";
 export * from "./cutVideo.js";
-/**
- * 获取视频信息的接口定义
- */
-export interface VideoInfo {
-    /** 视频文件路径 */
-    path: string;
-    /** 视频时长（秒） */
-    duration: number;
-    /** 视频时长格式化字符串 */
-    durationFormatted: string;
-    /** 视频宽度 */
-    width: number;
-    /** 视频高度 */
-    height: number;
-    /** 视频编码格式 */
-    videoCodec: string;
-    /** 音频编码格式 */
-    audioCodec: string;
-    /** 视频比特率 */
-    bitrate: number;
-    /** 帧率 */
-    fps: number;
-    /** 文件大小（字节） */
-    fileSize: number;
-    /** 文件大小格式化字符串 */
-    fileSizeFormatted: string;
-    /** 原始 ffprobe 输出信息 */
-    rawInfo: string;
-}
-/**
- * 获取视频信息（使用 ffprobe）
- * @param videoPath 视频文件路径
- * @returns 视频信息对象
- */
-export declare function getVideoInfo(videoPath: string): VideoInfo;
-/**
- * 批量获取视频信息
- * @param videoPaths 视频文件路径数组
- * @returns 视频信息对象数组
- */
-export declare function getMultipleVideoInfo(videoPaths: string[]): VideoInfo[];
-/**
- * 获取详细的视频信息（包含更多元数据）
- * @param videoPath 视频文件路径
- * @returns 详细的视频信息
- */
-export declare function getDetailedVideoInfo(videoPath: string): any;
+export * from "./getVideoInfo.js";
+export * from "./extractAudio.js";