Skip to content
Back to search

sonic-match-mcp

MCP server that watches video footage and returns license-safe BGM matches, hook windows, and ffmpeg ducking specs for agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/js713-lab--sonic-match-mcp/badge.svg)](/listings/js713-lab--sonic-match-mcp)

HTML

<a href="/listings/js713-lab--sonic-match-mcp"><img src="/api/listings/js713-lab--sonic-match-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires **Python 3.10+** and `ffmpeg` / `ffprobe` on PATH. `yt-dlp` is optional and **off by default** (`SONICMATCH_ALLOW_YTDLP=0`) because platform extractors break and may violate ToS. Prefer a local file.

pip install git+https://github.com/js713-lab/sonic-match-mcp.git
sonicmatch-mcp            # or: python3 -m sonicmatch

With [uv](https://github.com/astral-sh/uv), no clone:

uvx --from git+https://github.com/js713-lab/sonic-match-mcp.git sonicmatch-mcp

From a clone (editable + tests):

git clone https://github.com/js713-lab/sonic-match-mcp.git
cd sonic-match-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env   # optional keys

# stdio (Claude Desktop / Cursor)
sonicmatch-mcp

# streamable HTTP (web editors)
sonicmatch-mcp --http --port 8765
# same clone, uv
uv venv && uv pip install -e ".[dev]"
uv run sonicmatch-mcp

v0.2 works **offline-ish** with a 20-track seed catalog aimed at Reel editors (cafe, product, talking-head, travel, food, fashion, event). Gemini, Jamendo, and Freesound are optional and degrade with a note in the tool response. Seed rows have no hosted audio on purpose — `preview_mix` synthesizes a demo bed. For real ads, point `SONICMATCH_LIBRARY_PATH` / `EPIDEMIC_LIBRARY_PATH` / `ARTLIST_LIBRARY_PATH` at JSON you already licensed.

pytest   # generates tiny color mp4s with ffmpeg

Not on PyPI yet. Install from git.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 416 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Sonicmatch
  2. <!-- mcp-name: io.github.js713-lab/sonicmatch-mcp -->
  3. [![CI](https://github.com/js713-lab/sonic-match-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/js713-lab/sonic-match-mcp/actions/workflows/ci.yml)
  4. [![PyPI](https://img.shields.io/pypi/v/sonicmatch-mcp)](https://pypi.org/project/sonicmatch-mcp/)
  5. [![License: MIT](https://img.shields.io/github/license/js713-lab/sonic-match-mcp)](LICENSE)
  6. [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-6b4fbb)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.js713-lab%2Fsonicmatch-mcp/versions/latest)
  7. [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
  8. **Video-native MCP server for license-safe BGM.** Watches the footage — not the script — and returns a shortlist, a 12–20s hook, and an ffmpeg ducking spec.
  9. <p align="center">
  10. <img src="https://github.com/js713-lab/sonic-match-mcp/raw/main/docs/banner.jpg" alt="Sonicmatch — video in, license-safe BGM out. Ingest, Analyze, Match, Mix." width="100%">
  11. </p>
  12. Package / CLI: [`sonicmatch-mcp`](https://github.com/js713-lab/sonic-match-mcp). A [Model Context Protocol](https://modelcontextprotocol.io) server for Claude Desktop, Cursor, Codex, and other MCP clients. Drop an Instagram Reel, YouTube Short, or TikTok-style clip. Get royalty-free / Creative Commons matches with the license printed on every row.
  13. Video-to-BGM already exists. The wedge is not “I also match music”:
  14. - it watches the **footage**, not the script
  15. - it returns a **hook window** + ffmpeg ducking spec
  16. - it is **agent-native**
  17. - it **prints the license** instead of lying
  18. Catalog quality will kill or save this. More tools will not.
  19. ```
  20. Video or URL in
  21. → scene / mood / pace / speech analysis
  22. → license-safe BGM shortlist
  23. + beat/cut hints
  24. + optional mix preview
  25. ```
  26. Do **not** treat this as “script in → YouTube Music search out.” That already exists (`mcp-bgm-recommender`). Sonicmatch watches the **video**.
  27. | You own | You do not own |
  28. |---|---|
  29. | Local file / public URL ingest | Platform music licenses |
  30. | Mood, energy curve, speech vs silence, scene cuts | Meta/TikTok “trending audio” graph |
  31. | CC / royalty-free catalogs + optional paid adapters | Spotify / IG official libraries |
  32. | Ranked tracks, preview URLs, mix spec, ffmpeg | Auto-publish to Instagram |
  33. **North star:** `ingest_video` → `analyze_video_music` → `recommend_bgm` → `preview_mix` → `export_mix_spec`
  34. ## License warning (read this)
  35. - The **code** is MIT.
  36. - **Every track has its own license.** It is printed on every recommendation.
  37. - Nothing here is an official Instagram sticker, TikTok Commercial Music Library track, or YouTube Audio Library API result.
  38. - Do not recommend commercial pop unless the adapter is explicitly a **user-owned licensed library**.
  39. - CC-BY still needs attribution. CC-BY-NC is **not** ok for ads / shops. Non-commercial tracks are **never auto-recommended**.
  40. - For ads / shops, wire a **user-owned** Artlist / Epidemic JSON (`examples/user_library.example.json`). Do not scrape those sites.
  41. - Content ID can still hit you if you point at the wrong source. A CC label is not a waiver.
  42. ## Demo
  43. > I dropped `./clip.mp4`. Analyze it for an Instagram Reel and recommend 5 instrumental BGMs. Then mix the top pick with ducking and give me the ffmpeg command.
  44. That prompt is the product. Install below, wire Claude Desktop, Cursor, or Codex, and paste it.
  45. ## Quick start
  46. Requires **Python 3.10+** and `ffmpeg` / `ffprobe` on PATH. `yt-dlp` is optional and **off by default** (`SONICMATCH_ALLOW_YTDLP=0`) because platform extractors break and may violate ToS. Prefer a local file.
  47. The PyPI project is `sonicmatch-mcp`. The console script is `sonicmatch-mcp`, which is what `uvx` and `pipx` run. `python -m sonicmatch` is the same server. The PyPI badge stays empty until the first tag is published. Install from git until then. Maintainer steps: [PUBLISH.md](PUBLISH.md).
  48. ### Works today (git)
  49. ```bash
  50. uvx --from git+https://github.com/js713-lab/sonic-match-mcp.git sonicmatch-mcp
  51. ```
  52. ```bash
  53. pip install git+https://github.com/js713-lab/sonic-match-mcp.git
  54. sonicmatch-mcp --version # or: python -m sonicmatch --version
  55. ```
  56. ### After the first PyPI release
  57. ```bash
  58. uvx sonicmatch-mcp
  59. # or
  60. pipx install sonicmatch-mcp
  61. sonicmatch-mcp --version
  62. ```
  63. ### From a clone (editable + tests)
  64. ```bash
  65. git clone https://github.com/js713-lab/sonic-match-mcp.git
  66. cd sonic-match-mcp
  67. python3 -m venv .venv
  68. source .venv/bin/activate
  69. pip install -e ".[dev]"
  70. cp .env.example .env # optional keys
  71. # stdio (Claude Desktop / Cursor / Codex)
  72. sonicmatch-mcp
  73. # streamable HTTP (web editors). No authentication. Keep it on loopback.
  74. sonicmatch-mcp --http --port 8765
  75. ```
  76. ```bash
  77. # same clone, uv
  78. uv venv && uv pip install -e ".[dev]"
  79. uv run sonicmatch-mcp
  80. ```
  81. ```bash
  82. pytest # generates tiny color mp4s with ffmpeg
  83. ruff check src tests
  84. ```
  85. The seed catalog is about 20 Reel-editor rows (cafe, product, talking-head, travel, food, fashion, event) plus a vocal fixture and a CC-BY-NC fixture. It runs without API keys. Gemini, Jamendo, and Freesound are optional and degrade with a note in the tool response. Seed rows have no hosted audio on purpose — `preview_mix` synthesizes a demo bed. For real ads, point `SONICMATCH_LIBRARY_PATH` / `EPIDEMIC_LIBRARY_PATH` / `ARTLIST_LIBRARY_PATH` at JSON you already licensed.
  86. | Variable | Required | What it does |
  87. |---|---|---|
  88. | `GEMINI_API_KEY` | no | Gemini video understanding for `analyze_video_music` |
  89. | `JAMENDO_CLIENT_ID` | no | Jamendo search |
  90. | `FREESOUND_API_KEY` | no | Freesound beds and loops |
  91. | `SONICMATCH_LIBRARY_PATH` | no | User-owned library JSON. Also `EPIDEMIC_LIBRARY_PATH`, `ARTLIST_LIBRARY_PATH` |
  92. | `SONICMATCH_ALLOW_YTDLP` | no | `1` turns on platform URL ingest. Default `0` |
  93. | `SONICMATCH_MAX_DOWNLOAD_MB` | no | Download cap. Default 200 |
  94. | `SONICMATCH_HTTP_HOST` / `SONICMATCH_HTTP_PORT` | no | `--http` bind. Default `127.0.0.1:8765` |
  95. ## Features
  96. - **Watches the picture.** Gemini video understanding when `GEMINI_API_KEY` is set; otherwise local ffmpeg / audio heuristics (optional Whisper, PySceneDetect, librosa).
  97. - **License on every row.** CC / royalty-free / user-owned library. Non-commercial tracks are never auto-recommended. Generated beds stay out of auto recs.
  98. - **Editor-shaped output.** 12–20s hook in/out, speech ducking, ffmpeg recipe, mix spec for CapCut / Premiere / DaVinci / your agent.
  99. - **Agent-native MCP.** stdio for Claude Desktop and Cursor; streamable HTTP for web editors. Never ships raw multi-MB video through the payload — you get an `asset_id`.
  100. - **Works without API keys.** 20-track seed catalog for Reels. Optional Jamendo, Freesound, and user-owned Artlist / Epidemic JSON.
  101. - **Cuts on the beat.** `suggest_cuts` snaps scene cuts to a BPM grid and returns EDL-ish intro / peak / outro.
  102. - **Brand lock.** Save BPM / mood / no-vocals kits and pass `brand_kit=…` into `recommend_bgm`.
  103. - **Series, not one-offs.** `analyze_batch` (max 20) clusters mood and returns one shared mini-playlist.
  104. - **Honest about closed graphs.** No fake “trending audio,” official IG stickers, or Content-ID-safe stamps. yt-dlp platform ingest is opt-in.
  105. ## Tools
  106. | Tool | What it does |
  107. |---|---|
  108. | `status` | ffmpeg / keys / seed count / day-1 risk gates |
  109. | `ingest_video` | Local path or HTTPS URL → `asset_id` (never video bytes). Platform URLs need `SONICMATCH_ALLOW_YTDLP=1` |
  110. | `analyze_video_music` | Mood, energy curve, speech, scenes, hook window, BPM, search queries |
  111. | `recommend_bgm` | 3–7 ranked tracks + why + license + hook in/out |
  112. | `search_music` | Free-text / BPM / mood over seed + optional catalogs |
  113. | `get_track` | One track’s metadata, license, attribution, URLs |
  114. | `preview_mix` | Hook trim, loop, optional ducking → preview files + ffmpeg + mix spec |
  115. | `export_mix_spec` | Mix spec + ffmpeg + attribution (no render unless `render=true`) |
  116. | `suggest_cuts` | Beat grid, snapped scene cuts, EDL, intro / peak / outro |
  117. | `generate_bed` | Demo bed marked `source=generated`. Requires `i_understand_not_commercially_cleared=true` |
  118. | `save_brand_kit` | Persist BPM / moods / no-vocals for `recommend_bgm(brand_kit=…)` |
  119. | `analyze_batch` | Up to 20 clips → mood cluster + shared mini-playlist |
  120. Also ships a prompt template: **“Score this video like an IG music sticker.”**
  121. ### Product rules (Instagram-like, not Instagram)
  122. - Prefer **instrumental** when `speech_coverage > 0.25`
  123. - Recommend a **hook window**, not the whole song
  124. - Show **why** (`cuts at 0.8s average, 112 BPM, warm gold hour`)
  125. - Always return **license + attribution text**
  126. - 3–7 tracks, not 40
  127. - User can override mood / genre / no-lyrics / platform / energy
  128. - Never claim “cleared for Instagram official sticker” unless it actually is
  129. ## Example
  130. Prompt:
  131. > I dropped `./clip.mp4`. Analyze it for an Instagram Reel and recommend 5 instrumental BGMs. Then mix the top pick with ducking and give me the ffmpeg command.
  132. The agent should call, in order:
  133. 1. `ingest_video` with the local path. The result is an `asset_id`, not video bytes.
  134. 2. `analyze_video_music` with `platform_hint` set to `instagram_reel`.
  135. 3. `recommend_bgm` with that `asset_id` and `max_results` of 5.
  136. 4. `preview_mix` on the top track with ducking, then `export_mix_spec`.
  137. A recommendation row carries `score`, `reason`, `suggested_in_out` (the hook), `ducking`, `license_ok_for_platform`, and `content_id_risk` (`unknown` or `likely`, never `cleared`). Seed fixtures include `seed_golden_hour_latte` (CC0-1.0) and `seed_indie_porch_110` (CC-BY-4.0). They have no hosted audio. `preview_mix` synthesizes a demo bed. CC-BY-NC rows are searchable and are not auto-recommended.
  138. ## Claude Desktop
  139. `claude_desktop_config.json`. From git, no clone:
  140. ```json
  141. {
  142. "mcpServers": {
  143. "sonicmatch": {
  144. "command": "uvx",
  145. "args": [
  146. "--from",
  147. "git+https://github.com/js713-lab/sonic-match-mcp.git",
  148. "sonicmatch-mcp"
  149. ],
  150. "env": {
  151. "GEMINI_API_KEY": "",
  152. "JAMENDO_CLIENT_ID": "",
  153. "FREESOUND_API_KEY": ""
  154. }
  155. }
  156. }
  157. }
  158. ```
  159. After a clone, `command` can be the absolute path of `.venv/bin/sonicmatch-mcp`. After the PyPI release, `args` is just `["sonicmatch-mcp"]`. Copy-paste files: [`examples/claude_desktop.mcp.json`](examples/claude_desktop.mcp.json), [`examples/claude_desktop.pypi.mcp.json`](examples/claude_desktop.pypi.mcp.json).
  160. ## Cursor
  161. `.cursor/mcp.json` (project) or `~/.cursor/mcp.json`. From git, no clone — [`examples/cursor.mcp.json`](examples/cursor.mcp.json):
  162. ```json
  163. {
  164. "mcpServers": {
  165. "sonicmatch": {
  166. "command": "uvx",
  167. "args": [
  168. "--from",
  169. "git+https://github.com/js713-lab/sonic-match-mcp.git",
  170. "sonicmatch-mcp"
  171. ],
  172. "env": {
  173. "GEMINI_API_KEY": "",
  174. "JAMENDO_CLIENT_ID": "",
  175. "FREESOUND_API_KEY": ""
  176. }
  177. }
  178. }
  179. }
  180. ```
  181. After PyPI, use [`examples/cursor.pypi.mcp.json`](examples/cursor.pypi.mcp.json) (`uvx` with args `["sonicmatch-mcp"]`). From a clone: `"command": "uv", "args": ["--directory", "/absolute/path/to/sonic-match-mcp", "run", "sonicmatch-mcp"]`. After `pip install`, `"command": "python3", "args": ["-m", "sonicmatch"]` works if that interpreter has the package.
  182. ## Codex
  183. Codex reads `~/.codex/config.toml`. The same file is shared with the Codex IDE extension and the ChatGPT desktop app. Works today — [`examples/codex.config.toml`](examples/codex.config.toml):
  184. ```toml
  185. [mcp_servers.sonicmatch]
  186. command = "uvx"
  187. args = ["--from", "git+https://github.com/js713-lab/sonic-match-mcp.git", "sonicmatch-mcp"]
  188. [mcp_servers.sonicmatch.env]
  189. GEMINI_API_KEY = ""
  190. JAMENDO_CLIENT_ID = ""
  191. FREESOUND_API_KEY = ""
  192. ```
  193. Or from the CLI:
  194. ```bash
  195. codex mcp add sonicmatch -- uvx --from git+https://github.com/js713-lab/sonic-match-mcp.git sonicmatch-mcp
  196. ```
  197. After the PyPI release, the args shrink to `sonicmatch-mcp`. That file is [`examples/codex.pypi.config.toml`](examples/codex.pypi.config.toml):
  198. ```bash
  199. codex mcp add sonicmatch -- uvx sonicmatch-mcp
  200. ```
  201. `codex mcp list` should show `sonicmatch`. A trusted project can use `.codex/config.toml` instead of the home file.
  202. User-owned Epidemic/Artlist JSON shape: [`examples/user_library.example.json`](examples/user_library.example.json). Registry metadata: [`server.json`](server.json). HTTP editors can point at `http://127.0.0.1:8765/mcp` after `sonicmatch-mcp --http`.
  203. ## Hosted (sonic.codecrafter.dev)
  204. The GitHub repo stays **MIT**. Running it yourself is not metered.
  205. The public endpoint charges credits per tool call. A trial key is 25 credits. Pack prices: Reel 500 credits / $9, Studio 3000 credits / $39. Card checkout is not connected on the host yet.
  206. The landing page is https://sonic.codecrafter.dev. Use **Use the sample clip** there, or download [`examples/sample-clip.mp4`](examples/sample-clip.mp4) and upload it, to try a match without your own footage.
  207. 1. Open https://sonic.codecrafter.dev and take a trial key (or use a paid key).
  208. 2. `export SONICMATCH_API_KEY=sm_…`
  209. 3. Add to Cursor: the button on that page, or paste `examples/cursor.hosted.mcp.json` into `~/.cursor/mcp.json`.
  210. ```json
  211. {
  212. "mcpServers": {
  213. "sonicmatch": {
  214. "url": "https://sonic.codecrafter.dev/mcp",
  215. "headers": {
  216. "Authorization": "Bearer ${env:SONICMATCH_API_KEY}"
  217. }
  218. }
  219. }
  220. }
  221. ```
  222. `--http` has no authentication. Keep it on loopback. The Docker image binds `0.0.0.0` so the container port works — do not publish that port to the internet. See [SECURITY.md](SECURITY.md).
  223. ## Architecture
  224. ```mermaid
  225. flowchart TB
  226. subgraph mcp [MCP Server - FastMCP / Python - stdio + HTTP]
  227. tools[ingest_video / analyze_video_music / recommend_bgm / preview_mix / export_mix_spec / suggest_cuts]
  228. end
  229. tools --> ingest
  230. tools --> brain
  231. tools --> hub
  232. tools --> mixer
  233. ingest[Ingestor<br/>yt-dlp · ffmpeg · ffprobe · URL/file]
  234. brain[Video Brain<br/>Gemini / local VL · librosa · PySceneDetect · Whisper]
  235. hub[Music Hub<br/>seed CC · Jamendo · Freesound · user library · generate]
  236. mixer[Mixer<br/>ffmpeg · ducking · loop/trim · EDL cuts]
  237. hub --> index[Track index<br/>tags + license + embeddings · SQLite · optional LanceDB]
  238. ```
  239. Hard rule: **never send raw multi-MB video through the MCP payload.** Store locally, pass an `asset_id`. Loopback, `file://`, and private IPs are rejected (SSRF).
  240. ## VideoSonic profile
  241. Analysis returns structured JSON, not a paragraph:
  242. ```json
  243. {
  244. "duration_sec": 18.4,
  245. "aspect": "9:16",
  246. "content_type": "lifestyle",
  247. "has_speech": true,
  248. "speech_coverage": 0.62,
  249. "existing_music": false,
  250. "overall_mood": ["warm", "playful"],
  251. "energy_mean": 0.62,
  252. "energy_curve": [{"t": 0, "energy": 0.3}, {"t": 4, "energy": 0.8}],
  253. "pacing": "fast-cut",
  254. "scenes": [{"start": 0, "end": 3.2, "description": "cafe exterior", "energy": 0.4}],
  255. "hook_window": [9.0, 15.0],
  256. "suggested_bpm": [95, 118],
  257. "avoid": ["dark cinematic drone", "aggressive trap", "lyrics-dense"],
  258. "search_queries": ["warm acoustic pop instrumental cafe"],
  259. "platform_hint": "instagram_reel",
  260. "analyzer": "local"
  261. }
  262. ```
  263. - **Primary:** Gemini video understanding when `GEMINI_API_KEY` is set.
  264. - **Fallback:** ffmpeg scene cuts + WAV energy / silence / ZCR heuristics. Optional `faster-whisper`, `scenedetect`, `librosa` if installed (`pip install 'sonicmatch-mcp[local-vl]'`).
  265. ## Music hub
  266. Pluggable, license-first. v0 ships:
  267. | Adapter | When | License reality |
  268. |---|---|---|
  269. | **Seed catalog** (`data/seed_tracks.json`) | always | 20 CC0 / CC-BY Reel beds + a vocal fixture + a CC-BY-NC fixture (NC is never auto-recommended) |
  270. | **Jamendo** | `JAMENDO_CLIENT_ID` | CC, check commercial |
  271. | **Freesound** | `FREESOUND_API_KEY` | CC, good for beds/loops not songs |
  272. | **User library JSON** | `SONICMATCH_LIBRARY_PATH` / `EPIDEMIC_LIBRARY_PATH` / `ARTLIST_LIBRARY_PATH` | **you** already licensed it; we do not scrape paid sites |
  273. | **Generate** | `generate_bed` | always `source=generated`; local sine demo unless you swap a real model |
  274. Ranking (weighted): mood/energy → instrumental if speech → duration/loop → BPM vs cut rate → license fit → tag embedding cosine → user constraints. `recommend_bgm` drops non-commercial and generated tracks instead of downranking them.
  275. Tracks are indexed in SQLite (`~/.cache/sonicmatch-mcp/db/tracks.sqlite`) with a 24-d tag embedding. If `lancedb` is installed (`pip install 'sonicmatch-mcp[embeddings]'`), vectors are also upserted there.
  276. Seed tracks have no remote audio files on purpose (you should host files you actually have the rights to). `preview_mix` synthesizes a CC0 demo bed so the mixer still runs offline. `generate_bed` is a catalog-miss fallback and is **not** cleared for ads.
  277. ## Docker
  278. ```bash
  279. docker build -t sonicmatch-mcp .
  280. # Loopback-only publish. The process inside the container has no HTTP auth.
  281. docker run --rm -p 127.0.0.1:8765:8765 -v sonic-cache:/data/cache sonicmatch-mcp
  282. ```
  283. ## Roadmap
  284. Catalog > new tools.
  285. - [x] Freesound adapter (loops / beds)
  286. - [x] Tag embeddings in SQLite (+ optional LanceDB extra)
  287. - [x] Epidemic Sound / Artlist as **user-owned JSON** plugins (no scrape)
  288. - [x] Beat-grid vs scene-cut suggestions (EDL-ish `suggest_cuts`)
  289. - [x] MCP registry listing (`server.json`)
  290. - [x] Generate tool, marked `source=generated` (local demo; swap a real model at your own legal risk)
  291. - [x] Official MCP registry listing via GitHub Release MCPB (see [PUBLISH.md](PUBLISH.md))
  292. - [x] Non-commercial licenses excluded from auto `recommend_bgm`
  293. - [ ] 20 seed beds a Reel editor would actually keep, with audio you host
  294. - [ ] User-owned Artlist / Epidemic JSON as the default path for ads
  295. - [ ] Real CLAP audio embeddings
  296. - [x] PyPI project metadata, console script, and tag-triggered Trusted Publishing (`.github/workflows/release.yml`)
  297. - [ ] First upload on PyPI (`uvx sonicmatch-mcp`). Maintainer steps are in [PUBLISH.md](PUBLISH.md). The name was unregistered as of 2026-10-21.
  298. ## Why this can be a good open-source project
  299. **Yes if** you nail: (1) video-native analysis, (2) license honesty on every row, (3) editor-shaped output (hook in/out, ducking, mix spec), (4) a catalog someone would keep.
  300. **No if** you only wrap YouTube Music search, or if the first five recs sound like leftover stock beds.
  301. Day-1 risk gates (enforced in code, not slogans):
  302. | Risk | Gate |
  303. |---|---|
  304. | **Content ID** | Every rec/search/get_track includes `content_id_warning`. CC/RF is never "Content-ID-safe". `content_id_risk` is `unknown` or `likely`, never `cleared`. |
  305. | **yt-dlp ToS / broken extractors** | Platform URL ingest is off unless `SONICMATCH_ALLOW_YTDLP=1`. Failures map to `YTDLP_EXTRACTOR` and tell you to pass a local file. |
  306. | **Upload size / SSRF** | HTTPS-only remote ingest, no `file://` / loopback / private IPs, `SONICMATCH_MAX_DOWNLOAD_MB` (default 200) on files, HTTP, and yt-dlp `--max-filesize`. |
  307. | **“Trending” is a closed Meta graph** | Queries for trending/viral/IG audio/TikTok sound return empty + `TRENDING_UNAVAILABLE`. `recommend_bgm` always sets `trending_available=false`. |
  308. | **Generation-model commercial terms** | `generate_bed` refuses unless `i_understand_not_commercially_cleared=true`. Generated tracks are excluded from auto `recommend_bgm`. |
  309. ## Use cases
  310. IG Reel / Story · Shopee product clip · YouTube Shorts agent · CapCut/Premiere companion · campus recap · podcast clipper · travel-vlog batch · brand-kit lock (BPM + no vocals) · silent-film / accessibility · multi-agent studio.
  311. ## Contributing
  312. [CONTRIBUTING.md](CONTRIBUTING.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) · [SECURITY.md](SECURITY.md) · [CHANGELOG.md](CHANGELOG.md) · [starter issues](docs/good-first-issues.md)
  313. ## License
  314. MIT. Track licenses are independent of the repo license.
  315. From [CodeCrafter](https://codecrafter.dev).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.