Show ffmpeg/yt-dlp availability and which music adapters have keys.

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.

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.

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.

Free-text search over seed + optional Jamendo / Freesound / user library.

Return one track's metadata, license string, attribution text, and URLs.

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 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).

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 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 a brand kit (BPM lock + no vocals + mood whitelist). Pass brand_kit=name to recommend_bgm.

Analyze up to 20 clips, cluster moods, return one consistent mini-playlist for the series.