ui-audio-theme

UI オーディオテーマジェネレーター

ElevenLabs の text-to-sound-effects API を使用して、統一感のある控えめでミニマルな UI 効果音セットを生成します。「オーディオテーマ」を作成します。これは、共通の美的感覚を持ち、標準的な UI 操作の定数に対応する、統一されたサウンドセットです。

環境変数に ELEVENLABS_API_KEY を設定する必要があります。セットアップ手順については README.md を参照してください。

ゲームおよびテレビの UI との関係

このスキルは、既存製品のオーディオ監査、セマンティックイベントとサウンドの対応表、UI サウンド候補の生成、視覚的な試聴、非破壊編集、ノーマライズ、採用済みアセットマニフェスト、再利用可能なサウンドスロットやピッカーの改善を一元的に担当します。design-game-ui は、ゲーム／テレビ専用 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：試聴と調整（インタラクティブピッカー）

好みは自動化できません。ベースラインを生成したら、各スロットをユーザーに試聴してもらい、反復して調整します。実行環境に応じて、2 つの方法から選んでください。

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 の SFX のラウドネスはプロンプトの表現に左右されます。「静か」「控えめ」な雰囲気を指定すると、ピークが -31 dBFS の音声が生成されることがあり、アプリ側で UI 音量を 20～40% に設定すると聞こえなくなります。そのため、ジェネレーターはデフォルトで全ファイルのピークを -3 dBFS に正規化します（ffmpeg が必要です。生の出力を維持するには --no-normalize を渡してください）。音色の指定には雰囲気を表す言葉を使い、ラウドネスはアプリの音量設定で調整してください。

統合時の注意点

• 自動再生ポリシー：ブラウザーは、ページ上でユーザーが最初にクリック、タップ、またはキー入力するまで、すべての音声をブロックします。ホバー時のサウンドは、最初の操作後にのみ再生されます。これはブラウザーの厳格なルールであり、実装上の選択ではありません。
• ホバー時の効果音：クリック音より40～60％小さい音量で再生し、（約90msで）スロットリングして、カーソルがメニュー上を移動したときに連続再生されないようにします。
• ホバーの使い分け：主要なナビゲーションやメニューの閲覧には nav-item-hover、その他のインタラクティブな項目には item-hover、実際にツールチップが表示されたときにのみ tooltip-show を使用します。ツールチップ音を全体共通のホバー音にしないでください。
• トランザクション：ウォレットまたはネットワークからブロードキャストされたトランザクション ID が返された後に tx-sent を、意味のある待機状態へ移行したときに tx-pending を、最初に確認済み／履行済みの状態へ移行したときに tx-confirmed を、受信者向けの UI でのみ tx-received を再生します。処理を開始するだけのボタンクリック時には、これらを再生しないでください。
• 編集：元のファイルは変更せず、shell=True を使わずに数値範囲を制限した ffmpeg フィルターで改訂版を出力し、出力にヘッドルームを確保して、置き換える前に直前に承認されたスナップショットを保持します。意図的なゲイン変更を打ち消すような方法で、編集済みファイルをノーマライズしないでください。
• 機械的な確認だけでなく、実際に音を聴いて確認する：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 — テーマを生成する CLI ツール
• 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 フック、Howler.js）、アクセシビリティに関するガイダンス