# 機能設計書 128-kshlib.dll

## 概要

本ドキュメントは、KShootManiaにおけるkshlib.dllの設計を記述する。Switch Audio、チャートファイルオープン、MD5ハッシュ、Twitter連携、ディレクトリ更新検知などの複合的なユーティリティ機能を提供するネイティブDLLである。

### 本機能の処理概要

kshlib.dllは、KShootManiaの多岐にわたるユーティリティ機能を提供するネイティブDLLである。BASSオーディオエンジンと連携したSwitch Audio機能、KSH譜面ファイルのメタデータ解析、IR用MD5ハッシュ計算、Twitter API連携、ディレクトリ変更検知など、HSP3単体では実装が困難な複数の機能をまとめて提供する。

**業務上の目的・背景**：KShootManiaのプレイ機能において、楽曲の途中で音声ファイルをシームレスに切り替えるSwitch Audio機能が必要であり、BASS Audio Libraryとの高度な連携が求められる。また、IR連携用のMD5ハッシュ計算、譜面メタデータの効率的な解析などもHSPスクリプトだけでは処理速度や機能面で不十分であるため、ネイティブDLLとして実装されている。

**機能の利用シーン**：
- ゲームプレイ画面でのSwitch Audio再生（特定タイミングでの音源切替）
- 譜面ファイルからのメタデータ取得（チャート情報の読み取り）
- IR用MD5ハッシュの計算
- ディレクトリの更新検知（楽曲リストの差分更新）

**主要な処理内容**：
1. KSHLib_Init: DLLの初期化（ベースディレクトリ設定）
2. KSHLib_SwitchAudioOpen/Free: Switch Audio用オーディオストリームの作成・解放
3. KSHLib_OpenChartFile/CloseChartFile: 譜面ファイルの開閉
4. KSHLib_GetChartMetaDataValue: 譜面メタデータの取得
5. KSHLib_IsChartUTF8: 譜面ファイルのUTF-8判定
6. KSHLib_GetChartMD5Hash: 譜面のMD5ハッシュ計算
7. KSHLib_IsDirectoryUpdated: ディレクトリの更新検知
8. KSHLib_GetTwitterAPIKey/GetHMACSHA1/GetTwitterStringLength: Twitter API連携
9. KSHLib_BASS_VST_GetParam_Double: VST パラメータのdouble型取得
10. KSHLib_GetVersion: DLLバージョン取得

**関連システム・外部連携**：BASS Audio Library（Switch Audio機能）、Twitter API、ファイルシステム。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主機能 | Switch Audio再生、MD5ハッシュ計算 |
| 3 | 曲選択画面 | 補助機能 | 譜面メタデータ取得、ディレクトリ更新検知 |

## 機能種別

データ連携・計算処理（ネイティブDLL連携）

## 入力仕様

### 入力パラメータ

#### KSHLib_Init

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| dirDefault | sptr | Yes | アプリケーションのベースディレクトリパス | 有効なパスであること |

#### KSHLib_SwitchAudioOpen

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| index | int | Yes | Switch Audioチャンネルインデックス | 0以上 |
| filePath | sptr | Yes | 音声ファイルのパス | 存在するファイルであること |
| flags | int | Yes | BASSストリームフラグ(0x20000等) | 有効なフラグ値 |

#### KSHLib_GetChartMD5Hash

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| filePath | sptr | Yes | 譜面ファイルのパス | 存在するファイルであること |
| dest | var | Yes | MD5ハッシュ値の格納先 | 十分なサイズが確保されていること |

#### KSHLib_OpenChartFile

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| filePath | sptr | Yes | 譜面ファイルのパス | 存在するファイルであること |

### 入力データソース

ファイルシステム上の譜面ファイル(.ksh)、音声ファイル(.ogg/.mp3/.wav)。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| KSHLib_GetVersion戻り値 | int | DLLのバージョン番号 |
| KSHLib_SwitchAudioOpen戻り値 | int | BASSストリームハンドル(mid_sw配列に格納) |
| KSHLib_OpenChartFile戻り値 | int | チャートファイルポインタ(pChart) |
| KSHLib_GetChartMetaDataValue戻り値 | str | メタデータの値文字列 |
| KSHLib_IsChartUTF8戻り値 | int | 1=UTF-8, 0=その他 |
| KSHLib_IsDirectoryUpdated戻り値 | int | 1=更新あり, 0=更新なし |
| MD5ハッシュ値 | str(32文字) | 正規化譜面データのMD5ハッシュ |

### 出力先

呼び出し元のHSPスクリプト変数

## 処理フロー

### 処理シーケンス

```
1. アプリケーション起動時
   └─ KSHLib_Init(dir_default): DLL初期化

2. ゲームプレイ時
   ├─ KSHLib_SwitchAudioOpen: Switch Audio用ストリーム作成
   ├─ (プレイ中: 特定タイミングで音源切替)
   └─ KSHLib_SwitchAudioFree: ストリーム解放

3. 譜面情報取得時
   ├─ KSHLib_OpenChartFile: 譜面ファイルを開く
   ├─ KSHLib_GetChartMetaDataValue: メタデータ値取得
   ├─ KSHLib_IsChartUTF8: エンコーディング判定
   └─ KSHLib_CloseChartFile: 譜面ファイルを閉じる

4. IR連携時
   └─ KSHLib_GetChartMD5Hash: MD5ハッシュ計算
```

### フローチャート

```mermaid
flowchart TD
    A[アプリ起動] --> B[KSHLib_Init: DLL初期化]
    B --> C{処理種別}
    C -->|Switch Audio| D[KSHLib_SwitchAudioOpen]
    D --> E[プレイ中: 音源切替]
    E --> F[KSHLib_SwitchAudioFree]
    C -->|メタデータ取得| G[KSHLib_OpenChartFile]
    G --> H[KSHLib_GetChartMetaDataValue]
    H --> I[KSHLib_CloseChartFile]
    C -->|MD5計算| J[KSHLib_GetChartMD5Hash]
    C -->|ディレクトリ検知| K[KSHLib_IsDirectoryUpdated]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-128-01 | DLL初期化必須 | KSHLib_Init呼び出しが他の関数呼び出しの前提条件 | アプリケーション起動時 |
| BR-128-02 | チャートファイルライフサイクル | Open→GetMetaData→Closeの順序で操作 | メタデータ取得時 |
| BR-128-03 | Switch Audioフラグ | 0x20000フラグを使用してストリーム作成 | SwitchAudioOpen時 |
| BR-128-04 | メタデータデフォルト値 | メタデータが存在しない場合のデフォルト値を指定可能 | GetChartMetaDataValue |

### 計算ロジック

MD5ハッシュ計算のロジックはDLL内部に実装。KSHLib_GetChartMetaDataValueは、HSP側ラッパー(kshlib.as 21-24行目)で文字列長を事前取得してバッファを確保する。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 0 | ストリーム作成失敗 | Switch Audio用ファイルが見つからない | 代替パスで再試行(play_audio_effects.hsp) |
| 0 | チャートファイルオープン失敗 | 譜面ファイルが不正 | 呼び出し元でエラー処理 |

### リトライ仕様

Switch Audio: ファイルが見つからない場合、相対パスと絶対パスの両方を試行する(play_audio_effects.hsp 190-194行目)。

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

該当なし。

## パフォーマンス要件

ネイティブDLL実装により高速に動作。特にSwitch AudioはBASSエンジンとの直接連携により低レイテンシを実現。

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

- Twitter API連携機能(KSHLib_GetTwitterAPIKey)ではAPIキーがDLL内にハードコードされている可能性がある
- HMAC-SHA1の計算機能を提供するが、暗号化処理の安全性はDLL実装に依存

## 備考

- kshootmania.hsp 757行目で`KSHLib_Init dir_default`として初期化
- kshlib.asではKSHLib_GetChartMetaDataValueのHSPラッパーが定義されており、文字列長の自動取得とバッファ確保を行う
- KSHLib_BASS_VST_GetParam_DoubleはBASSのVSTパラメータをdouble型で取得する特殊な関数
- select.hsp内のKSHLib_OpenChartFile呼び出し箇所はコメントアウトされている(3137,3449行目)

---

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

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

### 推奨読解順序

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

DLL関数のインターフェースを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshlib.as | `src/kshlib.as` | 全DLL関数宣言(4-19行目) |
| 1-2 | kshlib.as | `src/kshlib.as` | KSHLib_GetChartMetaDataValueラッパー(21-24行目) |

**読解のコツ**: `#cfunc`は戻り値のある関数、`#func`は戻り値のない関数。`sptr`は文字列ポインタ。ラッパー関数でKSHLib_GetChartMetaDataValueLength→KSHLib_GetChartMetaDataValue_の2段階呼び出しでバッファサイズを自動管理している。

#### Step 2: 初期化と主要呼び出しを理解する

DLLの初期化と各機能の呼び出し箇所を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshootmania.hsp | `kshootmania.hsp` | KSHLib_Init呼び出し(757行目) |
| 2-2 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | KSHLib_SwitchAudioOpen呼び出し(190,194行目) |

**主要処理フロー**:
1. **757行目(kshootmania.hsp)**: `KSHLib_Init dir_default` - DLL初期化
2. **190行目(play_audio_effects.hsp)**: `mid_sw.cnt=KSHLib_SwitchAudioOpen(cnt,swaudio.cnt,0x20000)` - Switch Audioストリーム作成
3. **194行目(play_audio_effects.hsp)**: `mid_sw.cnt=KSHLib_SwitchAudioOpen(cnt,getpath(ccsongfile,32)+swaudio.cnt,0x20000)` - 代替パスでの再試行

#### Step 3: メタデータ取得の仕組みを理解する

KSHLib_GetChartMetaDataValueのラッパー実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshlib.as | `src/kshlib.as` | ラッパー関数定義(20-25行目) |

**主要処理フロー**:
- **22行目**: `sdim ret, KSHLib_GetChartMetaDataValueLength@(pChart, key, defaultValue)` - 文字列長取得とバッファ確保
- **23行目**: `KSHLib_GetChartMetaDataValue_@ pChart, key, ret, defaultValue` - 実データ取得
- **24行目**: `return ret` - 結果返却

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

```
kshootmania.hsp (757行目: KSHLib_Init)
    |
    +-- play_audio_effects.hsp
    |       |
    |       +-- KSHLib_SwitchAudioOpen (190,194行目)
    |       +-- KSHLib_SwitchAudioFree (後始末)
    |
    +-- play_chart_load.hsp
    |       |
    |       +-- KSHLib_GetChartMD5Hash (IR用ハッシュ計算)
    |
    +-- select.hsp (コメントアウト: 3137,3449行目)
    |       |
    |       +-- KSHLib_OpenChartFile (非使用)
    |       +-- KSHLib_GetChartMetaDataValue (非使用)
    |
    +-- kshlib.as (ラッパー関数)
            |
            +-- KSHLib_GetChartMetaDataValue (21-24行目)
                    +-- KSHLib_GetChartMetaDataValueLength
                    +-- KSHLib_GetChartMetaDataValue_
```

### データフロー図

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

dir_default -----------> KSHLib_Init ------------------> (初期化完了)

index + filePath -------> KSHLib_SwitchAudioOpen --------> BASSストリームハンドル
  + flags(0x20000)          |                              (mid_sw配列に格納)
                           +-- BASSエンジン連携

譜面ファイルパス -------> KSHLib_GetChartMD5Hash --------> MD5ハッシュ値(32文字)
                           |
                           +-- メタデータ除外・正規化
                           +-- MD5計算

pChart + key -----------> KSHLib_GetChartMetaDataValue --> メタデータ値(文字列)
  + defaultValue            |
                           +-- キーに対応する値の検索
                           +-- 未存在時はdefaultValue返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshlib.as | `src/kshlib.as` | ソース | kshlib.dllのHSPバインディング定義 |
| kshlib.dll | `kshlib.dll` | DLL | 複合ユーティリティのネイティブ実装 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | KSHLib_Init呼び出し(757行目) |
| play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | ソース | KSHLib_SwitchAudioOpen呼び出し(190,194行目) |
| play_chart_load.hsp | `src/scene/play/play_chart_load.hsp` | ソース | KSHLib_GetChartMD5Hash呼び出し |
| select.hsp | `src/scene/select.hsp` | ソース | KSHLib_OpenChartFile(コメントアウト: 3137,3449行目) |
