# 機能設計書 56-Sidechain Compressor

## 概要

本ドキュメントは、K-ShootMania（KSM）のプレイ画面におけるSidechain Compressorオーディオエフェクトの設計を記述する。Sidechain Compressorは、BPMに同期した周期的な音量ダッキング（ポンピング効果）を生成するエフェクトである。

### 本機能の処理概要

Sidechain CompressorエフェクトはFXノートのロング区間で発動し、sich.dllを通じてオーディオストリームにBPM同期のサイドチェインコンプレッション効果を適用する。ビートに同期したトリガーにより音量を周期的に変調させる。

**業務上の目的・背景**：サイドチェインコンプレッサーはEDM（電子ダンスミュージック）において広く使用されるポンピング効果を実現するエフェクトである。キック（バスドラム）のタイミングに合わせた音量変調により、楽曲にグルーヴ感を付与する。

**機能の利用シーン**：プレイ画面においてFXノートのロング区間でSidechain Compressorが指定されている場合に発動する。ビート同期のトリガーにより周期的な音量変調が適用される。

**主要な処理内容**：
1. 譜面読み込み時にSidechain Compressorの使用フラグ（fl_SiCh）を設定
2. sich.dllをオーディオストリームにロード
3. period/holdTime/attackTime/releaseTime/ratio/delayTimeの各パラメータ初期化
4. BPM連動のperiod自動調整
5. ビート同期トリガー（sich_trigger変数の0/1トグル）

**関連システム・外部連携**：BASS Audio Library経由でsich.dllを制御する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | sich.dllによるサイドチェインコンプレッサーエフェクト適用 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| period | FXDEF_LENGTH (float) | Yes | トリガー周期（デフォルト0.25=4分音符） | 0.0以上 |
| holdTime | FXDEF_LENGTH (float) | Yes | ホールドタイム（デフォルト-0.050=50ms固定） | 負値はms固定 |
| attackTime | FXDEF_LENGTH (float) | Yes | アタックタイム（デフォルト-0.010=10ms固定） | 負値はms固定 |
| releaseTime | FXDEF_LENGTH (float) | Yes | リリースタイム（デフォルト0.0625=1/16拍） | 0.0以上 |
| ratio | FXDEF_INT (int) | Yes | コンプレッション比（デフォルト5:1） | 1〜100 |
| delayTime | FXDEF_LENGTH (float) | Yes | ディレイタイム | 0.0以上 |

### 入力データソース

- KSH譜面ファイルのFXノート定義（FX_SICH=19）
- ユーザー定義エフェクト
- BPMデータ
- ビート位置データ（sich_beat）

## 出力仕様

### 出力データ

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

### 出力先

オーディオ出力デバイス

## 処理フロー

### 処理シーケンス

```
1. 譜面読み込みフェーズ
   └─ FX_SICH（定数値19）を検出し fl_SiCh=1 を設定
2. VSTエフェクト初期化（applyVSTEffects）
   └─ fl_SiCh=1の場合、sich.dllをロード（優先度14）
   └─ holdTime(param1)=0.0050, attackTime(param2)=0.0, releaseTime(param3)=0.0010 を設定
3. BPM連動処理
   └─ BPM変化時にperiod(param4)を 60*0.5*1000/bpmfx/10 で再計算
4. ビート同期トリガー
   └─ sich_beat変化時にsich_triggerを0/1トグルしparam0に設定
5. FXノート区間切替
   └─ ON:  ratio(param5)=0.05
   └─ OFF: ratio(param5)=0.01
```

### フローチャート

```mermaid
flowchart TD
    A[譜面読み込み] --> B{FX_SICH定義あり?}
    B -->|Yes| C[fl_SiCh=1を設定]
    B -->|No| D[SidechainCompressor未使用]
    C --> E[sich.dllロード]
    E --> F[processAudioEffects]
    F --> G{BPM変化?}
    G -->|Yes| H[period再計算]
    G -->|No| I{ビート変化?}
    H --> I
    I -->|Yes| J[sich_triggerトグル -> param0]
    I -->|No| K{FXノート区間変化?}
    J --> K
    K -->|ON| L[ratio=0.05]
    K -->|OFF| M[ratio=0.01]
    L --> F
    M --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-56-1 | BPM連動period | BPM変化時に `60*0.5*1000/bpmfx/10` で再計算 | bpmfx!=bpmfxp |
| BR-56-2 | ビート同期トリガー | sich_beat変化かつc2bnow変化時にsich_triggerを0/1トグル | sich_beat!=sich_beatp かつ FX_SICH有効 |
| BR-56-3 | ON時ratio設定 | ratio(param5)=0.05f | feffectnow=FX_SICH |
| BR-56-4 | OFF時ratio設定 | ratio(param5)=0.01 | feffectp=FX_SICH OFF |
| BR-56-5 | レーザー処理後実行 | SidechainのトリガーはFXエフェクト処理の後に実行 | processAudioEffects末尾 |

### 計算ロジック

- **period**: `maxf(minf(60.0*0.5*1000/bpmfx/10, 1.0), 0.0)`
- **sich_beat**: `(cnowfx - b2c(c2bnow)) / UNIT_MEASURE_4` （4分音符単位のビート位置）
- **sich_trigger**: 0/1トグル（ビート変化ごと）

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

不要。

## パフォーマンス要件

- VSTエフェクト優先度: 14（他エフェクトより低い=後に処理）
- トリガー処理はレーザーエフェクト処理の後に実行

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

外部DLL（sich.dll）の読み込みリスク。

## 備考

- Sidechain Compressor DLL: "sich.dll"
- エフェクト定数値: FX_SICH = 19, FXDEF_FXTYPE_SICH = 9
- パラメータ数: 6
- トリガー処理が他のFXエフェクトの後に実行される点が特徴（1217-1242行目）
- ユーザー定義エフェクトのSidechainも同様のトリガー機構を使用

---

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

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

### 推奨読解順序

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

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

- **22行目**: `#define FX_SICH 19`
- **45行目**: `#define FXDEF_FXTYPE_SICH 9`
- **184-194行目**: パラメータテーブル（period, holdTime, attackTime, releaseTime, ratio, delayTime）

**読解のコツ**: holdTimeとattackTimeのデフォルト値が負数（-0.050, -0.010）であることに注意。FXDEF_LENGTH型で負値はミリ秒固定値を意味する。

#### Step 2: VSTエフェクト初期化

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | sich.dllのロードとパラメータ初期化 |

- **284-289行目**: fl_SiCh=1でsich.dllロード、holdTime/attackTime/releaseTime初期設定

#### Step 3: ビート同期トリガーとリアルタイム処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | BPM連動、ビート同期、ON/OFF切替 |

- **404行目**: BPM変化時のperiod再計算
- **439-440行目**: sich_beat計算（4分音符ビート位置）
- **655-657行目**: OFF時にratio=0.01
- **739-741行目**: ON時にratio=0.05
- **776-782行目**: ビート変化時のsich_triggerトグル
- **1217-1242行目**: ユーザー定義Sidechainのトリガー処理（FXエフェクト処理後）

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

```
play_init
    |
    +-- loadKSHChartFile -> fl_SiCh=1
    |
    +-- applyVSTEffects
    |       +-- BASS_VST_ChannelSetDSP(sich.dll) -> hFX_SiCh
    |       +-- holdTime/attackTime/releaseTime初期設定
    |
    +-- processAudioEffects
            +-- BPM変化 -> period(param4)再計算
            +-- FXノート切替 -> ratio(param5)設定
            +-- ビート同期 -> sich_triggerトグル -> param0
            +-- (レーザー処理後) ユーザー定義Sidechainトリガー
```

### データフロー図

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

BPMデータ ---------------> period計算(param4) ------------> sich.dll
ビート位置(sich_beat) ---> sich_triggerトグル(param0) ----> コンプレッション
FXノート(FX_SICH) -------> ratio設定(param5) ------------->   |
音楽ストリーム ---------> BASS Audio Library --------------> スピーカー出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| fxdef.hsp | `src/audio/fxdef.hsp` | ソース | SidechainCompressorパラメータ定義 |
| play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | ソース | VSTエフェクト制御・ビート同期トリガー |
| play_chart_load.hsp | `src/scene/play/play_chart_load.hsp` | ソース | 譜面読み込みとフラグ設定 |
| sich.dll | `lib/sich.dll` | 外部DLL | Sidechain Compressor VSTプラグイン |
