soundeffects

Sound Effects Track Generator

Setup (First Time Only)

This skill requires Python dependencies. Run once after installing:

cd <PLUGIN_DIR>/engine
uv sync

Where <PLUGIN_DIR> is wherever you cloned/installed this plugin (e.g., ~/.claude/plugins/soundeffects-claude-code/).

System requirements: ffmpeg, Python 3.10+, uv (Python package manager)

Workflow

1. Get file path from user argument (e.g., /soundeffects:soundeffects /path/to/video.mp4)
2. Verify file exists and get duration: ffmpeg -i <file> 2>&1 | grep Duration
3. Prepare audio for Whisper:
   • If video (.mp4, .mov, .mkv): extract audio: ffmpeg -i <video> -vn -acodec pcm_s16le -ar 16000 -ac 1 /tmp/sfx_audio_extract.wav -y
   • If audio (.wav, .mp3, .aac, .m4a): convert to 16kHz mono: ffmpeg -i <audio> -vn -acodec pcm_s16le -ar 16000 -ac 1 /tmp/sfx_audio_extract.wav -y
4. Transcribe with Whisper (word-level timestamps):

   cd <PLUGIN_DIR>/engine
   uv run python -c "
   import whisper, json
   model = whisper.load_model('base')
   result = model.transcribe('/tmp/sfx_audio_extract.wav', word_timestamps=True, language='en')
   words = []
   for seg in result['segments']:
       for w in seg.get('words', []):
           words.append({'word': w['word'].strip(), 'start': round(w['start'], 3), 'end': round(w['end'], 3)})
   for w in words:
       print(f'{w[\"start\"]:7.3f}s  {w[\"word\"]}')
   "
   

   IMPORTANT: <PLUGIN_DIR> = the root of this plugin. Find it by looking for the engine/ folder containing build_sfx_track.py. Common locations:
   • ~/.claude/plugins/soundeffects-claude-code/
   • Wherever the user cloned the repo
5. Map SFX placements -- analyze transcript, assign ~25-40 contextual SFX + 9-10 digital readouts
6. Update EVENTS_FINAL in <PLUGIN_DIR>/engine/build_sfx_track.py with the new placements
7. Build track:

   cd <PLUGIN_DIR>/engine
   uv run python build_sfx_track.py --output "<video_dir>/<video_name> - SFX Track.wav" --duration-ms <duration>
   

8. Open output folder: open <video_directory> (macOS) or xdg-open <video_directory> (Linux)