| name | hermes-editing-yt |
| description | Use when driving the hermes-editing-yt subtitle-driven auto video editor through MCP. Wraps the local Python pipeline (ffmpeg + Whisper + SRT parsing) as 11 tools (autoedit, autocut, automark, render_segments, parse_srt_text, build_segments_from_srt, whisper_transcribe, gpu_transcribe, list_videos, list_subtitles, server_info) so any MCP client (Hermes Agent, Claude Desktop, Cursor) can cut long gameplay/long-form video into highlight reels without touching ffmpeg flags. |
| version | 1.1.0 |
| author | Bernardo (hermes-editing-yt project) + black-wave (Hermes Agent) |
| license | MIT |
| metadata | {"hermes":{"tags":["video","editing","ffmpeg","whisper","mcp","hermes-editing-yt","autoedit","pipeline","subtitles","gpu"],"related_skills":["native-mcp","hermes-agent"]}} |
hermes-editing-yt Autoedit MCP Plugin
A standalone MCP server that wraps the hermes-editing-yt auto video editor — the
pipeline originally built for the Helgstr1 / MOTNH 2 / Deerclops workflow on
the G: SSD — into a clean tool surface that any MCP-speaking agent can
call. Same ffmpeg + local-Whisper logic, no hardcoded paths, no interactive
prompts.
Overview
The hermes-editing-yt pipeline is subtitle-driven: it takes a long .mp4, extracts
audio, transcribes it via local GPU Whisper (or reuses an existing .srt),
groups nearby subtitle cues into keep-segments, marks highlights from
keywords / punctuation, then optionally renders the concatenated segments
back out as a single MP4. This skill packages that pipeline as a
FastMCP 3.x server (11 tools) plus a skill_manage-style description
block that loads automatically when the tools are discovered by Hermes.
The server is pure-Python and dependency-light: fastmcp, ffmpeg,
ffprobe, faster-whisper, plus an NVIDIA GPU with working
CUDA + cuBLAS + cuDNN for the local transcription path.
When to Use
- An MCP client (Hermes Agent, Claude Desktop, Cursor, mcporter) needs to
cut a long video into a highlight reel from a transcript.
- A workflow has raw footage + an SRT and wants a deterministic,
re-runnable cut plan as JSON / CSV.
- A different agent (Codex, Claude Code, OpenCode) needs the same
autoedit pipeline without rebuilding the ffmpeg command line.
- You want a quick
list_videos / parse_srt_text /
build_segments_from_srt preview before paying for the full
ffmpeg/Whisper run.
- You have raw audio and need an SRT fast — call
gpu_transcribe directly
without going through the full pipeline.
Don't use for: semantic / visual scene selection (this pipeline is
subtitle-driven only — it doesn't read video frames); for that, layer a
vision model on top of parse_srt_text first.
Tool Reference
| Tool | Pure? | Purpose |
|---|
server_info | yes | Health/version snapshot, default paths, env overrides |
list_videos(root) | I/O | Recursive .mp4/.mkv/.mov/.avi/.m4v/.webm discovery |
list_subtitles(root) | I/O | Recursive .srt/.vtt discovery |
parse_srt_text(text) | yes | Parse SRT/WebVTT → {count, cues:[{index,start,end,text}]} |
build_segments_from_srt(text, duration_seconds, ...) | yes | Preview keep-segments + markers from SRT text + known duration |
whisper_transcribe(wav_path, output_srt_path, url?) | I/O + net | POST a 16kHz mono WAV to local Whisper HTTP server, save SRT |
gpu_transcribe(wav_path, output_srt_path, model?, device?, ...) | GPU | Transcribe via local faster-whisper (CTranslate2), no HTTP hop |
render_segments(video_path, output_mp4_path, segments_json, ...) | ffmpeg | Render a JSON list of {start,end} segments into a single MP4 |
automark(video_path, output_dir, ...) | full | Audio + SRT + plan + CSVs (no render) |
autocut(video_path, output_dir, ...) | full | automark + render MP4 |
autoedit(video_path, output_dir, ...) | full | Same as autocut (the original CLI's "full export bundle") |
All segmentation/render knobs from the original script are exposed as
keyword args on the relevant tool:
lead_in (0.30 s), tail_out (0.45 s), merge_gap (1.20 s),
min_segment (0.85 s) — automark / autocut / autoedit /
build_segments_from_srt / render_segmentsvideo_codec (libx264), preset (medium), crf (18),
audio_codec (aac), audio_bitrate (192k) — autocut / autoedit /
render_segments
Transcription knobs (apply to gpu_transcribe AND autoedit/autocut/
automark when no SRT is provided):
transcribe_backend ("faster-whisper" default / "http" / "none")whisper_model ("large-v3", "medium", "small", "tiny")whisper_device ("cuda" default / "cpu")whisper_compute_type ("float16" default / "int8" / etc.)whisper_language (optional ISO code, auto-detect if omitted)whisper_beam_size (default 5)
Install (Hermes Agent)
-
Install Python deps for the hermes-editing-yt server itself (one-time, in
the Python the MCP server will run under — e.g.
C:\Users\Bernardo\AppData\Local\Programs\Python\Python314\python.exe):
PY="C:\Users\Bernardo\AppData\Local\Programs\Python\Python314\python.exe"
"$PY" -m pip install fastmcp faster-whisper pytest
"$PY" -m pip install "nvidia-cublas-cu12==12.9.2.10"
ffmpeg and ffprobe must be on PATH. The skill will fail loudly
(server_info.ffmpeg_available == false) if they're missing.
winget install Gyan.FFmpeg is the easiest install on Windows.
-
Install the MCP SDK in the Hermes venv. Hermes's Windows venv is
stripped (no pip) per the hermes-agent skill notes. Use uv:
cd "C:\Users\Bernardo\AppData\Local\hermes\hermes-agent"
uv pip install --python ./venv/Scripts/python.exe mcp
Without this, hermes mcp add hermes-editing-yt will fail with
"MCP server 'hermes-editing-yt' requires the 'mcp' Python SDK, but it is not
installed". See references/windows-gpu-whisper-setup.md for the
full cuBLAS + Hermes venv install recipe.
-
Wire into Hermes with the official helper (it writes the
right block in ~\AppData\Local\hermes\config.yaml for you):
cd "C:\Users\Bernardo\AppData\Local\hermes\hermes-agent"
echo "y" | ./venv/Scripts/hermes mcp add hermes-editing-yt \
--command "C:\\Users\\Bernardo\\AppData\\Local\\Programs\\Python\\Python314\\python.exe" \
--args "G:\\- hermes-editing-yt\tools\\video_workflow\\mcp_server.py"
The MCP server has 11 tools; the prompt asks you to enable all of
them — accept the default.
-
Restart the gateway (or /reset in chat):
hermes gateway restart
-
Verify:
hermes mcp list
hermes mcp test hermes-editing-yt
In chat, ask the agent: "Call mcp_hermes-editing-yt_server_info" — you
should see the 11-tool manifest including gpu_transcribe.
-
Optional env overrides (set before hermes starts, or in
~\AppData\Local\hermes\.env):
HERMES_EDITING_YT_WHISPER_URL=http://127.0.0.1:51746/transcribe
HERMES_EDITING_YT_OUTPUT_DIR=G:\- hermes-editing-yt\output
HERMES_EDITING_YT_RAW_DIR=G:\- hermes-editing-yt\Unedited (RAW)
HERMES_EDITING_YT_WHISPER_MODEL=large-v3
HERMES_EDITING_YT_WHISPER_DEVICE=cuda
HERMES_EDITING_YT_WHISPER_COMPUTE=float16
These only affect server_info defaults — the MCP tool args take
precedence when supplied.
Common Workflows
1. Preview a cut plan from an existing SRT (no ffmpeg)
User: Use hermes-editing-yt to preview a cut plan from
G:\- hermes-editing-yt\Editing\New folder\Untitled - February 8, 2026 (1).srt
for a 10000s video.
Agent: mcp_hermes-editing-yt_build_segments_from_srt(
text=<file_contents>,
duration_seconds=10000)
→ JSON with segment_count, kept_duration_seconds, segments[], markers[]
2. Full autocut with existing SRT (no transcription needed)
User: autocut Helgstr1.mp4 to G:\- hermes-editing-yt\output\preview
Agent: mcp_hermes-editing-yt_autocut(
video_path="G:\\- hermes-editing-yt\Editing\\New folder\\Helgstr1.mp4",
output_dir="G:\\- hermes-editing-yt\output\\preview",
srt_path="G:\\- hermes-editing-yt\Editing\\New folder\\Untitled - February 8, 2026 (1).srt")
→ JSON with rendered_video, segment_count, plan_path, …
3. End-to-end autocut with LOCAL GPU Whisper (no SRT, no network)
This is the new default. The MCP server calls faster-whisper on the
RTX 5060 directly — no HTTP server hop, no need to start a separate
Whisper process.
User: autoedit Helgstr1.mp4 with GPU transcription
Agent: mcp_hermes_editing_yt(
video_path="G:\\- hermes-editing-yt\Editing\\New folder\\Helgstr1.mp4",
output_dir="G:\\- hermes-editing-yt\output\\gpu_helgstr1",
whisper_model="large-v3", # or "medium" / "small" for speed
whisper_device="cuda", # "cpu" to force fallback
whisper_compute_type="float16")
The model is loaded once per session and cached, so repeat runs
(plan → autocut → re-render) skip the multi-second model-load tax.
4. Transcribe only (no cut, no render)
User: Transcribe Helgstr1.wav to an SRT
Agent: mcp_hermes-editing-yt_gpu_transcribe(
wav_path="G:\\- hermes-editing-yt\output\\some\\Helgstr1_whisper_input.wav",
output_srt_path="G:\\- hermes-editing-yt\output\\some\\Helgstr1.srt",
model="medium", # faster than large-v3 for a quick pass
language="en") # skip auto-detect
5. Transcribe via remote HTTP server (legacy path)
Set transcribe_backend="http" and the whisper_url to your server:
mcp_hermes_editing_yt(
video_path=...,
output_dir=...,
transcribe_backend="http",
whisper_url="http://127.0.0.1:51746/transcribe")
CLI / Library (unchanged from the original)
The refactor is backwards-compatible. The original CLI still works:
python "G:\- hermes-editing-yttools\video_workflow\auto_video_workflow.py" autoedit `
--video "G:\- hermes-editing-yt\Editing\New folder\Helgstr1.mp4" `
--output-dir "G:\- hermes-editing-yt\output\cli-run"
And the library can be imported directly:
import sys
sys.path.insert(0, r"G:\- hermes-editing-yttools\video_workflow")
import hermes_editing_yt as lib
result = lib.run_pipeline(
mode="autocut",
video_path=Path(".../Helgstr1.mp4"),
output_dir=Path(".../run"),
config=lib.PipelineConfig(lead_in=0.5, tail_out=0.6, crf=20),
)
print(result.rendered_video, len(result.keep_segments), "segments")
Files in this plugin
G:\- hermes-editing-yttools\video_workflow\
├── auto_video_workflow.py # ORIGINAL CLI (preserved, untouched)
├── auto_video_workflow.legacy.bak.py # Pre-refactor safety copy
├── hermes_editing_yt.py # Refactored library + CLI entry
├── mcp_server.py # FastMCP 3.x server (this plugin)
├── README.md # Original README (preserved)
├── run_gpu_helgstr1.py # end-to-end Helgstr1 smoke script
├── tests/
│ ├── test_hermes_editing_yt.py # 35 pytest cases, all pure functions
│ └── test_mcp_server.py # MCP smoke over stdio, 11 tools
└── __pycache__/ # bytecode
The references/ folder lives next to SKILL.md in
~\AppData\Local\hermes\skills\media\hermes-editing-yt\references\:
references/windows-gpu-whisper-setup.md — cuBLAS 12 vs 13 fix,
Hermes venv pip, nvidia-cublas-cu12 install, full error→fix tablereferences/mcp-smoke-test-pattern.md — how to write smoke tests
for MCP servers with heavy first-call costs (3-layer pattern: tiny
model + CPU + pass-through assertions)
Common Pitfalls
-
"ffmpeg not available" — install from gyan.dev / brew / apt, or
point PATH at an existing build. The original hermes-editing-yt box already has
it at C:\Users\Bernardo\AppData\Local\Microsoft\WinGet\Links\ffmpeg.
server_info() reports ffmpeg_available directly.
-
"MCP server requires the 'mcp' Python SDK" — the Hermes venv
doesn't ship with the MCP SDK. Install with
uv pip install --python <hermes-venv>/Scripts/python.exe mcp. See
references/windows-gpu-whisper-setup.md for why this is needed
(Hermes's mcp client lives in its own venv, not the system Python
that the hermes-editing-yt server itself uses).
-
No SRT and transcribe_backend="none" — pass
transcribe_backend="faster-whisper" (default) or "http", OR
pre-supply an srt_path. The pipeline raises a clear EditingYtError
if it can't find an SRT and the backend can't produce one.
-
GPU transcription first call is slow — large-v3 is ~3 GB and
the first call pays a multi-second model-load + cuDNN init tax.
Subsequent calls in the same MCP server session reuse the cached
model. The transcription itself runs at near-realtime on the RTX
5060 (sm_120, 8 GB). Use whisper_model="medium" or "small" for
faster (but less accurate) transcriptions.
-
Whisper HTTP server unreachable (legacy path) — when using
transcribe_backend="http", the whisper_transcribe tool returns a
JSON {"error": "Whisper server is not reachable..."}. Either start
your Whisper server (the hermes-editing-yt box uses port 51746) or just use
the GPU backend instead.
-
autocut takes a long time — ffmpeg re-encodes each segment
(libx264 medium CRF 18). A 1-hour source typically renders in
5–15 min on a modern CPU. The MCP timeout must be ≥ 600 s for the
hermes-editing-yt server entry.
-
CUDA float16 fails (no cuDNN / wrong driver / cuBLAS 12 missing)
— the GPU backend auto-falls-back to CPU float32 and returns the
actual device / compute_type in the result JSON. If even CPU
fails, you get a clear EditingYtError. On RTX 5060 + PyTorch
2.12+cu130 specifically, you'll hit
cublas64_12.dll is not found or cannot be loaded because torch
ships v13 but ctranslate2 wants v12 — the library's
_ensure_cublas12_on_path() registers the right directory
automatically. Full diagnosis in
references/windows-gpu-whisper-setup.md.
-
Output dir doesn't exist — run_pipeline calls
mkdir(parents=True, exist_ok=True), so this is automatic. But the
parent must be writable — on the hermes-editing-yt box, G:\- hermes-editing-yt\output
is fine, but a sandboxed Hermes profile running under a different
user might not have write access. Check ACLs.
-
Long paths on Windows — keep paths under ~250 chars to avoid
OSError 206 ("filename or extension too long"). The
Helgstr1_8m.mp3 / Helgstr1_CUT.mp4 workflow hits this occasionally;
the refactored code uses Path.resolve() to canonicalize but doesn't
shorten.
-
SRT cue numbering is wrong — the original CLI's parse_srt used
the SRT index field literally. The new parse_subtitles auto-assigns
if the first line isn't a bare integer (e.g. WebVTT cues), so the
source_index on markers can differ by ±1 between old and new runs
for mixed-format inputs. Pure-SRT inputs are unchanged.
-
Smoke test for the MCP server times out — the first call to
gpu_transcribe triggers a 3 GB model download (large-v3) +
multi-second load. The shipped tests/test_mcp_server.py uses
model="tiny", device="cpu", compute_type="float32" so the
smoke stays under 30 s. If you write your own smoke, follow the
3-layer pattern in references/mcp-smoke-test-pattern.md.
Verification Checklist
Run Tests
unset PYTHONPATH
cd "G:\- hermes-editing-yttools\video_workflow"
python -m pytest tests/ -v
Expected: 35 pure unit tests pass in <1 s + the MCP smoke
exercises 11 tools (smoke takes ~30 s; the gpu_transcribe call
inside the smoke uses the tiny model + CPU to stay fast).
Run the Server Manually (for debugging)
python "G:\- hermes-editing-yttools\video_workflow\mcp_server.py"
python "G:\- hermes-editing-yttools\video_workflow\mcp_server.py" --http 8765
Reference: env vars & defaults
| Env var | Default | Used by |
|---|
HERMES_EDITING_YT_WHISPER_URL | http://127.0.0.1:51746/transcribe | whisper_transcribe tool (HTTP backend) |
HERMES_EDITING_YT_OUTPUT_DIR | G:\- hermes-editing-yt\output | server_info default_output_dir |
HERMES_EDITING_YT_RAW_DIR | G:\- hermes-editing-yt\Unedited (RAW) | server_info default_raw_dir |
HERMES_EDITING_YT_WHISPER_MODEL | large-v3 | GPU backend default model |
HERMES_EDITING_YT_WHISPER_DEVICE | cuda | GPU backend default device |
HERMES_EDITING_YT_WHISPER_COMPUTE | float16 | GPU backend default compute type |
HERMES_EDITING_YT_WHISPER_LANG | (auto-detect) | GPU backend default language code |
HERMES_EDITING_YT_WHISPER_BEAM | 5 | GPU backend default beam size |
The MCP tool args (video_path, output_dir, whisper_url,
whisper_model, …) always take precedence over the env defaults.
See also
native-mcp — how Hermes Agent's built-in MCP client works
(stdio/HTTP transport, tool naming, security model)hermes-agent — hermes mcp add/list/test CLI- The original
auto_video_workflow.py CLI (preserved for one-shots)
tests/test_hermes_editing_yt.py — 35 reference cases for the librarytests/test_mcp_server.py — full MCP smoke over stdioreferences/windows-gpu-whisper-setup.md — cuBLAS 12 vs 13 fix,
Hermes venv pip, nvidia-cublas-cu12 install, full error→fix tablereferences/mcp-smoke-test-pattern.md — how to write smoke tests
for MCP servers with heavy first-call costs
