mcpField
O
openverse-sfx

openverse-sfx

github.com/varnan-tech创意与媒体68714 次安装2 周前更新
代码仓库

关于 openverse-sfx

openverse-sfx 是一项通过 Openverse 为视频添加许可音乐和音效的技能，面向视频制作者。它以测量指导节拍对齐、混音、导出验证和署名记录，而非依赖主观听感。

主要功能

  1. 01搜索符合许可条件的 Openverse 音频
  2. 02追踪节拍并对齐视频剪切
  3. 03标准化音乐与音效电平
  4. 04测量并验证导出的 MP4
  5. 05将音频署名记录到 credits.txt

适用场景

  1. 01为视频剪辑寻找许可音效
  2. 02让场景剪切和标题贴合音乐节拍
  3. 03检查 MP4 导出后的响度与峰值
  4. 04为下载的音频整理署名信息

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/varnan-tech/opendirectory --skill openverse-sfx

安装后在 Claude Code 中输入/openverse-sfx确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

package.json
README.md
references/
ffmpeg_recipes.md
scripts/
beat_grid.py
sfx_fetch.py
sfx_normalize.py
sfx_search.py
verify_mix.py

详细介绍

openverse-sfx：通过测量验证、可免费使用的音效设计

你无法听见声音。此技能中的每项决策都通过测量（librosa、ffmpeg ebur128、波形图）做出，并在导出的文件上验证——绝不凭感觉，也绝不要告诉用户听起来不错。改为给用户一份简短的时间戳列表，让他们戴上耳机检查。

所有音频均来自 Openverse（https://api.openverse.org）：520 万个可免费使用的音频文件，无需 API 密钥，费用为 $0。绝不要在代码中合成音乐或音效——不要生成正弦波提示音或噪声突发。只使用真实的授权录音。

关键规则

  1. 必须筛选许可证。 只使用 Openverse 中符合 license=cc0,by,pdm 和 source=freesound,jamendo 的结果。scripts/sfx_search.py 会强制执行此规则——不要绕过它。
  2. 每种声音只搜索一次。 Openverse 匿名使用每天约限 200 次搜索。每种声音（"whoosh"、"ui pop"、"upbeat loop"）只搜索一次，然后从候选列表中挑选。不要改写查询词后重新搜索。
  3. 必须提供 credits.txt。 使用 CC BY 音频时，必须注明出处。每个下载文件的 attribution 字段都必须原样写入 credits.txt。scripts/sfx_fetch.py 会自动完成此操作。CC0/PDM 无需注明出处，但仍要记录。
  4. 先安装前置依赖。 如果缺少，请在开始前安装：ffmpeg，以及 pip install librosa matplotlib numpy scipy。
  5. 测量导出的 MP4，绝不要测量导出前的 WAV。 AAC 压缩和手机单声道播放会改变效果；只有最终交付的文件才算数。

工作流

步骤 1 - 音乐

使用用户提供的曲目，或在 Openverse 中搜索一首（python3 scripts/sfx_search.py --query "upbeat loop" --min-ms 15000）。记下来源和许可证。使用 scripts/sfx_fetch.py 将其下载到 sfx/，以便将出处信息写入 credits.txt。

步骤 2 - 节拍网格

运行 python3 scripts/beat_grid.py sfx/<music_file>。它会绘制 120 Hz 以下的波形（底鼓所在频段）和检测到的节拍网格，数值检测节拍是否错位，并写入 beats.json。打开 beatgrid.png：红线必须正好落在底鼓尖峰上。如果没有，请将整个网格移动半个节拍间隔（脚本会进行数值检查，并在半拍对齐的得分高出 >5% 时自动移动）。

步骤 3 - 将重要动作对齐节拍

将场景切换、标题出现和重要动画安排在 beats.json 中的节拍上。如果可以修改动画，就把切换对齐到最近的节拍。如果不能，就调整音乐的起始位置，让现有切换落在节拍上（在音乐输入上使用 -itsoffset / adelay）。

步骤 4 - 每次切换和重要动作配一个现成音效

如果项目已有音效库，先使用它；如果缺少需要的声音，请询问用户。否则，每种声音调用一次 sfx_search.py：移动用 whoosh，元素出现用 pop，点击用 click，打字用 typing sounds。从候选列表中为每个镜头的动作挑选最合适的音效，并使用 sfx_fetch.py 下载所选音效。

第 5 步 - 按照正确的层级混音
  • 旁白是最响的音轨；有人说话时，音乐会降低音量（使用侧链闪避或手动音量自动化）。
  • 音效应高于音乐，而且源文件的响度差异很大——根据测量结果对每个音轨进行归一化，绝不要使用固定的音量倍数：
    • 单次音效峰值归一化至 -3 dBTP，使用 scripts/sfx_normalize.py（单次音效依靠瞬态突出，因此按峰值而非 LUFS 归一化；绝不要对短音效运行 ffmpeg loudnorm——其 3 秒缓冲区会毁掉短文件）。
    • 音乐背景归一化至 -20 LUFS。
    • 具体命令见 references/ffmpeg_recipes.md。
  • 目标是交付的 MP4 集成响度达到 -16 LUFS，真峰值低于 -4 dBFS，确保 AAC 压缩后或手机扬声器以单声道播放时都不会削波。母带设为 TP=-4.5：AAC 编码会产生约 0.3-0.6 dB 的过冲，而母带设为 -4.0 时，混流后的文件会超出门限。
  • 阅读 references/ffmpeg_recipes.md，查看闪避、按节拍时间放置音效和两遍 loudnorm 的确切 ffmpeg 命令。
第 6 步 - 验证导出文件，然后提供检查时间点

对每个提示时间运行 python3 scripts/verify_mix.py final.mp4 --cue <t1> --cue <t2> ...。此脚本会使用 ebur128 测量导出的 MP4，在每个提示时间前后各截取一帧，并绘制带有提示线的导出波形。确认响度和峰值达标，且每个提示都落在波形尖峰上，其对应帧也显示剪辑或标题。然后提供 5 个供用户戴耳机检查的时间戳和 credits.txt 的路径。不要声称听起来不错。

脚本

脚本用途
scripts/sfx_search.py搜索 Openverse，并强制应用许可和来源筛选条件（freesound,jamendo 中的 cc0,by,pdm）；按时长筛选；生成包含署名字段的 JSON 候选列表
scripts/sfx_fetch.py使用 Python 标准库（urllib.request）将所选文件下载到 sfx/，并将原始署名信息追加到 credits.txt
scripts/sfx_normalize.py使用 ebur128 测量、增益处理并重新测量；音效单次播放使用峰值模式（-3 dBTP），背景音轨使用 LUFS 模式——适用于 loudnorm 会损毁短文件的情况
scripts/beat_grid.py使用 librosa 追踪节拍，进行数值化的节拍偏移锁定检查，绘制低于 120 Hz 的底鼓频段／节拍网格（beatgrid.png），并生成 beats.json
scripts/verify_mix.py检查导出 MP4 的 ebur128 响度和真峰值，截取提示时间前后帧，绘制波形图（verify/waveform.png），并给出 PASS／NEEDS FIX 结果

参考资料

  • references/ffmpeg_recipes.md - 提供音乐节拍偏移、按提示时间放置音效、人声旁白侧链闪避，以及两遍 loudnorm 以达到 -16 LUFS／-4 dBTP 的确切 ffmpeg 命令。编写任何 ffmpeg 命令前都要阅读此文件。

评论

支持 Markdown