Content
<div align="center">
<h1>VibeStudio</h1>
<p>Headless, zero-runtime video editing powered by MCP and FFMPEG</p>
<p>
<a href="https://github.com/wizenheimer/vibestudio/tree/main/assets/ffmpegserver_tools.json"><strong>Explore the docs »</strong></a>
</p>
</div>
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
```bash
# macOS
brew install jq
# Ubuntu/Debian
sudo apt-get install jq
# CentOS/RHEL
sudo yum install jq
```
3. **FFmpeg** with common codecs
```bash
# macOS
brew install ffmpeg
# Ubuntu/Debian
sudo apt-get install ffmpeg
# CentOS/RHEL
sudo yum install ffmpeg
```
## Installation
1. **Clone the repository**
```bash
git clone https://github.com/wizenheimer/vibestudio.git
cd vibestudio
```
2. **Make scripts executable**
```bash
chmod +x ffmpegserver.sh mcpserver_core.sh
```
## Available Tools
### get_media_info
Get detailed information about a media file.
```json
{
"input_file": "path/to/media.mp4"
}
```
### convert_video
Convert video to different format or codec.
```json
{
"input_file": "input.avi",
"output_file": "output.mp4",
"codec": "h264" // optional
}
```
### extract_audio
Extract audio track from video.
```json
{
"input_file": "video.mp4",
"output_file": "audio.mp3",
"audio_format": "mp3" // optional, default: mp3
}
```
### trim_media
Trim video or audio to specified duration.
```json
{
"input_file": "input.mp4",
"output_file": "output.mp4",
"start_time": "00:01:30",
"duration": "00:00:30"
}
```
### merge_videos
Concatenate multiple videos.
```json
{
"input_files": ["video1.mp4", "video2.mp4", "video3.mp4"],
"output_file": "merged.mp4"
}
```
### add_subtitles
Burn subtitles into video.
```json
{
"input_file": "video.mp4",
"subtitle_file": "subtitles.srt",
"output_file": "video_with_subs.mp4"
}
```
### resize_video
Change video dimensions.
```json
{
"input_file": "input.mp4",
"output_file": "output.mp4",
"width": 1280,
"height": 720
}
```
### extract_frames
Extract frames as images.
```json
{
"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.
```json
{
"input_pattern": "frame_%04d.png",
"output_file": "video.mp4",
"fps": "30", // optional, default: 30
"duration": "10" // optional
}
```
### apply_video_filter
Apply FFmpeg filters.
```json
{
"input_file": "input.mp4",
"output_file": "output.mp4",
"filter": "hflip,blur=5"
}
```
### generate_thumbnail
Create thumbnail from video.
```json
{
"input_file": "video.mp4",
"output_file": "thumbnail.jpg",
"time": "00:00:05" // optional, default: 00:00:01
}
```
### convert_audio
Convert audio format.
```json
{
"input_file": "input.wav",
"output_file": "output.mp3",
"audio_format": "mp3",
"bitrate": "320k" // optional, default: 192k
}
```
### normalize_audio
Normalize audio volume.
```json
{
"input_file": "input.mp3",
"output_file": "normalized.mp3"
}
```
## Usage with VS Code
1. **Update VS Code settings.json**
```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
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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](https://github.com/muthuishere/mcp-server-bash-sdk)
- [FFmpeg](https://ffmpeg.org/)
## 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.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available