@xiping/node-utils 1.0.60 → 1.0.61

package/lib/src/ffmpeg/README.md

@@ -0,0 +1,371 @@
+# FFmpeg 工具模块
+
+基于 FFmpeg/FFprobe 的 Node.js 视频处理工具集，提供视频信息获取、缩略图生成、视频截取、音频提取及运行环境检查等功能。
+
+本模块由 `@xiping/node-utils` 包统一导出，使用时从包根路径导入即可：`import { ... } from '@xiping/node-utils'`。
+
+## 功能概览
+
+| 功能       | 说明                     | 依赖        |
+|------------|--------------------------|-------------|
+| 视频信息   | 时长、分辨率、编码、比特率等 | ffprobe    |
+| 缩略图生成 | 多帧合成预览图（AVIF/WebP/JPEG/PNG） | ffmpeg + sharp |
+| 视频截取   | 按时间范围截取，流复制不重编码 | ffmpeg     |
+| 提取音频   | 从视频中提取音轨为 mp3/m4a/wav | ffmpeg     |
+| 环境检查   | 检测 ffmpeg/ffprobe 是否可用 | -          |
+
+## 安装要求
+
+### 依赖包
+
+- Node.js
+- [shelljs](https://www.npmjs.com/package/shelljs)
+- [sharp](https://www.npmjs.com/package/sharp)（仅缩略图功能需要）
+
+### 系统要求
+
+- **ffprobe**：视频信息相关接口需要（通常随 ffmpeg 一起安装）
+- **ffmpeg**：缩略图、视频截取需要
+
+### 安装 FFmpeg / FFprobe
+
+**macOS:**
+
+```bash
+brew install ffmpeg
+```
+
+**Ubuntu/Debian:**
+
+```bash
+sudo apt update
+sudo apt install ffmpeg
+```
+
+**CentOS/RHEL:**
+
+```bash
+sudo yum install ffmpeg
+```
+
+**Windows:**
+
+从 [FFmpeg 官网](https://ffmpeg.org/download.html) 下载并将可执行文件加入 PATH，或使用 Chocolatey：
+
+```bash
+choco install ffmpeg
+```
+
+---
+
+## 1. 视频信息（getVideoInfo）
+
+使用 ffprobe 获取视频元数据：时长、分辨率、编码、比特率、帧率、文件大小等。
+
+### 基本使用
+
+```typescript
+import { getVideoInfo } from '@xiping/node-utils';
+
+const videoInfo = getVideoInfo('/path/to/video.mp4');
+console.log(videoInfo.durationFormatted, videoInfo.width, videoInfo.height);
+```
+
+### 检查 ffprobe 是否可用
+
+```typescript
+import { isFfprobeAvailable } from '@xiping/node-utils';
+
+if (isFfprobeAvailable()) {
+  console.log('ffprobe 可用');
+}
+```
+
+### 批量获取
+
+```typescript
+import { getMultipleVideoInfo } from '@xiping/node-utils';
+
+const infos = getMultipleVideoInfo(['/path/video1.mp4', '/path/video2.mp4']);
+```
+
+### 获取详细元数据（含章节等）
+
+```typescript
+import { getDetailedVideoInfo } from '@xiping/node-utils';
+
+const detailed = getDetailedVideoInfo('/path/to/video.mp4');
+```
+
+### VideoInfo 结构
+
+```typescript
+interface VideoInfo {
+  path: string;
+  duration: number;           // 秒
+  durationFormatted: string;
+  width: number;
+  height: number;
+  videoCodec: string;
+  audioCodec: string;
+  bitrate: number;
+  fps: number;
+  fileSize: number;           // 字节
+  fileSizeFormatted: string;
+  rawInfo: string;            // 原始 ffprobe JSON
+}
+```
+
+---
+
+## 2. 缩略图生成（getThumbnail）
+
+从视频中等间隔提取多帧，用 sharp 合成为一张缩略图，支持 AVIF/WebP/JPEG/PNG。
+
+### 基本使用
+
+```typescript
+import { getThumbnail } from '@xiping/node-utils';
+
+const result = await getThumbnail('/path/to/video.mp4', {
+  frames: 60,           // 提取帧数（默认 60）
+  columns: 4,           // 每行列数（默认 4）
+  outputWidth: 3840,    // 输出宽度（默认 3840）
+  format: 'avif',       // 'avif' | 'webp' | 'jpeg' | 'png'
+  quality: 80,          // 1–100
+  outputFileName: 'thumbnail.avif',
+});
+
+console.log(result.outputPath);
+console.log(result.metadata);
+```
+
+### 进度回调
+
+```typescript
+const result = await getThumbnail('/path/to/video.mp4', {
+  frames: 30,
+  onProgress(progress) {
+    console.log(progress.phase, progress.percent, progress.message);
+    // phase: 'analyzing' | 'extracting' | 'composing' | 'encoding' | 'done'
+  },
+});
+```
+
+### 选项说明
+
+| 选项            | 类型     | 默认值         | 说明           |
+|-----------------|----------|----------------|----------------|
+| frames          | number   | 60             | 提取的帧数     |
+| columns         | number   | 4              | 缩略图列数     |
+| outputWidth     | number   | 3840           | 输出图宽度     |
+| outputFileName  | string   | thumbnail.avif | 输出文件名     |
+| format          | string   | 'avif'         | avif/webp/jpeg/png |
+| quality         | number   | 80             | 1–100          |
+| batchSize       | number   | 10             | 合成时每批帧数 |
+| maxConcurrency  | number   | 4              | 提取帧并发数   |
+| tempDir         | string   | -              | 自定义临时目录 |
+| onProgress      | function | -              | 进度回调       |
+
+### 返回值
+
+```typescript
+{
+  buffer: Buffer;
+  outputPath: string;
+  metadata: {
+    frames: number;
+    duration: number;
+    outputSize: { width: number; height: number };
+  };
+}
+```
+
+**注意**：输入路径需为**绝对路径**；使用前请确保已安装 ffmpeg（可用下方「环境检查」接口检测）。
+
+---
+
+## 3. 视频截取（cutVideo）
+
+按开始时间、时长或结束时间截取片段，使用流复制（`-c copy`），不重新编码。
+
+### 基本使用
+
+```typescript
+import { cutVideo, cutVideoByTimeRange, cutVideoByDuration, cutVideoFromStart } from '@xiping/node-utils';
+
+// 从 30 秒开始截取 60 秒
+const result = await cutVideo('/path/to/video.mp4', {
+  startTime: '00:00:30',
+  duration: '00:01:00',
+  outputFormat: 'mp4',
+  overwrite: true,
+});
+
+// 按时间范围：1:30 到 3:45
+const r2 = await cutVideoByTimeRange('/path/to/video.mp4', '00:01:30', '00:03:45');
+
+// 从 2 分钟开始截取 90 秒
+const r3 = await cutVideoByDuration('/path/to/video.mp4', '00:02:00', '00:01:30');
+
+// 只取前 30 秒
+const r4 = await cutVideoFromStart('/path/to/video.mp4', 30);
+```
+
+### CutVideoOptions
+
+```typescript
+{
+  startTime?: string;      // 开始时间，如 '00:00:30' 或秒数
+  duration?: string;       // 持续时间
+  endTime?: string;        // 结束时间（与 duration 二选一）
+  outputFileName?: string;
+  outputFormat?: string;   // 默认 'mp4'
+  tempDir?: string;
+  overwrite?: boolean;      // 是否覆盖已存在文件
+}
+```
+
+### CutVideoResult
+
+```typescript
+{
+  outputPath: string;
+  metadata: {
+    originalDuration: number;
+    cutDuration: number;
+    startTime: string;
+    endTime: string;
+    fileSize: number;
+    processingTime: number;
+  };
+}
+```
+
+时间格式支持：`HH:MM:SS`、`MM:SS` 或纯秒数。输入路径需为**绝对路径**。更多说明见 [README_cutVideo.md](./README_cutVideo.md)。
+
+---
+
+## 4. 提取音频（extractAudio）
+
+从视频文件中仅提取音频轨，输出为独立音频文件（mp3、m4a、wav）。
+
+### 基本使用
+
+```typescript
+import { extractAudio } from '@xiping/node-utils';
+
+const result = await extractAudio('/path/to/video.mp4', {
+  outputFormat: 'mp3',   // 'mp3' | 'm4a' | 'wav'，默认 'mp3'
+  outputFileName: 'audio.mp3',
+  overwrite: true,
+});
+
+console.log(result.outputPath);
+console.log(result.metadata.duration, result.metadata.fileSize);
+```
+
+### 进度回调
+
+```typescript
+const result = await extractAudio('/path/to/video.mp4', {
+  outputFormat: 'mp3',
+  onProgress(progress) {
+    console.log(progress.phase, progress.percent, progress.message);
+    // phase: 'preparing' | 'encoding' | 'done'
+    if (progress.currentTime != null && progress.duration != null) {
+      console.log(`已处理 ${progress.currentTime}/${progress.duration} 秒`);
+    }
+  },
+});
+```
+
+### 选项说明
+
+| 选项            | 类型     | 默认值   | 说明                         |
+|-----------------|----------|----------|------------------------------|
+| outputFileName  | string   | 源文件名.格式 | 输出文件名                   |
+| outputFormat    | string   | 'mp3'    | mp3 / m4a / wav              |
+| overwrite       | boolean  | false    | 是否覆盖已存在文件           |
+| tempDir         | string   | -        | 自定义临时目录               |
+| copyStream      | boolean  | true     | 尽量流复制不重编码（格式兼容时） |
+| onProgress      | function | -        | 进度回调                     |
+
+### 返回值
+
+```typescript
+{
+  outputPath: string;
+  metadata: {
+    duration: number;      // 音频时长（秒）
+    fileSize: number;      // 输出文件大小（字节）
+    processingTime: number; // 处理耗时（毫秒）
+  };
+}
+```
+
+输入路径需为**绝对路径**；若视频无音轨将抛错。使用前请确保已安装 ffmpeg。
+
+---
+
+## 5. 环境检查（check）
+
+```typescript
+import { checkFFmpegAvailability, isFfprobeAvailable } from '@xiping/node-utils';
+
+if (checkFFmpegAvailability()) {
+  console.log('ffmpeg 可用');
+}
+if (isFfprobeAvailable()) {
+  console.log('ffprobe 可用');
+}
+```
+
+- **checkFFmpegAvailability()**：用于缩略图、视频截取、提取音频前检查。
+- **isFfprobeAvailable()**：用于视频信息接口前检查。
+
+---
+
+## 错误处理
+
+各函数在以下情况会抛出错误，建议用 try/catch 包裹：
+
+- 文件不存在或路径无效
+- 未安装 ffmpeg/ffprobe 或不可用
+- 格式/参数不支持（如时间超出视频时长、视频无音轨）
+- 权限或磁盘空间不足
+
+```typescript
+try {
+  const info = getVideoInfo('/path/to/video.mp4');
+} catch (err) {
+  console.error(err.message);
+}
+```
+
+---
+
+## 支持格式
+
+ffprobe/ffmpeg 支持常见容器与编码，例如：
+
+- 容器：MP4, AVI, MOV, MKV, FLV, WMV, WebM, OGV, 3GP 等
+- 具体支持以系统安装的 FFmpeg 版本为准
+
+---
+
+## API 速览
+
+| 接口                     | 说明 |
+|--------------------------|------|
+| `getVideoInfo(path)`     | 获取视频基本信息 |
+| `getMultipleVideoInfo(paths)` | 批量获取视频信息 |
+| `getDetailedVideoInfo(path)`  | 获取详细元数据（含章节等） |
+| `getThumbnail(path, options)` | 生成多帧缩略图（异步） |
+| `cutVideo(path, options)`     | 按选项截取视频（异步） |
+| `cutVideoByTimeRange(path, start, end, options)` | 按起止时间截取 |
+| `cutVideoByDuration(path, start, duration, options)` | 按起始+时长截取 |
+| `cutVideoFromStart(path, durationSeconds, options)`   | 从开头截取 N 秒 |
+| `extractAudio(path, options)` | 从视频提取音频（异步） |
+| `isFfprobeAvailable()`   | 检测 ffprobe 是否可用 |
+| `checkFFmpegAvailability()` | 检测 ffmpeg 是否可用 |

package/lib/src/ffmpeg/README_cutVideo.md

@@ -0,0 +1,220 @@
+# Video Cutter (视频截取器)
+
+一个基于 FFmpeg 的 Node.js 视频截取工具，支持精确的时间控制和高性能的视频处理。
+
+## 功能特性
+
+- 🎯 **精确时间控制** - 支持多种时间格式 (HH:MM:SS, 秒数)
+- ⚡ **高性能处理** - 使用 FFmpeg 的 copy 模式，避免重新编码
+- 🛡️ **输入验证** - 完整的参数验证和错误处理
+- 📁 **灵活输出** - 支持自定义输出格式和文件名
+- 🔄 **临时文件管理** - 自动清理临时文件
+- 📊 **详细元数据** - 返回处理结果和文件信息
+
+## 安装依赖
+
+确保系统已安装 FFmpeg：
+
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu/Debian
+sudo apt update
+sudo apt install ffmpeg
+
+# Windows
+# 下载并安装 FFmpeg，或使用 chocolatey: choco install ffmpeg
+```
+
+## API 参考
+
+### 主要函数
+
+#### `cutVideo(videoPath, options)`
+
+主要的视频截取函数。
+
+**参数：**
+- `videoPath` (string): 输入视频文件的绝对路径
+- `options` (CutVideoOptions): 截取选项
+
+**返回值：**
+- `Promise<CutVideoResult>`: 包含输出路径和元数据的对象
+
+#### `cutVideoByTimeRange(videoPath, startTime, endTime, options)`
+
+按时间范围截取视频的便捷函数。
+
+#### `cutVideoByDuration(videoPath, startTime, duration, options)`
+
+按持续时间截取视频的便捷函数。
+
+#### `cutVideoFromStart(videoPath, durationSeconds, options)`
+
+从视频开头截取指定秒数的便捷函数。
+
+### 类型定义
+
+#### CutVideoOptions
+
+```typescript
+interface CutVideoOptions {
+  startTime?: string;        // 开始时间 (格式: HH:MM:SS 或秒数)
+  duration?: string;         // 持续时间 (格式: HH:MM:SS 或秒数)
+  endTime?: string;          // 结束时间 (格式: HH:MM:SS 或秒数)
+  outputFileName?: string;   // 输出文件名
+  outputFormat?: string;     // 输出格式 (mp4, avi, mov, etc.)
+  tempDir?: string;          // 临时目录
+  overwrite?: boolean;       // 是否覆盖已存在的文件
+}
+```
+
+#### CutVideoResult
+
+```typescript
+interface CutVideoResult {
+  outputPath: string;
+  metadata: {
+    originalDuration: number;    // 原视频时长(秒)
+    cutDuration: number;         // 截取时长(秒)
+    startTime: string;           // 开始时间
+    endTime: string;             // 结束时间
+    fileSize: number;            // 输出文件大小(字节)
+    processingTime: number;      // 处理时间(毫秒)
+  };
+}
+```
+
+## 使用示例
+
+### 基本用法
+
+```typescript
+import { cutVideo } from './cutVideo.js';
+
+// 从第30秒开始截取60秒
+const result = await cutVideo('/path/to/video.mp4', {
+  startTime: '00:00:30',
+  duration: '00:01:00'
+});
+
+console.log('输出文件:', result.outputPath);
+console.log('文件大小:', result.metadata.fileSize);
+```
+
+### 按时间范围截取
+
+```typescript
+import { cutVideoByTimeRange } from './cutVideo.js';
+
+// 截取 1:30 到 3:45 之间的片段
+const result = await cutVideoByTimeRange(
+  '/path/to/video.mp4',
+  '00:01:30',
+  '00:03:45'
+);
+```
+
+### 按持续时间截取
+
+```typescript
+import { cutVideoByDuration } from './cutVideo.js';
+
+// 从第2分钟开始截取90秒
+const result = await cutVideoByDuration(
+  '/path/to/video.mp4',
+  '00:02:00',
+  '00:01:30'
+);
+```
+
+### 从头开始截取
+
+```typescript
+import { cutVideoFromStart } from './cutVideo.js';
+
+// 截取视频前30秒
+const result = await cutVideoFromStart(
+  '/path/to/video.mp4',
+  30
+);
+```
+
+### 自定义输出选项
+
+```typescript
+const result = await cutVideo('/path/to/video.mp4', {
+  startTime: '00:01:00',
+  duration: '00:02:00',
+  outputFileName: 'my_cut_video.mp4',
+  outputFormat: 'mp4',
+  overwrite: true
+});
+```
+
+### 使用自定义临时目录
+
+```typescript
+const result = await cutVideo('/path/to/video.mp4', {
+  startTime: '00:00:30',
+  duration: '00:01:00',
+  tempDir: '/custom/temp/directory'
+});
+```
+
+## 时间格式支持
+
+支持多种时间格式：
+
+- `HH:MM:SS` - 标准时间格式 (如: `01:30:45`)
+- `MM:SS` - 分钟:秒格式 (如: `30:45`)
+- 秒数 - 纯数字格式 (如: `90.5`)
+
+## 错误处理
+
+函数会抛出以下类型的错误：
+
+- **文件不存在**: 输入视频文件不存在
+- **FFmpeg 未安装**: 系统未安装 FFmpeg
+- **时间参数无效**: 开始时间大于等于视频时长
+- **输出文件已存在**: 输出文件存在且未设置覆盖选项
+- **FFmpeg 执行失败**: 视频处理过程中出现错误
+
+```typescript
+try {
+  const result = await cutVideo('/path/to/video.mp4', {
+    startTime: '00:00:30',
+    duration: '00:01:00'
+  });
+} catch (error) {
+  console.error('视频截取失败:', error.message);
+}
+```
+
+## 性能优化
+
+- 使用 FFmpeg 的 `-c copy` 参数避免重新编码
+- 自动管理临时文件，处理完成后自动清理
+- 支持自定义临时目录以优化 I/O 性能
+
+## 注意事项
+
+1. **路径要求**: 输入路径必须是绝对路径
+2. **文件权限**: 确保对输入和输出目录有读写权限
+3. **磁盘空间**: 确保有足够的磁盘空间存储输出文件
+4. **FFmpeg 依赖**: 必须安装 FFmpeg 才能使用此模块
+
+## 日志输出
+
+模块会输出详细的处理日志，包括：
+- 参数验证结果
+- FFmpeg 命令执行
+- 处理进度和结果
+- 错误信息
+
+日志格式：`[VideoCutter] 消息内容`
+
+## 许可证
+
+MIT License

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,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/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/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. 某些格式转换可能不支持所有选项（如透明度）

package/lib/src/srt-to-vtt/README.md

@@ -0,0 +1,189 @@
+# SRT到VTT转换器
+
+这个模块提供了在Node.js环境中将SRT字幕文件转换为WebVTT格式的功能。
+
+## 功能特性
+
+- ✅ 从文件读取SRT并转换为VTT
+- ✅ 支持批量转换多个SRT文件
+- ✅ 支持字符串内容直接转换
+- ✅ 自动验证SRT格式
+- ✅ 完整的错误处理
+- ✅ TypeScript支持
+
+## 安装
+
+```bash
+npm install @xiping/node-utils
+```
+
+## 使用方法
+
+### 1. 从文件读取SRT并转换为VTT字符串
+
+```typescript
+import { convertSrtFileToVtt } from '@xiping/node-utils/src/srt-to-vtt';
+
+try {
+  const vttContent = convertSrtFileToVtt('./subtitles.srt');
+  console.log('转换后的VTT内容:', vttContent);
+} catch (error) {
+  console.error('转换失败:', error);
+}
+```
+
+### 2. 从文件读取SRT并保存为VTT文件
+
+```typescript
+import { convertSrtFileToVttFile } from '@xiping/node-utils/src/srt-to-vtt';
+
+try {
+  // 指定输出路径
+  const outputPath = convertSrtFileToVttFile('./subtitles.srt', './output/subtitles.vtt');
+  console.log('VTT文件已保存到:', outputPath);
+  
+  // 或者使用默认输出路径（同目录，扩展名改为.vtt）
+  const defaultOutputPath = convertSrtFileToVttFile('./subtitles.srt');
+  console.log('默认输出路径:', defaultOutputPath);
+} catch (error) {
+  console.error('文件转换失败:', error);
+}
+```
+
+### 3. 批量转换多个SRT文件
+
+```typescript
+import { batchConvertSrtToVtt } from '@xiping/node-utils/src/srt-to-vtt';
+
+try {
+  const srtFiles = [
+    './subtitles1.srt',
+    './subtitles2.srt',
+    './subtitles3.srt'
+  ];
+  
+  const results = batchConvertSrtToVtt(srtFiles, './output');
+  
+  results.forEach(result => {
+    if (result.success) {
+      console.log(`✅ ${result.input} -> ${result.output}`);
+    } else {
+      console.error(`❌ ${result.input}: ${result.error}`);
+    }
+  });
+} catch (error) {
+  console.error('批量转换失败:', error);
+}
+```
+
+### 4. 从字符串内容直接转换
+
+```typescript
+import { convertSrtStringToVtt } from '@xiping/node-utils/src/srt-to-vtt';
+
+try {
+  const srtContent = `1
+00:00:00,000 --> 00:00:04,000
+这是第一行字幕
+
+2
+00:00:04,000 --> 00:00:08,000
+这是第二行字幕`;
+
+  const vttContent = convertSrtStringToVtt(srtContent);
+  console.log('转换后的VTT内容:', vttContent);
+} catch (error) {
+  console.error('字符串转换失败:', error);
+}
+```
+
+## API参考
+
+### convertSrtFileToVtt(srtFilePath: string): string
+
+从文件读取SRT内容并转换为VTT格式字符串。
+
+**参数:**
+- `srtFilePath`: SRT文件路径
+
+**返回值:**
+- 转换后的VTT内容字符串
+
+**异常:**
+- 文件不存在时抛出错误
+- 文件格式无效时抛出错误
+
+### convertSrtFileToVttFile(srtFilePath: string, outputPath?: string): string
+
+从文件读取SRT内容并转换为VTT格式，同时保存到文件。
+
+**参数:**
+- `srtFilePath`: SRT文件路径
+- `outputPath`: 输出VTT文件路径（可选）
+
+**返回值:**
+- 输出文件路径
+
+### batchConvertSrtToVtt(srtFilePaths: string[], outputDir?: string): Array<{ input: string; output: string; success: boolean; error?: string }>
+
+批量转换多个SRT文件到VTT格式。
+
+**参数:**
+- `srtFilePaths`: SRT文件路径数组
+- `outputDir`: 输出目录（可选）
+
+**返回值:**
+- 转换结果数组，包含每个文件的转换状态
+
+### convertSrtStringToVtt(srtContent: string): string
+
+从字符串内容直接转换为VTT格式。
+
+**参数:**
+- `srtContent`: SRT内容字符串
+
+**返回值:**
+- VTT格式字符串
+
+## 格式说明
+
+### SRT格式
+```
+1
+00:00:00,000 --> 00:00:04,000
+字幕内容
+
+2
+00:00:04,000 --> 00:00:08,000
+字幕内容
+```
+
+### WebVTT格式
+```
+WEBVTT
+
+00:00:00.000 --> 00:00:04.000
+字幕内容
+
+00:00:04.000 --> 00:00:08.000
+字幕内容
+```
+
+## 主要差异
+
+1. **时间格式**: SRT使用逗号分隔毫秒，VTT使用点分隔
+2. **头部**: VTT需要`WEBVTT`头部
+3. **索引**: SRT包含序号，VTT不包含
+
+## 错误处理
+
+所有函数都包含完整的错误处理：
+
+- 文件不存在
+- 文件格式错误
+- 权限问题
+- 编码问题
+
+## 示例
+
+查看 `example.ts` 文件获取完整的使用示例。 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiping/node-utils",
-  "version": "1.0.60",
+  "version": "1.0.61",
   "description": "node-utils",
   "type": "module",
   "author": "The-End-Hero <527409987@qq.com>",
@@ -20,12 +20,12 @@
   },
   "scripts": {
     "test": "echo \"Error: run tests from root\" && exit 1",
-    "build": "tsc"
+    "build": "tsc && node scripts/copy-readmes.js"
   },
   "bugs": {
     "url": "https://github.com/The-End-Hero/wang-ping/issues"
   },
-  "gitHead": "ccc3b005287f15abceac6210833bf8c8ace3fbaf",
+  "gitHead": "6cb2ac8c64a780abb18ec793978d3adfff71fba7",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"