@evio/ffai 1.0.1 → 1.0.3

package/README.md

@@ -1,111 +1,262 @@
 # FFmpeg 视频处理工具
 
-一个基于 FFmpeg 的命令行工具，用于批量处理视频和音频文件，支持视频转码、音频合并、字幕添加等功能。
+一个基于 FFmpeg 的命令行工具，用于批量处理视频和音频文件，支持视频转码、音频合并、字幕添加等功能。适用于自动化视频制作、批量视频处理等场景。
 
-## 功能特性
+## ✨ 功能特性
 
-- 🎬 批量视频转码和拼接
-- 🎵 多音频文件合并
-- 📝 自动添加字幕（支持 SRT 格式）
-- 🎲 智能视频选择（随机或全部模式）
-- 📦 支持 glob 模式匹配文件
-- ⚙️ 基于 JSON 配置文件的任务管理
+- 🎬 **批量视频转码和拼接** - 支持多种视频格式转换为 MP4，自动拼接多个视频片段
+- 🎵 **多音频文件混音** - 将多个音频文件混合为一个音轨，支持 glob 模式批量处理
+- 📝 **自动添加字幕** - 支持自定义时间格式的字幕文件，自动渲染到视频上
+- 🎲 **智能视频选择** - 随机模式根据音频时长智能选择视频片段，避免重复
+- 📦 **Glob 模式匹配** - 灵活的文件匹配模式，支持通配符批量处理
+- ⚙️ **JSON 配置管理** - 基于配置文件的任务管理，支持批量任务处理
+- 🔄 **自动化工作流** - 一键完成从素材到成品的全流程处理
 
-## 安装
+## 📋 前置要求
 
+- **Node.js** >= 14.0.0
+- **FFmpeg** - 必须在系统中安装并配置到环境变量
+
+### 安装 FFmpeg
+
+**macOS:**
+```bash
+brew install ffmpeg
+```
+
+**Ubuntu/Debian:**
 ```bash
+sudo apt update
+sudo apt install ffmpeg
+```
+
+**Windows:**
+从 [FFmpeg 官网](https://ffmpeg.org/download.html) 下载并配置环境变量
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+# 克隆项目
+git clone <repository-url>
+cd <project-directory>
+
+# 安装依赖
 npm install
+
+# 构建项目
 npm run build
-```
 
-## 使用方法
+# 全局安装（可选）
+npm link
+```
 
-### 基本命令
+### 基本使用
 
 ```bash
-ffai build <task-file.json>
+# 执行任务配置文件
+ffai build task.json
 ```
 
+## 📖 详细使用说明
+
 ### 任务配置文件
 
-创建一个 JSON 配置文件来定义处理任务：
+创建一个 JSON 配置文件来定义处理任务，支持多个任务批量执行：
 
 ```json
 [
   {
     "audios": ["audio1.mp3", "audio2.mp3"],
     "videos": "videos/*.mp4",
-    "narration": "subtitle.srt",
+    "narration": "subtitle.txt",
     "videoTranscodeable": true,
     "videoPackMode": "random"
+  },
+  {
+    "audios": "bgm/*.mp3",
+    "videos": ["clip1.mp4", "clip2.mp4"],
+    "narration": "subtitle2.txt",
+    "videoPackMode": "all"
   }
 ]
 ```
 
-### 配置参数说明
+### 配置参数详解
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `audios` | `string \| string[]` | ✅ | 音频文件路径，支持数组或 glob 模式（如 `bgm/*.mp3`）<br>⚠️ **重要**：如果是数组，最终音频时长由第一个音频文件决定，其他音频会被混音叠加 |
+| `videos` | `string \| string[]` | ✅ | 视频文件路径，支持数组或 glob 模式（如 `videos/*.mp4`） |
+| `narration` | `string` | ✅ | 字幕文件路径，使用自定义时间格式 |
+| `videoTranscodeable` | `boolean` | ❌ | 是否对视频进行转码，默认 `false`。启用后会将所有视频统一转码为 H.264/AAC 格式 |
+| `videoPackMode` | `'random' \| 'all'` | ❌ | 视频打包模式，默认 `'all'`<br>- `random`: 根据音频时长随机选择视频片段<br>- `all`: 使用所有视频文件 |
+
+### 字幕文件格式
 
-- `audios`: 音频文件路径，支持数组或 glob 模式
-- `videos`: 视频文件路径，支持数组或 glob 模式
-- `narration`: 字幕文件路径（SRT 格式）
-- `videoTranscodeable`: 是否对视频进行转码（可选，默认 false）
-- `videoPackMode`: 视频打包模式
-  - `random`: 随机选择视频片段直到满足音频时长
-  - `all`: 使用所有视频文件
+字幕文件使用简化的时间格式，每行一条字幕：
 
-## 工作流程
+```
+00:05-00:10 这是第一条字幕
+00:12-00:18 这是第二条字幕
+00:20-00:25 支持中文和英文
+```
 
-1. 读取配置文件中的任务列表
-2. 转码视频文件（如果启用）
-3. 合并多个音频文件
-4. 根据模式选择和拼接视频
-5. 添加背景音频
-6. 添加字幕
-7. 输出最终视频到 `task-{index}/video.mp4`
+格式说明：
+- 时间格式：`MM:SS-MM:SS 字幕内容`
+- 开始时间和结束时间用 `-` 分隔
+- 时间和文本之间用空格分隔
 
-## 示例
+## 🔄 工作流程
 
-```bash
-# 使用配置文件执行任务
-ffai build tasks.json
+工具会按以下步骤自动处理每个任务：
+
+1. **检查 FFmpeg** - 验证 FFmpeg 是否可用
+2. **解析配置** - 读取任务配置文件
+3. **视频转码**（可选）- 将视频统一转码为 MP4 格式（H.264 + AAC）
+4. **音频混音** - 将多个音频文件混合为一个音轨
+5. **视频选择** - 根据模式选择视频片段
+6. **视频拼接** - 将选中的视频片段拼接成完整视频
+7. **添加音频** - 为视频添加混音后的背景音频
+8. **渲染字幕** - 将字幕渲染到视频上
+9. **输出成品** - 生成最终视频文件
+
+## 📂 输出结构
+
+每个任务会在当前目录下创建 `task-{index}` 文件夹：
+
+```
+task-0/
+├── videos/          # 转码后的视频文件（如果启用 videoTranscodeable）
+│   ├── 1.mp4
+│   ├── 2.mp4
+│   └── ...
+├── tmp/             # 临时文件目录
+├── audio.mp3        # 混音后的音频文件
+└── video.mp4        # 最终输出的视频文件 ⭐
 ```
 
-配置文件示例：
+## 💡 使用示例
+
+### 示例 1：随机视频片段 + 多音频混音
 
 ```json
 [
   {
-    "audios": ["bgm/*.mp3"],
-    "videos": ["clips/*.mp4"],
-    "narration": "subtitles/video1.srt",
+    "audios": ["bgm/music1.mp3", "bgm/music2.mp3"],
+    "videos": "clips/*.mp4",
+    "narration": "subtitles/narration.txt",
     "videoTranscodeable": true,
     "videoPackMode": "random"
   }
 ]
 ```
 
-## 输出
+这个配置会：
+- 混合两个背景音乐
+- 从 `clips/` 目录随机选择视频片段，直到总时长匹配音频
+- 转码所有视频为统一格式
+- 添加字幕
 
-每个任务会在当前目录下创建 `task-{index}` 文件夹，包含：
+### 示例 2：使用所有视频 + Glob 模式
 
-- `videos/`: 转码后的视频文件（如果启用转码）
-- `audio.mp3`: 合并后的音频文件
-- `video.mp4`: 最终输出的视频文件
+```json
+[
+  {
+    "audios": "audio/*.mp3",
+    "videos": ["intro.mp4", "content.mp4", "outro.mp4"],
+    "narration": "subtitle.txt",
+    "videoPackMode": "all"
+  }
+]
+```
 
-## 依赖
+这个配置会：
+- 混合 `audio/` 目录下的所有 MP3 文件
+- 按顺序拼接三个视频文件
+- 不进行视频转码（使用原始格式）
 
-- Node.js
-- FFmpeg（需要系统安装）
+### 示例 3：批量处理多个任务
 
-## 开发
+```json
+[
+  {
+    "audios": "task1/audio.mp3",
+    "videos": "task1/videos/*.mp4",
+    "narration": "task1/subtitle.txt",
+    "videoPackMode": "random"
+  },
+  {
+    "audios": "task2/audio.mp3",
+    "videos": "task2/videos/*.mp4",
+    "narration": "task2/subtitle.txt",
+    "videoPackMode": "all"
+  }
+]
+```
+
+## 🛠️ 开发
 
 ```bash
-# 开发模式
+# 开发模式（使用 ts-node 直接运行）
 npm run dev
 
-# 构建
+# 构建项目
 npm run build
+
+# 构建并修复 ESM 导入路径
+npm run fix
 ```
 
-## License
+## 📝 API 说明
+
+项目提供了一系列可复用的函数，可以在其他项目中引入使用：
+
+```typescript
+import {
+  getMediaDuration,      // 获取媒体文件时长
+  transcodeVideo,        // 转码单个视频
+  transcodeVideos,       // 批量转码视频
+  concatVideos,          // 拼接多个视频
+  mergeAudioFiles,       // 混音多个音频文件
+  addBackgroundAudio,    // 为视频添加背景音频
+  addSubTitles,          // 为视频添加字幕
+  checkFfmpegAvailable   // 检查 FFmpeg 是否可用
+} from '@evio/ffai';
+```
+
+## ⚠️ 注意事项
+
+1. **FFmpeg 必须安装** - 工具依赖 FFmpeg，请确保已正确安装
+2. **字幕字体** - macOS 默认使用宋体（`/System/Library/Fonts/Supplemental/Songti.ttc`），其他系统可能需要修改字体路径
+3. **视频格式** - 建议启用 `videoTranscodeable` 以确保所有视频格式统一，避免拼接问题
+4. **文件路径** - 所有路径都相对于执行命令的当前目录
+5. **临时文件** - 处理完成后会自动清理临时文件，保留最终成品
+
+## 🐛 常见问题
+
+**Q: 提示 "FFmpeg is not available"**  
+A: 请确保已安装 FFmpeg 并配置到系统环境变量中
+
+**Q: 视频拼接后出现黑屏或卡顿**  
+A: 建议启用 `videoTranscodeable: true` 将所有视频转码为统一格式
+
+**Q: 字幕显示不正常**  
+A: 检查字幕文件格式是否正确，时间格式必须为 `MM:SS-MM:SS`
+
+**Q: 音频混音后声音太小或太大**  
+A: FFmpeg 的 `amix` 滤镜会自动调整音量，如需手动控制可修改 `lib.ts` 中的混音参数
+
+## 📄 License
 
 ISC
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+---
+
+**版本**: 1.0.2  
+**作者**: @evio/ffai

package/dist/index.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const node_path_1 = require("node:path");
 const task_1 = require("./task");
+const lib_1 = require("./lib");
 const program = new commander_1.Command();
 const pkg = require('../package.json');
 program
@@ -13,6 +14,10 @@ program
 program
     .command('build <file>')
     .action(async (file) => {
+    const enable = await (0, lib_1.checkFfmpegAvailable)();
+    if (!enable) {
+        throw new Error('FFmpeg is not available or not installed. Please install FFmpeg to continue.');
+    }
     const taskFile = (0, node_path_1.resolve)(process.cwd(), file);
     if (!taskFile.endsWith('.json')) {
         throw new Error(`Task file must end with '.json' extension. Received: ${file}`);

package/dist/lib.d.ts

@@ -30,6 +30,7 @@ export declare function concatVideos(files: string[], outputFilePath: string, tm
 export declare function addBackgroundAudio(inputVideoPath: string, outputVideoPath: string, audioPath: string): Promise<void>;
 /**
  * 合并多个音频文件(.mp3) - 重叠播放（混音）
+ * 以第一个音频的时长为准，超过的部分会被切掉
  * @param audioFiles 音频文件路径数组
  * @param outputFilePath 输出文件路径
  */
@@ -43,3 +44,4 @@ export declare function mergeAudioFiles(audioFiles: string[], outputFilePath: st
  * @returns Promise
  */
 export declare function addSubTitles(inputfile: string, outputfile: string, texts: string, fontfile?: string): Promise<void>;
+export declare function checkFfmpegAvailable(): Promise<boolean>;

package/dist/lib.js

@@ -10,6 +10,7 @@ exports.concatVideos = concatVideos;
 exports.addBackgroundAudio = addBackgroundAudio;
 exports.mergeAudioFiles = mergeAudioFiles;
 exports.addSubTitles = addSubTitles;
+exports.checkFfmpegAvailable = checkFfmpegAvailable;
 const fluent_ffmpeg_1 = __importDefault(require("fluent-ffmpeg"));
 const dayjs_1 = __importDefault(require("dayjs"));
 const node_fs_1 = require("node:fs");
@@ -145,14 +146,17 @@ function addBackgroundAudio(inputVideoPath, outputVideoPath, audioPath) {
 }
 /**
  * 合并多个音频文件(.mp3) - 重叠播放（混音）
+ * 以第一个音频的时长为准，超过的部分会被切掉
  * @param audioFiles 音频文件路径数组
  * @param outputFilePath 输出文件路径
  */
-function mergeAudioFiles(audioFiles, outputFilePath) {
+async function mergeAudioFiles(audioFiles, outputFilePath) {
+    if (!audioFiles?.length) {
+        throw new Error("音频文件列表为空");
+    }
+    // 获取第一个音频文件的时长
+    const firstAudioDuration = await getMediaDuration(audioFiles[0]);
     return new Promise((_resolve, reject) => {
-        if (!audioFiles?.length) {
-            return reject(new Error("音频文件列表为空"));
-        }
         // 创建FFmpeg命令实例
         const cmd = (0, fluent_ffmpeg_1.default)();
         // 添加所有音频文件作为输入
@@ -164,14 +168,15 @@ function mergeAudioFiles(audioFiles, outputFilePath) {
         // 设置音频混音滤镜
         // 使用 complexFilter 来处理多个输入流的混合
         // amix 滤镜会将多个音频流混合在一起，默认会自动调整音量
-        // 使用 amix=inputs=N:duration=first 参数来保持与第一个输入相同的时长
+        // duration=first 参数保持与第一个输入相同的时长
         cmd.complexFilter(`amix=inputs=${inputCount}:duration=first`);
         // 设置输出选项
         cmd.outputOptions([
             "-c:a libmp3lame", // 使用MP3编码器
             "-b:a 192k", // 设置音频比特率
             "-ar 44100", // 设置音频采样率
-            "-ac 2" // 设置声道数
+            "-ac 2", // 设置声道数
+            `-t ${firstAudioDuration}` // 明确限制输出时长为第一个音频的时长
         ])
             // .on("start", (cmd) => console.log("混音音频命令:", cmd, '\n'))
             // .on("progress", (progress) => {
@@ -233,7 +238,7 @@ function addSubTitles(inputfile, outputfile, texts, fontfile) {
                 // max_width: "w*0.8", // 最大宽度为视频宽度的80%，超过则自动换行
                 // line_spacing: 8, // 行间距为8像素
                 x: "(w-text_w)/2", // 水平居中
-                y: "(h-text_h-200)", // 底部以上100像素的位置，确保在视频范围内
+                y: "(h-text_h-300)", // 底部以上100像素的位置，确保在视频范围内
                 enable: `between(t,${e.start},${e.end})`,
             },
         };
@@ -261,3 +266,15 @@ function addSubTitles(inputfile, outputfile, texts, fontfile) {
             .save(outputfile);
     });
 }
+function checkFfmpegAvailable() {
+    return new Promise((resolve) => {
+        fluent_ffmpeg_1.default.getAvailableFormats((err, formats) => {
+            if (err) {
+                resolve(false);
+            }
+            else {
+                resolve(true);
+            }
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evio/ffai",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "一个基于 FFmpeg 的命令行工具，用于批量处理视频和音频文件，支持视频转码、音频合并、字幕添加等功能。",
   "main": "dist/lib.js",
   "scripts": {