1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Code が VST プラグインの GUI を画面に出さずに描いて CI で検査した話

1
Posted at

はじめに

Claude Code と一緒に、DAW 用のスペクトラム表示のプラグインを作りました。入力の音の周波数ごとの大きさを曲線で表示するプラグインです。

image.gif

GUI の確認は DAW で開いて目で見るしかないと思っていました。ところが、Claude Code が出してきた計画は、GUI を画面に出さずに描き、その画像を正解の画像と比べて、GitHub Actions の CI で検査するというものでした。

結果として、GPU も画面もない CI のランナーで、GUI 描画を検査するという芸当を Claude Code はやってのけました。ただし、画面に出さない描画で確かめられるのは「決めたとおりの描画」までです。GUI の開閉については pluginval、使用感については最終的に人の目視が必要でした。

Simple Spectrum とは

今回作ったプラグインです。VST 3 と CLAP の形式で、Windows x64 と Linux x86_64 向けに MIT ライセンスで公開しています。

プラグインは CLAP の C の API で書き、VST 3 版は clap-wrapper で同じコードから作っています。

Visage とは

Visage は、シンセサイザー Vital の作者が公開している、GPU で描く UI のライブラリです。MIT ライセンスで、Windows では Direct3D 11、Linux では Vulkan で描きます。CLAP のプラグインに組み込む公式の例があり、画面に出さずに描いて画素を読み出す機能 (Canvas::setWindowless と takeScreenshot) も持っています。

対象読者

  • Claude Code などの AI コーディングエージェントで DAW のプラグインや GUI を持つアプリを作っている方
  • プラグインの GUI を CI で自動で確かめられる範囲を知りたい方

検証環境

  • Windows 11
  • GitHub Actions の windows-2022 と ubuntu-24.04 のランナー
  • Visage 1.0.0、clap-wrapper 0.17.0
  • pluginval 2.0.0-beta3、clap-validator 0.4.1
  • Claude Code

背景

プラグインの GUI には、ふつうのデスクトップのアプリにない制約があります。

  • プラグインは自分のウインドウを持たず、DAW が渡す親のウインドウの中に子のウインドウを作ります。Linux では、X11 の接続を DAW に登録し、DAW のループから呼び返してもらいます
  • clap-wrapper で作った VST 3 版では、プラグインが DAW に登録するタイマーの周期が 30 ms 未満なら 30 ms に丸められます。DAW のタイマーで描き直すと、表示は 1 秒あたり約 33 回が上限になります
  • GitHub Actions のランナーには GPU がありません。GPU で描く GUI は、CPU で GPU の働きを真似るソフトウェアの実装の上で動く必要があります

Claude Code に、プラグインの検証ツールを調べてもらったところ、GUI を開くのは pluginval だけでした。pluginval は GUI を開閉し、GUI を開いたまま音を処理したりパラメーターを動かしたりして、異常終了しないことを確かめます。clap-validator と VST 3 SDK の validator には、GUI のテストがありませんでした。

描かれた中身を CI で確かめていた実例は、chowdsp_utils の 1 件だけ見つかりました。固定の入力から描いた画像を、正解の画像と許容誤差付きで比べる方式です。今回はこれにならいました。

構成

GUI の確認を、次の 4 つのレイヤーに分けました。

# レイヤー 確かめること 方法
1 表示の数値 ピークの位置、音の大きさの読み、軸の範囲、平滑化、GUI の大きさを変えたときの位置 描画から切り離した計算の単体テスト
2 描画 決まった入力から、決まった絵が描けること 画面に出さずに描き、正解の画像と比べる
3 GUI の開閉 GUI を開く・閉じる・処理中に開く・開いたままパラメーターを動かす pluginval (strictness 10)
4 見た目と操作感 DAW の中での見え方、GUI の大きさの変更、高解像度の画面、ちらつき リリース前に人が確かめるチェックリスト

描画の関数の共有

プラグインの GUI が描くときも、テストが画面に出さずに描くときも、同じ描画の関数 drawSpectrum を呼びます。テストは、利用者が見る画素そのものを確かめていることになります。プラグインの GUI は、描くたびに音のスレッドから受け取った音を解析し、曲線を描いて、次のフレームの描画を予約します (コードの最後の window->redraw())。

src/plugin.cpp
void drawFrame(Plugin *p, visage::Canvas &canvas)
{
	visage::ApplicationWindow *window = p->window.get();
	const ssp::DisplaySettings settings = displaySettings(p);
	p->analyzer.setSampleRate(p->sampleRate.load(std::memory_order_relaxed));
	p->analyzer.setSettings(settings);
	const size_t count = p->ring.read(p->ringCursor, p->scratch.data(), p->scratch.size());
	p->analyzer.push(p->scratch.data(), count);
	p->analyzer.update();
	const int width = int(std::lround(window->width()));
	const int height = int(std::lround(window->height()));
	ssp::drawSpectrum(canvas, width, height, p->analyzer.columns(ssp::plotArea(width, height).width),
			  settings.floorDb);
	window->redraw();
}

FFT と描画は GUI のスレッドで行い、音のスレッドは解析する音をロックなしで受け渡すだけにしています。CPU が足りないときに、音が途切れるのではなく、表示のフレームレートが下がるようにするためです。

経過時間の数え方

スペクトラムの表示は、毎回の解析の結果をそのまま描かず、前回までの表示と混ぜ合わせて滑らかに動かします。新しい結果を混ぜる割合は、前回の解析からの経過時間で決まります。この経過時間を時計で測ると、同じ入力でもマシンの速さによって混ぜる割合が変わり、描かれる絵も変わってしまいます。これではテストで正解の画像と比べられません。そこで、経過時間を時計ではなく、前回の解析から受け取ったサンプルの数で数えるようにしました。

src/spectrum-analyzer.cpp
	const double tau = settings_.smoothing * kMaxSmoothingSeconds * sampleRate_;
	const double alpha = ready_ && tau > 0.0 ? 1.0 - std::exp(-double(pending_) / tau) : 1.0;

pending_ が前回の解析から受け取ったサンプルの数で、alpha が新しい結果を混ぜる割合です。同じ入力を同じ区切りで渡せば、いつどこで描いても同じ絵になります。

正解の画像との比較

テストは、固定の入力 (1 kHz の正弦波と、種を固定したピンクノイズ) を解析して画面に出さずに描き、正解の画像と画素ごとに比べます。1 画素の 4 つのチャンネルのうち最も大きい差が 4 階調を超えた画素を「違う画素」と数え、違う画素が全体の 0.2 % 以下なら合格にしました。違う画素は赤く塗った差分の画像に書き出し、テストが失敗したときに目で原因を探せるようにしています。

tests/render-test.cpp
	for (size_t p = 0; p < size_t(kWidth) * kHeight; ++p) {
		int worst = 0;
		for (int c = 0; c < 4; ++c)
			worst = std::max(worst, std::abs(int(a[4 * p + c]) - int(expected[4 * p + c])));
		result.maxChannel = std::max(result.maxChannel, worst);
		if (worst > kChannelTolerance) {
			++result.differing;
			diff[4 * p] = 255;
			diff[4 * p + 1] = 40;
			diff[4 * p + 2] = 40;
		} else {
			for (int c = 0; c < 3; ++c)
				diff[4 * p + c] = uint8_t(expected[4 * p + c] / 3);
		}
		diff[4 * p + 3] = 255;
	}

同じテストの中で、わざと誤りを入れた 2 枚の画像も描いて比べます。1 kHz のはずのピークを 2 kHz に描いた画像と、曲線のない画像です。この 2 枚を正解の画像と比べると不合格になることを確かめ、許容誤差が甘すぎて何でも通る状態になっていないことを保証しています。

GPU のない Linux での描画

Linux のランナーでは、Mesa の lavapipe (CPU で動く Vulkan の実装) を入れ、仮想の画面 Xvfb の上で pluginval を動かします。lavapipe のドライバーの定義ファイルは、パッケージの中から探して VK_DRIVER_FILES に指定しています。

.github/workflows/build.yaml
          # The file name of lavapipe's driver manifest differs between Mesa versions, so look it up in the package.
          # An empty VK_DRIVER_FILES would hide every driver, so stop here if it is missing.
          icd=$(dpkg -L mesa-vulkan-drivers | grep -E '/lvp_icd[^/]*\.json$' | head -n 1)
          if [ -z "${icd}" ]; then
            dpkg -L mesa-vulkan-drivers | grep -E '\.json$'
            echo "lavapipe driver manifest not found" >&2
            exit 1
          fi
          echo "VK_DRIVER_FILES=${icd}" >> "${GITHUB_ENV}"

CI の記録では、選ばれたデバイスは llvmpipe (LLVM 20.1.2, 256 bits)、種類は PHYSICAL_DEVICE_TYPE_CPU でした。Windows のランナーには特別な設定をしていません。

検証と結果

同じ入力での再現性

同じ入力から 2 回描いた画像の差は、手元の GPU、CI の Windows、CI の Linux のすべてで 0 バイトでした。

環境の間の差

文字の目盛りを含む 640 × 320 画素 (204,800 画素) の画像を、環境の間で比べました。

比べた組 違う画素の数 (画素) 1 チャンネルの最大の差 (階調)
CI の Linux (lavapipe) と CI の Windows 22 1
CI の Linux (lavapipe) と手元の GPU 323 1

Direct3D 11 と Vulkan、ソフトウェアの描画と GPU と、描画の仕組みがまったく違うのに、差は目では分からない 1 階調にとどまりました。この結果から、正解の画像は CI の Linux が描いた 1 枚にして、Windows の CI でも同じ画像と比べています。

2026111602-qiita-spectrum-gui-test-golden.png

比べたのは 1 種類の画像だけです。文字や細かい図形の多い GUI では、環境の間の差が増えると思います。正解の画像を OS ごとに持つ方式も考えられます。

誤りを入れた画像の検出

わざと誤りを入れた 2 枚は、どちらも不合格と判定されました。

入れた誤り 違う画素の数 (画素) 違う画素の割合 (%) 結果
ピークを 2 kHz に描く 1,780 0.87 不合格
曲線を描かない 71,643 34.98 不合格

ピークをずらした画像の差分は、次のように赤く表示されます。

2026111602-qiita-spectrum-gui-test-broken-moved-peak.png

2026111602-qiita-spectrum-gui-test-difference-moved-peak.png

GUI の開閉の検査

pluginval は、strictness 10 で、GUI を開くテストも含めて GPU のない Windows と Linux のランナーで合格しました。GUI を開いたまま全パラメーターを動かすテストや、処理を止めた状態で GUI を開くテストも含みます。

ブログ用に、CI の Linux で仮想の画面を撮影すると、プラグインの GUI と同じ描画を表示したデモのウインドウが写っていました。

2026111602-qiita-spectrum-gui-test-xvfb-window.png

人による確認

最後に、9 項目のチェックリストで、DAW の中での見え方、GUI の大きさの変更、パラメーターの反映、保存と読み込み、ちらつきを私が確かめました。すべて問題ありませんでした。

つまずいた点

CI を通すまでに、Claude Code は 3 回つまずきました。どれも GPU のない環境に特有の問題でした。

  • lavapipe の定義ファイルを、最初は lvp_icd.*.json という決め打ちの名前で探していました。Ubuntu 24.04 の Mesa 25.2.8 では lvp_icd.json という名前で見つからず、空の VK_DRIVER_FILES がすべてのドライバーを隠して、vulkaninfo が「Found no drivers!」で失敗しました。上の抜粋のとおり、パッケージの中から探す形に直しました
  • Visage は、Vulkan のヘッダーがシステムにあればそれを使い、なければ自分で取得します。CI ではシステムのヘッダーが見つかり、配布物に入れるライセンス文の場所が変わって構成が止まりました。バージョンとハッシュを固定したヘッダーを取得して Visage に渡す形にしました
  • ブログ用の撮影の段で、裏で動かした Xvfb とデモのウインドウを引数のない wait で待ったところ、終わらない Xvfb まで待ち続け、CI が 30 分以上止まりました。待つ対象をデモのプロセスに限り、段に 5 分の上限を付けました

考察

これが成り立ったのは、画面に出さずに描けて画素を読み出せる GUI のライブラリを最初に選んでいたからだと考えています。Claude Code は、ライブラリの選定フェーズの時点で既に、GPU 無しでの描画を見越して計画に入れていました。GUI のライブラリを選ぶときに、テストのしやすさも選定基準に入れておくのがよさそうです。

まとめ

Claude Code は、プラグインの GUI を画面に出さずに描いて正解の画像と比べることで、GPU も画面もない CI で GUI の描画を検査することができました。GUI の確認は DAW で開いて目で見るしかないというのは思い込みでした。GUI を持つプラグインやアプリをエージェントと一緒に作っている方の参考になれば幸いです。

参考

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?