ui-sound-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

    ▁▂▄▆█▆▄▂▁

█  █ ██ ▄██▀ ██▀▄
█  █ ██  ▀▄  ██ █
▀██▀ ██ ▀██▄ ██▄▀

Describe what your UI should sound like. Preview it, tweak it, and download it from the browser.

    ▁▂▄▆█▆▄▂▁

█  █ ██ ▄██▀ ██▀▄
█  █ ██  ▀▄  ██ █
▀██▀ ██ ▀██▄ ██▄▀

描述你想要的UI音效是什么样的。在浏览器中预览、调整并下载它。

UI Sound Design

UI音效设计

Translate plain-English sound descriptions into working Web Audio API code. No audio engineering background needed — describe what you want to hear, and this skill provides the synthesis knowledge to make it real.

将通俗易懂的音效描述转化为可运行的Web Audio API代码。无需音频工程背景——描述你想要听到的音效，本技能会提供合成知识将其变为现实。

Workflow

工作流

Every sound follows this loop: Describe → Generate → Listen → Refine (with optional Review for auditing existing code)

每个音效都遵循这个循环：描述 → 生成 → 试听 → 优化（可选审核环节用于检查现有代码）

1. Describe

1. 描述

The user describes the sound in plain language. Ask clarifying questions using this framework:

Four questions before generating any sound:

What triggers it? (click, hover, toggle, notification, transition, success, error)
What's the emotional tone? (satisfying, subtle, urgent, playful, professional, minimal)
How prominent should it be? (barely perceptible, noticeable, attention-grabbing)
Any reference points? (iOS keyboard, Slack notification, macOS trash, game UI, "like a bubble popping")

If the user gives a vague request like "make a click sound", use sensible defaults from the recipes and generate immediately — don't over-ask.

用户用通俗语言描述音效。使用以下框架提出澄清问题：

生成音效前的四个问题：

触发场景是什么？（点击、悬停、切换、通知、过渡、成功、错误）
情绪基调是什么？（令人满意、微妙、紧急、活泼、专业、极简）
突出程度如何？（几乎察觉不到、明显、引人注意）
有没有参考示例？（iOS键盘音、Slack提示音、macOS回收站音效、游戏UI音效、“像气泡破裂的声音”）

如果用户给出模糊请求，比如“做一个点击音效”，直接使用配方中的合理默认值生成即可——不要过度追问。

2. Generate

2. 生成

Match the description to a sound category (see quick reference below)
Load the recipe from
```
references/sound-recipes.md
```
Apply the vocabulary bridge to translate adjectives into parameter changes
For novel sounds not covered by recipes, compose from building blocks in
```
references/web-audio-api.md
```
Output format: HTML preview by default (adapt
```
assets/sound-preview.html
```
), or ES module / React hook / class if requested

将描述匹配到对应的音效类别（见下方快速参考）
从
```
references/sound-recipes.md
```
加载配方
应用词汇映射表将形容词转化为参数调整
对于配方未覆盖的新型音效，从
```
references/web-audio-api.md
```
的基础模块组合构建
输出格式：默认是HTML预览（基于
```
assets/sound-preview.html
```
修改），若有需求也可输出ES模块、React Hook或类

3. Listen

3. 试听

Provide the HTML preview file so the user can open it in a browser and hear the sound immediately. Each sound includes a download button that exports a .wav file for use in production code or handoff to developers. Include labeled buttons for each sound variation. The preview must:

Handle AudioContext suspension (user gesture to start)
Use the singleton AudioContext pattern
Include visual feedback on play (the template handles this)

提供HTML预览文件，让用户可以在浏览器中打开并立即听到音效。每个音效都包含下载按钮，可导出.wav文件用于生产代码或交付给开发人员。为每个音效变体添加带标签的按钮。预览必须满足：

处理AudioContext暂停状态（需用户交互启动）
使用单例AudioContext模式
播放时提供视觉反馈（模板已处理此功能）

4. Refine

4. 优化

When the user gives feedback, translate it using the vocabulary bridge and adjust parameters. Common refinement patterns:

"I like it but..." → tweak 1-2 parameters
"Completely wrong" → try a different recipe/approach
"Too much/little" → scale the relevant parameter up/down
"More like X" → identify what makes X distinctive and match those characteristics

当用户给出反馈时，通过词汇映射表转化并调整参数。常见优化模式：

“我喜欢这个，但……” → 调整1-2个参数
“完全不对” → 尝试不同的配方/方法
“太响/太轻” → 按比例调整相关参数
“更像X” → 找出X的独特特征并匹配这些特性

5. Review (optional)

5. 审核（可选）

Enter review mode when the user says "review", "audit", or "check my sound code", or pastes existing Web Audio code for evaluation.

Steps:

Load rules from
```
references/audio-rules.md
```
Scan the code against each rule, starting with Critical priority
Report findings using the format in
```
audio-rules.md
```
— one line per violation with
```
file:line — [rule-id] description
```
Provide a summary table (pass/fail counts by priority)
Suggest concrete fixes for each failing rule

When to stay in generate mode: If the user's request is ambiguous (e.g., "here's my click sound" without asking for review), default to the generative workflow. Only enter review mode when the intent to audit is clear.

当用户说“审核”、“检查”或“查看我的音效代码”，或是粘贴现有Web Audio代码要求评估时，进入审核模式。

步骤：

从
```
references/audio-rules.md
```
加载规则
从最高优先级的关键规则开始，逐一扫描代码
按照
```
audio-rules.md
```
中的格式报告结果——每个违规项一行，格式为
```
文件:行号 — [规则ID] 描述
```
提供汇总表格（按优先级统计通过/失败数量）
为每个失败规则提供具体的修复建议

**何时保持生成模式：**如果用户的请求模糊（例如“这是我的点击音效”但未要求审核），默认使用生成工作流。只有当明确有审核意图时才进入审核模式。

Vocabulary Bridge

词汇映射表

This is the core translation layer. When the user uses subjective language, map it to synthesis parameters:

User Says	Parameter Change	Example
"Brighter"	Raise frequency or filter cutoff	Filter cutoff 1500 → 3000 Hz
"Warmer"	Lower filter cutoff, use sine/triangle wave	Switch sawtooth → sine, cutoff 3000 → 1200
"Darker"	Lower frequency, reduce high harmonics	Add lowpass filter at 800 Hz
"Snappier"	Shorter attack and decay	Decay 0.15 → 0.05s
"Softer"	Lower volume, longer attack, gentle envelope	Volume 0.3 → 0.15, attack 0 → 0.01s
"Louder" / "More prominent"	Raise volume (max 0.8)	Volume 0.2 → 0.4
"Fuller" / "Richer"	Layer oscillators, add detune	Add second osc detuned +7 cents
"Thinner"	Remove layers, use sine wave, raise highpass	Single sine, highpass at 500 Hz
"More metallic"	FM synthesis, inharmonic ratios	Mod ratio 1.4, increase mod depth
"More organic" / "Natural"	Use noise components, subtle randomness	Mix in filtered noise burst
"Shorter" / "Crisper"	Reduce total duration	Duration 0.15 → 0.06s
"Longer" / "More sustained"	Increase duration and sustain	Duration 0.1 → 0.3s, add sustain phase
"More playful"	Higher pitch, bounce/overshoot	Frequency +200 Hz, add pitch overshoot
"More professional"	Subtle, clean, minimal	Lower volume, sine wave, short duration
"Retro" / "8-bit"	Square wave, quantized pitch	Switch to square, use note frequencies
"Bubbly"	Rapid pitch drop, sine wave	startFreq 2000, quick exponential drop

这是核心的转换层。当用户使用主观描述时，将其映射为合成参数：

用户描述	参数调整	示例
“更明亮”	提高频率或滤波器截止频率	滤波器截止频率1500 → 3000 Hz
“更温暖”	降低滤波器截止频率，使用正弦/三角波	从锯齿波切换为正弦波，截止频率3000 → 1200
“更暗沉”	降低频率，减少高次谐波	添加800 Hz低通滤波器
“更干脆”	缩短起音和衰减时间	衰减时间0.15 → 0.05s
“更柔和”	降低音量，延长起音，使用平缓包络	音量0.3 → 0.15，起音0 → 0.01s
“更大声” / “更突出”	提高音量（最大0.8）	音量0.2 → 0.4
“更饱满” / “更丰富”	叠加振荡器，添加失谐	添加第二个失谐+7音分的振荡器
“更单薄”	移除叠加层，使用正弦波，提高高通滤波器频率	单个正弦波，500 Hz高通滤波器
“更具金属感”	FM合成，非谐和比例	调制比例1.4，增加调制深度
“更自然” / “有机感”	使用噪声成分，添加细微随机性	混入滤波噪声脉冲
“更短” / “更清脆”	缩短总时长	时长0.15 → 0.06s
“更长” / “更持续”	增加时长和延音	时长0.1 → 0.3s，添加延音阶段
“更活泼”	更高音调，弹跳/过冲	频率+200 Hz，添加音调过冲
“更专业”	微妙、干净、极简	降低音量，正弦波，短时长
“复古” / “8位机风格”	方波，量化音调	切换为方波，使用音符频率
“泡泡感”	快速降调，正弦波	起始频率2000，快速指数下降

Sound Categories — Quick Reference

音效类别——快速参考

Category	Duration	Recipe	Trigger	Key Character
Click	10–80ms	`references/sound-recipes.md#click`	Button press, tap	Noise burst, bandpass filtered
Toggle	80–200ms	`references/sound-recipes.md#toggle`	Switch on/off	Rising/falling pitch sweep
Hover	30–80ms	`references/sound-recipes.md#hover`	Mouse enter	Gentle, nearly subliminal
Success	200–500ms	`references/sound-recipes.md#success`	Task complete, save	Ascending major third
Error	150–400ms	`references/sound-recipes.md#error`	Validation fail, rejected	Descending, buzzy
Warning	150–350ms	`references/sound-recipes.md#warning`	Caution state	Double pulse, mid-range
Notification	200–800ms	`references/sound-recipes.md#notification`	New message, alert	Bell-like FM synthesis
Whoosh	100–400ms	`references/sound-recipes.md#whoosh`	Page transition, slide	Filtered noise sweep
Pop	30–80ms	`references/sound-recipes.md#pop`	Add item, bubble, appear	Sine with pitch drop
Custom	varies	`references/web-audio-api.md`	Anything else	Compose from building blocks

类别	时长	配方	触发场景	核心特征
点击音	10–80ms	`references/sound-recipes.md#click`	按钮按压、轻触	噪声脉冲，带通滤波
切换音	80–200ms	`references/sound-recipes.md#toggle`	开关切换	音调上升/下降扫频
悬停音	30–80ms	`references/sound-recipes.md#hover`	鼠标进入	柔和，几乎难以察觉
成功提示音	200–500ms	`references/sound-recipes.md#success`	任务完成、保存	上行大三度
错误提示音	150–400ms	`references/sound-recipes.md#error`	验证失败、操作被拒	下行，嗡嗡声
警告提示音	150–350ms	`references/sound-recipes.md#warning`	警告状态	双脉冲，中频段
通知提示音	200–800ms	`references/sound-recipes.md#notification`	新消息、警报	钟铃状FM合成
过渡呼啸音	100–400ms	`references/sound-recipes.md#whoosh`	页面过渡、滑动	滤波噪声扫频
弹出音	30–80ms	`references/sound-recipes.md#pop`	添加项目、气泡、出现	正弦波降调
自定义	可变	`references/web-audio-api.md`	其他场景	从基础模块组合构建

Critical Implementation Rules

关键实现规则

AudioContext user-gesture requirement

AudioContext用户交互要求

Browsers block audio until a user interaction (click, tap, keydown). Always initialize or resume the AudioContext inside an event handler. The singleton pattern in

references/web-audio-api.md

handles this.

浏览器会阻止音频播放，直到用户进行交互（点击、轻触、按键）。务必在事件处理器内初始化或恢复AudioContext。

references/web-audio-api.md

中的单例模式已处理此问题。

Never ramp gain to zero

切勿将增益线性降至零

exponentialRampToValueAtTime(0, ...)

throws an error. Always ramp to

0.001

— it's inaudible but mathematically valid. This applies to every sound. No exceptions.

exponentialRampToValueAtTime(0, ...)

会抛出错误。务必降至

0.001

——这个音量不可闻，但在数学上是有效的。所有音效都需遵循此规则，无例外。

Node cleanup

节点清理

OscillatorNodes auto-disconnect after
```
stop()
```
— no manual cleanup needed
BufferSourceNodes are one-shot — create a new one each play
For long-lived filter/gain nodes, call
```
disconnect()
```
when done
Never create a new AudioContext per sound — use the singleton

OscillatorNode在
```
stop()
```
后会自动断开连接——无需手动清理
BufferSourceNode是一次性的——每次播放都要创建新的实例
对于长期存在的滤波器/增益节点，使用完毕后调用
```
disconnect()
```
切勿为每个音效创建新的AudioContext——使用单例模式

Volume safety

音量安全

Default volume:
```
0.3
```
(gain value)
Maximum volume:
```
0.8
```
— never exceed this
Hover sounds:
```
0.03–0.08
```
(barely perceptible)
UI sounds should complement, not dominate — err on the side of quiet

默认音量：
```
0.3
```
（增益值）
最大音量：
```
0.8
```
——切勿超过此值
悬停音效：
```
0.03–0.08
```
（几乎察觉不到）
UI音效应起到补充作用，而非主导——宁小勿大

Scheduling precision

调度精度

Capture

const now = ctx.currentTime

once at the start of each sound function. Derive all scheduling times from

now

. Never read

currentTime

multiple times.

在每个音效函数开始时捕获一次

const now = ctx.currentTime

。所有调度时间都基于

now

计算。切勿多次读取

currentTime

。

Use exponential ramps by default

默认使用指数渐变

exponentialRampToValueAtTime

sounds natural for both volume and frequency.

linearRampToValueAtTime

sounds mechanical. Only use linear for sub-50ms transitions.

exponentialRampToValueAtTime

在音量和频率调整上听起来更自然。

linearRampToValueAtTime

听起来机械生硬。仅在小于50ms的过渡中使用线性渐变。

Output Formats

输出格式

HTML Preview (default)

HTML预览（默认）

Adapt

assets/sound-preview.html

. Self-contained, no dependencies, opens in any browser. Best for the iterative listen-refine loop. Includes WAV download — click the download button on any sound to get a .wav file. Sound functions must use

(ctx, dest)

parameters with fallback defaults for download support, and each sound needs a matching entry in the

durations

map.

基于

assets/sound-preview.html

修改。自包含、无依赖，可在任何浏览器中打开。最适合“试听-优化”的迭代循环。包含WAV下载功能——点击任意音效的下载按钮即可获取.wav文件。音效函数必须使用

(ctx, dest)

参数，并为下载支持提供回退默认值，每个音效都需要在

durations

映射中添加对应条目。

ES Module

ES模块

javascript

// ui-sounds.js
export function playClick(options) { /* ... */ }
export function playSuccess(options) { /* ... */ }

javascript

// ui-sounds.js
export function playClick(options) { /* ... */ }
export function playSuccess(options) { /* ... */ }

React Hook

javascript

// useUISound.js
export function useUISound() {
  const ctxRef = useRef(null);
  const getCtx = useCallback(() => { /* singleton */ }, []);
  return { playClick, playSuccess, /* ... */ };
}

javascript

// useUISound.js
export function useUISound() {
  const ctxRef = useRef(null);
  const getCtx = useCallback(() => { /* singleton */ }, []);
  return { playClick, playSuccess, /* ... */ };
}

Sound Library Class

音效库类

Use the

UISoundLibrary

class from

references/sound-recipes.md

. Bundles all sounds with enable/disable and master volume control.

使用

references/sound-recipes.md

中的

UISoundLibrary

类。将所有音效打包，支持启用/禁用和主音量控制。

Resources

资源

references/

web-audio-api.md
— Core Web Audio API building blocks: oscillators, envelopes, filters, noise, FM synthesis, factory patterns, common mistakes. Load when building custom sounds or understanding low-level mechanics.
sound-recipes.md
— Complete working implementations for all 9 sound categories plus a bundled
```
UISoundLibrary
```
class. Each recipe includes parameters, code, tuning guide, and variations. Start here for most requests.
audio-rules.md
— Formal validation rules with IDs, priorities, and pass/fail examples. Load when reviewing existing code or when you need to verify generated output against best practices.
tone-js.md
— Tone.js abstractions for faster prototyping. Simplified synth types, recipe equivalents, effects, and a conversion guide to vanilla Web Audio. Load when the user prefers Tone.js or wants rapid iteration.

web-audio-api.md
—— 核心Web Audio API基础模块：振荡器、包络、滤波器、噪声、FM合成、工厂模式、常见错误。在构建自定义音效或理解底层机制时加载。
sound-recipes.md
—— 所有9种音效类别的完整可运行实现，以及打包的
```
UISoundLibrary
```
类。每个配方包含参数、代码、调优指南和变体。大多数请求从这里开始。
audio-rules.md
—— 正式验证规则，包含ID、优先级和通过/失败示例。在审核现有代码或需要验证生成输出是否符合最佳实践时加载。
tone-js.md
—— Tone.js抽象层，用于快速原型开发。简化的合成器类型、等效配方、效果，以及与原生Web Audio的转换指南。当用户偏好Tone.js或需要快速迭代时加载。

assets/

sound-preview.html
— Self-contained HTML template with all 10 default sounds, visual feedback, and AudioContext handling. Adapt this for every preview output.

sound-preview.html
—— 自包含HTML模板，包含10种默认音效、视觉反馈和AudioContext处理。每次预览输出都基于此模板修改。