Vibestudio

🚀 VibeStudio

Headless, zero-runtime video editing powered by MCP and FFMPEG, designed for high - performance video editing tasks for AI assistants.

🚀 Quick Start

VibeStudio is a high - performance, headless video editing server tailored for AI assistants. Written entirely in Bash and based on the Model Context Protocol (MCP), it offers advanced FFmpeg capabilities without any runtime dependencies.

⚠️ Important Note

Heads up! Make sure your volume’s on

Video Link

It exposes powerful media editing tools for video, audio, etc., as lightweight, local shell commands. This makes it a perfect fit for AI agents that need reliable, fast, and traceable tool - based workflows.

✨ Features

Video Operations

• Format Conversion: Convert between various video formats such as MP4, AVI, MKV, MOV, etc.
• Video Trimming: Extract specific parts of videos with frame - accurate precision.
• Video Merging: Seamlessly concatenate multiple videos.
• Video Resizing: Adjust video dimensions for different platforms.
• Subtitle Addition: Burn subtitles directly into videos.
• Frame Extraction: Export video frames as high - quality images.
• Image to Video: Create videos from image sequences.
• Video Filters: Apply professional filters like blur, sharpen, rotate, and color correction.
• Thumbnail Generation: Automatically create preview images.

Audio Operations

• Audio Extraction: Extract audio tracks from videos in any format.
• Format Conversion: Convert between audio formats such as MP3, AAC, WAV, FLAC, OGG.
• Audio Trimming: Precisely cut audio files.
• Volume Normalization: Normalize audio levels for consistent playback.

Analysis Tools

• Media Information: Obtain detailed metadata about any media file.

📦 Installation

Prerequisites

1. Bash shell (version 4.0+)
2. jq for JSON processing

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

3. FFmpeg with common codecs

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

Steps

1. Clone the repository

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

2. Make scripts executable

   chmod +x ffmpegserver.sh mcpserver_core.sh
   

💻 Usage Examples

Available Tools

get_media_info

Get detailed information about a media file.

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

convert_video

Convert video to different format or codec.

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

extract_audio

Extract audio track from video.

{
  "input_file": "video.mp4",
  "output_file": "audio.mp3",
  "audio_format": "mp3" // optional, default: mp3
}

trim_media

Trim video or audio to specified duration.

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

merge_videos

Concatenate multiple videos.

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

add_subtitles

Burn subtitles into video.

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

resize_video

Change video dimensions.

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

extract_frames

Extract frames as images.

{
  "input_file": "video.mp4",
  "output_pattern": "frame_%04d.png",
  "fps": "1", // optional, default: 1
  "start_time": "00:00:10", // optional
  "duration": "00:00:05" // optional
}

create_video_from_images

Create video from image sequence.

{
  "input_pattern": "frame_%04d.png",
  "output_file": "video.mp4",
  "fps": "30", // optional, default: 30
  "duration": "10" // optional
}

apply_video_filter

Apply FFmpeg filters.

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

generate_thumbnail

Create thumbnail from video.

{
  "input_file": "video.mp4",
  "output_file": "thumbnail.jpg",
  "time": "00:00:05" // optional, default: 00:00:01
}

convert_audio

Convert audio format.

{
  "input_file": "input.wav",
  "output_file": "output.mp3",
  "audio_format": "mp3",
  "bitrate": "320k" // optional, default: 192k
}

normalize_audio

Normalize audio volume.

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

Usage with VS Code

1. Update VS Code settings.json

   {
     "mcp": {
       "servers": {
         "vibestudio": {
           "type": "stdio",
           "command": "/absolute/path/to/vibestudio-mcp/ffmpegserver.sh",
           "args": [],
           "env": {}
         }
       }
     }
   }
   

2. Use with GitHub Copilot Chat

   /mcp vibestudio get_media_info {"input_file": "video.mp4"}
   /mcp vibestudio convert_video {"input_file": "input.avi", "output_file": "output.mp4"}
   

Specific Examples

Example 1: Convert and Resize Video

# Convert AVI to MP4 and resize to 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

Example 2: Extract Audio and Normalize

# Extract audio from video and normalize volume
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

Example 3: Create GIF from Video

# Extract frames and create animated sequence
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

📚 Documentation

Common Video Filters

Here are some useful filters for the apply_video_filter tool:

• Blur: "blur=10" (value: 0 - 100)
• Sharpen: "unsharp=5:5:1.0"
• Horizontal Flip: "hflip"
• Vertical Flip: "vflip"
• Rotate 90°: "transpose=1"
• Rotate 180°: "transpose=2,transpose=2"
• Grayscale: "colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3"
• Brightness: "eq=brightness=0.1" (-1.0 to 1.0)
• Contrast: "eq=contrast=1.5" (0.0 to 2.0)
• Fade In: "fade=in:0:30" (fade in over 30 frames)
• Speed Up 2x: "setpts=0.5*PTS"
• Slow Down 2x: "setpts=2.0*PTS"

Troubleshooting

Common Issues

1. "mcpserver_core.sh: No such file or directory"
   • Solution: Download mcpserver_core.sh from the MCP Bash SDK repository
   • Run: curl -O https://raw.githubusercontent.com/wizenheimer/vibestudio/main/mcpserver_core.sh
2. "jq: command not found"
   • Solution: Install jq using your package manager
   • macOS: brew install jq
   • Linux: sudo apt-get install jq
3. "ffmpeg: command not found"
   • Solution: Install FFmpeg
   • macOS: brew install ffmpeg
   • Linux: sudo apt-get install ffmpeg
4. Permission denied errors
   • Solution: Make scripts executable
   • Run: chmod +x ffmpegserver.sh mcpserver_core.sh
5. JSON parsing errors
   • Check logs: tail -f logs/ffmpegserver.log
   • Validate JSON: echo '{"your": "json"}' | jq .

Debug Mode

Enable verbose logging by modifying the log level in ffmpegserver.sh or checking the full logs:

# Watch logs in real-time
tail -f logs/ffmpegserver.log

# Check last 50 log entries
tail -n 50 logs/ffmpegserver.log

Sanity Tests

Run these tests to ensure VibeStudio is properly installed:

Test 1: Check Core Dependencies

# Check if jq is installed
jq --version
# Expected: jq-1.6 or higher

# Check if FFmpeg is installed
ffmpeg -version
# Expected: ffmpeg version details

# Check if mcpserver_core.sh exists
ls -la mcpserver_core.sh
# Expected: File should exist with execute permissions

Test 2: Test MCP Server Initialization

# Test server initialization
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"clientInfo": {"name": "test"}}, "id": 1}' | ./ffmpegserver.sh | jq
# Expected: JSON response with serverInfo and capabilities

Test 3: List Available Tools

# List all available tools
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}' | ./ffmpegserver.sh | jq
# Expected: JSON response with array of 14 tools

Test 4: Test Media Info Tool (with sample file)

# First, create a test video file
ffmpeg -f lavfi -i testsrc=duration=1:size=320x240:rate=30 -f lavfi -i sine=frequency=1000:duration=1 test_video.mp4

# Test get_media_info tool
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_media_info", "arguments": {"input_file": "test_video.mp4"}}, "id": 3}' | ./ffmpegserver.sh
# Expected: JSON response with media information (duration, codecs, resolution)

Test 5: Test Error Handling

# Test with non-existent file
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_media_info", "arguments": {"input_file": "non_existent.mp4"}}, "id": 4}' | ./ffmpegserver.sh
# Expected: JSON error response with "File not found" message

# Test with invalid method
echo '{"jsonrpc": "2.0", "method": "invalid_method", "id": 5}' | ./ffmpegserver.sh
# Expected: JSON error response with code -32601

Test 6: Check Logs

# Check if logging is working
tail -n 20 logs/ffmpegserver.log
# Expected: Log entries for all the above test commands

Test 7: Full Integration Test

# Create a simple test video and process it
ffmpeg -f lavfi -i testsrc=duration=3:size=640x480:rate=30 -f lavfi -i sine=frequency=1000:duration=3 test_source.mp4

# Extract a 1-second clip
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

# Check if output was created
ls -la test_trimmed.mp4
# Expected: File should exist with size > 0

# Clean up test files
rm -f test_video.mp4 test_source.mp4 test_trimmed.mp4

Required Files Structure

Your VibeStudio installation should have this structure:

vibestudio-mcp/
├── mcpserver_core.sh        # Core MCP server (from MCP Bash SDK)
├── ffmpegserver.sh          # VibeStudio main script
├── assets/
│   ├── ffmpegserver_config.json
│   └── ffmpegserver_tools.json
└── logs/
    └── ffmpegserver.log     # Created automatically

Limitations

• No real - time streaming support
• Sequential processing only (no parallel operations)
• File paths must be accessible from the script location
• Large files may take significant processing time
• Some advanced FFmpeg features require manual filter construction

Shoutout

• MCP Server Bash SDK
• FFmpeg

Contributing

VibeStudio welcomes contributions! Please feel free to submit issues and enhancement requests.

📄 License

This project is licensed under the MIT License, following the original MCP Server Bash SDK.