Video Merger CLI (vvm)

一个基于 Node.js 和 FFmpeg 的视频合并 CLI 工具，支持为视频添加片头、片尾，以及批量处理多个视频文件。

功能特性

• ✅ 视频合并：将两个视频合并为一个（支持开头或结尾位置）
• ✅ 批量处理：批量处理目录下的所有视频文件
• ✅ 灵活配置：支持命令行参数和配置文件两种方式
• ✅ 素材管理：独立管理片头、片尾等素材
• ✅ 规则匹配：支持按文件名模式应用不同的处理规则
• ✅ 全局安装：可作为全局命令行工具使用

前置要求

• Node.js >= 16.0.0
• FFmpeg（必须已安装并添加到系统环境变量）

安装 FFmpeg

Windows:

# 使用 Chocolatey
choco install ffmpeg

# 或从官网下载: https://ffmpeg.org/download.html

macOS:

brew install ffmpeg

Linux:

sudo apt-get install ffmpeg

安装

全局安装（推荐）

npm install -g @yeah126139163/video-merger-cli

本地开发

# 克隆项目
git clone <repository-url>
cd vvm

# 安装依赖
npm install

# 构建项目
npm run build

# 链接到全局
npm link

快速开始

1. 合并两个视频

vvm merge video1.mp4 video2.mp4 output.mp4

将 video2.mp4 合并到 video1.mp4 的结尾，输出为 output.mp4。

参数说明：

• <video1>: 第一个视频文件路径
• <video2>: 第二个视频文件路径
• [output]: 输出文件路径（默认：output.mp4）
• -p, --position <position>: 合并位置，start 或 end（默认：end）

示例：

# 合并到开头
vvm merge video1.mp4 video2.mp4 output.mp4 -p start

# 合并到结尾（默认）
vvm merge video1.mp4 video2.mp4 output.mp4 -p end

2. 批量处理视频

vvm batch ./videos -i intro.mp4 -o outro.mp4 -d output

批量处理 ./videos 目录下的所有视频，为每个视频添加片头 intro.mp4 和片尾 outro.mp4，输出到 output 目录。

参数说明：

• [inputDir]: 输入目录路径
• -i, --intro <path>: 片头视频路径
• -o, --outro <path>: 片尾视频路径
• -d, --dir <path>: 输出目录路径（默认：输入目录/output）
• -c, --config <path>: 配置文件路径（使用配置文件时优先）

示例：

# 只添加片头
vvm batch ./videos -i intro.mp4 -d output

# 只添加片尾
vvm batch ./videos -o outro.mp4 -d output

# 同时添加片头和片尾
vvm batch ./videos -i intro.mp4 -o outro.mp4 -d output

3. 使用配置文件批量处理

# 创建配置文件模板
vvm init -f my-config.json

# 使用配置文件批量处理
vvm batch -c my-config.json

配置文件说明

配置文件使用 JSON 格式，提供更灵活的批量处理规则。

目录结构建议

建议按照以下结构组织项目文件：

your-project/
├── assets/              # 素材目录
│   ├── intro.mp4       # 片头视频
│   ├── outro.mp4       # 片尾视频
│   └── watermark.png   # 水印图片（可选）
├── videos/             # 待处理的视频目录
│   ├── video1.mp4
│   └── video2.mp4
├── output/             # 输出目录（自动创建）
├── vvm.config.json     # 配置文件
└── README.md

配置文件结构

{
  "materials": {
    "intro": {
      "path": "./assets/intro.mp4",
      "enabled": true
    },
    "outro": {
      "path": "./assets/outro.mp4",
      "enabled": true
    },
    "watermark": {
      "path": "./assets/watermark.png",
      "enabled": false
    }
  },
  "batchRules": [
    {
      "pattern": "*.mp4",
      "applyIntro": true,
      "applyOutro": true,
      "outputDir": "./output"
    },
    {
      "pattern": "special_*.mp4",
      "applyIntro": false,
      "applyOutro": true,
      "outputDir": "./output/special"
    }
  ],
  "output": {
    "format": "mp4",
    "codec": "libx264",
    "quality": "high"
  }
}

配置项说明

materials（素材配置）

• intro: 片头视频

  • path: 片头文件路径
  • enabled: 是否启用（true/false）

• outro: 片尾视频

  • path: 片尾文件路径
  • enabled: 是否启用（true/false）

• watermark: 水印图片（预留功能，暂未实现）

  • path: 水印文件路径
  • enabled: 是否启用（true/false）

batchRules（批量规则）

数组形式，支持多个规则。每个规则包含：

• pattern: 文件匹配模式（支持 glob 语法）

  • *.mp4: 匹配所有 mp4 文件
  • special_*.mp4: 匹配以 special_ 开头的 mp4 文件
  • **/*.mp4: 递归匹配所有子目录的 mp4 文件

• applyIntro: 是否应用片头（true/false）

• applyOutro: 是否应用片尾（true/false）

• outputDir: 输出目录路径

output（输出配置）

• format: 输出格式（如：mp4）
• codec: 编码器（如：libx264）
• quality: 质量设置（如：high, medium, low）

配置文件示例

示例 1：简单批量处理

{
  "materials": {
    "intro": {
      "path": "./assets/intro.mp4",
      "enabled": true
    },
    "outro": {
      "path": "./assets/outro.mp4",
      "enabled": true
    }
  },
  "batchRules": [
    {
      "pattern": "*.mp4",
      "applyIntro": true,
      "applyOutro": true,
      "outputDir": "./output"
    }
  ],
  "output": {
    "format": "mp4",
    "codec": "libx264",
    "quality": "high"
  }
}

示例 2：多规则处理

{
  "materials": {
    "intro": {
      "path": "./assets/intro.mp4",
      "enabled": true
    },
    "outro": {
      "path": "./assets/outro.mp4",
      "enabled": true
    }
  },
  "batchRules": [
    {
      "pattern": "*.mp4",
      "applyIntro": true,
      "applyOutro": true,
      "outputDir": "./output"
    },
    {
      "pattern": "preview_*.mp4",
      "applyIntro": false,
      "applyOutro": false,
      "outputDir": "./output/preview"
    },
    {
      "pattern": "final_*.mp4",
      "applyIntro": true,
      "applyOutro": true,
      "outputDir": "./output/final"
    }
  ],
  "output": {
    "format": "mp4",
    "codec": "libx264",
    "quality": "high"
  }
}

命令参考

vvm merge

合并两个视频文件。

vvm merge <video1> <video2> [output] [options]

选项：

• -p, --position <position>: 合并位置（start/end），默认：end

示例：

vvm merge video1.mp4 video2.mp4 merged.mp4
vvm merge video1.mp4 video2.mp4 merged.mp4 -p start

vvm batch

批量处理目录下的视频文件。

vvm batch [inputDir] [options]

选项：

• -i, --intro <path>: 片头视频路径
• -o, --outro <path>: 片尾视频路径
• -d, --dir <path>: 输出目录路径
• -c, --config <path>: 配置文件路径

示例：

vvm batch ./videos -i intro.mp4 -d output
vvm batch ./videos -o outro.mp4 -d output
vvm batch ./videos -i intro.mp4 -o outro.mp4 -d output
vvm batch -c config.json

vvm init

创建配置文件模板。

vvm init [options]

选项：

• -f, --file <path>: 配置文件路径，默认：vvm.config.json

示例：

vvm init
vvm init -f my-config.json

vvm --help

显示帮助信息。

vvm --help
vvm merge --help
vvm batch --help

vvm --version

显示版本信息。

vvm --version

使用场景

场景 1：为视频添加统一片头

vvm batch ./my_videos -i ./assets/intro.mp4 -d ./output

场景 2：为视频添加片尾

vvm batch ./my_videos -o ./assets/outro.mp4 -d ./output

场景 3：为不同类型的视频应用不同规则

使用配置文件 config.json：

{
  "materials": {
    "intro": {
      "path": "./assets/intro.mp4",
      "enabled": true
    },
    "outro": {
      "path": "./assets/outro.mp4",
      "enabled": true
    }
  },
  "batchRules": [
    {
      "pattern": "tutorial_*.mp4",
      "applyIntro": true,
      "applyOutro": true,
      "outputDir": "./output/tutorials"
    },
    {
      "pattern": "demo_*.mp4",
      "applyIntro": true,
      "applyOutro": false,
      "outputDir": "./output/demos"
    }
  ],
  "output": {
    "format": "mp4",
    "codec": "libx264",
    "quality": "high"
  }
}

执行：

vvm batch -c config.json

场景 4：合并两个视频

vvm merge part1.mp4 part2.mp4 full_video.mp4

工作原理

1. 视频合并：使用 FFmpeg 的 concat 功能将两个视频合并为一个
2. 批量处理：使用 glob 模式匹配文件，逐个处理
3. 片头/片尾：通过控制合并顺序实现（添加到开头或结尾）
4. 临时文件：同时添加片头和片尾时，会创建临时文件进行中间处理
5. 统一编码参数：在合并前，系统会自动将所有视频重新编码为统一的参数（分辨率、帧率、编码格式等），确保视频兼容性和播放质量
6. 时间戳修复：使用 -fflags +genpts 和 -avoid_negative_ts 参数修复视频时间戳问题，支持拖动进度条
7. 输出文件命名：批量处理时，输出文件名与原文件名保持一致，仅扩展名统一为 .mp4。例如：video1.mov 处理后输出为 video1.mp4

注意事项

1. FFmpeg 要求：必须安装 FFmpeg 并添加到系统环境变量
2. 文件路径：建议使用绝对路径，或确保相对路径正确
3. 输出目录：输出目录不存在时会自动创建
4. 文件格式：建议使用相同的视频格式和编码器
5. 临时文件：处理完成后会自动删除临时文件
6. 磁盘空间：确保有足够的磁盘空间存储输出文件
7. 视频编码：系统会自动统一视频编码参数，处理时间可能较长
8. 播放器兼容性：生成的视频支持所有主流播放器（VLC、Windows Media Player、PopPlayer 等）
9. 进度条支持：生成的视频支持拖动进度条和时间跳转

故障排除

问题 1：提示 "FFmpeg not found"

解决方案：

• 检查 FFmpeg 是否已安装：ffmpeg -version
• 确保 FFmpeg 已添加到系统环境变量

问题 2：合并后的视频质量下降

解决方案：

• 系统会自动统一编码参数，确保质量
• 如果仍然不满意，可以调整源视频的质量设置

问题 3：批量处理速度慢

解决方案：

• 由于需要重新编码视频，处理时间较长是正常的
• 减少同时处理的视频数量
• 确保系统有足够的 CPU 和内存资源

问题 4：某些视频无法合并

解决方案：

• 系统会自动统一编码参数，大多数视频都能正常合并
• 如果仍然失败，使用 FFprobe 检查视频信息：ffprobe -i video.mp4
• 确保视频文件没有损坏

问题 5：合并后的视频无法拖动进度条

解决方案：

• 系统已自动修复时间戳问题，支持拖动进度条
• 如果仍然有问题，请尝试使用 VLC 播放器
• 确保视频文件已完全生成（检查文件大小是否正常）

问题 6：合并后的视频画面不显示

解决方案：

• 系统已统一编码参数，确保画面正常显示
• 如果仍然看不到画面，请尝试使用 VLC 或 Windows Media Player
• 检查视频文件是否完整（文件大小应该大于几 MB）

开发

项目结构

vvm/
├── bin/
│   └── vvm                  # CLI 入口文件
├── src/
│   ├── index.ts            # 主入口
│   ├── merger.ts           # 视频合并核心逻辑
│   └── batch.ts            # 批量处理逻辑
├── dist/                   # 编译输出目录
├── package.json
├── tsconfig.json
└── README.md

开发命令

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建项目
npm run build

# 链接到全局
npm link

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

1.1.0 (2026-01-07)

• 📝 优化文档，修复包名不一致问题
• 📝 添加作者信息到 package.json
• 📝 补充项目目录结构说明
• 📝 补充输出文件命名规则说明
• 🎨 改进文档结构，提高可读性

1.0.0 (2026-01-07)

• ✨ 初始版本发布
• ✅ 支持视频合并功能
• ✅ 支持批量处理
• ✅ 支持配置文件
• ✅ 支持片头/片尾独立配置
• ✅ 支持规则匹配
• 🔧 统一视频编码参数，确保合并兼容性
• 🔧 修复视频时间戳问题，支持拖动进度条
• 🔧 优化输出文件名，与原文件名保持一致
• 🔧 使用 concat demuxer 提高合并效率

联系方式

如有问题或建议，欢迎通过以下方式联系：

• 微信：w846903522
• 邮箱：[email protected]
• 个人主页：https://blog.zbztb.cn
• GitHub Issues：提交 Issue 反馈问题