# 機能設計書 54-Tape Stop

## 概要

本ドキュメントは、K-ShootMania（KSM）のプレイ画面におけるTape Stopオーディオエフェクトの設計を記述する。Tape Stopはテープレコーダーの停止を模した、ピッチが急速に下降して停止するエフェクトである。

### 本機能の処理概要

Tape Stopエフェクトは、FXノートのロング区間で発動し、tstp.dllを通じてオーディオストリームにテープストップ処理を適用する。L/R独立のデュアルインスタンスを持ち、左右レーザーに個別に割り当て可能である。

**業務上の目的・背景**：テープストップはDJ文化から派生した効果音であり、楽曲の一部を劇的に停止させる演出に使用される。音楽ゲームにおいては、譜面の演出効果として重要な役割を果たす。

**機能の利用シーン**：プレイ画面においてFXノートのロング区間でTape Stopが指定されている場合に発動する。speed（停止速度）パラメータにより停止の速さを制御できる。

**主要な処理内容**：
1. 譜面読み込み時にTape Stopの使用フラグ（fl_TStp）を設定
2. tstp.dllの2インスタンスをロード（L/R独立制御用）
3. speed（停止速度）とtrigger（開始トリガー）パラメータの制御
4. FXノート区間のON/OFF時にtriggerを切替

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| speed | FXDEF_RATE (float) | Yes | テープ停止の速度（デフォルト0.50） | 0.0〜1.0 |
| trigger | FXDEF_SWITCH (float) | Yes | エフェクト開始トリガー | 0.0 or 1.0 |
| mix | FXDEF_RATE (float) | Yes | エフェクトミックス率 | 0.0〜1.0 |

### 入力データソース

- KSH譜面ファイルのFXノート定義（FX_TSTP=17）
- ユーザー定義エフェクト（#define_fx）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 音声ストリーム | audio stream | Tape Stop処理が適用されたオーディオ出力 |
| hFX_TStp | int[2] | L/R独立のVSTエフェクトハンドル配列 |

### 出力先

オーディオ出力デバイス

## 処理フロー

### 処理シーケンス

```
1. 譜面読み込みフェーズ
   └─ FX_TSTP（定数値17）を検出し fl_TStp=1 を設定
2. VSTエフェクト初期化（applyVSTEffects）
   └─ fl_TStp=1の場合、tstp.dllを2インスタンスロード
   └─ hFX_TStp.0: 優先度19（L用）
   └─ hFX_TStp.1: 優先度18（R用）
3. FXノート区間切替
   └─ ON:  speed設定, trigger(param0)=1.0, mix(param2)=1.0
   └─ OFF: trigger(param0)=0
4. L/R排他制御
   └─ 片方OFF時にもう片方のtrigger(param2)=0にリセット
```

### フローチャート

```mermaid
flowchart TD
    A[譜面読み込み] --> B{FX_TSTP定義あり?}
    B -->|Yes| C[fl_TStp=1を設定]
    B -->|No| D[TapeStop未使用]
    C --> E[tstp.dll x2インスタンスロード]
    E --> F[processAudioEffects]
    F --> G{FXノート区間変化?}
    G -->|ON| H[speed設定, trigger=1, mix=1]
    G -->|OFF| I[trigger=0]
    H --> J[もう片方のparam2=0]
    I --> F
    J --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-54-1 | デュアルインスタンス | L/R独立で2つのtstp.dllインスタンスを持つ | fl_TStp=1 |
| BR-54-2 | トリガー制御 | ON時にtrigger(param0)=1, OFF時にtrigger=0 | feffectnow.cnt=FX_TSTP |
| BR-54-3 | L/R排他 | 片方ON時にもう片方のparam2を0にリセット | feffectnow.cnt=FX_TSTP |
| BR-54-4 | speed設定 | feffectparam/100.0でspeedを正規化 | FX_TSTP ON時 |

### 計算ロジック

- **speed設定**: `BASS_VST_SetParam_R hFX_TStp.cnt, 1, double(feffectparam.cnt)/100.0`
- **trigger ON**: `BASS_VST_SetParam_R hFX_TStp.cnt, 0, 1.0`
- **mix ON**: `BASS_VST_SetParam_R hFX_TStp.cnt, 2, 1.0`

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

不要。

## パフォーマンス要件

- VSTエフェクト優先度: 19（L用）、18（R用）
- 2インスタンスのため他エフェクトよりCPU負荷が高い可能性

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

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

## 備考

- Tape Stop DLL: "tstp.dll"
- エフェクト定数値: FX_TSTP = 17, FXDEF_FXTYPE_TSTP = 7
- VSTパラメータ: param0=trigger, param1=speed, param2=mix
- L/R独立の2インスタンス構成が他エフェクトとの大きな違い

---

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

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

### 推奨読解順序

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

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

- **20行目**: `#define FX_TSTP 17`
- **43行目**: `#define FXDEF_FXTYPE_TSTP 7`
- **160-170行目**: パラメータテーブル（speed, trigger, mix）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | 2インスタンスロード |

- **245-250行目**: hFX_TStp配列初期化（-1,-1）、fl_TStp=1でtstp.dllを2つロード

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | ON/OFF切替とL/R制御 |

- **611-616行目**: OFF時のtrigger=0リセットとL/R排他処理
- **708-712行目**: ON時のspeed/trigger/mix設定

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

```
play_init
    |
    +-- loadKSHChartFile -> fl_TStp=1
    |
    +-- applyVSTEffects
    |       +-- BASS_VST_ChannelSetDSP(tstp.dll) x2 -> hFX_TStp[0], hFX_TStp[1]
    |
    +-- processAudioEffects
            +-- FXノート切替
                    +-- ON:  speed設定, trigger=1, mix=1
                    +-- OFF: trigger=0, 対側param2=0
```

### データフロー図

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

FXノート(FX_TSTP) ----> processAudioEffects ----------> hFX_TStp.0 (L用)
  feffectparam -------> speed/trigger/mix設定 --------> hFX_TStp.1 (R用)
音楽ストリーム -------> tstp.dll (2インスタンス) -----> スピーカー出力
```

### 関連ファイル一覧

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