ui-audio-theme

UI 音效主题生成器

使用 ElevenLabs text-to-sound-effects API 生成协调统一、微妙简约的 UI 音效集。创建“音频主题”——一组美学风格一致、对应标准 UI 交互常量的协调音效。

需要在环境中设置 ELEVENLABS_API_KEY。设置说明请参阅 README.md。

与游戏和电视 UI 的关系

此技能是现有产品音频审查、语义事件到音效的映射、UI 音效候选生成、试听、非破坏性编辑、标准化、已接受素材清单，以及可复用音效槽位或选择器改进的唯一负责人。design-game-ui 负责专为游戏／电视界面设计的上游语义反馈事件映射：每个事件的含义、触发时机、所需的视觉对应内容、重复策略、无障碍要求和验收标准。

从 design-game-ui 调用时，使用其事件映射，不要重新设计导航或为原始按键触发音效。Frames 负责音频制作；应用工程师负责运行时播放生命周期；游戏 UI 负责人验收集成后的行为。voice-clone 独立使用，仅当所需素材为语音时才应使用。

工作流

步骤 0：审查现有产品

如果应用已存在，或者主题创建后新增了身份验证／支付／区块链功能，请先审查现有应用，再生成或重新接线音效。按照 references/audit-and-wiring.md 中的说明，复制 assets/event-map-template.json，并验证填写完成的映射：

python scripts/audit_theme.py ./audio-event-map.json \
  --theme ./public/audio/ui/theme.json

盘点路由、覆盖层、异步任务、身份验证、支付、区块链操作、键盘和游戏手柄输入中的语义状态转换。将每个事件映射到一种音效或有记录说明的有意静音。将未使用的主题槽位视为信息，而不是添加嘈杂接线的理由。要求同时具备源代码证据和浏览器中的可听证据。在评估素材前，先修正事件边界。

步骤 1：了解 UI 风格

生成音效前，先了解应用的美学风格：

应用背景：

• 应用类型是什么？（钱包、仪表盘、社交、效率）
• 用户的主要情绪是什么？（信任、愉悦、专注、平静）
• 界面偏专业还是活泼？

音频方向：

• 偏好的基调是什么？（温暖／自然、干净／数字化、复古／怀旧、未来感）
• 参考音效有哪些？（类似 Apple 的点击声、游戏哔哔声、银行提示音）

步骤 2：选择风格预设

assets/vibe-presets.json 中的可用预设：

预设	基调	最适合
corporate-trust	温暖、专业	银行、金融
crypto-modern	数字化、干净	钱包应用、交易
playful-delight	明亮、友好	社交、消费类
minimal-focus	极简克制	效率、工具
retro-digital	复古 8 位风格	游戏、怀旧
pixel-minimal	安静的 8 位风格	像素艺术网站、复古仪表盘
premium-luxury	丰富、精致	高端应用

步骤 3：生成音频主题

# Using preset vibe
python scripts/generate_theme.py \
  --vibe "crypto-modern" \
  --output-dir "./audio-theme"

# Using custom vibe description
python scripts/generate_theme.py \
  --vibe-custom "warm organic subtle wooden interface sounds" \
  --output-dir "./audio-theme"

# Generate specific categories only
python scripts/generate_theme.py \
  --vibe "crypto-modern" \
  --categories buttons feedback transactions \
  --output-dir "./audio-theme"

# List available presets
python scripts/generate_theme.py --list-vibes

# List all sound names
python scripts/generate_theme.py --list-sounds

步骤 4：重新生成单个音效

python scripts/generate_theme.py \
  --regenerate "button-click-primary,notification-success" \
  --vibe "crypto-modern" \
  --output-dir "./audio-theme"

步骤 5：试听并优化（交互式选择器）

品味无法自动化——生成基线版本后，让用户试听每个音效槽位并迭代。根据运行环境选择以下两种策略之一：

A. 本地选择器服务（默认——适用于 Claude Code 和 Codex）：

python scripts/sound_picker.py --vibe pixel-minimal --output-dir ./audio-theme
# → http://127.0.0.1:7777

它会提供一个本地页面，其中每个音效槽位都包含：当前文件的播放按钮、可编辑的生成提示词（根据氛围预先填好）、通过 ElevenLabs 无限生成新候选项的“生成下一个”按钮（自动标准化），以及始终展开的精简波形卡片。选中的音频会显示持久的视觉状态，点击任意卡片的波形即可打开共享编辑器。精简的图标控件支持：

• 将候选项采纳到其当前事件槽位；
• 将合适但槽位不对的候选项分配给其他事件，无需重新生成；
• 打开可视化波形编辑器，其中包含可拖动的裁剪手柄、点击定位播放、选区播放，以及可通过键盘调整的裁剪边界；
• 创建非破坏性修订版本，并提供清晰标注的淡入、淡出、音量、混响、延迟时间和延迟量滑块；以及
• 删除临时候选项及其衍生修订版本，同时不删除已采纳的线上主题文件。

每次编辑都会创建一个新修订版本。采纳替换文件时，选择器会先将之前采纳的文件存入历史记录，因此，返回早期版本只需像平常一样试听并采纳。选择器会在 theme.json 中记录提示词、源槽位、编辑方案、分配来源和历史记录。在后台运行它，将 URL 提供给用户，并且只有在用户明确接受每个槽位的音效后才继续。由于它绑定到 localhost，因此不受 CSP 限制。

选择器是默认的审核界面，不是可选的润色步骤。将本地 URL 提供给用户，并等待其明确选择每个槽位的音效。不要将首次生成的基线版本视为已采纳，也不要用文件名或文字描述代替试听。采纳后，将记录下来的获胜提示词和事件到文件的清单交给 Frames 或实现负责人。

**B. Artifact 试听看板（仅限 Claude Code，适用于倾向使用托管页面的情况）：**托管的 Artifacts 会强制执行严格的 CSP——不允许外部请求，因此无法在 artifact 内实时生成。替代做法是：使用 --regenerate 为每个槽位预先生成 2-4 个候选项，将每个 mp3 以 base64 data: URI 的形式嵌入带有播放按钮和候选项提示词的 HTML 页面中，通过 Artifact 工具发布，并让用户回复选择结果及提示词调整，以便进行下一轮生成。采用迭代轮次，而不是无限点击“下一个”；候选项数量保持较少——base64 音频会让页面大小增加约 33%。

响度标准化

ElevenLabs 的音效响度会随提示词措辞变化——“安静”或“微妙”的氛围可能会生成峰值达到 -31 dBFS 的音效，当应用将音量设为 20-40% 时，音效可能会听不见。因此，生成器默认会将每个文件的峰值标准化到 -3 dBFS（需要 ffmpeg；传入 --no-normalize 可保留原始输出）。保留用于描述音色的氛围词；让应用的音量设置控制响度。

集成注意事项

• 自动播放策略：浏览器会阻止所有音频播放，直到用户首次在页面上点击、轻触或按键。只有在首次交互后，悬停触发的声音才会生效——这是浏览器的硬性规则，并非实现选择。
• 悬停提示音：音量应比点击声低 40-60%，并进行限频（约 90ms），避免光标扫过菜单时声音连发。
• 悬停语义：主要导航／菜单浏览使用 nav-item-hover，其他交互项使用 item-hover，仅在实际显示工具提示时使用 tooltip-show。不要将工具提示声音用作全局悬停音效。
• 交易：钱包／网络返回广播交易 ID 后播放 tx-sent；进入有实际意义的等待状态时播放 tx-pending；首次进入已确认／已完成状态时播放 tx-confirmed；仅在面向收款方的界面中播放 tx-received。切勿在仅启动操作的按钮点击时触发这些声音。
• 编辑：保持原文件不可变，使用有界数值 ffmpeg 滤镜生成修订版本，不要使用 shell=True；留出输出余量，并在替换前保留先前接受的快照。切勿通过归一化编辑后的文件来抵消有意设置的增益变化。
• 通过听感验证，而不只是机械检查：audio.play() 成功解析只能证明已播放，不能证明声音可感知。发布前，使用 ffmpeg -i file.mp3 -af volumedetect -f null - 检查峰值，并以应用实际音量倍数试听。

声音类别

按钮

常量	描述
button-click-primary	主操作按钮
button-click-secondary	次要／幽灵按钮
button-click-destructive	删除／取消操作

导航

常量	描述
item-hover	通用交互项悬停／聚焦
nav-item-hover	主导航／菜单项悬停／聚焦
nav-tab-switch	标签页导航
nav-back	返回按钮／手势
nav-forward	前进导航
nav-menu-open	打开菜单抽屉
nav-menu-close	关闭菜单

反馈

常量	描述
notification-success	成功确认
notification-error	错误警报
notification-warning	警告指示
notification-info	信息通知
notification-badge	徽标／计数器更新

状态

常量	描述
toggle-on	开关已启用
toggle-off	开关已禁用
checkbox-check	复选框已选中
checkbox-uncheck	复选框已取消选中
loading-start	开始加载
loading-complete	加载完成

模态框

常量	描述
modal-open	模态框显示
modal-close	模态框关闭
tooltip-show	显示工具提示
dropdown-open	展开下拉菜单
dropdown-close	收起下拉菜单

交易（钱包专用）

常量	描述
tx-sent	交易已发送
tx-received	已收到付款
tx-pending	交易等待中
tx-confirmed	确认成功

输出结构

audio-theme/
├── theme.json              # Theme manifest
├── constants.ts            # TypeScript constants
├── .picker/                # Immutable candidates, revisions, and history
├── buttons/
│   ├── button-click-primary.mp3
│   ├── button-click-secondary.mp3
│   └── button-click-destructive.mp3
├── navigation/
├── feedback/
├── states/
├── modals/
└── transactions/

脚本选项

--vibe NAME           Preset vibe name
--vibe-custom DESC    Custom vibe description
--output-dir PATH     Output directory (default: ./audio-theme)
--format FORMAT       mp3 or wav (default: mp3)
--categories CATS     Specific categories to generate
--regenerate SOUNDS   Comma-separated sounds to regenerate
--prompt-influence N  0-1, higher = stricter prompt adherence (default: 0.5)
--list-vibes          Show available presets
--list-sounds         Show all sound names

资源

• scripts/generate_theme.py — 用于生成主题的命令行工具
• scripts/sound_picker.py — 本地试听、分配、编辑和历史记录 UI
• scripts/audit_theme.py — 根据主题验证现有应用的语义事件映射
• references/audit-and-wiring.md — 现有产品清单、接线和证据工作流
• references/sound-design-guide.md — 详细的声音设计最佳实践
• assets/vibe-presets.json — 预定义的氛围配置
• assets/theme-template.json — 示例输出清单
• assets/event-map-template.json — 可审计的交互到声音映射模板
• README.md — 前置条件、设计理念、集成示例（React hook、Howler.js）和无障碍指南