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
   

💻 使用示例

基礎用法

在 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

📚 詳細文檔

可用工具

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

常用視頻濾鏡

以下是 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"

🔧 技術細節

常見問題及解決方法

"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

"jq: command not found"

• 解決方案：使用包管理器安裝 jq。
• macOS：brew install jq
• Linux：sudo apt-get install jq

"ffmpeg: command not found"

• 解決方案：安裝 FFmpeg。
• macOS：brew install ffmpeg
• Linux：sudo apt-get install ffmpeg

權限拒絕錯誤

• 解決方案：使腳本可執行。
• 執行命令：chmod +x ffmpegserver.sh mcpserver_core.sh

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 功能需要手動構建濾鏡。

📄 許可證

本項目遵循 MIT 許可證，與原始的 MCP Server Bash SDK 保持一致。

鳴謝

• MCP Server Bash SDK
• FFmpeg

貢獻

VibeStudio 歡迎貢獻！請隨時提交問題和改進請求。