VibeStudio is a high-performance, headless video editing server designed for AI assistants. Built entirely in Bash and based on the Model Context Protocol (MCP), it delivers advanced FFmpeg functionality with zero runtime dependencies.

💡 Note: Heads up! Make sure your volume’s on

https://github.com/user-attachments/assets/7fe093ff-0abf-43af-b2fa-34a64ebe1fe8

It exposes powerful media editing tools—video, audio, and more—as lightweight, local shell commands. This makes it ideal for AI agents needing reliable, fast, and traceable tool-based workflows.

Why Choose VibeStudio?

• Zero runtime overhead – no Python, Node.js, or other runtimes required
• Fully self-contained – pure Bash scripts, easy to inspect and audit
• No frameworks – no servers, RPC layers, or glue code
• MCP-compatible – integrates seamlessly with any assistant that supports tool calls
• Debug-friendly – transparent, traceable CLI commands with clear inputs/outputs

Features

Video Operations

• Format Conversion: Convert between video formats (MP4, AVI, MKV, MOV, etc.)
• Video Trimming: Extract specific portions of videos with frame-accurate precision
• Video Merging: Seamlessly concatenate multiple videos
• Video Resizing: Change video dimensions for any platform
• 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 (blur, sharpen, rotate, color correction)
• Thumbnail Generation: Create preview images automatically

Audio Operations

• Audio Extraction: Extract audio tracks from videos in any format
• Format Conversion: Convert between audio formats (MP3, AAC, WAV, FLAC, OGG)
• Audio Trimming: Cut audio files with precision
• Volume Normalization: Normalize audio levels for consistent playback

Analysis Tools

• Media Information: Get detailed metadata about any media file

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

Installation

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

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

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

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.