# 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