ui-sound-design

  ▁ ▃ ▅ ▇ ▅ ▃ ▁     ▁ ▃ ▅ ▇ ▅ ▃ ▁     ▁ ▃ ▅ ▇ ▅ ▃ ▁
██╗   ██╗██╗    ███████╗ ██████╗ ██╗   ██╗███╗   ██╗██████╗
██║   ██║██║    ██╔════╝██╔═══██╗██║   ██║████╗  ██║██╔══██╗
██║   ██║██║    ███████╗██║   ██║██║   ██║██╔██╗ ██║██║  ██║
██║   ██║██║    ╚════██║██║   ██║██║   ██║██║╚██╗██║██║  ██║
╚██████╔╝██║    ███████║╚██████╔╝╚██████╔╝██║ ╚████║██████╔╝
 ╚═════╝ ╚═╝    ╚══════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═══╝╚═════╝
      ░ ▒ ▓ █ ▓ ▒ ░     ░ ▒ ▓ █ ▓ ▒ ░     ░ ▒ ▓ █ ▓ ▒ ░
       ██████╗ ███████╗███████╗██╗ ██████╗ ███╗   ██╗
       ██╔══██╗██╔════╝██╔════╝██║██╔════╝ ████╗  ██║
       ██║  ██║█████╗  ███████╗██║██║  ███╗██╔██╗ ██║
       ██║  ██║██╔══╝  ╚════██║██║██║   ██║██║╚██╗██║
       ██████╔╝███████╗███████║██║╚██████╔╝██║ ╚████║
       ╚═════╝ ╚══════╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝
  ▇ ▅ ▃ ▁ ▃ ▅ ▇     ▇ ▅ ▃ ▁ ▃ ▅ ▇     ▇ ▅ ▃ ▁ ▃ ▅ ▇

描述你的 UI 应该呈现怎样的声音。 在浏览器中预览、调整并下载。

UI 音效设计

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

工作流

每种声音都遵循以下循环：描述 → 生成 → 聆听 → 优化（可选的 审查 用于审核现有代码）

1. 描述

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

生成声音前的四个问题：

1. 什么操作会触发它？（点击、悬停、切换、通知、过渡、成功、错误）

2. 情绪基调是什么？（悦耳、微妙、紧迫、活泼、专业、简约）

3. 声音应该多突出？（几乎听不出来、明显、引人注意）

4. 有什么参考示例？（iOS 键盘、Slack 通知、macOS 废纸篓、游戏 UI、“像泡泡破裂”）

5. 有音频参考文件吗？ 如果用户有想要模仿的 .wav 或 .mp3 文件，请让他们运行分析器：

   node skills/ui-sound-design/tools/analyze-sound.mjs path/to/reference.wav
   

   然后粘贴输出结果。收到声音配置文件后：

   1. 加载 references/audio-file-references.md，查看解读指南
   2. 阅读 synthesis_suggestion 代码块，获取初始参数
   3. 使用 recipe_starting_point 匹配最接近的声音类别
   4. 从 references/sound-recipes.md 加载对应配方
   5. 使用配置文件建议的参数覆盖配方默认值
   6. 应用配置文件 VOCABULARY MATCH 部分中的词汇映射术语
   7. 按照常规流程继续生成

如果用户提出“做一个点击声”之类的模糊请求，请采用配方中的合理默认值并立即生成——不要追问太多。

2. 生成

1. 将描述匹配到一个声音类别（参见下方的速查表）
2. 从 references/sound-recipes.md 加载配方
3. 应用词汇映射，将形容词转换为参数调整
4. 对于配方未涵盖的新颖声音，根据 references/web-audio-api.md 中的基础组件进行组合
5. 默认输出格式：HTML 预览（调整 assets/sound-preview.html），也可按需输出 ES 模块、React hook 或类

3. 聆听

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

• 处理 AudioContext 挂起状态（通过用户手势启动）
• 使用单例 AudioContext 模式
• 播放时提供视觉反馈（模板已处理此项）

4. 优化

用户提供反馈时，使用词汇映射进行转换并调整参数。常见的优化方式：

• “我喜欢，但……” → 调整 1-2 个参数
• “完全不对” → 尝试其他配方或方法
• “太强/太弱” → 提高/降低相关参数
• “更像 X” → 找出 X 的鲜明特点，并匹配这些特征

5. 审查（可选）

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

步骤：

1. 从 references/audio-rules.md 加载规则
2. 按照每条规则检查代码，从“严重”优先级开始
3. 使用 audio-rules.md 中的格式报告发现的问题——每项违规占一行，格式为 file:line — [rule-id] description
4. 提供汇总表（按优先级统计通过/失败数量）
5. 针对每项未通过的规则提出具体修复建议

何时继续使用生成模式： 如果用户的请求不明确（例如只说“这是我的点击声”，没有要求审查），默认采用生成工作流。只有在明确表示要进行审核时才进入审查模式。

词汇转换

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

用户描述	参数调整	示例
“更明亮”	提高频率或滤波器截止频率	滤波器截止频率 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 位”	使用方波，将音高量化	切换为方波，使用音符频率
“更有气泡感”	快速降低音高，使用正弦波	startFreq 2000，快速指数下降

声音类别——速查表

类别	时长	配方	触发条件	主要特征
点击	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	其他情况	用基本构件组合

关键实现规则

AudioContext 的用户手势要求

浏览器会在用户交互（点击、轻触、按下按键）之前阻止音频。务必在事件处理程序中初始化或恢复 AudioContext。references/web-audio-api.md 中的单例模式可以处理此问题。

切勿将增益渐变至零

exponentialRampToValueAtTime(0, ...) 会抛出错误。始终渐变至 0.001——该值听不见，但在数学上有效。此规则适用于所有声音，无一例外。

节点清理

• OscillatorNodes 会在调用 stop() 后自动断开连接——无需手动清理
• BufferSourceNodes 只能播放一次——每次播放都要创建一个新的节点
• 对于长期存在的滤波器／增益节点，使用完毕后调用 disconnect()
• 切勿为每个声音都创建新的 AudioContext——应使用单例

音量安全

• 默认音量：0.3（增益值）
• 最大音量：0.8——切勿超过
• 悬停音效：0.03–0.08（几乎难以察觉）
• UI 音效应起到衬托作用，而非喧宾夺主——宁可偏轻

调度精度

在每个声音函数开头只捕获一次 const now = ctx.currentTime。所有调度时间都从 now 推导。切勿多次读取 currentTime。

默认使用指数渐变

exponentialRampToValueAtTime 在音量和频率变化上都听起来自然。linearRampToValueAtTime 听起来很机械。仅在过渡时间短于 50 ms 时使用线性渐变。

输出格式

HTML 预览（默认）

改编 assets/sound-preview.html。该文件独立完整、无依赖，可在任何浏览器中打开。最适合反复聆听和优化。包含 WAV 下载功能——点击任意声音上的下载按钮即可获取 .wav 文件。声音函数必须使用 (ctx, dest) 参数并提供回退默认值，以支持下载功能；每个声音还需要在 durations 映射中有对应条目。

ES 模块

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

React Hook

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

声音库类

使用 references/sound-recipes.md 中的 UISoundLibrary 类。将所有声音打包在一起，并提供启用／禁用和主音量控制功能。

资源

references/

• 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 或希望快速迭代时加载。
• audio-file-references.md — 如何解读 analyze-sound.mjs 命令行工具生成的声音特征。将音频分析指标映射到合成参数和配方选择。在用户提供音频文件参考的声音特征时加载。

assets/

• sound-preview.html — 独立完整的 HTML 模板，包含全部 10 种默认声音、视觉反馈和 AudioContext 处理。每次输出预览时都要改编此模板。

tools/

• analyze-sound.mjs — 用于分析 .wav／.mp3 文件并输出声音特征的命令行脚本。运行 node tools/analyze-sound.mjs <file>。零依赖——适用于任何 Node.js 安装。原生支持 .wav；其他格式需要 ffmpeg。输出时长、包络、频谱内容、音调特征，以及可直接映射到配方参数的合成建议。