@xiping/node-utils 1.0.60 → 1.0.62

package/lib/src/ffmpeg/cutVideo.js

@@ -1,5 +1,5 @@
-import shell from "shelljs";
 import * as fs from "fs";
+import { runSync } from "./runSync.js";
 import * as path from "node:path";
 import * as os from "node:os";
 import { checkFFmpegAvailability } from "./check.js";
@@ -40,7 +40,12 @@ function normalizeTimeFormat(time) {
 // 获取视频时长
 function getDurationInSeconds(videoPath) {
     log('Getting video duration', { videoPath });
-    const result = shell.exec(`ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "${videoPath}"`, { silent: true });
+    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}`);
     }
@@ -104,20 +109,6 @@ function timeToSeconds(timeStr) {
     }
     throw new Error(`Invalid time format: ${timeStr}`);
 }
-// 构建 FFmpeg 命令
-function buildFFmpegCommand(inputPath, outputPath, startTime, duration, options) {
-    const { overwrite = false } = options;
-    // 使用 copy 模式，保持原视频编码和质量
-    let command = `ffmpeg -ss ${startTime} -i "${inputPath}" -t ${duration}`;
-    // 复制视频和音频流，不重新编码
-    command += ' -c copy';
-    // 其他设置
-    command += ' -avoid_negative_ts make_zero';
-    command += ' -y'; // 自动覆盖输出文件
-    // 输出文件
-    command += ` "${outputPath}"`;
-    return command;
-}
 // 临时目录管理
 async function withTempDir(fn, customTempDir) {
     const tempDir = customTempDir || fs.mkdtempSync(path.join(os.tmpdir(), "video-cut-"));
@@ -169,11 +160,16 @@ export const cutVideo = async (videoPath, options = {}) => {
         // 使用临时目录处理
         await withTempDir(async (tempDir) => {
             const tempOutputPath = path.join(tempDir, `temp_output.${outputFormat}`);
-            // 构建 FFmpeg 命令
-            const command = buildFFmpegCommand(validatedPath, tempOutputPath, timeParams.startTime, timeParams.duration, options);
-            log('Executing FFmpeg command', { command });
-            // 执行 FFmpeg 命令
-            const result = shell.exec(command, { silent: true });
+            log('Executing FFmpeg command', { startTime: timeParams.startTime, duration: timeParams.duration });
+            const result = runSync("ffmpeg", [
+                "-ss", timeParams.startTime,
+                "-i", validatedPath,
+                "-t", timeParams.duration,
+                "-c", "copy",
+                "-avoid_negative_ts", "make_zero",
+                "-y",
+                tempOutputPath,
+            ]);
             if (result.code !== 0) {
                 throw new Error(`FFmpeg failed: ${result.stderr}`);
             }

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

@@ -0,0 +1,36 @@
+/** 提取音频进度信息，用于 onProgress 回调 */
+export interface ExtractAudioProgress {
+    /** 当前阶段 */
+    phase: "preparing" | "encoding" | "done";
+    /** 总进度 0–100 */
+    percent: number;
+    /** 可读描述 */
+    message?: string;
+    /** 当前已处理时长（秒） */
+    currentTime?: number;
+    /** 视频总时长（秒） */
+    duration?: number;
+}
+export interface ExtractAudioOptions {
+    /** 输出文件名 */
+    outputFileName?: string;
+    /** 输出格式，默认 mp3 */
+    outputFormat?: "mp3" | "m4a" | "wav";
+    /** 是否覆盖已存在文件 */
+    overwrite?: boolean;
+    /** 自定义临时目录 */
+    tempDir?: string;
+    /** 是否尽量流复制不重编码（仅当格式兼容时有效，如 m4a 保留 aac） */
+    copyStream?: boolean;
+    /** 进度回调 */
+    onProgress?: (progress: ExtractAudioProgress) => void;
+}
+export interface ExtractAudioResult {
+    outputPath: string;
+    metadata: {
+        duration: number;
+        fileSize: number;
+        processingTime: number;
+    };
+}
+export declare function extractAudio(videoPath: string, options?: ExtractAudioOptions): Promise<ExtractAudioResult>;

package/lib/src/ffmpeg/extractAudio.js

@@ -0,0 +1,190 @@
+import { spawn } from "node:child_process";
+import { runSync } from "./runSync.js";
+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 = 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 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（runSync），无进度 */
+function runFfmpegSync(inputPath, outputPath, outputFormat, copyStream, audioCodec) {
+    const args = buildFfmpegArgs(outputPath, outputFormat, copyStream, audioCodec);
+    args[1] = inputPath;
+    log("Executing FFmpeg command", { inputPath, outputPath });
+    const result = runSync("ffmpeg", args);
+    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.js

@@ -1,5 +1,5 @@
-import shell from "shelljs";
 import Sharp from "sharp";
+import { runSync } from "./runSync.js";
 import * as fs from "fs";
 import * as path from "node:path";
 import * as os from "node:os";
@@ -22,7 +22,12 @@ function validateAndSanitizePath(inputPath) {
 // 获取视频时长
 function getDurationInSeconds(videoPath) {
     log('Getting video duration', { videoPath });
-    const result = shell.exec(`ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "${videoPath}"`, { silent: true });
+    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}`);
     }
@@ -40,7 +45,15 @@ async function extractFrames(videoPath, tempDir, frames, interval, maxConcurrenc
         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 });
+            const result = runSync("ffmpeg", [
+                "-ss", String(t),
+                "-i", videoPath,
+                "-vframes", "1",
+                "-q:v", "10",
+                "-an",
+                "-threads", "4",
+                framePath,
+            ]);
             if (result.code === 0) {
                 log(`Frame ${i + 1}/${total} extracted`, { time: t });
                 resolve();

package/lib/src/ffmpeg/getVideoInfo.js

@@ -1,4 +1,5 @@
-import shell from "shelljs";
+import * as fs from "node:fs";
+import { runSync } from "./runSync.js";
 /**
  * 格式化文件大小
  * @param bytes 字节数
@@ -32,12 +33,16 @@ function formatDuration(seconds) {
  * @returns 视频信息对象
  */
 export function getVideoInfo(videoPath) {
-    // 检查文件是否存在
-    if (!shell.test("-f", videoPath)) {
+    if (!fs.existsSync(videoPath)) {
         throw new Error(`视频文件不存在: ${videoPath}`);
     }
-    // 使用 ffprobe 获取 JSON 格式的视频信息
-    const result = shell.exec(`ffprobe -v quiet -print_format json -show_format -show_streams "${videoPath}"`, { silent: true });
+    const result = runSync("ffprobe", [
+        "-v", "quiet",
+        "-print_format", "json",
+        "-show_format",
+        "-show_streams",
+        videoPath,
+    ]);
     if (result.code !== 0) {
         throw new Error(`获取视频信息失败: ${result.stderr}`);
     }
@@ -98,10 +103,18 @@ export function getMultipleVideoInfo(videoPaths) {
  * @returns 详细的视频信息
  */
 export function getDetailedVideoInfo(videoPath) {
-    if (!shell.test("-f", videoPath)) {
+    if (!fs.existsSync(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 });
+    const result = runSync("ffprobe", [
+        "-v", "quiet",
+        "-print_format", "json",
+        "-show_format",
+        "-show_streams",
+        "-show_chapters",
+        "-show_private_data",
+        videoPath,
+    ]);
     if (result.code !== 0) {
         throw new Error(`获取详细视频信息失败: ${result.stderr}`);
     }

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

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

package/lib/src/ffmpeg/index.js

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

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

@@ -0,0 +1,15 @@
+/**
+ * 同步执行外部命令（跨平台、兼容 Electron，不依赖 shell）。
+ * 使用 spawnSync + 参数数组，避免 shell 解析和路径/空格问题。
+ *
+ * @param command 可执行文件名（如 ffmpeg、ffprobe）
+ * @param args 参数列表（路径无需额外引号）
+ * @returns 与 shelljs.exec 兼容的 { code, stdout, stderr }
+ */
+export declare function runSync(command: string, args: string[], options?: {
+    encoding?: BufferEncoding;
+}): {
+    code: number;
+    stdout: string;
+    stderr: string;
+};

package/lib/src/ffmpeg/runSync.js

@@ -0,0 +1,20 @@
+import { spawnSync } from "node:child_process";
+/**
+ * 同步执行外部命令（跨平台、兼容 Electron，不依赖 shell）。
+ * 使用 spawnSync + 参数数组，避免 shell 解析和路径/空格问题。
+ *
+ * @param command 可执行文件名（如 ffmpeg、ffprobe）
+ * @param args 参数列表（路径无需额外引号）
+ * @returns 与 shelljs.exec 兼容的 { code, stdout, stderr }
+ */
+export function runSync(command, args, options) {
+    const encoding = options?.encoding ?? "utf8";
+    const result = spawnSync(command, args, {
+        encoding,
+        windowsHide: true,
+    });
+    const stdout = (result.stdout ?? "");
+    const stderr = (result.stderr ?? "");
+    const code = result.status ?? (result.signal ? -1 : 0);
+    return { code, stdout, stderr };
+}

package/lib/src/image/README.md

@@ -0,0 +1,230 @@
+# 图片格式转换工具
+
+基于 Sharp 的高性能图片格式转换工具，支持多种图片格式之间的转换，包括 JPG、PNG、WebP、AVIF 等。
+
+## 功能特性
+
+- 🚀 高性能图片格式转换
+- 📐 支持尺寸调整和缩放
+- 🎨 支持质量控制和压缩选项
+- 📦 批量转换支持
+- 🖼️ 缩略图生成
+- 📊 详细的转换统计信息
+- 🔍 图片信息获取
+
+## 支持的格式
+
+### 输入格式
+- JPEG/JPG
+- PNG
+- WebP
+- AVIF
+- TIFF
+- GIF
+
+### 输出格式
+- JPEG/JPG
+- PNG
+- WebP
+- AVIF
+- TIFF
+
+## 安装依赖
+
+确保项目中已安装 Sharp：
+
+```bash
+npm install sharp
+```
+
+## 基本用法
+
+### 1. 单张图片转换
+
+```typescript
+import { convertImage } from '@xiping/node-utils';
+
+// 将 JPG 转换为 WebP
+const result = await convertImage(
+  './input/sample.jpg',
+  './output/sample.webp',
+  'webp',
+  {
+    quality: 85,
+    width: 800,
+    height: 600
+  }
+);
+
+console.log('转换结果:', result);
+```
+
+### 2. 批量转换
+
+```typescript
+import { batchConvert } from '@xiping/node-utils';
+
+const files = [
+  {
+    inputPath: './input/image1.jpg',
+    outputPath: './output/image1.webp',
+    format: 'webp'
+  },
+  {
+    inputPath: './input/image2.png',
+    outputPath: './output/image2.avif',
+    format: 'avif'
+  }
+];
+
+const results = await batchConvert(files, {
+  quality: 80,
+  width: 1200
+});
+```
+
+### 3. 创建缩略图
+
+```typescript
+import { createThumbnail } from '@xiping/node-utils';
+
+const result = await createThumbnail(
+  './input/large-image.jpg',
+  './output/thumbnail.jpg',
+  200,
+  200,
+  'jpeg',
+  { quality: 90 }
+);
+```
+
+### 4. 获取图片信息
+
+```typescript
+import { getImageInfo } from '@xiping/node-utils';
+
+const info = await getImageInfo('./input/sample.jpg');
+console.log('图片信息:', info);
+```
+
+## 高级用法
+
+### 使用 ImageConverter 类
+
+```typescript
+import { ImageConverter } from '@xiping/node-utils';
+
+// 转换为 WebP（推荐用于 Web）
+await ImageConverter.toWebP('./input.jpg', './output.webp', 85);
+
+// 转换为 AVIF（最新格式，压缩率更高）
+await ImageConverter.toAVIF('./input.jpg', './output.avif', 80);
+
+// 转换为 PNG（保持透明度）
+await ImageConverter.toPNG('./input.jpg', './output.png', true);
+
+// 转换为 JPEG（通用格式）
+await ImageConverter.toJPEG('./input.png', './output.jpg', 90);
+```
+
+### 创建响应式图片
+
+```typescript
+import { ImageConverter } from '@xiping/node-utils';
+
+const sizes = [
+  { width: 320, height: 240, suffix: 'small' },
+  { width: 640, height: 480, suffix: 'medium' },
+  { width: 1280, height: 960, suffix: 'large' }
+];
+
+const results = await ImageConverter.createResponsiveImages(
+  './input/hero-image.jpg',
+  './output/',
+  'hero',
+  sizes
+);
+```
+
+## 转换选项
+
+```typescript
+interface ConvertOptions {
+  /** 输出质量 (1-100)，仅对 JPEG、WebP、AVIF 有效 */
+  quality?: number;
+  /** 是否保持透明度，仅对 PNG、WebP 有效 */
+  keepTransparency?: boolean;
+  /** 输出宽度，保持宽高比 */
+  width?: number;
+  /** 输出高度，保持宽高比 */
+  height?: number;
+  /** 是否强制调整尺寸（不保持宽高比） */
+  forceResize?: boolean;
+  /** 压缩级别 (0-9)，仅对 PNG 有效 */
+  compressionLevel?: number;
+  /** 是否渐进式编码，仅对 JPEG 有效 */
+  progressive?: boolean;
+}
+```
+
+## 转换结果
+
+```typescript
+interface ConvertResult {
+  /** 输入文件路径 */
+  inputPath: string;
+  /** 输出文件路径 */
+  outputPath: string;
+  /** 原始文件大小（字节） */
+  originalSize: number;
+  /** 转换后文件大小（字节） */
+  convertedSize: number;
+  /** 压缩率 */
+  compressionRatio: number;
+  /** 转换耗时（毫秒） */
+  processingTime: number;
+}
+```
+
+## 格式推荐
+
+### Web 应用
+- **WebP**: 现代浏览器支持，压缩率高，推荐用于 Web
+- **AVIF**: 最新格式，压缩率最高，但浏览器支持有限
+- **JPEG**: 通用格式，兼容性最好
+
+### 移动应用
+- **WebP**: Android 原生支持，iOS 14+ 支持
+- **JPEG**: 通用兼容性
+
+### 打印/专业用途
+- **PNG**: 无损压缩，支持透明度
+- **TIFF**: 专业格式，支持多种压缩算法
+
+## 性能优化建议
+
+1. **批量处理**: 使用 `batchConvert` 进行批量转换
+2. **质量设置**: 根据用途调整质量参数（Web 用 80-85，打印用 90-95）
+3. **尺寸优化**: 根据显示需求设置合适的输出尺寸
+4. **格式选择**: 优先使用 WebP 或 AVIF 以获得更好的压缩率
+
+## 错误处理
+
+所有函数都会抛出详细的错误信息，建议使用 try-catch 进行错误处理：
+
+```typescript
+try {
+  const result = await convertImage(inputPath, outputPath, 'webp');
+  console.log('转换成功:', result);
+} catch (error) {
+  console.error('转换失败:', error.message);
+}
+```
+
+## 注意事项
+
+1. 确保输入文件存在且可读
+2. 输出目录会自动创建
+3. GIF 格式暂不支持输出
+4. 大文件转换可能需要较长时间，建议在后台处理
+5. 某些格式转换可能不支持所有选项（如透明度）