sound-effects

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sound effects

音效（Sound effects）

Claude can't hear. So this skill never judges sound by feel: it measures every step, and it hands the user 5 timestamps to check with headphones. It never says "it sounds good".

The approach is Vox's sound-pass prompt (@Voxyz_ai, https://x.com/Voxyz_ai/status/2109358372873183564, 11 Oct 2026). Keep that credit.

Claude 听不见。因此，这个 skill 绝不凭感觉判断声音：它会测量每一步，并向用户提供 5 个时间戳，以便佩戴耳机检查。它绝不会声称 "it sounds good"。

这种方法来自 Vox 的 sound-pass prompt（@Voxyz_ai，https://x.com/Voxyz_ai/status/2109358372873183564，2026 年 10 月 11 日）。请保留这项署名。

Default kit (use this first)

默认素材包（Default kit，优先使用）

sfx/manifest.json

→

default_kit

: one sound per core category, picked by ear by Bart (12 Oct 2026). Use it unless the user asks for something else.

Category	Sound	Where it comes from
whoosh	"Whoosh" by qubodup	bundled `sfx/kit/whoosh.ogg` (CC0)
click	"Classic Click" by adh.dreaming	bundled `sfx/kit/click.ogg` (CC0)
pop	"POP SFX Neutral" by ethernel0	bundled `sfx/kit/pop.ogg` (CC0)
riser	"Cinematic Riser #3 subtle"	bundled `sfx/kit/riser.ogg` (CC0)
impact	"soft_impact3" by peoplearehappy	bundled `sfx/kit/impact.ogg` (CC0)
tick	"Click / Tick" by Squirrel_404	bundled `sfx/kit/tick.ogg` (CC0)
typing	Mixkit "Fast laptop keyboard typing" (#1392)	downloaded at runtime into `<out>/sound-effects-cache/` (Mixkit licence: never commit it)

Everything else in the manifest is an alternative (

alt_categories

lists which categories can stand in for each other). See

TOP-PICKS.md

for credits.

sfx/manifest.json

→

default_kit

：每个核心 category 配一个声音，由 Bart 凭耳挑选（2026 年 10 月 12 日）。除非用户要求其他内容，否则使用它。

Category	Sound	Where it comes from
whoosh	qubodup 的 "Whoosh"	内置 `sfx/kit/whoosh.ogg` （CC0）
click	adh.dreaming 的 "Classic Click"	内置 `sfx/kit/click.ogg` （CC0）
pop	ethernel0 的 "POP SFX Neutral"	内置 `sfx/kit/pop.ogg` （CC0）
riser	"Cinematic Riser #3 subtle"	内置 `sfx/kit/riser.ogg` （CC0）
impact	peoplearehappy 的 "soft_impact3"	内置 `sfx/kit/impact.ogg` （CC0）
tick	Squirrel_404 的 "Click / Tick"	内置 `sfx/kit/tick.ogg` （CC0）
typing	Mixkit "Fast laptop keyboard typing"（#1392）	运行时下载到 `<out>/sound-effects-cache/` （Mixkit licence：不得 commit）

manifest 中其余内容均为替代项（

alt_categories

列出哪些 categories 可以相互替代）。署名见

TOP-PICKS.md

。

Rules

规则

Never synthesize music or sound effects in code (no oscillator or sine beeps). Use real recorded files.
Sound effects: use the bundled library first.
```
sfx/manifest.json
```
lists every file with its category, duration, source and licence. All bundled files are CC0.
If the bundled library has nothing that fits, use the
```
runtime
```
entries in the manifest (Mixkit). Download them into the user's project, never into this skill folder, and never commit them. Mixkit allows use in videos but not standalone redistribution.
Music: a track the user gives you, or one with a licence that allows monetised YouTube use (Mixkit Stock Music Free License, CC0). Write the source and licence into
```
SOUND.md
```
. If neither exists, ask the user.
Measure the exported MP4, never the intermediate WAV.

绝不要在代码中合成 music 或 sound effects（不要使用 oscillator 或 sine beeps）。使用真实录制的文件。
Sound effects：优先使用内置库。
```
sfx/manifest.json
```
列出了每个文件的 category、duration、source 和 licence。所有内置文件均为 CC0。
如果内置库中没有合适的内容，请使用 manifest 中的
```
runtime
```
条目（Mixkit）。将它们下载到用户项目中，绝不下载到此 skill 文件夹，也不得 commit。Mixkit 允许在视频中使用，但不允许单独再分发。
Music： 使用用户提供的曲目，或使用 licence 允许在可变现的 YouTube 视频中使用的曲目（Mixkit Stock Music Free License、CC0）。将 source 和 licence 写入
```
SOUND.md
```
。如果两者均不存在，请询问用户。
测量导出的 MP4，绝不测量中间 WAV。

1. Set up

1. 设置

Needs ffmpeg and Python 3.10+. Install into a folder you can delete:

python3 -m venv .sound-effects
.sound-effects/bin/pip install librosa soundfile numpy scipy matplotlib

需要 ffmpeg 和 Python 3.10+。安装到一个随时可以删除的文件夹中：

python3 -m venv .sound-effects
.sound-effects/bin/pip install librosa soundfile numpy scipy matplotlib

2. Build the cue list

2. 构建 cue list

Read the video's duration and fps with

ffprobe

. List every moment that needs a sound. Take them from the composition source when you can (HyperFrames/Remotion timeline, GSAP labels, motion-broll

plan.json

). Otherwise detect scene cuts with

ffmpeg -i in.mp4 -vf "select='gt(scene,0.3)',showinfo" -f null -

. Write

cues.json

[{"t": 2.0, "type": "scene_cut", "desc": "cut to card"}, {"t": 4.2, "type": "typing", "dur": 1.3, "desc": "..."}]

The cue types map to library categories (

category_map

in the manifest):

Cue type	Category	Notes
movement (slide, camera move)	whoosh	starts 2 frames early; pick length to match the move
scene_cut	whoosh	short whoosh, 2 frames early ( `transition` sounds are alternatives)
appear	pop	on the frame
click	click	on the frame
typing	typing	looped/trimmed to `dur` , quiet
build_up	riser	ends on the next hit
reveal	impact	the loudest SFX
success	pop	( `ding` sounds are alternatives)
error_or_tech	glitch
hover_or_small_ui	tick	very quiet ( `ui-blip` and `click` are alternatives)
bed	ambience	under everything, optional

Use one sound per cue. Vary takes within a category so repeats don't sound robotic.

使用

ffprobe

读取视频的 duration 和 fps。列出每个需要声音的时刻。如果可以，请从 composition source 获取这些时刻（HyperFrames/Remotion timeline、GSAP labels、motion-broll

plan.json

）。否则，使用

ffmpeg -i in.mp4 -vf "select='gt(scene,0.3)',showinfo" -f null -

检测 scene cuts。将

cues.json

写为

[{"t": 2.0, "type": "scene_cut", "desc": "cut to card"}, {"t": 4.2, "type": "typing", "dur": 1.3, "desc": "..."}]

。

cue type 与库中 categories 的映射方式如下（

category_map

位于 manifest 中）：

Cue type	Category	Notes
movement（滑动、镜头移动）	whoosh	提前 2 帧开始；选择与移动时长匹配的长度
scene_cut	whoosh	短促的 whoosh，提前 2 帧开始（ `transition` sounds 可作为替代项）
appear	pop	与该帧对齐
click	click	与该帧对齐
typing	typing	循环或裁剪至 `dur` ，音量较低
build_up	riser	结束于下一次 hit
reveal	impact	音量最大的 SFX
success	pop	（ `ding` sounds 可作为替代项）
error_or_tech	glitch
hover_or_small_ui	tick	音量非常低（ `ui-blip` 和 `click` 可作为替代项）
bed	ambience	位于所有声音之下，可选

每个 cue 使用一个声音。在同一 category 内使用不同 take，避免重复音效显得机械。

3. Beat grid, and check it

3. 构建并检查 beat grid

Run

librosa.beat.beat_track

. librosa sometimes locks onto the off-beat. Low-pass the music below 120 Hz, plot it against the beat lines for the first 4 bars, and compare where the kicks land. If the kicks don't sit on the lines, shift the whole grid by the median offset and plot again. Show the user

beatgrid.png

运行

librosa.beat.beat_track

。librosa 有时会锁定到 off-beat。 对音乐进行 120 Hz 以下的 low-pass，将其与前 4 小节的 beat lines 叠加绘制，并比较 kicks 的落点。如果 kicks 没有落在 beat lines 上，则按 median offset 整体移动 grid，再次绘制。向用户展示

beatgrid.png

。

4. Put the big moves on the beat

4. 将关键动作放在节拍上

Hard cuts and reveals should land on a beat. If you can change the animation timings, change them. If you can't, move where the music starts (search offsets and pick the one with the smallest cut-to-beat error). Report the error per cut in ms.

Hard cuts 和 reveals 应落在 beat 上。如果可以更改动画 timing，就更改；如果不行，则调整音乐的起始位置（搜索 offsets，并选择 cut-to-beat error 最小的那个）。以 ms 为单位报告每次 cut 的 error。

5. Place SFX and mix

5. 放置 SFX 并混音

Priority: voiceover > SFX > music. The music bed sits around -12 dB under the SFX and ducks under any voiceover by 8–12 dB. Target about -16 LUFS integrated with true peak below -4 dBFS, so nothing clips after AAC compression or on a phone speaker. Export, measure, adjust gain or add a limiter, then export and measure again:

ffmpeg -nostats -i after.mp4 -af ebur128=peak=true -f null - 2>&1 | tail -12
ffmpeg -nostats -i after.mp4 -ac 1 -af ebur128=peak=true -f null - 2>&1 | tail -12   # mono check

优先级：voiceover > SFX > music。 music bed 的音量应比 SFX 低约 12 dB，并在出现 voiceover 时再 duck 8–12 dB。目标为 integrated loudness 约 -16 LUFS，且 true peak 低于 -4 dBFS，这样 AAC 压缩后或手机扬声器播放时都不会削波。导出、测量、调整 gain 或添加 limiter，然后再次导出并测量：

ffmpeg -nostats -i after.mp4 -af ebur128=peak=true -f null - 2>&1 | tail -12
ffmpeg -nostats -i after.mp4 -ac 1 -af ebur128=peak=true -f null - 2>&1 | tail -12   # mono check

6. Prove it

6. 提供验证证据

For every cue, grab one frame just before and just after it from the exported MP4, and plot the waveform around it (

checks/cue-XX.png

). Then pick the 5 riskiest timestamps (largest beat error, long sounds such as typing and risers, the reveal) and give them to the user to check with headphones.

对于每个 cue，从导出的 MP4 中截取其前一帧和后一帧各一帧，并绘制其附近的 waveform（

checks/cue-XX.png

）。然后选出 5 个风险最高的时间戳（beat error 最大、typing 和 risers 等长声音、reveal），交给用户佩戴耳机检查。

Original-quality files

原始质量文件

The bundled sounds are compressed OGG Vorbis previews (trimmed, normalised, often mono), which is fine for most videos. If a sound is too low quality for the job (audible artefacts, a close-up hero sound, a final master), fetch the original:

Look up the entry's
```
source_url
```
in
```
sfx/manifest.json
```
. Every bundled and
```
default_kit
```
entry has one.
Freesound (
```
freesound.org/people/<user>/sounds/<id>/
```
): the original is the Download button on that page. It needs a free Freesound account, so ask the user to download it (or use their API key if they give you one).
Kenney (
```
kenney.nl/assets/<pack>
```
): download the pack zip from that page. Each Kenney entry's
```
original_file
```
in the manifest names the exact file, e.g.
```
kenney_interface-sounds.zip → Audio/click_001.ogg
```
. The rule: drop the prefix (
```
kenney-interface-
```
→ interface-sounds,
```
kenney-ui-
```
→ ui-audio,
```
kenney-digital-
```
→ digital-audio,
```
kenney-impact-
```
→ impact-sounds,
```
kenney-sci-
```
→ sci-fi-sounds), then match the rest inside
```
Audio/
```
ignoring case, with
```
-
```
read as
```
_
```
(
```
kenney-digital-phaserup1
```
→
```
Audio/phaserUp1.ogg
```
,
```
kenney-impact-impactpunch-heavy-000
```
→
```
Audio/impactPunch_heavy_000.ogg
```
). Kenney's originals are OGG too, but unprocessed.
Save originals into the user's project (for example
```
sound-effects-cache/originals/
```
), never into this skill folder, and pass the file to the script via
```
--swaps
```
or by editing a copy of the manifest. Apply the same trim and level as the bundled file.

内置声音是压缩过的 OGG Vorbis 预览（已裁剪、标准化，且通常为单声道），适用于大多数视频。如果某个声音的质量不足以完成任务（存在明显 artefacts、近距离 hero sound 或 final master），请获取原文件：

在
```
sfx/manifest.json
```
中查找该条目的
```
source_url
```
。每个 bundled 和
```
default_kit
```
条目都有该地址。
Freesound（
```
freesound.org/people/<user>/sounds/<id>/
```
）：原文件是该页面上的 Download 按钮。它需要免费的 Freesound 账户，因此请让用户下载（或在用户提供 API key 时使用该 key）。

Kenney（

kenney.nl/assets/<pack>

）：从该页面下载 pack zip。manifest 中每个 Kenney 条目的

original_file

会指定准确文件，例如

kenney_interface-sounds.zip → Audio/click_001.ogg

。规则：去掉前缀（

kenney-interface-

→

interface-sounds

，

kenney-ui-

→

ui-audio

，

kenney-digital-

→

digital-audio

，

kenney-impact-

→

impact-sounds

，

kenney-sci-

→

sci-fi-sounds

），然后在

Audio/

中匹配其余部分，忽略大小写，并将

视为

（

kenney-digital-phaserup1

→

Audio/phaserUp1.ogg

，

kenney-impact-impactpunch-heavy-000

→

Audio/impactPunch_heavy_000.ogg

）。Kenney 的原文件也是 OGG，但未经处理。

将原文件保存到用户项目中（例如
```
sound-effects-cache/originals/
```
），绝不要保存到此 skill 文件夹，并通过
```
--swaps
```
将文件传给脚本，或编辑 manifest 的副本。对 bundled 文件应用相同的裁剪和电平处理。

Find more sounds

查找更多声音

When the user wants more or different sounds, search these sources, suggest 3–5 candidates with a link, creator and licence for each, and let the user pick. Only use or redistribute a sound as its licence allows.

Source	Search	Licence notes
Freesound	`https://freesound.org/search/?q=<words>&f=license:"Creative Commons 0"`	Use the CC0 filter. CC0 can be bundled and needs no credit (credit anyway). CC-BY needs credit in the video description; never bundle CC-BY-NC or use it commercially.
Kenney	`https://kenney.nl/assets/category:Audio`	All CC0. Free to use and bundle.
Mixkit	`https://mixkit.co/free-sound-effects/<category>/` (e.g. `whoosh` , `typing` )	Mixkit SFX Free License: fine in videos, including monetised ones, but no redistribution. Download only into the user's project at runtime; never commit or bundle it.
Pixabay	`https://pixabay.com/sound-effects/search/<words>/`	Free in videos, no credit needed, but no standalone redistribution. The user downloads it in a browser; never bundle it.
Sonniss GDC bundles	`https://sonniss.com/gameaudiogdc/`	Royalty-free in videos; no raw redistribution or AI training. Local use only.
YouTube Audio Library	YouTube Studio → Audio Library	For YouTube videos only; available only inside Studio. Never bundle it.

Only CC0 sounds may be added to this repo's

sfx/

folder, each with a manifest entry (file, category, duration, source_url, licence, attribution) and a row in

LICENSES.md

当用户需要更多或不同声音时，搜索这些来源，建议 3–5 个候选，每个附上 link、creator 和 licence，让用户选择。只能按照 licence 允许的方式使用或再分发声音。

Source	Search	Licence notes
Freesound	`https://freesound.org/search/?q=<words>&f=license:"Creative Commons 0"`	使用 CC0 过滤器。CC0 可以随仓库打包且无须署名（但仍建议署名）。CC-BY 需要在视频 description 中署名；绝不要打包 CC-BY-NC，也不得将其用于商业用途。
Kenney	`https://kenney.nl/assets/category:Audio`	全部为 CC0。可自由使用和打包。
Mixkit	`https://mixkit.co/free-sound-effects/<category>/` （例如 `whoosh` 、 `typing` ）	Mixkit SFX Free License：可用于视频，包括可变现的视频，但不允许再分发。仅在运行时下载到用户项目中；绝不要 commit 或 bundle。
Pixabay	`https://pixabay.com/sound-effects/search/<words>/`	在视频中免费使用且无须署名，但不允许单独再分发。用户需在浏览器中下载；绝不要 bundle。
Sonniss GDC bundles	`https://sonniss.com/gameaudiogdc/`	在视频中免版税使用；不允许原始文件再分发，也不允许用于 AI training。仅限本地使用。
YouTube Audio Library	YouTube Studio → Audio Library	仅适用于 YouTube 视频；只能在 Studio 内获取。绝不要 bundle。

只有 CC0 声音可加入此仓库的

sfx/

文件夹；每个声音都需有一条 manifest 条目（file、category、duration、source_url、licence、attribution），并在

LICENSES.md

中有一行记录。

Script

脚本

scripts/sound_pass.py

runs steps 3–6 end to end:

.sound-effects/bin/python scripts/sound_pass.py --video silent.mp4 --cues cues.json \
  --music track.mp3 --manifest sfx/manifest.json --out out/

It outputs

after.mp4

report.html

SOUND.md

(log, cue → file table, LUFS and peak numbers, the 5 timestamps),

beatgrid.png

and

checks/

. Read its log and fix anything over target. If you changed the animation timings, re-render first.

scripts/sound_pass.py

端到端执行步骤 3–6：

.sound-effects/bin/python scripts/sound_pass.py --video silent.mp4 --cues cues.json \
  --music track.mp3 --manifest sfx/manifest.json --out out/

它会输出

after.mp4

、

report.html

、

SOUND.md

（包含日志、cue → file 对照表、LUFS 和 peak 数值以及 5 个时间戳）、

beatgrid.png

和

checks/

。读取其日志，并修复所有超出目标的值。如果更改了动画 timing，请先重新渲染。

7. Swap report

7. 替换报告（Swap report）

sound_pass.py

also writes

report.html

. It lists every cue with its timestamp, category, the sound used (with a play button), the source page, licence and credit, plus the alternatives in that category, each with a play button and a "let model decide" option. Open it for the user. They choose, click Download swaps.json, and you re-run with

--swaps swaps.json

"auto"

means pick another sound from the alternatives. Keep cue indices stable between runs.

sound_pass.py

还会写入

report.html

。它会列出每个 cue 的 timestamp、category、使用的 sound（带播放按钮）、source page、licence 和 credit，以及该 category 中的 alternatives；每个 alternative 都带有播放按钮和一个 "let model decide" 选项。为用户打开该文件。用户做出选择后，点击 Download swaps.json，然后使用

--swaps swaps.json

重新运行。

"auto"

表示从 alternatives 中选择另一个声音。各次运行之间必须保持 cue indices 稳定。

Report to the user

向用户报告

Report the music source and licence, the beat-grid result (shifted or not, and by how much), the cut-to-beat errors, final LUFS and true peak (stereo and mono), and the 5 timestamps. Don't tell them it sounds good.

向用户报告 music source 和 licence、beat-grid 结果（是否 shift 以及 shift 幅度）、cut-to-beat errors、最终 LUFS 和 true peak（stereo 和 mono），以及 5 个时间戳。不要告诉他们 "it sounds good"。