io.github.js713-lab/sonicmatch-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GEMINI_API_KEY | No | Optional Gemini API key for video understanding. When set, Gemini is used as the primary analyzer. | |
| FREESOUND_API_KEY | No | Optional Freesound API key for CC loops and beds. | |
| JAMENDO_CLIENT_ID | No | Optional Jamendo API client ID for CC music search. | |
| ARTLIST_LIBRARY_PATH | No | Path to a JSON file of user-owned Artlist library tracks already licensed by the user. | |
| EPIDEMIC_LIBRARY_PATH | No | Path to a JSON file of user-owned Epidemic Sound library tracks already licensed by the user. | |
| SONICMATCH_ALLOW_YTDLP | No | Set to 1 to allow platform URL ingest with yt-dlp. Off by default (0) because platform extractors may break and violate ToS. Prefer local files. | 0 |
| SONICMATCH_LIBRARY_PATH | No | Path to a JSON file of user-owned library tracks already licensed by the user. | |
| SONICMATCH_MAX_DOWNLOAD_MB | No | Maximum download size in MB for remote ingest (default 200). | 200 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| statusA | Show ffmpeg/yt-dlp availability and which music adapters have keys. |
| ingest_videoA | Ingest a local video path or public http(s) URL. Accepts a filesystem path or an HTTPS video URL. YouTube/TikTok/Instagram via yt-dlp is OFF unless SONICMATCH_ALLOW_YTDLP=1 (ToS + extractor risk). Rejects file://, http, loopback, and private IPs (SSRF). Size-capped. Extracts duration/fps/aspect with ffprobe, a 16 kHz mono wav, up to 12 scene keyframes, and a 360p proxy. Returns an asset_id. Never returns video bytes. Call this first. Then call analyze_video_music with the asset_id. |
| analyze_video_musicA | Produce a structured VideoSonic profile for BGM matching. platform_hint: instagram_story | instagram_reel | tiktok | youtube_short | youtube_long | generic. Uses Gemini video understanding when GEMINI_API_KEY is set; otherwise local ffmpeg/audio heuristics (and optional faster-whisper / PySceneDetect if installed). Always fills search_queries even if analysis is weak. extra_notes: optional caption/script the user already has — used as a hint, not as a replacement for watching the video. |
| recommend_bgmA | Rank license-safe BGM. Pass asset_id and/or a VideoSonic profile. Defaults instrumental_only=True when speech_coverage > 0.25. catalog: auto | seed | jamendo | freesound | library auto = seed always, plus Jamendo/Freesound/user-library when configured. Each recommendation includes score, reason, suggested song in/out (12–20s high-energy slice), ducking hint, and license_ok_for_platform. max_results is clamped to 3–7. brand_kit: name previously saved with save_brand_kit. |
| search_musicC | Free-text search over seed + optional Jamendo / Freesound / user library. |
| get_trackC | Return one track's metadata, license string, attribution text, and URLs. |
| preview_mixA | Mix BGM under the video: hook trim, loop if needed, optional speech ducking. Returns preview mp3 + low-res mp4 paths, the ffmpeg command, and a mix_spec JSON an editor (CapCut / Premiere / DaVinci / your agent) can re-apply. Ducking uses ffmpeg sidechaincompress when the video has speech. Seed tracks without audio files get a synthesized CC0 demo bed so the pipeline still runs offline. |
| export_mix_specB | Export the mix spec + ffmpeg recipe + attribution without requiring a render. This is the editor companion output (CapCut / Premiere / DaVinci / agent). Set render=true to also write preview files (same as preview_mix). |
| suggest_cutsA | Snap detected scene cuts onto a beat grid. Returns EDL-ish spans and intro/peak/outro acts. bpm defaults to the VideoSonic suggested_bpm midpoint, or the track BPM if track_id is set. |
| generate_bedA | Generate a bed when the catalog misses. Always marked source=generated. Refuses unless i_understand_not_commercially_cleared=true. Local fallback is a sine-tremolo demo. NOT cleared for ads. Check Suno/Stable Audio/Lyria terms before swapping in a real generator. Generated tracks are excluded from recommend_bgm auto catalogs. |
| save_brand_kitB | Save a brand kit (BPM lock + no vocals + mood whitelist). Pass brand_kit=name to recommend_bgm. |
| analyze_batchA | Analyze up to 20 clips, cluster moods, return one consistent mini-playlist for the series. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| ig_music_sticker | Score this video like an IG music sticker (energy + hook, license-safe). |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 12 tools
Most tools have clearly distinct roles in the pipeline (ingest, analyze, recommend, search, render, export, cuts, bed generation). However, preview_mix and export_mix_spec overlap significantly since export_mix_spec with render=true is explicitly 'same as preview_mix', and recommend_bgm vs search_music both perform music lookup with some boundary overlap.
All tools follow the snake_case verb_noun pattern (ingest_video, recommend_bgm, suggest_cuts, save_brand_kit, etc.), except for the noun-only 'status'. That minor inconsistency is the only deviation, making the set predictable.
12 tools map directly to a coherent music-video workflow: video ingest, analysis, BGM recommendation/search, track details, mixing, export, cutting, generated beds, brand kit, and batch analysis. Every tool has a clear purpose and the count fits squarely in the well-scoped range.
The toolkit covers the essential lifecycle from video input to analysis, music selection, mix preview, specification export, and batch operation. Minor gaps exist like management of saved assets (e.g., updating brand kits or deleting generated beds), but the core workflow has no dead ends and agents can complete a full pipeline.