@xiping/node-utils 1.0.53 → 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>;