name	video-clean-audio-replace
description	Identifies background music in a video with voiceover, downloads the full official track, syncs it, and replaces the original audio with clean song audio only. Use when the user has a video with background music and talking, wants to find the song, get the full track (not a preview clip), replace or clean video audio, or remove voiceover from music.

Replace noisy/mixed video audio (music + talking) with the full clean studio track, synced and muxed. Original audio is fully removed.

Prerequisites

brew install ffmpeg yt-dlp
pip3 install shazamio demucs soundfile scipy numpy librosa

demucs needs unrestricted execution (required_permissions: ["all"]) — sandbox blocks its OpenMP shared memory.

Workflow checklist

Task Progress:
- [ ] Step 1: Extract audio from video
- [ ] Step 2: Identify song (Shazam, multiple clips)
- [ ] Step 3: Download full official track (not preview)
- [ ] Step 4: Separate vocals (Demucs) for sync
- [ ] Step 5: Detect sync offset and replace audio
- [ ] Step 6: Verify output (Shazam + duration)

Step 1: Extract audio

WORKDIR="<project-or-tmp-dir>"
INPUT="<path-to-video>"
ffmpeg -y -i "$INPUT" -vn -acodec pcm_s16le -ar 44100 "$WORKDIR/extracted.wav"

Step 2: Identify song

Sample several clips — voiceover blocks some segments:

for start in 0 15 30 45 60 75; do
  ffmpeg -y -ss $start -t 12 -i "$WORKDIR/extracted.wav" -ac 1 -ar 44100 "$WORKDIR/clip_${start}s.wav"
done

Run identification (use the installed skill's scripts/ directory):

SKILL_DIR="$(dirname "$(find ~/.cursor/skills ~/.agents/skills -path '*/video-clean-audio-replace/SKILL.md' 2>/dev/null | head -1)")"
python3 "$SKILL_DIR/scripts/identify_song.py" "$WORKDIR"/clip_*.wav

Pick the track that matches on multiple clips. Note artist, title, album.

Step 3: Download full track

Always use the full official source — never Apple Music/Spotify 30s previews.

"yt-dlp -x --audio-format wav --audio-quality 0 \ -o "$WORKDIR/song.%(ext)s" \ "ytsearch1: