geedback_clap

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs | README

README.md (5341B)

      1 # Geedback Clap
      2 
      3 ## Building
      4 
      5 After installing [Rust](https://rustup.rs/), you can compile Geedback Clap as follows:
      6 
      7 ```shell
      8 cargo xtask bundle geedback_clap --release
      9 ```
     10 
     11 # Geedback (CLAP Plugin via nih-plug)
     12 
     13 スマートフォンの6軸センサー（加速度・ジャイロ）のリアルタイムデータを、DAW（REAPER）のOSC受信・マッピング機能を介してパラメータとして受け取り、音響合成およびエンベロープ変調を行うCLAPシンセサイザープラグイン。
     14 
     15 ## 1. システムアーキテクチャ
     16 
     17 本システムは、ネットワーク処理をDAW側（REAPER）に委ねることで、プラグイン内部のオーディオスレッドのリアルタイム性と安全性を最大化する設計を採用する。
     18 
     19 
     20 ```mermaid
     21 graph TD
     22     A[スマートフォン ZIG SIM等] -->|Wi-Fi / UDP / OSCプロトコル| B[REAPER OSC受信とReaLearn(helgobox)]
     23     B -->|CLAP Parameter Automation / Modulation| C[nih-plug Geedback コア音響合成処理]
     24 ```
     25 
     26 ### 動作のフロー
     27 1. スマートフォンアプリから、PCの特定ポートへ6軸のOSCパケットをUDP伝送。
     28 2. REAPERがOSCを受信し、ReaLearnによってOSCの/ZIMSIG/iPad/accelや/quaternionを本プラグインのCLAPパラメータへ直接マッピング。
     29 3. `nih-plug` はDAWから高解像度なパラメータ変更イベント（`ParamValueEvent`）としてセンサー値を受け取り、音響合成ロジックへ供給。
     30 
     31 ---
     32 
     33 ## 2. プラグイン仕様 (Plugin Specifications)
     34 
     35 ### 基本情報
     36 * **フレームワーク:** `nih-plug` (Rust)
     37 * **フォーマット:** CLAP (Clever Audio Plug-in)
     38 * **プラグインタイプ:** シンセサイザー / インストゥルメント (`ClapFeature::Synthesizer`)
     39 
     40 ### パラメーター定義 (6軸入力)
     41 全てのセンサー値は、ホスト（REAPER）から `-1.0` 〜 `1.0` の一様化された `f32` 値として受け取る。各パラメータは `nih-plug` の `Smoother`（平滑化フィルタ）を通し、Wi-Fi通信のジッターに起因するノイズを抑制する。
     42 
     43 | パラメータID | パラメータ名 | 役割 | 処理（内部バッファでの扱い） |
     44 | :--- | :--- | :--- | :--- |
     45 | `accel_x` | Accel X | 加速度 X軸 | 内部エンベロープ/モジュレーションソース |
     46 | `accel_y` | Accel Y | 加速度 Y軸 | 内部エンベロープ/モジュレーションソース |
     47 | `accel_z` | Accel Z | 加速度 Z軸 | 内部エンベロープ/モジュレーションソース |
     48 | `gyro_x`  | Quaternion X  | 回転 X軸 | 内部エンベロープ/モジュレーションソース |
     49 | `gyro_y`  | Quaternion Y  | 回転 Y軸 | 内部エンベロープ/モジュレーションソース |
     50 | `gyro_z`  | Quaternion Z  | 回転 Z軸 | 内部エンベロープ/モジュレーションソース |
     51 
     52 ---
     53 
     54 ## 3. 実装要件 (Implementation Requirements)
     55 
     56 ### 3.1 データ平滑化 (Smoothing)
     57 スマホのOSC送信周期（例: 30Hz〜100Hz）と、オーディオスレッドのサンプリングレート（例: 44.1kHz）のギャップ、および通信の揺らぎを補正するため、各パラメータには必ず `nih-plug` 標準の `FloatParam` に備わっているスムージング機能を適用する。
     58 
     59 ### 3.2 音響合成ブロック (DSP Block)
     60 `ProcessHandler::process` 内において、平滑化された6軸の値を基準にエンベロープの形状やオシレーターの変調度をリアルタイムに書き換え、Geedbackの信号処理ロジックへとルーティングする。ネットワークソケット等のブロッキング処理は一切記述しない。
     61 
     62 ## 4. 使い方
     63 開発者の環境がReaper+ZIM SIGなため、使い方の説明もその環境で行います。他の環境での動作は保証しません。
     64 
     65 ### 4.1 送信側の準備
     66 Reaperを動かしているPCと同一のネットワーク内にZIM SIGをインストールしたスマートフォンやiPadを接続します。
     67 Zim SIGを起動したら、センサータブでACCELとQUATERNIONを有効化し、設定タブからMessage FormatをOSCに設定し、IPアドレスをReaper側のものにして、Startタブを押してストリーミングを開始します。
     68 
     69 ### 4.2 受信側の準備
     70 Reaperのトラックにhelgoboxを追加し、inputのところをクリックし、新しいOSCを追加するところで、PCのIPアドレスとZIMSIGで設定したポート番号、適当なデバイス名(ここでは例としてiPad)を設定します。
     71 
     72 ### 4.3 マッピング
     73 helgoboxのmappingで、add oneをクリックし、sourceでOSCを選択してから、アドレスのところに/ZIMSIG/iPad/accelなどと入力します。アドレスは`/`区切りであること以外は、かなり場合により様々です。が、上のLearnボタンを押すと良さげな例を示してくれるので、それのaccelの部分を自分で書き換えるなどすると、非常に楽に設定をすることができます。
     74 accelの値は3次元のfloatベクトルとして渡されるので、それが何番目の値かを下で選択できます。
     75 次に、Targetをダミーと設定されている部分をFX Parameterに変更し、どのトラックのどのFXのどのパラメーターに突っ込むかを設定します。