はじめに

GitHubで公開しているnonoha-engineを取得し、テンプレートのワークスペースを実行します。ブラウザでアプリが信号を処理する様子を確認し、同じ計算グラフをJSONファイルとAPIから読み書きします。

デスクトップアプリのnonoha Hubはプレリリース中です。公開後は、nonoha Hubからワークスペースを作成し、エディタを含めて実行できます。このページでは、公開しているリポジトリから始めます。

用意するもの

  • Git
  • uv:Pythonのパッケージとプロジェクトを管理するツールです。エンジンが使うPython 3.11がなければ、uvがインストールします。

エンジンを取得する

リポジトリをサブモジュールと一緒にクローンし、依存パッケージをインストールします。サブモジュールは、計算グラフのコアであるnonoha-coreと、SciPyを使うノード集のsci-nodesです。

Shell
git clone --recursive https://github.com/viestyle-dev/nonoha-engine.git
cd nonoha-engine
uv sync

Windowsでは、PowerShellで同じコマンドを実行します。

テンプレートのワークスペースを実行する

テンプレートのワークスペースを指定して、エンジンを起動します。

Shell
uv run python main.py --vnf templates/default/flows/default.vnf --plugins ./templates/default/plugins

ブラウザでhttp://localhost:8000/appを開くと、テンプレートのアプリ「Signal Lab」が表示されます。シンセサイザーの波形、スペクトル、帯域ごとのエネルギー、EMAフィルタで平滑化した信号がリアルタイムに描画され、周波数、倍音の数、波形の種類を画面から変更できます。エンジンを止めるときは、ターミナルでCtrl+Cを押します。

Signal Labの画面。上段に波形とスペクトル、中段に帯域ごとのエネルギーとEMAフィルタで平滑化した信号、下段に周波数、倍音の数、波形の種類を変更するコントロールがある

計算グラフを読む

ワークスペースの計算グラフは、人と機械の両方が読めるJSONファイルです。テンプレートのappグラフは、templates/default/flows/default.vnf/graphs/app.vng/graph.jsonにあります。次はその抜粋です。ノード、プロパティ、エッジが書かれています。

JSON
{
  "nodes": {
    "Clock_1": { "type": "Clock", "properties": { "fs": 600.0, "pack_size": 20 } },
    "Synthesizer_1": { "type": "Synthesizer", "properties": { "frequency": 440.0, "harmonics": 4, "waveform_type": 0 } },
    "EmaFilter_1": { "type": "EmaFilter", "properties": { "in_type": "f32", "alpha": 0.3 } },
    "SpectrumAnalyzer_1": { "type": "SpectrumAnalyzer", "properties": { "fft_size": 256, "bass_cutoff": 0.15, "mid_cutoff": 0.5 } }
  },
  "edges": [
    { "source": "Clock_1.times", "target": "Synthesizer_1.time" },
    { "source": "Synthesizer_1.waveform", "target": "EmaFilter_1.series" },
    { "source": "Synthesizer_1.waveform", "target": "SpectrumAnalyzer_1.signal" },
    { "source": "EmaFilter_1.series", "target": ".smoothed" }
  ]
}

.で始まる名前(.smoothedなど)は、グラフ自身の入出力ポートです。アプリの画面は、この入出力ポートを通して計算グラフとやり取りします。

ClockとEmaFilterは、エンジンに組み込まれた標準のノードです。SynthesizerとSpectrumAnalyzerは、テンプレートのプラグインtemplates/default/plugins/user-nodesにある、普通のPythonで書いたノードです。使えるノードの一覧は、catalogコマンドでJSONファイルに書き出せます。

Shell
uv run python main.py --plugins ./templates/default/plugins catalog -o catalog.json

APIから読み書きする

エンジンは実行中、REST APIとWebSocket APIを提供します。エンジンを起動したまま、別のターミナルから計算グラフの情報を取得します。

Shell
curl http://localhost:8000/node-flow/graphs
curl http://localhost:8000/node-flow/graphs/app/nodes
curl http://localhost:8000/node-flow/graphs/app/nodes/EmaFilter_1/properties

EmaFilterのalphaを小さくすると、アプリの「SMOOTHED (EMA)」の線がなめらかになります。

Shell
curl -X PATCH http://localhost:8000/node-flow/graphs/app/nodes/EmaFilter_1/properties -H "Content-Type: application/json" -d '{"alpha": 0.05}'

PowerShellでは、Invoke-RestMethodを使います。

PowerShell
Invoke-RestMethod http://localhost:8000/node-flow/graphs
Invoke-RestMethod -Method Patch -Uri http://localhost:8000/node-flow/graphs/app/nodes/EmaFilter_1/properties -ContentType application/json -Body '{"alpha": 0.05}'

APIで変更したプロパティは、graph.jsonにも保存されます。テンプレートのファイルを書き換えたくないときは、エンジンを--readonlyを付けて起動します。ファイルを直接編集するときは、先にエンジンを止め、編集後に起動し直します。AIエージェントはファイルの編集もAPIの呼び出しもでき、どちらも同じ計算グラフを変更します。APIの一覧は、エンジンがhttp://localhost:8000/docsに表示します。

次に読む

  • しくみ:ワークスペース、グラフ、ノード、ポートと、流れるデータを説明します。
  • ノードとプラグインを書く:テンプレートのプラグインにノードを追加します。
  • カスタムのWeb UI:計算グラフとやり取りするページを書きます。
  • 計算グラフを図で確認し、編集するエディタ(nonoha-editor)は、ブラウザで動きます。公開しているnonoha-engineにはエディタのビルドが含まれておらず、nonoha Hubの配布物に含まれています。
  • APIの詳細は、nonoha-engineのAPIリファレンスにあります。
  • nonohaを構成するリポジトリは、エコシステムにまとめています。