# 機能設計書 130-BASS Audio Library

## 概要

本ドキュメントは、KShootManiaにおけるBASS Audio Libraryの設計を記述する。bass.dll / bass_fx.dll / bass_vst.dll / bassconv.dll の4つのDLLで構成されるオーディオエンジンDLL群であり、ゲーム全体の音声再生・エフェクト処理の基盤を提供する。

### 本機能の処理概要

BASS Audio Libraryは、Un4seen Developments社が提供するオーディオエンジンライブラリであり、KShootManiaの全ての音声処理の基盤となっている。OGG/MP3/WAV形式の音声ファイルの再生、VST(Virtual Studio Technology)エフェクトの適用、テンポ変更(FX)、再生位置のミリ秒単位制御(bassconv)など、音楽ゲームに必要な高度なオーディオ機能を提供する。

**業務上の目的・背景**：音楽ゲームでは、楽曲の正確な再生・タイミング同期・リアルタイムエフェクト処理が不可欠である。HSP3の標準音声機能では対応できない低レイテンシ再生、複数トラック同時再生、VSTエフェクト適用などの高度な要件を満たすために、BASS Audio Libraryを採用している。

**機能の利用シーン**：
- タイトル画面/選曲画面/リザルト画面のBGM再生
- ゲームプレイ画面での楽曲再生（デュアルトラック対応）
- プレビューBGMの再生・フェードイン/アウト
- VSTエフェクト(Retrigger/Gate/Flanger/Phaser等)の適用
- キー音(SE)の再生
- テンポ変更(半速再生)

**主要な処理内容**：
1. BASS_Init: オーディオエンジンの初期化
2. BASS_StreamCreateFile/URL: 音声ストリームの作成（ファイル/URL）
3. BASS_ChannelPlay/Pause/Stop: チャンネルの再生制御
4. BASS_ChannelSetAttribute: チャンネル属性の設定（音量等）
5. BASS_ChannelSlideAttribute: チャンネル属性のスムーズな変更（フェード等）
6. BASS_SampleLoad/GetChannel: サンプル音の読み込みと再生
7. BASS_ChannelSetFX: エフェクトの適用
8. BASS_FXSetParameters: エフェクトパラメータの設定
9. BASS_SetConfig: グローバル設定（バッファ長等）
10. BASS_FX_TempoCreate: テンポ変更ストリームの作成
11. BASS_VST_ChannelSetDSP: VSTエフェクトDLLの読み込み・適用
12. BASS_VST_SetParam: VSTエフェクトパラメータの設定
13. BASS_ChannelGetLength_ms/SetPosition_ms/GetPosition_ms: ミリ秒単位の再生位置制御

**関連システム・外部連携**：bass.dll, bass_fx.dll, bass_vst.dll, bassconv.dll, VSTエフェクトDLL群(lib/配下)。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | タイトル画面 | 補助機能 | タイトルBGM・SE再生 |
| 2 | IRサインイン画面 | 補助機能 | BGMフェードアウト・SE再生 |
| 3 | 曲選択画面 | 補助機能 | プレビューBGM・SE再生 |
| 5 | ゲームプレイ画面 | 主機能 | 楽曲再生・VSTエフェクト・キー音 |
| 6 | リザルト画面 | 補助機能 | リザルトBGM再生 |
| 7 | コースリザルト画面 | 補助機能 | コースリザルトBGM再生 |
| 8 | オプション設定画面 | 補助機能 | オプションBGM再生 |

## 機能種別

オーディオエンジン（音声再生・エフェクト処理基盤）

## 入力仕様

### 入力パラメータ

#### BASS_Init

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| device | int | Yes | デバイスID (-1=デフォルト) | -1以上 |
| freq | int | Yes | サンプルレート (44100Hz) | 正の整数 |
| flags | int | Yes | 初期化フラグ (0) | なし |
| win | int | Yes | ウィンドウハンドル (hwnd) | 有効なハンドル |

#### BASS_StreamCreateFile

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| mem | int | Yes | 0=ファイル, 1=メモリ | 0または1 |
| file/data | sptr/int | Yes | ファイルパスまたはメモリポインタ | なし |
| offset_lo | int | Yes | オフセット(下位) | 0 |
| offset_hi | int | Yes | オフセット(上位) | 0 |
| length_lo | int | Yes | 長さ(下位, 0=全体) | 0以上 |
| length_hi | int | Yes | 長さ(上位) | 0 |
| flags | int | Yes | ストリームフラグ | BASS_SAMPLE_LOOP=4等 |

#### BASS_VST_ChannelSetDSP

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| chan | int | Yes | BASSチャンネルハンドル | 有効なハンドル |
| dllFile | sptr | Yes | VSTプラグインDLLのパス | 存在するDLLファイル |
| createFlags | int | Yes | 作成フラグ (0) | なし |
| priority | int | Yes | DSP優先度 | 整数 |

### 入力データソース

ファイルシステム上の音声ファイル(.ogg/.mp3/.wav)、VSTプラグインDLL(lib/配下)。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| BASS_StreamCreateFile戻り値 | int | BASSストリームハンドル (0=失敗) |
| BASS_SampleLoad戻り値 | int | BASSサンプルハンドル (0=失敗) |
| BASS_ChannelSetFX戻り値 | int | エフェクトハンドル (0=失敗) |
| BASS_VST_ChannelSetDSP戻り値 | int | VSTエフェクトハンドル (-1=失敗) |
| BASS_ChannelGetPosition_ms戻り値 | int | 再生位置(ミリ秒) |
| BASS_ChannelGetLength_ms戻り値 | int | 楽曲長(ミリ秒) |
| BASS_ErrorGetCode戻り値 | int | 最後のエラーコード (0=成功) |

### 出力先

スピーカー/ヘッドフォン（音声出力）、呼び出し元のHSPスクリプト変数

## 処理フロー

### 処理シーケンス

```
1. アプリケーション起動時
   ├─ BASS_Init(-1, 44100, 0, hwnd): エンジン初期化
   └─ BASS_SetConfig: バッファ長・更新周期の設定

2. BGM再生時
   ├─ BASS_StreamCreateFile: ストリーム作成
   ├─ BASS_ChannelSetAttribute(id, 2, volume): 音量設定
   └─ BASS_ChannelPlay: 再生開始

3. ゲームプレイ時
   ├─ BASS_StreamCreateFile: 楽曲ストリーム作成(デュアルトラック)
   ├─ BASS_VST_ChannelSetDSP: VSTエフェクト読み込み
   ├─ BASS_ChannelPlay: 楽曲再生開始
   ├─ (毎フレーム) BASS_ChannelSetAttribute: 音量制御
   ├─ (毎フレーム) BASS_VST_SetParam: エフェクトパラメータ更新
   └─ (毎フレーム) BASS_ChannelGetPosition_ms: 再生位置取得

4. アプリケーション終了時
   └─ BASS_Free: エンジン解放(onexit)
```

### フローチャート

```mermaid
flowchart TD
    A[アプリ起動] --> B[BASS_Init: エンジン初期化]
    B --> C[BASS_SetConfig: バッファ設定]
    C --> D{シーン}
    D -->|BGM再生| E[BASS_StreamCreateFile]
    E --> F[BASS_ChannelSetAttribute: 音量]
    F --> G[BASS_ChannelPlay]
    D -->|プレイ開始| H[楽曲ストリーム作成]
    H --> I[BASS_VST_ChannelSetDSP: VSTロード]
    I --> J[BASS_ChannelPlay: 楽曲開始]
    J --> K[毎フレーム更新ループ]
    K --> L[BASS_ChannelGetPosition_ms]
    K --> M[BASS_VST_SetParam: エフェクト更新]
    D -->|終了| N[BASS_Free: エンジン解放]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-130-01 | 初期化パラメータ | サンプルレート44100Hz、デフォルトデバイスで初期化 | アプリケーション起動時 |
| BR-130-02 | ループ再生 | BASS_SAMPLE_LOOP(=4)フラグでBGMのループ再生 | タイトルBGM等 |
| BR-130-03 | 音量制御 | 属性ID=2(BASS_ATTRIB_VOL)で0.0～1.0の範囲で音量制御 | 全音声 |
| BR-130-04 | onexit解放 | BASS_Freeはonexit指定により自動解放 | アプリケーション終了時 |
| BR-130-05 | VSTエラーリトライ | BASS_VST_SetParam_Rで最大5回のリトライ | VSTパラメータ設定時 |
| BR-130-06 | ストリームフラグ | 0x20000(BASS_STREAM_DECODE)で楽曲ストリームを作成 | プレイ時 |

### 計算ロジック

音量計算: `double(mastervol)/100` により、0-100の整数値を0.0-1.0のfloat値に変換して適用。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 0 | ストリーム作成失敗 | ファイルが見つからない/非対応形式 | ハンドル値0を判定して処理スキップ |
| -1 | VSTロード失敗 | VSTプラグインDLLが見つからない/互換性なし | BASS_VST_SetParam_Rでvst_a != -1チェック |
| BASS_ErrorGetCode | エンジンエラー | 各種BASS API呼び出し失敗 | BASS_ErrorGetCode()で詳細コード取得 |

### リトライ仕様

BASS_VST_SetParam_R(bass_vst.as): VSTパラメータ設定時にエラーが発生した場合、最大5回のリトライを実行（12-22行目）。

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

該当なし。

## パフォーマンス要件

- 低レイテンシ音声再生: バッファ長(BASS_SetConfig)で調整可能
- 44100Hzサンプルレートでの高音質再生
- 複数チャンネル同時再生(デュアルトラック + キー音 + SE)
- VSTエフェクトのリアルタイム適用

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

- BASSライブラリは商用利用にはライセンスが必要
- VSTプラグインDLLの読み込みは信頼できるDLLのみに限定すべき

## 備考

- BASS Audio Libraryはhttp://www.un4seen.com/で配布されている
- 4つのDLLで構成: bass.dll(コア), bass_fx.dll(テンポ変更), bass_vst.dll(VST連携), bassconv.dll(位置変換)
- kshootmania.hsp(771行目)とkshooteditor.hsp(643行目)の両方でBASS_Initが呼び出される
- bass.asの`BASS_Free onexit`により、アプリケーション終了時に自動的にエンジンが解放される
- BASS_VST_SetParam_Rはbass_vst.as内のラッパーで、エラー時のリトライ機能を追加

---

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

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

### 推奨読解順序

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

4つのDLLバインディングファイルのインターフェースを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | bass.as | `src/bass.as` | コアAPI関数宣言(5-44行目): Init/StreamCreate/ChannelPlay等 |
| 1-2 | bass_fx.as | `src/bass_fx.as` | テンポ変更API(6行目): BASS_FX_TempoCreate |
| 1-3 | bass_vst.as | `src/bass_vst.as` | VST連携API(5-7行目): ChannelSetDSP/SetParam/GetParam |
| 1-4 | bassconv.as | `src/bassconv.as` | 位置変換API(5-7行目): GetLength_ms/SetPosition_ms/GetPosition_ms |

**読解のコツ**: BASS APIは「チャンネルハンドル」を中心に動作する。BASS_StreamCreateFileやBASS_SampleGetChannelでハンドルを取得し、そのハンドルに対してPlay/Stop/SetAttribute等の操作を行う。属性ID=2はBASS_ATTRIB_VOL(音量)を表す。

#### Step 2: 初期化処理を理解する

BASSエンジンの初期化と基本設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshootmania.hsp | `kshootmania.hsp` | BASS_Init呼び出し(771行目) |
| 2-2 | bass.as | `src/bass.as` | BASS_Free onexit定義(12行目) |

**主要処理フロー**:
1. **771行目(kshootmania.hsp)**: `BASS_Init -1,44100,0,hwnd` - デフォルトデバイスで44100Hz初期化
2. **12行目(bass.as)**: `#func BASS_Free onexit "BASS_Free"` - onexit指定で自動解放

#### Step 3: 音声再生の流れを理解する

代表的な音声再生パターン（タイトルBGM）を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | title.hsp | `src/scene/title.hsp` | BGMストリーム作成と再生(576-579行目) |

**主要処理フロー**:
- **576行目**: `titlebgmid=BASS_StreamCreateFile(0,dir_default+"\\se\\title_bgm.ogg",0,0,0,0,BASS_SAMPLE_LOOP)` - ループ付きストリーム作成
- **578行目**: `BASS_ChannelSetAttribute titlebgmid,2,double(mastervol)/100` - 音量設定
- **579行目**: `BASS_ChannelPlay titlebgmid` - 再生開始

#### Step 4: VSTエフェクトの適用を理解する

プレイ画面でのVSTエフェクト適用処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | BASS_VST_ChannelSetDSP呼び出し(208-296行目) |
| 4-2 | bass_vst.as | `src/bass_vst.as` | BASS_VST_SetParam_Rラッパー(12-23行目) |

**主要処理フロー**:
- **229行目**: `hFX_Retr=BASS_VST_ChannelSetDSP(mid.0,dir_default+"\\lib\\regawo.dll",0,25)` - Retriggerエフェクト適用
- **12-22行目(bass_vst.as)**: BASS_VST_SetParam_R - エラー時最大5回リトライするラッパー

#### Step 5: テンポ変更と位置制御を理解する

half speed再生と再生位置取得を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | kshooteditor.hsp | `kshooteditor.hsp` | BASS_FX_TempoCreate使用(15489行目) |
| 5-2 | bassconv.as | `src/bassconv.as` | ミリ秒単位の位置制御API |

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

```
kshootmania.hsp
    |
    +-- BASS_Init (771行目: エンジン初期化)
    |
    +-- title.hsp
    |       +-- BASS_StreamCreateFile (BGM作成)
    |       +-- BASS_ChannelSetAttribute (音量設定)
    |       +-- BASS_ChannelPlay (再生)
    |
    +-- select.hsp
    |       +-- BASS_StreamCreateFile/URL (プレビューBGM)
    |       +-- BASS_ChannelSlideAttribute (フェード)
    |
    +-- play_audio.hsp
    |       +-- BASS_StreamCreateFile (楽曲ストリーム)
    |       +-- BASS_ChannelPlay (楽曲再生)
    |
    +-- play_audio_effects.hsp
    |       +-- BASS_VST_ChannelSetDSP (VSTエフェクトロード)
    |       |       +-- regawo.dll (Retrigger/Gate/Wobble/Echo)
    |       |       +-- bitc.dll (BitCrusher)
    |       |       +-- flan.dll (Flanger)
    |       |       +-- phas.dll (Phaser)
    |       |       +-- pitc.dll (PitchShift)
    |       |       +-- tstp.dll (TapeStop)
    |       |       +-- sich.dll (Sidechain)
    |       +-- BASS_VST_SetParam_R (パラメータ設定)
    |       +-- BASS_ChannelSetFX (BASSエフェクト)
    |       +-- BASS_FXSetParameters (パラメータ設定)
    |
    +-- result.hsp / course_result.hsp
    |       +-- BASS_StreamCreateFile (リザルトBGM)
    |       +-- BASS_ChannelPlay (再生)
    |
    +-- BASS_Free (onexit: 自動解放)

kshooteditor.hsp
    |
    +-- BASS_Init (643行目)
    +-- BASS_SampleLoad (815-816行目: tick/tick2音)
    +-- BASS_StreamCreateFile (3972行目: 楽曲)
    +-- BASS_FX_TempoCreate (15489行目: テンポ変更)
    +-- BASS_VST_ChannelSetDSP (15515行目等: VSTエフェクト)
```

### データフロー図

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

音声ファイル(.ogg等) ----> BASS_StreamCreateFile ---------> ストリームハンドル
                              |                               |
                              v                               v
                         BASS_ChannelSetAttribute        スピーカー出力
                         BASS_ChannelPlay                 (再生開始)

VSTプラグイン(.dll) ------> BASS_VST_ChannelSetDSP -------> VSTハンドル
  (lib/配下)                  |                               |
                              v                               v
                         BASS_VST_SetParam              エフェクト適用済み音声
                         (パラメータ更新)

再生位置要求 -------------> BASS_ChannelGetPosition_ms ---> 位置(ミリ秒)
                              (bassconv.dll)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| bass.as | `src/bass.as` | ソース | bass.dllのHSPバインディング定義 |
| bass_fx.as | `src/bass_fx.as` | ソース | bass_fx.dllのHSPバインディング定義 |
| bass_vst.as | `src/bass_vst.as` | ソース | bass_vst.dllのHSPバインディング定義+リトライラッパー |
| bassconv.as | `src/bassconv.as` | ソース | bassconv.dllのHSPバインディング定義 |
| bass.dll | ルート | DLL | BASSオーディオエンジン本体 |
| bass_fx.dll | ルート | DLL | テンポ変更機能 |
| bass_vst.dll | ルート | DLL | VSTプラグイン連携 |
| bassconv.dll | ルート | DLL | ミリ秒単位の位置変換 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | BASS_Init呼び出し(771行目) |
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | BASS_Init呼び出し(643行目) |
| title.hsp | `src/scene/title.hsp` | ソース | タイトルBGM再生 |
| select.hsp | `src/scene/select.hsp` | ソース | プレビューBGM再生 |
| play_audio.hsp | `src/scene/play/play_audio.hsp` | ソース | 楽曲再生 |
| play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | ソース | VSTエフェクト適用 |
| result.hsp | `src/scene/result.hsp` | ソース | リザルトBGM再生 |
| course_result.hsp | `src/scene/course_result.hsp` | ソース | コースリザルトBGM再生 |
