openverse-sfx

​

Install

npx "@opendirectory.dev/skills" install openverse-sfx --target claude

npx skills add Varnan-Tech/opendirectory --skill openverse-sfx

/plugin marketplace add Varnan-Tech/opendirectory
/plugin install opendirectory-gtm-skills@opendirectory-marketplace

​

What It Does

• Searches Openverse’s 5.2M audio catalog for commercially usable music and sound effects (cc0, by, pdm from freesound and jamendo only)
• Downloads selected audio files into sfx/ and appends verbatim license attributions to credits.txt
• Tracks beats with librosa, isolates the sub-120 Hz kick-drum band, detects off-beat lock numerically, and plots beatgrid.png
• Aligns scene cuts and title reveals to beat timestamps in beats.json (or shifts music start timing so existing cuts land on the beat)
• Normalizes every audio layer by measurement: SFX one-shots by true peak (-3.0 dBTP) and music beds by integrated loudness (-20.0 LUFS)
• Ducks the music bed under voiceover using FFmpeg sidechain compression when speech is present
• Masters the final mix via two-pass EBU R128 loudnorm to -16.0 LUFS (-4.5 dBTP pre-AAC to leave headroom for encoder overshoot)
• Verifies the exported MP4 with ebur128, extracts before/after frames at every cue, renders verify/waveform.png, and returns 5 timestamps to check with headphones

​

Requirements

​

Setup

# Set up FFmpeg (macOS / Linux / Windows)
brew install ffmpeg

# Set up Python audio dependencies
pip install librosa matplotlib numpy scipy

​

How to Use

"Add sound to this video: launch-teaser.mp4"
"Add music and sound effects to my clip at ./demo.mp4"
"Sound design this product reveal video with an upbeat electronic loop and whoosh/pop SFX on every cut"
"Keep the voiceover in demo.mp4, duck a lo-fi music bed underneath, and add UI click sounds at the feature transitions"
"Find free licensed SFX on Openverse for my 15-second ad and mix it to -16 LUFS"

​

Why Measurement Instead of Guessing

• Off-beat lock correction: Beat trackers frequently lock onto hi-hat off-beats instead of the kick drum. beat_grid.py filters the waveform below 120 Hz, compares energy on the detected grid against a half-beat shift, and shifts the grid automatically when the off-beat alignment scores >5% higher.
• Peak normalization for short SFX: FFmpeg’s loudnorm filter uses a ~3-second rolling window that crushes short one-shots (a 0.5s pop drops by up to 35 dB). sfx_normalize.py measures true peak with ebur128=peak=true, applies exact linear gain to hit -3.0 dBTP, and re-measures to confirm tolerance.
• AAC encoder headroom: Mastering a WAV to -4.0 dBTP and encoding to 192k AAC adds 0.3-0.6 dB of true-peak overshoot. Two-pass mastering targets -4.5 dBTP on the WAV so the shipped MP4 stays safely below -4.0 dBTP.

​

Mix Hierarchy

​

Output

1. final.mp4: Video muxed with a 48 kHz / 192k AAC soundtrack mastered to -16 LUFS
2. credits.txt: Verbatim Openverse attribution lines for every downloaded track (required for CC BY audio)
3. beats.json & beatgrid.png: Detected tempo (BPM), beat timestamps in seconds, and kick-band alignment plot
4. verify/waveform.png & cue frames: Exported audio waveform with red cue markers plus before/after video frames (cue_<t>_before.png, cue_<t>_after.png) around every SFX cue
5. 5 headphone check timestamps: Specific moments in the final video for you to spot-check

​

Cost Per Run

• Openverse Audio API: free, no auth (~200 searches/day anonymous limit)
• Beat tracking, normalization, and verification (librosa, ffmpeg): local execution, $0
• Total: free

​

Standalone Scripts

# 1. Search Openverse for licensed music or SFX (cc0, by, pdm only)
python3 scripts/sfx_search.py --query "upbeat loop" --min-ms 15000
python3 scripts/sfx_search.py --query "whoosh" --max-ms 5000

# 2. Download a track and log its attribution to credits.txt
python3 scripts/sfx_fetch.py \
  --audio-url "https://..." \
  --name whoosh_cut1 \
  --attribution '"Deep Whoosh" by creator (CC0)'

# 3. Extract beat grid and check for off-beat lock
python3 scripts/beat_grid.py sfx/music.mp3 --out beats.json --plot beatgrid.png

# 4. Normalize SFX by true peak (-3 dBTP) or beds by LUFS (-20 LUFS)
python3 scripts/sfx_normalize.py sfx/whoosh_cut1.mp3 whoosh_n.wav
python3 scripts/sfx_normalize.py sfx/music.mp3 bed.wav --mode lufs --target -20

# 5. Verify the exported MP4 loudness, true peak, and cue alignment
python3 scripts/verify_mix.py final.mp4 --cue 0.8 --cue 2.4 --cue 4.1

​

Project Structure

openverse-sfx/
├── SKILL.md
├── README.md
├── package.json
├── scripts/
│   ├── sfx_search.py        Openverse search with license/source/duration filters
│   ├── sfx_fetch.py         Downloader + automatic credits.txt logger
│   ├── beat_grid.py         librosa beat tracker + sub-120 Hz off-beat lock check
│   ├── sfx_normalize.py     ebur128 peak/LUFS normalizer for short SFX and beds
│   └── verify_mix.py        Post-export MP4 loudness, peak, waveform, and frame verifier
└── references/
    └── ffmpeg_recipes.md    Exact FFmpeg commands for ducking, cue placement, and two-pass loudnorm

​

Plays Well With

​

License