Project Files
README
🎬 Local Video Tools for LM Studio
Reliable video processing for your local AI.
Inspect, trim, convert, and manage long-running FFmpeg jobs directly from LM Studio — locally, with hardware acceleration, and without holding one AI tool call open for the duration of a video encode.
Try the prompts · Install · How it works · Latest release · Roadmap
v0.1.3 Early Preview is out. This presentation-focused release adds a clearer plugin icon, direct LM Studio Hub installation guidance, and sharper positioning around reliable background video processing. Runtime behavior is unchanged from v0.1.2.
What this is: a reliable local execution layer for concrete video operations. The model decides what operation to request; FFmpeg does the actual media processing locally.
💬 Try these prompts
Attach a video in LM Studio and talk to it naturally:
| What you want | Ask your local model |
|---|---|
| 🎥 Inspect a video | Inspect this video and tell me its codec, resolution, duration and frame rate. |
| ✂️ Cut without quality loss | Cut seconds 2 through 10 from this video without changing quality. Use the fastest lossless method available. |
| 🎯 Make an exact cut | Create an accurate clip from exactly 2.0 seconds to 10.0 seconds. |
| ⚡ Convert with hardware acceleration | Convert this video to a 1920px-wide H.264 MP4 using hardware acceleration if available. |
| 📈 Check a long-running encode | Check the status of that video conversion. |
| 🛑 Cancel a job | Cancel that video conversion. |
No FFmpeg command memorization. No separate MCP configuration. The model chooses the right native tool and FFmpeg does the work locally.
🚀 What it can do
🎯 Why this exists
A local model can understand what you want to do with a video, but synchronous AI tool calls are a poor fit for real media-processing workloads.
A short metadata lookup or stream-copy trim can finish quickly. A 4K HEVC transcode can take much longer than the tool call is allowed to stay open, even though FFmpeg itself is still doing perfectly valid work on the local machine.
Local Video Tools is built around that concrete execution problem. Short operations run directly; expensive operations become background FFmpeg jobs that return a job ID immediately so the model can check progress, cancel work, and retrieve the result later.
The result is a video tool surface designed for local models, not just a thin FFmpeg wrapper.
✅ Tested on a real 4K HEVC workflow
The v0.1 release series was exercised against real 3840×2160 HEVC/H.265 MOV media on Apple Silicon.
| Workflow | Result |
|---|---|
| Inspect 4K HEVC metadata with ffprobe | ✅ Validated |
| Lossless stream-copy clip | ✅ Validated |
| Accurate background clip | ✅ Validated |
| 4K HEVC → 1080p H.264 | ✅ Validated |
Apple h264_videotoolbox acceleration | ✅ Validated |
| Background job progress/status | ✅ Validated |
| Job cancellation and process cleanup | ✅ Validated |
One of the key tests was simply asking:
Convert this video to a 1920px-wide H.264 MP4 using hardware acceleration if available.
Local Video Tools detected h264_videotoolbox, started FFmpeg as a background job, returned control to the model immediately, and let the model check the conversion until it completed.
That workflow is the core reason this project exists.
⚡ Quick start
Install from LM Studio Hub
-
Install FFmpeg and ffprobe locally. On macOS:
-
Open Local Video Tools on LM Studio Hub and select Run in LM Studio.
-
Enable Local Video Tools under LM Studio Integrations.
Local Video Tools is a native LM Studio plugin. You do not need to clone the repository, install Node.js, or add it to
mcp.jsonwhen installing from the Hub.
Develop from source
Requirements
- LM Studio with native TypeScript plugin support
- Node.js 22 or newer
- The LM Studio
lmsCLI available on yourPATH - FFmpeg and ffprobe installed locally
Clone and test:
Install/run the development build in LM Studio:
Then enable Local Video Tools under LM Studio Integrations.
🧰 Model-visible tools
The tool surface is deliberately small so local models have fewer overlapping choices.
| Tool | Purpose | Execution |
|---|---|---|
inspect_video | Read video/audio metadata and FFmpeg capabilities | Foreground |
clip_video | Fast lossless or accurate clipping | Foreground or background |
convert_video | Convert to H.264/HEVC and optionally resize | Background |
video_job_status | Read progress, speed, result, and errors | Foreground |
cancel_video_job | Cancel a running FFmpeg job | Foreground |
🧠 How it works
The language model does not encode the video itself. The model decides what operation to request; FFmpeg does the actual media processing locally.
⚡ Hardware acceleration
When hardware acceleration is enabled, Local Video Tools probes the local FFmpeg build and prefers a supported hardware encoder.
| Platform / hardware | Preferred path |
|---|---|
| Apple Silicon / macOS | VideoToolbox |
| NVIDIA GPU | NVENC |
| Intel | Quick Sync Video |
| Other / unsupported | CPU fallback |
Supported encoder detection includes h264_videotoolbox, hevc_videotoolbox, h264_nvenc, hevc_nvenc, h264_qsv, and hevc_qsv.
Software encoding is selected when the FFmpeg build does not advertise a suitable hardware encoder. If an advertised encoder fails at runtime because the hardware or driver is unavailable, the job reports the FFmpeg error; automatic software retry is planned.
🔒 Local-first by design
Local Video Tools is designed for local media workflows:
- FFmpeg and ffprobe run on your machine.
- The plugin itself does not upload videos to a remote video-processing service.
- Attached videos are staged inside the LM Studio working directory.
- Arbitrary external filesystem paths are disabled by default.
- Input paths are canonicalized, and symlinks cannot escape the working-directory boundary.
- Runtime input, output, and job directories reject symlinked path segments.
- FFmpeg will not overwrite an existing output file or follow an existing output symlink.
Your chosen language model, LM Studio configuration, and other integrations can have their own privacy characteristics. These guarantees apply specifically to Local Video Tools' video-processing behavior.
⚙️ Configuration
| Setting | Default | Purpose |
|---|---|---|
| FFmpeg path | Auto-detect | Override the ffmpeg executable |
| ffprobe path | Auto-detect | Override the ffprobe executable |
| Output directory | local-video-tools/outputs | Working-directory-relative output location |
| Hardware acceleration | auto | Prefer supported hardware encoders |
| External paths | Disabled | Allow files outside the LM Studio working directory |
| Maximum job duration | 2 hours | Upper bound for long-running FFmpeg work |
🖥️ Platform status
macOS / Apple Silicon is the best-tested environment for the v0.1 release series.
Windows/Linux discovery and NVIDIA/Intel hardware encoder support are implemented, but they need broader real-world testing across different FFmpeg builds and hardware configurations.
If you test Local Video Tools on another platform, bug reports and validation feedback are very welcome.
🗺️ What's next
Potential next steps include:
- batch video inspection
- frame extraction
- audio extraction
- dedicated resize workflows
- video concatenation
- overlays and subtitles
- better keyframe-aware clipping guidance
- broader acceleration testing
- expanded integration coverage
See the full roadmap.
🤝 Contributing
Contributions, focused feature proposals, and reproducible bug reports are welcome.
Please read CONTRIBUTING.md before opening a pull request. Security-sensitive issues should follow SECURITY.md rather than being reported publicly.
🎬 Reliable video processing for your local AI.
Download the latest release · Report a bug · Request a feature
MIT licensed.