ui-sound-design

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

UI の音をどのようにしたいか説明してください。 ブラウザーでプレビューし、調整して、ダウンロードできます。

UI サウンドデザイン

平易な英語でのサウンドの説明を、動作する Web Audio API コードに変換します。オーディオエンジニアリングの知識は必要ありません。聞きたい音を説明すれば、このスキルが合成に関する知識を活用して形にします。

ワークフロー

すべてのサウンドは次のループに沿って進みます。説明 → 生成 → 試聴 → 調整（既存コードを監査する場合は、任意でレビュー）

1. 説明

ユーザーが平易な言葉でサウンドを説明します。次のフレームワークを使って、明確化のための質問をしてください。

サウンドを生成する前に確認する4つの質問：

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 フック／クラス

3. 試聴

ユーザーがブラウザーで開いてすぐにサウンドを聞けるよう、HTML プレビューファイルを提供してください。各サウンドには、本番コードでの使用や開発者への引き継ぎに使える .wav ファイルを書き出すダウンロードボタンが含まれています。各サウンドバリエーションには、ラベル付きのボタンを用意してください。プレビューでは、次の点に対応する必要があります。

• AudioContext の一時停止状態を処理する（開始にはユーザーの操作が必要）
• シングルトンの AudioContext パターンを使用する
• 再生時に視覚的なフィードバックを表示する（テンプレートで対応済みです）

4. 調整

ユーザーからフィードバックがあったら、語彙ブリッジを使って解釈し、パラメーターを調整します。よくある調整パターン：

• 「気に入ったけれど……」→ 1〜2 個のパラメーターを微調整します
• 「まったく違う」→ 別のレシピやアプローチを試します
• 「強すぎる／弱すぎる」→ 該当するパラメーターを増減します
• 「X のように」→ X の特徴を特定し、その特徴に合わせます

5. レビュー（任意）

ユーザーが「レビュー」「監査」「サウンドコードをチェックして」と言った場合や、評価を求めて既存の Web Audio コードを貼り付けた場合は、レビューモードに入ります。

手順：

1. references/audio-rules.md からルールを読み込みます
2. 重大度「Critical」から順に、各ルールに照らしてコードをスキャンします
3. audio-rules.md の形式に従って、違反ごとに1行で報告します。形式は 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 にする
「厚みのある」／「豊かな」	オシレーターを重ね、デチューンを加える	2つ目のオシレーターを追加し、+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 のユーザージェスチャー要件

ブラウザーは、ユーザーが操作（クリック、タップ、keydown）するまで音声をブロックします。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 ミリ秒未満の遷移に限ってください。

出力形式

HTML プレビュー（デフォルト）

assets/sound-preview.html をベースに調整してください。依存関係のない自己完結型で、どのブラウザーでも開けます。反復的な試聴と調整に最適です。WAV のダウンロード機能があり、サウンド上のダウンロードボタンをクリックすると .wav ファイルを取得できます。サウンド関数はダウンロードに対応できるよう、フォールバックのデフォルト値を設定した (ctx, dest) パラメーターを使用する必要があります。また、各サウンドに対応するエントリーを durations マップに追加する必要があります。

ES モジュール

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

React フック

// 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 CLI ツールから出力されたサウンドプロファイルの解釈方法です。音声分析指標を合成パラメーターやレシピの選択に対応付けます。ユーザーが音声ファイルの参照から得たサウンドプロファイルを提供した場合に読み込んでください。

assets/

• sound-preview.html — 10 種類のデフォルトサウンド、視覚的なフィードバック、AudioContext の処理機能を備えた、自己完結型の HTML テンプレートです。すべてのプレビュー出力で、このテンプレートをベースに調整してください。

tools/

• analyze-sound.mjs — .wav/.mp3 ファイルを分析し、サウンドプロファイルを出力する CLI スクリプトです。node tools/analyze-sound.mjs <file> で実行します。依存関係は不要で、あらゆる Node.js 環境で動作します。.wav はネイティブでサポートされ、ほかの形式には ffmpeg が必要です。長さ、エンベロープ、スペクトル成分、調性、およびレシピのパラメーターに直接対応する合成案を出力します。