# 🎵 AmbisonicsPlayer (Azimuth)

Ambisonics 音源を読み込み、左右方向（Yaw）の回転操作でリスナーの向きを変えながら、ステレオまたはバイノーラルにデコードして再生できる Web アプリケーションです。

**▶ [アプリを開く](https://kagoiri.github.io/AmbisonicsPlayer/azimuth.html)**

## 特徴

- Ambisonics 音源（AmbiX / FuMa）を読み込み、リアルタイムにデコード再生
- 1次〜3次（FOA/SOA/TOA: 4/9/16チャンネル）対応
- 左右ドラッグ/スワイプによる Yaw（方位角）回転操作
- 3D 球体ギズモで回転状態を視覚的に表示
- ステレオデコード / バイノーラルデコード（HRTF 畳み込み）の切り替え
- 波形表示とクリックシーク
- ネットワークURL・ローカルファイル・Dropbox共有リンクに対応
- ファイルのドラッグ&ドロップ読み込み（デスクトップ）
- 音源URL・回転状態を含む共有リンクの生成
- キーボードショートカット対応
- ループ再生
- モバイル対応（レスポンシブデザイン）

## 対応フォーマット

**ファイル形式**: WAV / MP3 / FLAC / OGG

**チャンネル数**: 4ch（FOA）/ 9ch（SOA）/ 16ch（TOA）のみ対応

**フォーマット**: AmbiX（ACN/SN3D）推奨。FuMa 形式はファイル拡張子 `.amb` またはメタデータから自動検出します。

**サンプルレート**: 制限なし（読み込み時にデバイスのサンプルレートに自動変換）

## 使い方

### 基本操作

1. 音源を読み込む（URL入力またはローカルファイル選択）
2. 音源が読み込まれると回転 UI と再生コントロールが表示される
3. 「▶ 再生」で再生開始
4. 回転 UI（球体ギズモ）を左右にドラッグして音場を回転

### Azimuth 版について

この Azimuth 版は **Yaw（左右方向）の回転のみ** に対応したシンプルなバージョンです。上下方向のドラッグは無視されます。

全方向（Yaw / Pitch / Roll）の回転が必要な場合は [Full 版](full.html) をご利用ください。

### 音源の読み込み方法

**🌐 ネットワーク**: URL入力欄にアドレスを入力して「読込」ボタンをクリック

**📁 ローカル**: 「ファイルを選択 / ドロップ」ボタンをクリックしてファイルを選択。デスクトップではトラックパネル全体にファイルをドラッグ&ドロップすることもできます。

読み込み済みの音源は状態表示バーに表示され、✕ボタンでクリアできます。

### デコードモード

| モード | 説明 |
|--------|------|
| **ステレオ** | 基本的なステレオダウンミックス。スピーカー再生に適しています |
| **バイノーラル** | HRTF（頭部伝達関数）を使用した立体音響。ヘッドフォン再生に適しています |

デフォルトはバイノーラルモードです。バイノーラルモードには HRTF データファイル（`hrir_sh.json`）が必要です。

### 回転操作

球体ギズモを **左右にドラッグ** すると、Yaw（方位角）が変化します。球体の手前側に触れて回す感覚で操作できます。

- 赤い円（X軸）、緑の円（Y軸）、青い円（Z軸）が回転状態を示します
- 白い矢印はリスナーの正面方向を表します
- 「↺ 回転リセット」ボタンで初期位置に戻ります

### ネットワーク音源の対応状況

**使用可能な音源**
- CORSヘッダー（`Access-Control-Allow-Origin`）を返すWebサーバー上の音声ファイル
- Dropbox の共有リンク（自動的に直接ダウンロードURLに変換されます）
- 自分のWebサーバーやCDNにホストした音声ファイル
- GitHub Pages、Netlify、Vercel などの静的ホスティング上のファイル

**使用できない音源**
- Google Drive の共有リンク（ブラウザからのクロスオリジンアクセスがブロックされます）
- CORSヘッダーを返さないサーバー上のファイル
- ログインが必要なファイル

> **CORSとは**: ブラウザのセキュリティ機能で、異なるドメインからのファイル取得を制限する仕組みです。音源を配置するサーバーが `Access-Control-Allow-Origin` ヘッダーを返す必要があります。

### 音源の共有

「🔗 共有用URLをコピー」ボタンをクリックすると、現在の設定を含むURLがクリップボードにコピーされます。

共有URLに含まれる情報:
- 音源URL
- Yaw（回転角度）
- デコードモード（ステレオ/バイノーラル）
- 音量
- 再生開始位置
- ループ ON/OFF

> ローカルファイルから読み込んだ音源は共有URLに含まれません。デフォルト値のパラメータは省略されます。

共有URLを受け取った相手がリンクを開くと、確認画面が表示されます。クリックすると同じ音源・同じ回転状態で自動再生が開始されます。

### キーボードショートカット

| キー | 操作 |
|------|------|
| `Space` | 再生 / 停止 |
| `←` | 10秒戻る |
| `→` | 10秒進む |
| `↑` | 音量を上げる |
| `↓` | 音量を下げる |

### エラー・警告メッセージについて

| メッセージ | 原因と対処 |
|-----------|-----------|
| Google Driveの共有リンクには対応していません… | Google DriveのURLが入力されました。Dropboxや直接リンクをご利用ください |
| ファイルが見つかりません（404） | URLが間違っているか、ファイルが削除されています |
| アクセスが拒否されました（403） | ファイルの共有設定が非公開になっています |
| 音源の取得が拒否されました…（CORS制限） | サーバーがブラウザからの直接アクセスを許可していません |
| 対応していないチャンネル数です… | 4/9/16ch 以外のファイルが読み込まれました |
| Ambisonicsデコードを初期化できませんでした… | AudioWorklet の初期化に失敗しました。HTTPS 環境で使用してください |
| HRTFデータを読み込めませんでした… | `hrir_sh.json` の取得に失敗しました。ローカルファイルを選択してください |
| ⚠ 互換モードで動作中… | CORSの制限により互換モードで動作しています。Ambisonics回転処理は利用できません |

## 動作環境

- **必須**: HTTPS 環境（AudioWorklet は HTTPS でのみ動作します）
- **推奨ブラウザ**: Chrome、Firefox、Edge、Safari（最新版）
- **必要ファイル**: `azimuth.html` + `hrir_sh.json`（バイノーラルモード使用時）

> `file://` プロトコルでは AudioWorklet が動作しないため、ローカルでの動作確認にはローカルサーバー（`npx serve` 等）を使用してください。

## ライセンス

MIT License (Copyright (c) 2026 Kagoiri)