# 機能設計書 103-RPPエクスポート

## 概要

本ドキュメントは、K-Shoot Editor(譜面エディタ)におけるReaperプロジェクト(.rpp)形式へのエクスポート機能の設計を記述する。

### 本機能の処理概要

本機能は、編集中のKSH譜面データをREAPER(デジタルオーディオワークステーション)のプロジェクトファイル形式(.rpp)にエクスポートする。BPM変化・拍子変化・オーディオエフェクト(Retrigger等)の情報を含むREAPERプロジェクトXMLを生成し、音楽制作ソフトウェアでの編集・ミキシングを可能にする。

**業務上の目的・背景**: 譜面作成者がエフェクト付きの音楽トラックを制作するために、REAPERでの音声編集ワークフローとの連携が必要であった。v1.60より前に追加された機能であり、旧バージョンとの互換性維持のために残されている。

**機能の利用シーン**: ファイルメニューの「エクスポート」>「REAPERプロジェクト書き出し」(Ctrl+Alt+R)から実行する。エクスポート前に互換性に関する注意ダイアログが表示される。

**主要な処理内容**:
1. 互換性警告ダイアログの表示(v1.60以降のエフェクトは正確にエクスポートされない旨)
2. 保存先ファイルダイアログの表示(.rpp形式)
3. アナログ(レーザー)データのソート処理
4. 楽曲ファイルの長さ取得(BASS_StreamCreateFile/BASS_ChannelGetLength_ms)
5. REAPERプロジェクトXMLの生成(テンポマップ、オーディオトラック、VSTエフェクト設定)
6. Retrigger/Pitch Shift等のエフェクトオートメーション生成
7. ファイルへの書き出し(notesave)

**関連システム・外部連携**: BASS Audio Library(音楽ファイル長さ取得)、REAPER(出力ファイルの利用先)。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 譜面エディタ | 主画面 | ファイルメニュー > エクスポート > REAPERプロジェクト書き出し |

## 機能種別

データ連携(ファイルエクスポート)

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| 譜面データ | 各種配列 | Yes | 現在編集中の譜面データ(note/analog/bpml/beatl/spin等) | - |
| csongfile | 文字列 | Yes | 楽曲ファイルパス | ファイルが存在すること |

### 入力データソース

メモリ上の譜面データ配列

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| RPPファイル | テキストファイル | REAPER Project File形式のXMLテキスト |

### 出力先

ユーザーが指定した.rppファイルパス

## 処理フロー

### 処理シーケンス

```
1. 互換性警告ダイアログ表示
   └─ lang.0.48のメッセージを表示
2. 保存先ファイルダイアログ表示
   └─ dialog "rpp",17,lang.0.32
3. ファイル名に.rpp拡張子を付与（未設定の場合）
4. アナログデータのソート
   └─ 位置(analog.cnt.1)とレーン(analog.cnt.2)でソート
5. 楽曲ファイルの長さ取得
   └─ BASS_StreamCreateFile → BASS_ChannelGetLength_ms
6. RPPヘッダ生成
   └─ REAPER_PROJECT、RIPPLE、TEMPO等の基本設定
7. テンポマップ生成
   └─ bpml配列/beatl配列からTEMPOENVNEWセクションを生成
8. VSTエフェクト設定生成
   └─ dblue Glitch、TLs-Pocket_Limiter等のVSTプリセット
9. Retriggerオートメーション生成
   └─ note配列からRetrigger位置を抽出しPARMENVに変換
10. ファイル書き出し
    └─ notesave rppfname
```

### フローチャート

```mermaid
flowchart TD
    A[CMD_EXPORT_RPP受信] --> B[互換性警告ダイアログ]
    B --> C[保存先ダイアログ]
    C --> D{ファイル名指定?}
    D -->|No| E[処理中断]
    D -->|Yes| F[アナログデータソート]
    F --> G[楽曲ファイル長さ取得]
    G --> H[RPPヘッダ生成]
    H --> I[テンポマップ生成]
    I --> J[VSTエフェクト設定生成]
    J --> K[Retriggerオートメーション生成]
    K --> L[notesaveでファイル書き出し]
    L --> M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-103-01 | 互換性警告 | v1.60以降に追加されたエフェクトは正確にエクスポートされないことを警告する | 常時 |
| BR-103-02 | 拡張子自動付与 | 指定ファイル名に.rpp拡張子がない場合は自動付与する | ファイル名確定時 |
| BR-103-03 | 難易度サフィックス | 出力ファイル名に難易度サフィックス(_lt/_ch/_ex/_in)を付与する | RENDER_FILE設定時 |
| BR-103-04 | テンポマップ生成 | BPM変化と拍子変化の両方をREAPERのテンポエンベロープに変換する | 常時 |

### 計算ロジック

- テンポマップのタイミング計算: `c2ta(位置)` 関数でカウント値をミリ秒に変換し、さらに秒に変換(`/1000`)
- 拍子計算: `4*beatl.cnt.1/beatl.cnt.2` で小節あたりの拍数を算出

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | キャンセル | ファイルダイアログでキャンセル | 処理中断(acmd=-1:return) |

### リトライ仕様

リトライ処理はなし。

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

該当なし。

## パフォーマンス要件

特になし。

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

特になし。

## 備考

- RPPエクスポートは旧バージョン互換機能として位置づけられている
- VSTエフェクトの設定はBase64エンコードされたプリセットデータとしてハードコーディングされている
- 使用されるVSTプラグイン: TLs-Pocket_Limiter, dblue Glitch v1.3

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshooteditor.hsp | `kshooteditor.hsp` | 266-284行目: note/analog/bpml/beatl配列の構造(RPPエクスポートの入力データ) |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshooteditor.hsp | `kshooteditor.hsp` | 3932-5151行目: CMD_EXPORT_RPP処理全体 |

**主要処理フロー**:
1. **3932行目**: `if(cmd=CMD_EXPORT_RPP)` でコマンド判定
2. **3934行目**: 互換性警告ダイアログ表示
3. **3942行目**: `dialog "rpp",17,lang.0.32` で保存ダイアログ
4. **3946-3947行目**: ファイル名取得と.rpp拡張子付与
5. **3949-3967行目**: アナログデータのソート処理
6. **3970-3973行目**: 楽曲ファイルの長さ取得(BASS API)
7. **3975-3990行目**: RPPヘッダとテンポ設定の生成
8. **3995-4016行目**: BPM変化/拍子変化のテンポエンベロープ生成
9. **4047-4079行目**: Retriggerエフェクトのオートメーション生成
10. **5151行目**: `notesave rppfname` でファイル書き出し

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

```
*OnCommand
    └─ CMD_EXPORT_RPP
        ├─ dialog (警告ダイアログ)
        ├─ dialog (保存ダイアログ)
        ├─ BASS_StreamCreateFile (楽曲長さ取得)
        ├─ BASS_ChannelGetLength_ms
        ├─ c2ta (カウント→ms変換)
        └─ notesave (ファイル書き出し)
```

### データフロー図

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

note配列(エフェクト情報) ──▶  RPP生成エンジン            ───▶  .rppファイル
analog配列(レーザー)     ──▶  (テンポマップ・VST設定・        (REAPERプロジェクト)
bpml配列(BPM変化)       ──▶   オートメーション生成)
beatl配列(拍子変化)     ──▶
楽曲ファイル             ──▶  BASS API(長さ取得)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | RPPエクスポート処理(3932-5151行目) |
| bass.as | `src/bass.as` | ソース | BASS Audio Library関数バインディング |
