@evio/ffai 1.0.2 → 1.0.4

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/lib.js

@@ -230,15 +230,15 @@ function addSubTitles(inputfile, outputfile, texts, fontfile) {
             options: {
                 fontfile,
                 text: e.text,
-                fontsize: 36, // 增大字体大小，确保清晰可见
+                fontsize: 36, // 字体大小
                 fontcolor: "white", // 文字颜色设置为白色
-                box: 1, // 启用背景框
-                boxcolor: "black@0.7", // 半透明黑色背景，使用ffmpeg支持的格式
-                boxborderw: 4, // 调整边框宽度
-                // max_width: "w*0.8", // 最大宽度为视频宽度的80%，超过则自动换行
-                // line_spacing: 8, // 行间距为8像素
+                shadowcolor: "black@0.8", // 阴影颜色：黑色，透明度 0.8
+                shadowx: 2, // 阴影 X 轴偏移
+                shadowy: 2, // 阴影 Y 轴偏移
+                borderw: 2, // 文字边框宽度，创建渐变效果
+                bordercolor: "black@0.6", // 边框颜色：黑色，透明度 0.6
                 x: "(w-text_w)/2", // 水平居中
-                y: "(h-text_h-300)", // 底部以上100像素的位置，确保在视频范围内
+                y: "(h-text_h-300)", // 底部以上 300 像素的位置
                 enable: `between(t,${e.start},${e.end})`,
             },
         };

package/package.json

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