Vibestudio

🚀 VibeStudio

VibeStudio 是一款专为 AI 助手设计的高性能无头视频编辑服务器。它完全基于 Bash 构建，依托模型上下文协议（MCP），无需运行时依赖即可提供强大的 FFmpeg 功能。

🚀 快速开始

VibeStudio 是一个基于模型上下文协议（MCP）的高性能无头视频编辑服务器。它完全用 Bash 编写，提供高级的 FFmpeg 功能，且无需运行时依赖。

你可以通过以下链接探索文档。

⚠️ 重要提示

请注意！确保已开启音量。

点击查看视频

它将强大的媒体编辑工具（视频、音频等）以轻量级的本地 shell 命令形式提供，非常适合需要可靠、快速且可追溯的基于工具的工作流的 AI 代理。

✨ 主要特性

视频操作

• 格式转换：支持在多种视频格式（如 MP4、AVI、MKV、MOV 等）之间进行转换。
• 视频裁剪：能够以帧级精度提取视频的特定部分。
• 视频合并：可无缝拼接多个视频。
• 视频缩放：能为任何平台更改视频尺寸。
• 添加字幕：可直接将字幕嵌入视频。
• 帧提取：将视频帧导出为高质量图像。
• 图像转视频：从图像序列创建视频。
• 视频滤镜：应用专业滤镜（模糊、锐化、旋转、色彩校正等）。
• 缩略图生成：自动创建预览图像。

音频操作

• 音频提取：从任何格式的视频中提取音轨。
• 格式转换：支持在多种音频格式（如 MP3、AAC、WAV、FLAC、OGG）之间进行转换。
• 音频裁剪：精确裁剪音频文件。
• 音量归一化：归一化音频电平以实现一致的播放效果。

分析工具

• 媒体信息：获取任何媒体文件的详细元数据。

📦 安装指南

前提条件

1. Bash shell（版本 4.0 及以上）
2. jq 用于 JSON 处理

   # macOS
   brew install jq
   
   # Ubuntu/Debian
   sudo apt-get install jq
   
   # CentOS/RHEL
   sudo yum install jq
   

3. FFmpeg 及常用编解码器

   # macOS
   brew install ffmpeg
   
   # Ubuntu/Debian
   sudo apt-get install ffmpeg
   
   # CentOS/RHEL
   sudo yum install ffmpeg
   

安装步骤

1. 克隆仓库

   git clone https://github.com/wizenheimer/vibestudio.git
   cd vibestudio
   

2. 使脚本可执行

   chmod +x ffmpegserver.sh mcpserver_core.sh
   

💻 使用示例

可用工具

get_media_info

获取媒体文件的详细信息。

{
  "input_file": "path/to/media.mp4"
}

convert_video

将视频转换为不同的格式或编解码器。

{
  "input_file": "input.avi",
  "output_file": "output.mp4",
  "codec": "h264" // 可选
}

extract_audio

从视频中提取音轨。

{
  "input_file": "video.mp4",
  "output_file": "audio.mp3",
  "audio_format": "mp3" // 可选，默认值：mp3
}

trim_media

将视频或音频裁剪到指定的时长。

{
  "input_file": "input.mp4",
  "output_file": "output.mp4",
  "start_time": "00:01:30",
  "duration": "00:00:30"
}

merge_videos

拼接多个视频。

{
  "input_files": ["video1.mp4", "video2.mp4", "video3.mp4"],
  "output_file": "merged.mp4"
}

add_subtitles

将字幕嵌入视频。

{
  "input_file": "video.mp4",
  "subtitle_file": "subtitles.srt",
  "output_file": "video_with_subs.mp4"
}

resize_video

更改视频尺寸。

{
  "input_file": "input.mp4",
  "output_file": "output.mp4",
  "width": 1280,
  "height": 720
}

extract_frames

将帧提取为图像。

{
  "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

从图像序列创建视频。

{
  "input_pattern": "frame_%04d.png",
  "output_file": "video.mp4",
  "fps": "30", // 可选，默认值：30
  "duration": "10" // 可选
}

apply_video_filter

应用 FFmpeg 滤镜。

{
  "input_file": "input.mp4",
  "output_file": "output.mp4",
  "filter": "hflip,blur=5"
}

generate_thumbnail

从视频创建缩略图。

{
  "input_file": "video.mp4",
  "output_file": "thumbnail.jpg",
  "time": "00:00:05" // 可选，默认值：00:00:01
}

convert_audio

转换音频格式。

{
  "input_file": "input.wav",
  "output_file": "output.mp3",
  "audio_format": "mp3",
  "bitrate": "320k" // 可选，默认值：192k
}

normalize_audio

归一化音频音量。

{
  "input_file": "input.mp3",
  "output_file": "normalized.mp3"
}

在 VS Code 中使用

1. 更新 VS Code 的 settings.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：转换并缩放视频

# 将 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：提取音频并归一化

# 从视频中提取音频并归一化音量
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

# 提取帧并创建动画序列
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 中的日志级别或查看完整日志来启用详细日志记录：

# 实时查看日志
tail -f logs/ffmpegserver.log

# 查看最后 50 条日志记录
tail -n 50 logs/ffmpegserver.log

健全性测试

运行以下测试以确保 VibeStudio 已正确安装：

测试 1：检查核心依赖项

# 检查 jq 是否安装
jq --version
# 预期结果：jq-1.6 或更高版本

# 检查 FFmpeg 是否安装
ffmpeg -version
# 预期结果：ffmpeg 版本详细信息

# 检查 mcpserver_core.sh 是否存在
ls -la mcpserver_core.sh
# 预期结果：文件应存在且具有执行权限

测试 2：测试 MCP 服务器初始化

# 测试服务器初始化
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"clientInfo": {"name": "test"}}, "id": 1}' | ./ffmpegserver.sh | jq
# 预期结果：包含 serverInfo 和 capabilities 的 JSON 响应

测试 3：列出可用工具

# 列出所有可用工具
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}' | ./ffmpegserver.sh | jq
# 预期结果：包含 14 个工具数组的 JSON 响应

测试 4：测试媒体信息工具（使用示例文件）

# 首先，创建一个测试视频文件
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：测试错误处理

# 使用不存在的文件进行测试
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_media_info", "arguments": {"input_file": "non_existent.mp4"}}, "id": 4}' | ./ffmpegserver.sh
# 预期结果：包含 "File not found" 消息的 JSON 错误响应

# 使用无效方法进行测试
echo '{"jsonrpc": "2.0", "method": "invalid_method", "id": 5}' | ./ffmpegserver.sh
# 预期结果：代码为 -32601 的 JSON 错误响应

测试 6：检查日志

# 检查日志是否正常工作
tail -n 20 logs/ffmpegserver.log
# 预期结果：上述所有测试命令的日志条目

测试 7：完整集成测试

# 创建一个简单的测试视频并进行处理
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
• FFmpeg

贡献

VibeStudio 欢迎贡献！请随时提交问题和改进请求。

📄 许可证

本项目遵循 MIT 许可证，与原始的 MCP Server Bash SDK 保持一致。