# 機能設計書 53-Wobble

## 概要

本ドキュメントは、K-ShootMania（KSM）のプレイ画面におけるWobbleオーディオエフェクトの設計を記述する。Wobbleはローパスフィルターの周波数をBPMに同期してLFOで揺らすことで、ダブステップ系のウォブルベースサウンドを生成するエフェクトである。

### 本機能の処理概要

WobbleエフェクトはFXノートのロング区間で発動し、regawo.dllのGate/Wobble機能を利用してオーディオストリームにリアルタイムでウォブル処理を適用する。

**業務上の目的・背景**：ダブステップやエレクトロ系楽曲において、ウォブルベースは代表的な音響効果である。譜面制作者がFXノート区間にWobbleを指定することで、BPMに同期したフィルタースイープ効果を楽曲に付与できる。

**機能の利用シーン**：プレイ画面においてFXノートのロング区間でWobbleが指定されている場合に発動する。12分音符単位のLFO周期がデフォルトで使用され、BPM変化に追従する。

**主要な処理内容**：
1. 譜面読み込み時にWobbleエフェクトの使用フラグ（fl_Gate=1）を設定（Gateと共通DLL）
2. regawo.dllのWobble用パラメータ（param9=waveLength）を設定
3. BPM変化に応じたwaveLengthの自動調整
4. 小節先頭でのトリガータイミング同期（param19）
5. loFreq/hiFreq/Qによるフィルター特性制御

**関連システム・外部連携**：BASS Audio Library経由でregawo.dll（GateとWobbleを兼用するDLL）を制御する。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | regawo.dllによるウォブルベースエフェクト適用 |

## 機能種別

リアルタイム音声処理（VSTエフェクト適用）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| waveLength | FXDEF_LENGTH (float) | Yes | LFO周期（デフォルト12分音符=1/12拍） | 0.0以上 |
| mix | FXDEF_RATE (float) | Yes | エフェクトミックス率（デフォルト0.80） | 0.0〜1.0 |
| loFreq | FXDEF_FREQ (float) | Yes | 低域周波数（デフォルト500Hz） | 0〜22050Hz |
| hiFreq | FXDEF_FREQ (float) | Yes | 高域周波数（デフォルト20000Hz） | 0〜22050Hz |
| Q | FXDEF_FLOAT (float) | Yes | レゾナンス（デフォルト1.414） | 0〜50.0 |

### 入力データソース

- KSH譜面ファイルのFXノート定義（FX_WO12=16）
- ユーザー定義エフェクト（#define_fx / #define_filter）
- BPMデータ（bpml配列）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 音声ストリーム | audio stream | Wobble処理が適用されたオーディオ出力 |
| hFX_Gate | int | Gate/Wobble共用VSTエフェクトハンドル |

### 出力先

オーディオ出力デバイス（BASS Audio Libraryのオーディオストリーム経由）

## 処理フロー

### 処理シーケンス

```
1. 譜面読み込みフェーズ（play_chart_load.hsp）
   └─ FX_WO12（定数値16）を検出し fl_Gate=1 を設定（Gate DLLと共用）
2. VSTエフェクト初期化フェーズ（applyVSTEffects）
   └─ fl_Gate=1の場合、regawo.dllをロード（優先度17）
   └─ loFreq(param10)=500/22050, hiFreq(param11)=20000/22050, Q(param12)=1.414/50 等を初期化
3. BPM連動処理
   └─ BPM変化時: wobble_now>0 なら waveLength(param9)を 60*4*1000/bpmfx/10/wobble_now で再計算
4. FXノート区間切替
   └─ ON:  waveLength(param9) = 60*4*1000/bpmfx/10/feffectparam, wobble_now設定
   └─ OFF: waveLength(param9) = 0, wobble_now=0
5. トリガー同期
   └─ 小節先頭(c2bnow変化)でparam19にタイミング差分を設定
```

### フローチャート

```mermaid
flowchart TD
    A[譜面読み込み] --> B{FX_WO12定義あり?}
    B -->|Yes| C[fl_Gate=1を設定]
    B -->|No| D[Wobble未使用]
    C --> E[applyVSTEffects: regawo.dllロード]
    E --> F[processAudioEffects: 毎フレーム処理]
    F --> G{BPM変化?}
    G -->|Yes| H[waveLength再計算]
    G -->|No| I{FXノート区間変化?}
    H --> I
    I -->|ON| J[waveLength設定, wobble_now更新]
    I -->|OFF| K[waveLength=0]
    J --> L{小節先頭?}
    K --> F
    L -->|Yes| M[param19トリガー同期]
    L -->|No| F
    M --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-53-1 | Gate DLL共用 | WobbleはGateと同一DLL（regawo.dll）を使用し、param9（Wobble waveLength）で制御 | fl_Gate=1 |
| BR-53-2 | BPM連動waveLength | BPM変化時に `60*4*1000/bpmfx/10/wobble_now` で再計算 | wobble_now>0 |
| BR-53-3 | トリガー同期 | 小節先頭(c2bnow変化時)でparam19にタイミング差分を設定し位相リセット | c2bnow!=c2bnowp |
| BR-53-4 | デフォルト12分音符 | fx_div.FX_WO12=12で12分音符周期 | FX_WO12使用時 |

### 計算ロジック

- **waveLength**: `60.0*4.0*1000.0/bpmfx/10.0/wobble_now`
- **loFreq正規化**: `500.0/22050.0`
- **hiFreq正規化**: `20000.0/22050.0`
- **Q正規化**: `1.414/50.0`
- **トリガー同期**: `maxf(minf(dstat/10000.0, 1.0), 0.0)` （dstatは小節先頭からの時間差）

## データベース操作仕様

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | DLLロード失敗 | regawo.dllが存在しない場合 | エフェクト未適用で続行 |

### リトライ仕様

リトライ処理は行わない。

## トランザクション仕様

不要。

## パフォーマンス要件

- VSTエフェクト優先度: 17（Gateと共有）
- トリガー同期は小節先頭でのみ実行

## セキュリティ考慮事項

外部DLL（regawo.dll）の読み込みに関するDLL改竄リスク。

## 備考

- Wobble DLL: "regawo.dll"（Gate/Retrigger/Echo/Wobbleで共用）
- エフェクト定数値: FX_WO12 = 16, FXDEF_FXTYPE_WOBB = 6
- Gate DLLのparam9がWobble用waveLength、param10-12がloFreq/hiFreq/Q、param13がmix
- GateとWobbleは同一DLLの異なるパラメータ領域を使用

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | fxdef.hsp | `src/audio/fxdef.hsp` | Wobbleの定数定義とパラメータテーブル |

**読解のコツ**: WobbleはGateと同一DLL（regawo.dll）を使用するが、パラメータテーブルは独立している。fxdef_prmno配列でVSTパラメータ番号を確認すること。param9がwaveLength、param13がmixなど、Gate領域とは異なる番号を使用。

- **19行目**: `#define FX_WO12 16` - FXノート用Wobble定数（12分音符）
- **42行目**: `#define FXDEF_FXTYPE_WOBB 6` - エフェクトタイプ
- **62行目**: `fx_div.FX_WO12=12` - 12分音符分割数
- **148-158行目**: Wobbleパラメータテーブル

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play_chart_load.hsp | `src/scene/play/play_chart_load.hsp` | fl_Gateフラグ設定（Wobbleも同じフラグ） |

**主要処理フロー**:
1. **1160-1161行目**: `fx.fxnum.2=FX_WO12` 検出時に `fl_Gate=1`
2. **1892行目**: 組み込み定義でもfl_Gate=1を設定

#### Step 3: リアルタイム処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | BPM連動waveLength計算とトリガー同期 |

**主要処理フロー**:
- **411-413行目**: BPM変化時のwaveLength再計算
- **637-646行目**: FXノート区間切替時のwobble_now設定
- **724-727行目**: ON時のwaveLength設定
- **449-456行目**: 小節先頭でのトリガー同期（param19）

### プログラム呼び出し階層図

```
play_init
    |
    +-- loadKSHChartFile -> fl_Gate=1 (FX_WO12検出)
    |
    +-- applyVSTEffects
    |       +-- BASS_VST_ChannelSetDSP(regawo.dll) -> hFX_Gate
    |       +-- loFreq/hiFreq/Q/mix初期設定
    |
    +-- play_update -> processAudioEffects
            +-- BPM変化 -> waveLength(param9)再計算
            +-- FXノート区間切替
            |       +-- ON:  param9=waveLength, wobble_now更新
            |       +-- OFF: param9=0, wobble_now=0
            +-- 小節先頭 -> param19トリガー同期
```

### データフロー図

```
[入力]                      [処理]                           [出力]

KSH譜面(FX_WO12) -------> fl_Gate=1設定 -----------------> エフェクトフラグ
BPMデータ ---------------> waveLength計算 ----------------> VSTパラメータ(param9)
小節先頭タイミング ------> トリガー同期 ------------------> VSTパラメータ(param19)
音楽ストリーム ---------> regawo.dll(Wobble) -------------> スピーカー出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| fxdef.hsp | `src/audio/fxdef.hsp` | ソース | Wobbleパラメータ定義 |
| play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | ソース | VSTエフェクト制御 |
| play_chart_load.hsp | `src/scene/play/play_chart_load.hsp` | ソース | 譜面読み込みとフラグ設定 |
| regawo.dll | `lib/regawo.dll` | 外部DLL | Gate/Wobble/Retrigger/Echo共用VSTプラグイン |
