Sound Design Engine

このシステムは、高信頼性・低レイテンシなエッジ音響処理、および現場での動的なコンポジションルール更新を可能にするハイブリッドアーキテクチャの音響エンジンです。他システム（Python等のセンサー処理層）とはOSC経由で連携することを想定して設計されており、Raspberry Pi 5（ARM64 Linux）環境等での動作に最適化されています。

アーキテクチャ概要

本システムは、静的・超高速な「音響処理層」と動的・高度に抽象化された「制御層」を完全に分離したハイブリッド構成を採用しています。

1. Rust / C++ (信号処理層)

   • 全二重オーディオ I/O: cpal を介したリアルタイムな全二重オーディオ処理。
   • RNBO: C++でエクスポートされたRNBOモジュールによるDSP処理を担当。
   • Rustはコアシステムのループ制御、OSC処理、C++層へのFFI（rnbo_bridge.cpp）ブリッジ管理を行います。オーディオスレッドは完全にロックフリーかつヒープアロケーションフリーに保たれています。
   • セーフティ機構: 出力段で .clamp(-0.95, 0.95) による保護を行い、過大入力を防止します。

2. Lisp / Scheme (ロジック層・動的スクリプティング)

   • OSCメッセージの待ち受けと、受信したイベントのマッピングルールの動的評価（Steelエンジンを使用）。
   • 評価結果に基づき、ロックフリーのリングバッファ経由でオーディオスレッドへノンブロッキングなパラメータ更新指示（AudioCommand）を送信します。
   • プラグイン形式でロジックを動的に追加・変更することが可能です。

ディレクトリ構造

• core/
  • Cargo.toml / build.rs: ワークスペースおよびC++モジュールビルドの設定
  • src/:
    • main.rs: コアシステムループ、OSC、Lispバインディングのメイン処理
    • rnbo_bridge.cpp: C++ FFI ブリッジ
  • rnbo_exported/: エクスポートされたRNBO（C++）のソースファイル
  • scripts/:
    • main.scm: コア・ディスパッチャスクリプト（不変）
    • plugins/: ユーザー定義プラグイン（動的追加されるスクリプト類）

動作要件

• OS: Linux (Raspberry Pi 5 等のARM64推奨)
• オーディオ要件: libasound2-dev パッケージのインストール（cpal ビルドに必要）。

  sudo apt-get update && sudo apt-get install -y libasound2-dev

• 実行環境要件: リアルタイム割り込みを利用するため、Linuxの /etc/security/limits.d/audio.conf にて @audio - rtprio 95 等の設定が必要です。

チュートリアル: すぐに音を鳴らす

他のアプリを用意せずにOSC送信をテストし、すぐに音を鳴らして確認するためのチュートリアル用ツールが同梱されています。OSC通信のデフォルトポートは 127.0.0.1:57120 です。

1. メインエンジンの起動 ターミナルを開き、core ディレクトリでメインエンジンを起動します。

   cd core
   cargo run

2. チュートリアルデモの実行 別のターミナルを開き、同梱のOSC送信ツールを実行します。これにより 02_tutorial_demo.scm プラグインと連携してメロディが再生されます。

   cd core
   cargo run --bin tutorial_osc_sender

動的なロジックの追加

新しいマッピングルールやシンセロジックを追加する場合は、Rustコアを再ビルドする必要はありません。 core/scripts/plugins/ ディレクトリ内に新しい .scm (Scheme) ファイルを追加するだけで、次回起動時に自動的に読み込まれ、Lisp空間へ統合されます。

開発・コントリビューションの際は、AGENTS.md に記載されているルールを必ず確認し、遵守してください。