内容
<div align="center">
<h1>VibeStudio</h1>
<p>无头、零运行时视频编辑，由MCP和FFMPEG驱动</p>
<p>
<a href="https://github.com/wizenheimer/vibestudio/tree/main/assets/ffmpegserver_tools.json"><strong>探索文档 »</strong></a>
</p>
</div>
VibeStudio 是一个高性能、无头视频编辑服务器，专为AI助手设计。完全使用Bash构建，基于模型上下文协议（MCP），它提供了高级的FFmpeg功能，且无需运行时依赖。
> 💡 **注意：** 请确保您的音量已打开
https://github.com/user-attachments/assets/7fe093ff-0abf-43af-b2fa-34a64ebe1fe8
它提供了强大的媒体编辑工具——视频、音频等——作为轻量级、本地的shell命令。这使其成为需要可靠、快速和可追踪的基于工具的工作流的AI代理的理想选择。
### 为什么选择VibeStudio？
- **零运行时开销** – 无需Python、Node.js或其他运行时
- **完全自包含** – 纯Bash脚本，易于检查和审计
- **无框架** – 无服务器、RPC层或粘合代码
- **MCP兼容** – 与任何支持工具调用的助手无缝集成
- **易于调试** – 透明、可追踪的CLI命令，输入/输出清晰
## 功能
### 视频操作
- **格式转换**：在视频格式之间转换（MP4、AVI、MKV、MOV等）
- **视频修剪**：以帧精确度提取视频的特定部分
- **视频合并**：无缝连接多个视频
- **视频调整大小**：为任何平台更改视频尺寸
- **字幕添加**：将字幕直接烧入视频
- **帧提取**：将视频帧导出为高质量图像
- **图像转视频**：从图像序列创建视频
- **视频滤镜**：应用专业滤镜（模糊、锐化、旋转、色彩校正）
- **缩略图生成**：自动创建预览图像
### 音频操作
- **音频提取**：从视频中提取音频轨道，支持任意格式
- **格式转换**：在音频格式之间转换（MP3、AAC、WAV、FLAC、OGG）
- **音频修剪**：精确剪切音频文件
- **音量归一化**：归一化音频级别以获得一致的播放效果
### 分析工具
- **媒体信息**：获取任意媒体文件的详细元数据
## 先决条件
1. **Bash shell**（版本4.0+）
2. **jq** 用于JSON处理
```bash
# macOS
brew install jq
# Ubuntu/Debian
sudo apt-get install jq
# CentOS/RHEL
sudo yum install jq
```
3. **FFmpeg** 带有常用编解码器
```bash
# macOS
brew install ffmpeg
# Ubuntu/Debian
sudo apt-get install ffmpeg
# CentOS/RHEL
sudo yum install ffmpeg
```
## 安装
1. **克隆仓库**
```bash
git clone https://github.com/wizenheimer/vibestudio.git
cd vibestudio
```
2. **使脚本可执行**
```bash
chmod +x ffmpegserver.sh mcpserver_core.sh
```
## 可用工具
### get_media_info
获取媒体文件的详细信息。
```json
{
"input_file": "path/to/media.mp4"
}
```
### convert_video
将视频转换为不同的格式或编解码器。
```json
{
"input_file": "input.avi",
"output_file": "output.mp4",
"codec": "h264" // 可选
}
```
### extract_audio
从视频中提取音频轨道。
```json
{
"input_file": "video.mp4",
"output_file": "audio.mp3",
"audio_format": "mp3" // 可选，默认：mp3
}
```
### trim_media
将媒体修剪为指定的持续时间。
```json
{
"input_file": "input.mp4",
"output_file": "output.mp4",
"start_time": "00:01:30",
"duration": "00:00:30"
}
```
### merge_videos
连接多个视频。
```json
{
"input_files": ["video1.mp4", "video2.mp4", "video3.mp4"],
"output_file": "merged.mp4"
}
```
### add_subtitles
将字幕烧入视频。
```json
{
"input_file": "video.mp4",
"subtitle_file": "subtitles.srt",
"output_file": "video_with_subs.mp4"
}
```
### resize_video
更改视频尺寸。
```json
{
"input_file": "input.mp4",
"output_file": "output.mp4",
"width": 1280,
"height": 720
}
```
### extract_frames
将帧提取为图像。
```json
{
"input_file": "video.mp4",
"output_pattern": "frame_%04d.png",
"fps": "1", // 可选，默认：1
"start_time": "00:00:10", // 可选
"duration": "00:00:05" // 可选
}
```
### create_video_from_images
从图像序列创建视频。
```json
{
"input_pattern": "frame_%04d.png",
"output_file": "video.mp4",
"fps": "30", // 可选，默认：30
"duration": "10" // 可选
}
```
### apply_video_filter
应用FFmpeg滤镜。
```json
{
"input_file": "input.mp4",
"output_file": "output.mp4",
"filter": "hflip,blur=5"
}
```
### generate_thumbnail
从视频创建缩略图。
```json
{
"input_file": "video.mp4",
"output_file": "thumbnail.jpg",
"time": "00:00:05" // 可选，默认：00:00:01
}
```
### convert_audio
转换音频格式。
```json
{
"input_file": "input.wav",
"output_file": "output.mp3",
"audio_format": "mp3",
"bitrate": "320k" // 可选，默认：192k
}
```
### normalize_audio
归一化音频音量。
```json
{
"input_file": "input.mp3",
"output_file": "normalized.mp3"
}
```
## 与VS Code一起使用
1. **更新VS Code settings.json**
```json
{
"mcp": {
"servers": {
"vibestudio": {
"type": "stdio",
"command": "/absolute/path/to/vibestudio-mcp/ffmpegserver.sh",
"args": [],
"env": {}
}
}
}
}
```
2. **与GitHub Copilot Chat一起使用**
```
/mcp vibestudio get_media_info {"input_file": "video.mp4"}
/mcp vibestudio convert_video {"input_file": "input.avi", "output_file": "output.mp4"}
```
## 示例
### 示例1：转换和调整视频大小
```bash
# 将AVI转换为MP4并调整为720p
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "convert_video", "arguments": {"input_file": "movie.avi", "output_file": "movie_temp.mp4"}}, "id": 1}' | ./ffmpegserver.sh
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "resize_video", "arguments": {"input_file": "movie_temp.mp4", "output_file": "movie_720p.mp4", "width": 1280, "height": 720}}, "id": 2}' | ./ffmpegserver.sh
```
### 示例2：提取音频并归一化
```bash
# 从视频中提取音频并归一化音量
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "extract_audio", "arguments": {"input_file": "video.mp4", "output_file": "audio_raw.mp3"}}, "id": 1}' | ./ffmpegserver.sh
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "normalize_audio", "arguments": {"input_file": "audio_raw.mp3", "output_file": "audio_normalized.mp3"}}, "id": 2}' | ./ffmpegserver.sh
```
### 示例3：从视频创建GIF
```bash
# 提取帧并创建动画序列
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "extract_frames", "arguments": {"input_file": "video.mp4", "output_pattern": "frame_%04d.png", "fps": "10", "start_time": "00:00:05", "duration": "00:00:03"}}, "id": 1}' | ./ffmpegserver.sh
```
## 常用视频滤镜
以下是`apply_video_filter`工具的一些有用滤镜：
- **模糊**：`"blur=10"`（值：0-100）
- **锐化**：`"unsharp=5:5:1.0"`
- **水平翻转**：`"hflip"`
- **垂直翻转**：`"vflip"`
- **旋转90°**：`"transpose=1"`
- **旋转180°**：`"transpose=2,transpose=2"`
- **灰度**：`"colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3"`
- **亮度**：`"eq=brightness=0.1"`（-1.0至1.0）
- **对比度**：`"eq=contrast=1.5"`（0.0至2.0）
- **淡入**：`"fade=in:0:30"`（在30帧上淡入）
- **加速2倍**：`"setpts=0.5*PTS"`
- **减速2倍**：`"setpts=2.0*PTS"`
## 故障排除
### 常见问题
1. **"mcpserver_core.sh: No such file or directory"**
- 解决方案：从MCP Bash SDK存储库下载mcpserver_core.sh
- 运行：`curl -O https://raw.githubusercontent.com/wizenheimer/vibestudio/main/mcpserver_core.sh`
2. **"jq: command not found"**
- 解决方案：使用包管理器安装jq
- macOS：`brew install jq`
- Linux：`sudo apt-get install jq`
3. **"ffmpeg: command not found"**
- 解决方案：安装FFmpeg
- macOS：`brew install ffmpeg`
- Linux：`sudo apt-get install ffmpeg`
4. **权限被拒绝错误**
- 解决方案：使脚本可执行
- 运行：`chmod +x ffmpegserver.sh mcpserver_core.sh`
5. **JSON解析错误**
- 检查日志：`tail -f logs/ffmpegserver.log`
- 验证JSON：`echo '{"your": "json"}' | jq .`
### 调试模式
通过修改ffmpegserver.sh中的日志级别或检查完整日志来启用详细日志记录：
```bash
# 实时查看日志
tail -f logs/ffmpegserver.log
# 检查最后50条日志记录
tail -n 50 logs/ffmpegserver.log
```
## 健全性测试
运行这些测试以确保VibeStudio正确安装：
### 测试1：检查核心依赖项
```bash
# 检查jq是否安装
jq --version
# 预期：jq-1.6或更高
# 检查FFmpeg是否安装
ffmpeg -version
# 预期：ffmpeg版本详细信息
# 检查mcpserver_core.sh是否存在
ls -la mcpserver_core.sh
# 预期：文件应存在且具有执行权限
```
### 测试2：测试MCP服务器初始化
```bash
# 测试服务器初始化
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"clientInfo": {"name": "test"}}, "id": 1}' | ./ffmpegserver.sh | jq
# 预期：具有serverInfo和capabilities的JSON响应
```
### 测试3：列出可用工具
```bash
# 列出所有可用工具
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}' | ./ffmpegserver.sh | jq
# 预期：具有14种工具的JSON响应
```
### 测试4：测试媒体信息工具（带有示例文件）
```bash
# 首先，创建一个测试视频文件
ffmpeg -f lavfi -i testsrc=duration=1:size=320x240:rate=30 -f lavfi -i sine=frequency=1000:duration=1 test_video.mp4
# 测试get_media_info工具
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_media_info", "arguments": {"input_file": "test_video.mp4"}}, "id": 3}' | ./ffmpegserver.sh
# 预期：具有媒体信息（时长、编解码器、分辨率）的JSON响应
```
### 测试5：测试错误处理
```bash
# 使用不存在的文件进行测试
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_media_info", "arguments": {"input_file": "non_existent.mp4"}}, "id": 4}' | ./ffmpegserver.sh
# 预期：具有“文件未找到”消息的JSON错误响应
# 使用无效方法进行测试
echo '{"jsonrpc": "2.0", "method": "invalid_method", "id": 5}' | ./ffmpegserver.sh
# 预期：具有代码-32601的JSON错误响应
```
### 测试6：检查日志
```bash
# 检查日志是否正常工作
tail -n 20 logs/ffmpegserver.log
# 预期：上述所有测试命令的日志记录
```
### 测试7：完整集成测试
```bash
# 创建一个简单的测试视频并处理它
ffmpeg -f lavfi -i testsrc=duration=3:size=640x480:rate=30 -f lavfi -i sine=frequency=1000:duration=3 test_source.mp4
# 提取1秒的片段
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "trim_media", "arguments": {"input_file": "test_source.mp4", "output_file": "test_trimmed.mp4", "start_time": "00:00:01", "duration": "00:00:01"}}, "id": 6}' | ./ffmpegserver.sh
# 检查输出是否创建
ls -la test_trimmed.mp4
# 预期：文件应存在且大小 > 0
# 清理测试文件
rm -f test_video.mp4 test_source.mp4 test_trimmed.mp4
```
## 所需文件结构
您的VibeStudio安装应具有以下结构：
```
vibestudio-mcp/
├── mcpserver_core.sh # 核心MCP服务器（来自MCP Bash SDK）
├── ffmpegserver.sh # VibeStudio主脚本
├── assets/
│ ├── ffmpegserver_config.json
│ └── ffmpegserver_tools.json
└── logs/
└── ffmpegserver.log # 自动创建
```
## 限制
- 无实时流媒体支持
- 顺序处理仅（无并行操作）
- 文件路径必须从脚本位置可访问
- 大文件可能需要大量处理时间
- 一些高级FFmpeg功能需要手动筛选器构造
## 致谢
- [MCP Server Bash SDK](https://github.com/muthuishere/mcp-server-bash-sdk)
- [FFmpeg](https://ffmpeg.org/)
## 贡献
VibeStudio 欢迎贡献！请随意提交问题和增强请求。
## 许可证
该项目在MIT许可证下获得许可，遵循原始MCP服务器Bash SDK。
