KageLife は,Ebitengine の Kage シェーダーを保存するだけで画面にリアルタイム反映する,Go 製の VJ ライブコーディングツールです.
好きなエディタで shaders/ 以下の .kage を書き換えて保存すると,自動で再コンパイルして描画を差し替えます.
Time や Beat などの Uniform は自動で注入され,数字キーでのシェーダー切り替え,タップテンポに同期したクロスフェードでパフォーマンスできます.
名前について: 「Kage」は Ebitengine のシェーダー言語の名前です. KageLife という名前は,Hexler Limited のシェーダーのライブコーディング環境 KodeLife への敬意から付けました. KageLife は KodeLife および Hexler Limited とは関係のない,非公式で独立したプロジェクトです.
GitHub Releases からビルド済みの配布物を入手できます. 対象は次の 4 つです.
| OS | アーキテクチャ | uname -m の表示 |
ファイル名 |
|---|---|---|---|
| macOS | Apple シリコン | arm64 |
kagelife-<version>-darwin-arm64.tar.gz |
| macOS | Intel | x86_64 |
kagelife-<version>-darwin-amd64.tar.gz |
| Linux | x86_64 | x86_64 |
kagelife-<version>-linux-amd64.tar.gz |
| Linux | arm64 | aarch64 |
kagelife-<version>-linux-arm64.tar.gz |
以下の例は,Apple シリコンの Mac に ~/Applications/kagelife へ入れる場合です.
版・OS・アーキテクチャと置き場所は,使う環境に合わせて書き換えてください(Linux なら ~/.local/opt/kagelife など).
置き場所を作り,使う環境の tar.gz と,同じリリースにある SHA256SUMS を同じディレクトリに落とします.
VERSION=v0.2.0
ASSET=kagelife-$VERSION-darwin-arm64
mkdir -p ~/Applications/kagelife && cd ~/Applications/kagelifeGitHub CLI(gh)を使う場合:
gh release download $VERSION -R cyokozai/kagelife -p "$ASSET.tar.gz" -p SHA256SUMScurl を使う場合:
curl -LO https://github.com/cyokozai/kagelife/releases/download/$VERSION/$ASSET.tar.gz
curl -LO https://github.com/cyokozai/kagelife/releases/download/$VERSION/SHA256SUMSブラウザで落としてもかまいません.その場合は 2 つのファイルを置き場所へ移してください.
SHA256SUMS には全 OS の配布物が載っているので,落としたファイルの行だけを取り出して検証します.
# macOS
grep "$ASSET.tar.gz" SHA256SUMS | shasum -a 256 -c -
# Linux
grep "$ASSET.tar.gz" SHA256SUMS | sha256sum -c -kagelife-<version>-<os>-<arch>.tar.gz: OK と表示されれば検証は完了です.
tar -xzf "$ASSET.tar.gz"~/Applications/kagelife/<ASSET>/ に次のファイルが入ります.
| ファイル | 内容 |
|---|---|
kagelife |
実行ファイル |
shaders/ |
サンプルシェーダー |
README.md |
このファイル |
LICENSE |
ライセンス(MIT) |
-
macOS: ブラウザで落としたファイルには quarantine 属性が付き,そのままでは Gatekeeper に止められます.次のコマンドで外してください.
ghやcurlで落とした場合は属性が付かないので,No such xattr: com.apple.quarantineと表示されますが,問題ありません.xattr -d com.apple.quarantine "$ASSET/kagelife" -
Linux: X11 と OpenGL の実行時ライブラリが要ります.デスクトップ環境の入った多くのディストリビューションでは入っています.
展開したディレクトリの kagelife は PATH に入っていないので,そのまま kagelife と打つと command not found になります.
展開したディレクトリの中で ./kagelife と打てば起動できますが,どこからでも kagelife で呼べるようにするには,次の 2 つを行います.
版に依存しない入口として current というリンクを作ります.
ln -sfn ~/Applications/kagelife/$ASSET ~/Applications/kagelife/currentそのリンクを PATH に足します.zsh(macOS の既定)なら ~/.zshrc,bash なら ~/.bashrc の末尾に 1 行足し,シェルに読み込み直します.
echo 'export PATH="$PATH:$HOME/Applications/kagelife/current"' >> ~/.zshrc
source ~/.zshrc
which kagelife # ~/Applications/kagelife/current/kagelife と出れば完了~/.local/bin のように,すでに PATH に入っているディレクトリがあるなら,シェルの設定ファイルを触らずに ln -s ~/Applications/kagelife/current/kagelife ~/.local/bin/kagelife でもかまいません.
kagelife -shaders ~/Applications/kagelife/current/shaders-shaders を省くと,いまいるディレクトリの shaders/ を読みます(起動した場所に依存します).
コマンドとして使うときは,使うシェーダーのフォルダを -shaders で指定してください.
新しい版を 1〜4 の手順で同じ置き場所に落として展開し,current のリンクを張り替えます.PATH の設定はそのままで使えます.
VERSION=<新しい版>
ASSET=kagelife-$VERSION-darwin-arm64
# 1〜4 の手順のあと
ln -sfn ~/Applications/kagelife/$ASSET ~/Applications/kagelife/current
kagelife -version古い版のディレクトリは,動作を確かめてから消してください.
配布物を使う場合は,「インストール」の 5 で PATH に入れていれば次を実行します.
PATH に入れていない場合は,展開したディレクトリで ./kagelife と打ちます(./ を付けないと command not found になります).
kagelife -shaders ~/Applications/kagelife/current/shadersソースから動かす場合は,リポジトリのルートディレクトリで次のどちらかを実行します.
make run
# または
go run .シェーダーは既定で相対パス shaders/ から読み込みます.別の場所を使うときは -shaders で指定します.
起動時に shaders/ 直下の .kage をファイル名順にすべてコンパイルし,読み込んだ一覧をターミナルに表示します.
コンパイルできなかったファイルは警告を出しますが,ファイル名順の番号はそのまま持ちます(後述の「シェーダーの番号」を参照).
| オプション | 既定値 | 内容 |
|---|---|---|
-shaders <dir> |
shaders |
シェーダーを読み込み,監視するディレクトリ |
-control-addr <addr> |
127.0.0.1:0 |
制御口の待受アドレス.ポート 0 は空いているポートを自動で選ぶ |
-version |
— | バージョンを表示して終了する |
-llm-slots <名前>,<名前> |
なし(無効) | LLM が書き込むシェーダーの予約名(1〜2 個).後述の「LLM 背景スロット」を参照 |
-av-offset <ms> |
0 |
映像の拍(uniform の Beat)を遅らせるミリ秒(0〜1000 の整数).Bluetooth スピーカーのように観客の聞く音が遅れる会場で,映像を音に合わせる.Time・Frame・クロスフェードの進み方・タップの時刻はずらさない.0 以外なら HUD に AV offset を出す.範囲外は起動エラー |
-list-displays |
— | ディスプレイの番号・名前・大きさ・拡大率を表示して終了する(ウィンドウは開かない) |
-display <N> |
なし | ウィンドウ(全画面)を出すディスプレイの番号(1 始まり.-list-displays の番号).範囲外なら一覧を出して起動エラー |
-fullscreen |
— | 起動時から全画面にする.全画面のあいだはマウスカーソルを隠し,F でウィンドウに戻すと表示に戻す |
-link |
無効 | (実験)Carabiner 経由で Ableton Link(rekordbox の LINK など)に BPM と拍を合わせる.後述の「Ableton Link で拍を合わせる」を参照 |
-link-addr <addr> |
127.0.0.1:17000 |
-link のときに接続する Carabiner の待受アドレス |
-render-scale <S> |
1.0 |
シェーダーを描く解像度の倍率(0.25〜1.0).1.0 未満なら画面 × S の大きさに描き,線形補間で拡大して出す(GPU の負荷を下げる).このときシェーダーの Resolution は縮めた大きさ,Cursor も同じ倍率で縮めた座標になる.HUD は縮めない.制御口の state の resolution は画面の大きさのまま.範囲外は起動エラー |
./kagelife -shaders ~/vj/shaders外部ディスプレイ(会場の HDMI など)に全画面で出すときは,先に番号を確かめてから指定します.
./kagelife -list-displays
# display 1: ... / display 2: ... のように出る
./kagelife -display 2 -fullscreenshaders/直下に.kageファイルを置きます(サブディレクトリは監視しません).- ファイルを保存すると(書き込みまたは新規作成のイベント),100ms のデバウンスをかけてから再コンパイルし,描画を差し替えます.
- 起動後に新しく作った
.kageは,ファイル名順の位置に加わります. - コンパイルエラーのときは直前のシェーダーをそのまま描画し続け,HUD とターミナルにエラーを表示します.アプリは落ちません.
shaders/直下の.kageは,ファイル名の昇順に1,2,3… と番号(スロット)を持ちます.- コンパイルに失敗したファイルも番号を持ちます.あとで直して保存すれば,その番号のまま使えるようになります.
- コンパイルに失敗したファイルの番号キー(
Shift付きも含む)を押しても無視され,表示は変わりません. - 番号をそろえたいときは,
01_uv.kageのようにファイル名の先頭に数字を付けてください.
| キー | 動作 |
|---|---|
1 〜 9 |
N 番目のシェーダーに即座に切り替える |
Shift + 1 〜 9 |
N 番目のシェーダーへクロスフェードする(フェード時間は拍数で指定) |
Space |
タップテンポ.叩いた間隔から BPM を求める(-link で Link に同期中は無視する) |
[ |
クロスフェードの拍数を 1 段階減らす |
] |
クロスフェードの拍数を 1 段階増やす |
H |
HUD(BPM・フェード拍数・ミックス比・エラー)の表示を切り替える |
F |
フルスクリーンを切り替える(フルスクリーンのあいだはマウスカーソルを隠す) |
- ウィンドウの初期サイズは 640x480 で,リサイズできます.
- HUD の BPM は,まだタップしていない既定値のときに
(default)と表示されます. - HUD の 2 行目に,実測の fps(
FPS)と直近 5 秒のフレーム時間の最大値(FrameMax(5s),ms)を出します.-render-scaleが 1.0 未満なら倍率(RenderScale)も出します.長時間の負荷試験で fps が落ちていないかを見るのに使います.
- クロスフェードの拍数は
0.5 / 1 / 2 / 3 / 4 / 8 / 16から選びます.初期値は4です. - フェードの長さは拍数と BPM から求めます.タップ前でも既定の 120 BPM で進むので,すぐに使えます.
- フェード中に拍数や BPM を変えても画面は飛ばず,その時点から新しい速さで進みます.
- フェード中に別のフェードを指示したときは,次のように扱います(Mix は切り替え先が占める割合
0..1).
| 指示 | 動作 |
|---|---|
| フェード中の切り替え先と同じシェーダー | 無視する(フェードを続ける) |
| Mix < 0.5 で,切り替え元のシェーダー | フェードを取りやめ,切り替え元のままにする |
| 上記以外で,Mix ≥ 0.5 | 切り替え先を確定させてから,新しいフェードを始める |
| 上記以外で,Mix < 0.5 | 切り替え元のままにして,新しいフェードを始める |
詳細は ADR-008 にあります.
注意:
-linkは実機(rekordbox などの Link の相手と Carabiner)ではまだ確かめていません.確かめたのは,偽の Carabiner を使った単体テストと CI だけです.ライブで使う前に,手元で拍が合うかを確かめてください.合わないときは-linkを外してください.タップテンポで動きます.
-link を付けると,Carabiner(Ableton Link を TCP のテキストで中継する別のプログラム)に接続し,Link のセッション(rekordbox の LINK など)の BPM と拍に合わせます.
kagelife は Link の SDK を持たず,Carabiner とだけ話します.Carabiner は自分で入手して,kagelife を動かす機体で先に起動しておきます(127.0.0.1 しか受け付けないため).
- Mac 1 台(rekordbox と kagelife が同じ Mac): その Mac で
./Carabinerを起動し,rekordbox の LINK を ON にしてから./kagelife -linkを起動します. - 2 台(rekordbox の機体と kagelife の機体を LAN でつなぐ): Carabiner は kagelife 側の機体で起動します.Link は同じ LAN の上で相手を探すので,2 台は同じネットワークにつなぎます.rekordbox の機体には Carabiner は要りません.
./Carabiner # 別のターミナルで起動し,開いたままにする
./kagelife -link # 既定の 127.0.0.1:17000 に接続する- Carabiner の入手・署名の確かめ方・rekordbox の LINK の入れ方は docs/poc-carabiner-link.md にあります.
- Link の相手がいるあいだ(同期中)は,BPM(HUD・クロスフェードの進み方)と
Beatを Link から取ります.-av-offsetは Link の拍にも掛かります.Spaceのタップは BPM も拍頭も変えません. - HUD の状態行に
Link: synced (1 peer)のように出ます.同期していないときはLink: offline (tap)(Carabiner につながらない)・Link: waiting (tap)(応答待ち)・Link: no peers (tap)(Link の相手がいない)で,タップテンポで動きます. - 同期が切れたら(Carabiner が落ちた・rekordbox の LINK を OFF にした),切れる直前の Link の BPM と拍頭をそのまま引き継いでタップテンポに戻ります.拍は飛びません.Carabiner が戻ると自動でつなぎ直します.
- 制御口の
POST /v1/bpm(set_bpm)は同期中も受け付けますが,次のフレームまでに Link の値へ戻ります.GET /v1/stateのbpmは同期中は Link の BPM です(40〜300 に丸めた値).
go run . -llm-slots llm_a,llm_bLLM(制御口を使う MCP サーバ)が書き込むシェーダーの名前を 1〜2 個予約します.2 個を勧めます(一方を映している間に,もう一方へ書かせる).
名前は制御口の名前規則 ^[a-z0-9][a-z0-9_-]{0,63}$ に合わせ,.kage は付けません.重複・3 個以上・規則違反は起動エラーです.
| キー | 動作 |
|---|---|
1 〜 7 |
予約名を除いたシェーダーのうち,ファイル名順で N 番目に切り替える(Shift でクロスフェード) |
8 / 9 |
予約名の 1 個目 / 2 個目に切り替える(Shift でクロスフェード).shaders/<名前>.kage がまだ無いとき,またはその名前がこのプロセスで一度もコンパイルに成功していないときは何もしない.一度成功していれば,あとでファイルのコンパイルが失敗しても,最後に成功した中身に切り替わる |
0 |
直前に映っていた予約名以外のシェーダーへ即座に戻す.記録が無いときと,記録したシェーダーが使えないときは,予約名以外でコンパイルに成功している最初のシェーダーへ.それも無ければ何もしない.フェード中に押すとフェードを打ち切る(予約名へ向かうフェードなら切り替え元へ,予約名以外へ向かうフェードならフェード先へ即座に切り替わる) |
- 制御口の
PUT /v1/shaders/{name}は予約名にだけ書けます.予約名以外は403 forbidden_name,映っている予約名(表示中,またはクロスフェード中のフェード先)は409 slot_liveで断ります. GET /v1/stateのllm_slotsに予約名がフラグの順で入ります(フラグ無しなら[]).- フラグを付けなければ,キーと制御口は今までどおりです.
シェーダー内で同じ名前と型の変数を宣言すると,毎フレーム値が入ります.宣言していない Uniform は無視されます.
| 名前 | Kage の型 | 意味 |
|---|---|---|
Time |
float |
起動からの経過秒数 |
Resolution |
vec2 |
描画先の幅と高さ(ピクセル) |
Beat |
float |
拍内の位相 0..1.タップも制御口の POST /v1/bpm もまだ無いときは既定の 120 BPM で刻む.タップするたびにそのタップが拍頭になり,2 回目のタップから叩いた間隔の BPM で刻む(1 回目と,2 秒を超えて空けた後のタップでは直前の BPM を保つ).POST /v1/bpm はタップの前でも後でも BPM と拍頭(呼んだ時刻)を設定し,それまでのタップ履歴を捨てる.BPM は 40〜300 に制限される.-link で Link に同期中は Link の拍内の位相 |
Cursor |
vec2 |
マウスカーソルの位置(ピクセル) |
Frame |
int |
起動からのフレーム数 |
Random |
float |
フレームごとに変わる [0, 1) の乱数 |
//kage:unit pixels
package main
var Time float
var Beat float
var Resolution vec2
func Fragment(dstPos vec4, srcPos vec2, color vec4) vec4 {
uv := dstPos.xy / Resolution
pulse := 1.0 - Beat
r := sin(Time + uv.x*6.28)*0.5 + 0.5
return vec4(r*pulse, uv.y*pulse, 0.5, 1.0)
}//kage:unit pixels を付けると dstPos がピクセル座標になり,Resolution で割ると 0..1 の座標になります.
| ファイル | 内容 |
|---|---|
shaders/01_uv.kage |
UV 座標をそのまま色にする |
shaders/02_time_sin.kage |
Time の sin 波で色が移ろうグラデーション |
shaders/03_smooth_circle.kage |
拍に合わせて脈打つ,縁のなめらかな円 |
shaders/04_ripple.kage |
中心から広がる波紋が拍で光る |
shaders/05_rotation_grid.kage |
回転する格子.拍で明るさが変わる |
shaders/06_kaleidoscope.kage |
6 分割の万華鏡 |
shaders/07_plasma.kage |
sin を重ねたプラズマ |
shaders/08_beat_flash.kage |
拍頭で広がって減衰するフラッシュ |
shaders/09_cursor_light.kage |
マウスカーソルの位置に光源が付いてくる |
KageLife は起動中,127.0.0.1 に HTTP/JSON の制御口(v1)を開きます.
待受アドレスは -control-addr で変えられます.同じマシンの外からは届きません.
LLM などの外部のプログラムは,この制御口を通して状態の取得,シェーダーの読み書き,切り替えとクロスフェード,BPM の設定を行えます.
- 契約(エンドポイント・認証・エラー)は ADR-006 を正典とします.
GET /v1/stateのlast_errorには,PUT とファイル監視で起きた失敗のうち最新の 1 件が入ります.起動時の読み込みで失敗したファイルは入らず,HUD とログにだけ出ます.- MCP の stdio サーバは別リポジトリ cyokozai/kagelife-mcp にあり,この制御口へ中継します.
- Stream Deck から操作する常駐アプリは別リポジトリ cyokozai/kagelife-deck にあり,この制御口の
GET /v1/previewsとPOST /v1/keysを使います.
配布物(GitHub Releases の tar.gz)を使うだけなら,Go や cgo は要りません.以下はソースからビルドする場合の要件です.
- Go 1.27 以上
- cgo(
CGO_ENABLED=1)と C コンパイラ.Ebitengine が OpenGL / Metal を使うためです. - Linux では X11 と OpenGL の開発パッケージが要ります.Dev Container のイメージ(Alpine)では次のパッケージを入れています.
build-basepkgconfigmesa-devlibx11-devlibxrandr-devlibxinerama-devlibxcursor-devlibxi-devlibxxf86vm-devalsa-lib-dev
Dev Container を使うと,チーム全員が同じ開発環境を再現できます.
イメージは container/Dockerfile から作られ,Go ツールチェーン,上記の開発パッケージ,golangci-lint,dlv,gopls,GitHub CLI が入っています.
- Docker がインストール済みであること
- Visual Studio Code がインストール済みであること
- VS Code 拡張機能 Dev Containers がインストール済みであること
- VS Code でリポジトリのルートディレクトリを開く
- コマンドパレットを開く(
Cmd+Shift+P/Ctrl+Shift+P) Dev Containers: Reopen in Containerを選択する- コンテナのビルドが完了するまで待つ
コンテナ起動後は,.devcontainer/post_create.sh が依存ライブラリを取得します(go mod download / go mod tidy).
| コマンド | 内容 |
|---|---|
make run |
アプリを起動する |
make test |
go test -race ./... を実行する(データ競合検出つき) |
make test-v |
テストを詳細出力で実行する |
make lint |
golangci-lint run を実行する |
make build |
カレント OS 向けのネイティブバイナリ kagelife をビルドする |
make clean |
ビルド成果物を削除する |
make help |
ターゲットの一覧を表示する |
build-darwin-* / build-linux-* / build-all / dist / package-* は cgo を使うため,対応する OS のランナー(CI)でのみ動きます.
テスト駆動(t_wada 流: Red → Green → Refactor)で進めます.
Red → 失敗するテストを書く
Green → テストが通る最小限のコードを書く
Refactor → コードをきれいにする(テストは常にグリーン)
ロジックは internal/ 以下のパッケージ(control / filewatcher / shadermgr / tempo / uniform)に切り出してユニットテストを書きます.
シェーダーの描画結果そのものは目視で確認します.
GitHub Actions で次を実行します.
| ワークフロー | きっかけ | 内容 |
|---|---|---|
.github/workflows/ci.yml |
main / dev への push とプルリクエスト |
gofmt の未整形検出・go vet・go test -race・golangci-lint |
.github/workflows/release.yml |
タグ v*.*.* の push |
CI を通したうえで 4 ターゲットをビルドし,tar.gz と SHA256SUMS を添えて GitHub Release を作る.タグに - を含む(v1.0.0-rc.1 など)ときはプレリリースにする |
.
├── main.go # エントリポイント.入力処理・Uniform 注入・描画
├── internal/
│ ├── control/ # 127.0.0.1 の HTTP/JSON の制御口 v1(ADR-006)
│ ├── filewatcher/ # fsnotify による shaders/ の監視とデバウンス
│ ├── shadermgr/ # シェーダーのロード・再コンパイル・切り替え・クロスフェード
│ ├── tempo/ # タップテンポ(BPM と拍内の位相)
│ └── uniform/ # シェーダーに渡す Uniform の組み立て
├── shaders/ # .kage シェーダー(ホットリロード対象)
├── container/ # 開発用 Dockerfile
├── .devcontainer/ # Dev Container 設定
└── docs/ # PRD・ADR・開発プロセス
設計判断の記録は docs/adr/ に,要件は docs/prd.md にあります.
main と dev への直接プッシュを禁止し,プルリクエスト経由のマージを強制します.
GitHub の Rulesets(Settings > Rules > Rulesets)で設定しています.
main と dev
| ルール | 説明 |
|---|---|
| Restrict deletions | ブランチの削除を禁止する |
| Block force pushes | force push による履歴の書き換えを禁止する |
| Require a pull request before merging | マージ前に PR を必須にする.承認 1 件・コードオーナーのレビュー・レビューのスレッドの解決が必要.マージ方式は merge のみ |
| Automatically request Copilot code review | PR 作成時に Copilot のコードレビューを自動でリクエストする |
- 必須のステータスチェックは,今は設定していません.CI の
test/lintを登録する予定です. - 個人リポジトリのため,Organization admin によるバイパスはありません.
GitHub Issues をチケットとして使用し,1 チケット 1 ブランチで作業を管理します.
main
└─ dev
└─ feat/*** ─── 作業 ─── PR ──→ dev ─── PR ──→ main
- GitHub Issues で
[FEAT]チケットを作成する devブランチからfeat/***ブランチを切る(ブランチ名はチケットに記載)feat/***ブランチで作業を行う- 作業完了後,
feat/***からdevへ PR を作成してマージする
dev から main へマージするには,以下の条件をすべて満たす必要があります.
| 条件 | 状態 |
|---|---|
| CI テストが全て通過していること | 必須 |
| CD によるステージング環境へのデプロイが成功していること | 予定 |
| 開発者がログ・メトリクス・トレースの取得を確認していること | 予定 |
.gitmessage をコミットメッセージのテンプレートとして使用します.
リポジトリをクローン後,以下のコマンドを 1回だけ 実行してください.
git config commit.template .gitmessage設定後は git commit を実行すると,以下のテンプレートがエディタに表示されます.
# feat | fix | docs | refactor | test | chore
<type>: <subject>
Refs: #
| type | 用途 |
|---|---|
feat |
新機能の追加 |
fix |
バグ修正 |
docs |
ドキュメントのみの変更 |
refactor |
機能変更を伴わないコード改善 |
test |
テストの追加・修正 |
chore |
ビルド・設定などの雑務 |
各チケットには以下の役割を記載します.R はチケット作成者自身が担います.
| 役割 | 説明 |
|---|---|
| R: 実行責任者 (Responsible) | 実際に作業を行う人.チケット作成者が担当する |
| A: 説明責任者 (Accountable) | 成果物に対して最終責任を持つ人 |
| C: 協業先 (Consulted) | 作業に際して相談・協力を求める人 |
| I: 報告先 (Informed) | 進捗・完了を報告する人 |
- cyokozai/kagelife-mcp: LLM(Claude Code など)から KageLife を操作するための stdio MCP サーバです.起動中の KageLife の制御口へ中継します.
- cyokozai/kagelife-deck: Stream Deck MK.2 から KageLife の制御口 v1 を操作する常駐アプリです(Linux).
- cyokozai/kagelife-shaders: KageLife で読み込む Kage シェーダーのプリセット集です.
MIT License です.全文は LICENSE を参照してください.