コンテンツプラグイン
プラグインを入れて使い、自分でも作る。
コンテンツプラグインは、Celesta 本体にない機能を追加します。独自のコードで描くレイヤーや、音声合成チャンネルのようなコンポーネントライブラリです。プラグインはコンピューターに置くフォルダーで、コンポジションからは @celesta-plugin/<id> としてコンポーネントを import します。
プラグインは新しい機能で、今後も変わる可能性があります。デスクトップアプリのプレビューと celesta-exporter で動作し、@celesta.studio/web と CPU リファレンスレンダラーでは動作しません。
プラグインを入れる
プラグインは celesta-plugin.json のあるフォルダーです。いちばん簡単なのは、ユーザーのプラグインフォルダーに置く方法です。
| OS | ユーザーのプラグインフォルダー |
|---|---|
| Windows | %APPDATA%\Celesta\plugins |
| macOS | ~/Library/Application Support/Celesta/plugins |
| Linux など | $XDG_DATA_HOME/celesta/plugins(未設定なら ~/.local/share/celesta/plugins) |
Celesta は次の順にプラグインを探し、同じ id のプラグインが複数あれば先に見つかったものを使います。
- エクスポーターの各
--plugin-dir - 環境変数
CELESTA_PLUGIN_PATHの各フォルダー(Windows は;、それ以外は:区切り) - デスクトップアプリでは、開いているプロジェクトのプラグインフォルダー(信頼したあと。プロジェクトに同梱するプラグインを参照)
- ユーザーのプラグインフォルダー
- デスクトップアプリの Plugins タブで追加したフォルダー
- Celesta に同梱のプラグインフォルダー(Windows は実行ファイルの隣の
plugins、macOS のアプリはContents/Resources/PlugIns、それ以外は実行ファイルのフォルダーから見た../lib/celesta/plugins)
プラグインは、どのバージョンの Celesta で動くかを示します。別のバージョン向けに作られたプラグインや、それを示していないプラグインは読み飛ばされ、その理由が Problems タブ、Plugins タブ、celesta-exporter と MCP サーバーの出力に表示されます。お使いの Celesta 向けに作られたリリースを入れてください。読み飛ばされたプラグインは、この順で後に見つかる同じ id のプラグインを隠しません。たとえば、リストの後ろにお使いの Celesta 向けのメディアプラグインがあれば、そちらが使われます。Plugins タブでオフにしたプラグインも同じく、後のプラグインを隠しません。
1・2・3・5 で指定するフォルダーはプラグインそのものでも、複数のプラグインを入れたフォルダーでもかまいません。CELESTA_PLUGIN_PATH には絶対パスを指定してください。相対パスは、Celesta を起動した場所によって指すフォルダーが変わるため読み飛ばされます。
macOS や Linux などの Unix 系では、3〜6 のフォルダーや、そこにあるプラグインの中身を他のユーザーが書き換えられる場合(グループやその他に書き込み権限がある、所有者が root でも自分でもない)は使いません。プラグインのファイルを書き換えられる人は、それを使う人の権限でコードを動かせるからです。chmod -R go-w で書き込み権限を外してください。
celesta-exporter --react film.tsx out.mp4 --plugin-dir ~/celesta-plugins
信頼と承認
プロジェクトを開くと、そのコードがコンピューター上で動きます。プラグインも自分のコードを動かします。そのためデスクトップアプリは、どちらも動かす前に確認します。
- プロジェクト:初めて開くとき、そのフォルダーを信頼するかを尋ねます。信頼するまでは何も評価しません。インターネットからダウンロードしたプロジェクトは、その旨が確認に表示されます(Windows)。File > Create New Project で作ったプロジェクトは最初から信頼済みです。信頼が及ぶのはそのプロジェクトのフォルダーで、その下にある、自分の
celesta.config.jsonを持つ別のプロジェクトには及びません。プロジェクトのルートにcelesta.config.jsonがあれば信頼は記憶されます。ないフォルダーでは、アプリを終了するまで有効で、次に起動したときにまた尋ねます。プロジェクトを作るとcelesta.config.jsonも作られます。 - プラグイン:ユーザーのプラグインフォルダーや追加したフォルダーにあるプラグインと、プロジェクトが持ち込むプラグインは、許可するまで動きません。見つけたときに確認し、更新などでマニフェストやマニフェストが指すファイル(プログラム・モジュール・型定義)が変わったときにも改めて確認します。プラグインのフォルダーにあるそれ以外のファイルは確認の対象外です。許可するまで、プラグインのコードは一切動かず、Problems には承認待ちと表示されます。それを import するプロジェクトも開けますが、プラグインのコンポーネントは何も描かないので、そのレイヤーはプレビューに出ません。コンポーネント以外の関数を
prepareなどで呼ぶと、承認待ちであることを示すエラーになります。許可すると、プラグインを使ってプロジェクトを読み込み直します。--plugin-dirやCELESTA_PLUGIN_PATHで指定したプラグインと、Celesta に同梱のプラグインは確認しません。
選んだ内容は Celesta の設定フォルダーの settings.json に保存されます。設定フォルダーは Windows では %APPDATA%\Celesta、macOS では ~/Library/Application Support/Celesta、それ以外では $XDG_CONFIG_HOME/celesta(未設定なら ~/.config/celesta)です。
celesta-exporter と MCP サーバーは確認しませんが、アプリで選んだ内容に従います。上のフォルダーのうちプロジェクトのもの以外を探し、オフにしたプラグインは使いません。ユーザーのプラグインフォルダーや追加したフォルダーにあるプラグインは、アプリで今の内容のまま許可したものだけを使い、そうでなければ承認待ちとして読み飛ばします。承認待ちのプラグインを import するエントリーは読み込みに失敗し、そのプラグインと許可の方法がエラーに表示されます。レイヤーが欠けたまま気づかずに書き出されることはありません。アプリを使わずにそのプラグインを使うには、次のどちらかにします。
celesta-exporterに--allow-plugin <id>を指定する(複数指定できます)。その書き出しの間だけ、そのプラグインを今の内容のまま使います。設定には何も保存しません。アプリでオフにしたプラグインはオフのままです。--plugin-dirやCELESTA_PLUGIN_PATHでフォルダーを指定する。これらは確認の対象外です。アプリで許可していないプラグインを MCP サーバーに使わせるときは、この方法を使います。
celesta-exporter --react film.tsx out.mp4 --allow-plugin flag
プロジェクトに同梱するプラグイン
プロジェクトは自分のフォルダーにプラグインを入れて持ち込めます。プロジェクトのルートにある celesta.config.json に、そのフォルダーを書きます。
{
"plugins": {
"paths": ["./plugins"]
}
}
各パスはプロジェクトのルートからの相対パスで、ルートの中を指す必要があります。デスクトップアプリは、プロジェクトを信頼したあと、これらのフォルダーを CELESTA_PLUGIN_PATH の次、ユーザーのプラグインフォルダーの前に探します。celesta.config.json のあるフォルダーが、信頼の確認で表示されるプロジェクトのルートにもなります。このファイルがなければ、エントリーのあるフォルダーがルートです。celesta-exporter はこれらのフォルダーを探さないので、--plugin-dir で指定してください。
Plugins タブ
デスクトップアプリはプロジェクトを開くたびにプラグインを探します。右側のドックの Plugins タブには、見つかったプラグインのコピーがすべて、次のまとまりに分けて一覧表示されます。
- This project:開いているプロジェクトの
celesta.lockが指定するレジストリのプラグイン(プロジェクトを信頼したあと)。見出しに、ロックを解決したときの Celesta のバージョンが表示されます。 - Global:すべてのプロジェクト向けにレジストリから入れたプラグインと、Celesta に同梱のプラグイン(Bundled と表示)。同じ id のコピーが 2 つあれば、それぞれが 1 行になり、使われないほうには
Not used: Registry runsのように、代わりに動いているものが表示されます。 - Installed by hand:プロジェクトのフォルダー、ユーザーのプラグインフォルダー、追加したフォルダー、
CELESTA_PLUGIN_PATHにあるプラグイン - Added folders:追加したフォルダー
各行には、プラグインの id とバージョン、その下に種類(Media、Content、Components)と状態(オン、オフ、承認待ち、セキュリティアドバイザリーによる Blocked、Deprecated、Yanked、Not installed、No build for this computer)が表示されます。行のボタンは、状態に応じた操作をします。承認待ちのプラグインを Allow で許可する、このコンピューターにないロックしたバージョンを Download で入れる、レジストリにある新しいバージョンに Update to で更新する(ロックしたプラグインは、プロジェクトの要件の範囲内だけ)、のどれかです。そのほかの操作は、行の ⋯ ボタンにあります。
- Turn Off と Turn On。オフのプラグインは、アプリでも
celesta-exporterでも動かず、探す順で次にある同じ id のプラグインがあれば、代わりにそれが使われます。たとえば、ユーザーのプラグインフォルダーにあるプラグインをオフにすると、Celesta に同梱のものに戻ります。承認待ちのプラグインはこのように譲らないので、許可していないプラグインが、気づかないうちにリストの後ろのプラグインに置き換わることはありません - Show Folder:プラグインのフォルダーを開く
- ロックしたプラグインの Remove from this project(
celesta plugin removeと同じ)と、すべてのプロジェクト向けに入れたプラグインの Uninstall(ダウンロードしたものはcelesta plugin gcまで残ります)
タブのツールバーの ⋯ ボタンには、プラグインを入れたフォルダーを追加する Add Folder…(ユーザーのプラグインフォルダーの次に探されます)と、ユーザーのプラグインフォルダーを開く Open Plugin Folder(なければ作ります)があります。追加したフォルダーは、横の Remove で外せます。Reload Plugins(File メニューにもあります)で読み込み直すと、アプリを開いたまま入れたプラグインも読み込めます。
オン・オフ、許可、追加したフォルダーはほかの選択と同じく settings.json に保存され、プロジェクトは新しい設定のプラグインで開き直されます。読み飛ばしたプラグインとその理由は、タブの下と Problems タブに表示されます。
レイヤーを描くプラグインは独立したプログラムとして動き、フレームに必要になった時点で Celesta が起動します。プログラムはプラグインに同梱され、対応するプラットフォームごとに用意されます。
コンポーネントを使う
import { Composition } from '@celesta.studio/react';
import { Flag } from '@celesta-plugin/flag';
export default function Root() {
return (
<Composition width={1280} height={720} fps={30} durationInFrames={150}>
<Flag src="./portrait.png" x={80} y={160} amplitude={0.1} />
</Composition>
);
}
どのフォルダーにもないプラグインを import したエントリーは読み込みに失敗し、プラグイン名がエラーに表示されます。フレームは時刻だけで決まります。プラグインのレイヤーも props とフレームだけで決まるため、プレビュー・書き出し・シークの結果が一致します。
プラグインのプログラムが起動しないときや、レイヤーのモデルを開けないときは、プレビューはそのエラーを Problems タブに表示し、フレームごとにプラグインへ聞き直すことはしません。プラグインを直したら Reload Plugins を使ってください。<Flag> の src のような、レイヤーが描く元のファイルを直したときは、次のフレームで新しいファイルを使って試し直します。
プラグインは、モデルの利用条件のように、レイヤーが描くものについてのお知らせを出すことがあります。デスクトップアプリは、そのレイヤーをプレビューしている間と、そのレイヤーを描いた書き出しが終わったときの書き出しの項目で、それを Problems タブに表示します。celesta-exporter は一度だけ出力します。警告は warning:、情報だけのものは note: で始まります。
プロジェクトの TypeScript サポートは、各プラグインの型定義を .celesta/plugins/ にコピーするので、コードエディターで props を補完できます。デスクトップアプリがプロジェクトを開いたときは、プロジェクト自身のプラグインと承認待ちのプラグインの型定義もコピーします。型定義はコードを実行しません。
デスクトップアプリでは、プラグインのコンポーネントを Add メニューから追加することもできます。メニューでは Celesta 本体の要素の後に並びます。選ぶと Image や Rect と同じように追加できます。ファイルを受け取るコンポーネントは先にファイルを尋ね、そのあとドラッグで置く場所を決めます。VRM アバターのようにモデルファイルを受け取るコンポーネントは、指定された種類のファイルだけを受け付け(Choose a .vrm file)、レイヤーの縦横比で枠を描きます。アプリは要素を書き込むとき、import { Flag } from '@celesta-plugin/flag' のようなプラグインの import も追加します。
レジストリのプラグイン
プロジェクトは、Celesta のプラグインレジストリにあるプラグインも指定できます。celesta コマンドがそれを探してバージョンを選び、プロジェクトの celesta.lock に記録して、Celesta が管理するフォルダーにダウンロードします。プラグインのフォルダーを手で置く必要はなく、別のコンピューターでも同じバージョンのプラグインが使われます。
レジストリは新しい機能です。公式レジストリは https://registry.celesta.studio で、Celesta はレジストリの署名付きファイルを Celesta に組み込まれた鍵で確認します。レジストリにつながらないときは、レジストリが必要なコマンドが celesta: error: could not fetch … で失敗します。remove、list、audit、gc と、プラグインをダウンロード済みのロックに対する install はそのときも動きます(そのとき audit は、前に取得したアドバイザリーの一覧とプラグインの情報で確認します)。このページの acme.charts などのプラグイン名は例です。
デスクトップアプリでも、Plugins タブから同じことができます(アプリでの操作を参照)。信頼したプロジェクトのプレビューと書き出しは、ロックしたバージョンのプラグインで動きます。celesta-exporter と MCP サーバーもロックを読みます。
アプリでの操作
デスクトップアプリは celesta plugin と同じことを同じルールで行うので、どちらで準備したプロジェクトも、もう一方でそのまま使えます。
プラグインを探す:Plugins タブのツールバーの Find plugins… か、File メニューの Find Plugins… を選ぶと、Assets の代わりにプラグインのページが開きます。左側にはレジストリのプラグインが最新バージョンとともに並び、検索欄に入力すると id か説明で絞り込めます。プラグインを選ぶと、右側に詳細が表示されます。種類と公開者、対応するターゲット、入手元、このコンピューターにすでにあるもの、セキュリティアドバイザリー、そして各バージョンの状態(Published、Deprecated、Yanked、Withdrawn、Blocked)とダウンロードサイズです。
検索欄の横の Include pre-releases は、ページが勧めるバージョンを決めます。実行している Celesta 自身がプレリリースのときはオン、そうでなければオフになります。安定版の Celesta を使っている人が、知らないうちにプレリリースを入れてしまうことはありません。現在、公式のプラグインはどれもプレリリースです。この設定はアプリを終了するまで保たれ、すでに書かれた要件が許す範囲は変えません。
インストール・追加・固定:詳細の下のボタンは、プラグインによって変わります。
- Install は、メディアプラグイン(コーデック)をすべてのプロジェクト向けに入れます。
celesta plugin install --globalと同じです。Pin to this project は、そのバージョンを開いているプロジェクトにもロックします(add --pinと同じ)。 - Add to this project は、それ以外のプラグインを
plugins.dependenciesとcelesta.lockに追加してダウンロードします。celesta plugin addと同じです。勧められたバージョンについて、^0.10.0-alpha.3のように^<バージョン>の要件を書きます。 - すでに勧められたバージョンが入っていればボタンは Installed、古いバージョンが入っていれば Update to になります。プロジェクトがロックしているプラグインでは、Update to はプロジェクトの要件が許す最新のバージョンを勧めます。要件の外にしか新しいバージョンがないときはボタンが無効になり、
celesta.config.json asks for ^0.2のように理由が表示されます。勧められるバージョンがないときはボタンが無効になり、理由が表示されます。このコンピューター向けのビルドがない、別の Celesta が必要、Include pre-releases がオフでプレリリースしかない、のいずれかです。 - プロジェクト向けのボタンには、
celesta.config.jsonがあり、信頼済みのプロジェクトが必要です。ない場合は無効になり、Add plugins to a project with celesta.config.jsonと表示されます。celesta.config.jsonのないフォルダーに追加したプラグインは動かないため、Celesta がこのファイルを勝手に作ることはありません。
処理中は、ボタンが Installing… になり、その下にダウンロードしたバイト数が表示されます。ページを閉じても処理は続き、Plugins タブの行に進み具合が出ます。終わると、Celesta はプラグインを探し直してプロジェクトを開き直します。完了のメッセージは出ません。変わった行がその知らせです。失敗したときは、ボタンの下に原因が表示され、詳細は Problems タブで確認できます。
更新と削除:レジストリに新しいバージョンがあると、Plugins タブの行に Update to が表示されます。ロックしたプラグインは、celesta plugin update と同じくプロジェクトの要件の範囲内で更新され、プロジェクトが読み込み直されて、プレビューにすぐ新しいバージョンが反映されます。行の ⋯ メニューには、celesta plugin remove と同じ Remove from this project と、すべてのプロジェクト向けに入れたプラグイン用の Uninstall があります。
ダウンロードしていないプラグインがあるプロジェクトを開いたとき:プロジェクトを信頼すると、Celesta は celesta.lock を確認します。ロックしたプラグインがこのコンピューターになければ、Download 2 plugins for “film”? と尋ね、プラグインごとにバージョンとサイズを表示します。Download で取得してプロジェクトを読み込み直し、Not Now ならそのまま開きます。この質問は、アプリを起動するたびにプロジェクトごとに 1 回だけです。Not Now を選んだあとも、足りないプラグインは Problems に表示され、This project の見出しに Download が残ります。
Celesta をアップグレードしたあと:公式のプラグインは Celesta のマイナーバージョンに合わせて作られるため、古い Celesta で作ったロックには、もう読み込めないバージョンが載っています。そのとき Celesta は “film” was locked with Celesta 0.9 と伝え、Update Plugins を提案します。これは、読み込めないプラグインだけを解決し直してロックを書き換えます。アップグレードのあとの ^0.10.0-alpha.3 のように、プラグインの要件が動くバージョンを一つも許さないときは、実行する前にプラグインごとに知らせます。たとえば Changes vrm in celesta.config.json from ^0.10.0-alpha.3 to ^0.11.0 のようにです。Update Plugins を選ぶと、この変更を認めたことになります。途中で失敗したら、celesta.config.json と celesta.lock は元の状態に戻ります。ロックがない、または古いプロジェクトや、Not Now を選んだあとのために、This project の見出しにも Update Plugins… があります。更新の途中で、どのバージョンも満たせない要件が見つかったときは、Update this project’s plugins? と尋ね、書き換える前にその変更を一覧にします。見せていない変更を celesta.config.json に加えることはありません。
コンポジションが、ここにないプラグインをインポートしているとき:プレビューは no plugin "code" is installed: … で失敗します。プロジェクトの celesta.config.json がそのプラグインを宣言していれば、メッセージの続きに、足りない理由と入れ方が書かれます。プロジェクトにまだ celesta.lock がない、またはロックがまだそのプラグインをロックしていないときは、This project の見出しの Update Plugins… を選びます。ロックには載っているのに、このコンピューターに動かせるコピーがないときは、プロジェクトを信頼して Download を選びます(コピーが動かせない理由は Problems に表示されます)。どの場合も、プロジェクトのフォルダーで celesta plugin install を実行する方法も示されます。プロジェクトが宣言していないプラグインなら、代わりに (looked in CELESTA_PLUGIN_PATH) と表示されます。Find plugins… でプロジェクトに追加するか、プラグインフォルダーに置いてください。
Blocked・Deprecated・Yanked:セキュリティアドバイザリーに載ったプラグインは動きません。Celesta は acme.charts 1.2.3 was stopped という通知でアドバイザリーを伝え、修正版があれば Update to、なければ Show in Problems のボタンを出します。Update to は、Include pre-releases がオフでも、プレリリースの修正版まで更新します。修正版がプロジェクトの要件の外にあるときは、上と同じく、書き換える前に尋ねます。Celesta に同梱のプラグインのときは、Celesta を更新するよう伝えます。更新するまで、行には Blocked と表示されます。Deprecated のプラグイン(レジストリが置き換え先を示していればそれも)と、Yanked のバージョン(引き続き動きます)は、Problems タブに警告として表示されます。アドバイザリーの一覧が 7 日より古いときも同様です。
新しいバージョンの確認は、全員に共通の一覧 1 つだけを、プロジェクトを開くときと 1 日に 1 回読んで行います。そのため、どのプラグインを使っているかがレジストリに伝わることはありません。プラグイン個別の情報は、詳細の表示・更新・ダウンロードなど、それを必要とする操作をしたときだけ取得します。
celesta コマンド
デスクトップ版のパッケージでは、このコマンドは Celesta-export の隣に Celesta-cli という名前で入っています(Windows では Celesta-cli.exe、macOS では Celesta.app/Contents/MacOS/Celesta-cli)。大文字と小文字を区別しないファイルシステムでは、celesta と Celesta が同じ名前になってしまうためです。ソースからのビルドと Linux イメージでは celesta という名前です。このページとコマンド自身のメッセージでは celesta と書きます。
celesta plugin --help
各コマンドは、現在のフォルダーのプロジェクトを対象にします。現在のフォルダーから上にたどって最初に celesta.config.json があるフォルダーで、どこにもなければ現在のフォルダーです。別のフォルダーは --project <folder> で指定します。結果は標準出力に、警告とエラーは celesta: warning: … と celesta: error: … の形で標準エラー出力に出ます。終了ステータスは、成功すると 0、失敗すると 1、引数が正しくないと 2 です。
プロジェクトのプラグインを宣言する
celesta.config.json の plugins.dependencies には、プラグインの id ごとにバージョンの要件を書きます。意味は Cargo と同じで、"1.2" は 1.2.0 以降の 1.x(^1.2)、"0.2" は 0.2.x、"=1.2.3" は 1.2.3 だけを許します。plugins.targets には、プロジェクトが動く必要のあるシステムを macos-aarch64、windows-x86_64、linux-x86_64、any から書きます。省略すると最初の 3 つです。
{
"plugins": {
"dependencies": {
"acme.charts": "1.2"
},
"targets": ["macos-aarch64", "windows-x86_64", "linux-x86_64"]
}
}
plugins.dependencies は celesta plugin add と remove が書き込みます。ファイルのほかのキーは、順番も含めてそのまま残ります。Celesta は要件ごとに、要件に合い、動いている Celesta で使え、取り下げ(yank)もセキュリティアドバイザリーの対象にもなっておらず、すべてのターゲット向けのビルド(または any 向けのビルド)がある、いちばん新しいバージョンを選びます。すべてのターゲット向けのビルドがあるバージョンがなければ、このコンピューター向けのビルドがあるいちばん新しいバージョンを選び、足りないターゲットを警告します。
0.10.0-alpha.3 のようなプレリリースに要件が合うのは、@0.10.0-alpha.3 のように同じバージョンのプレリリースを要件が指すときだけです。そのため、要件なしの add と install --global はプレリリースを選びません。要件がほかの点では許すプレリリースしかないプラグインでは、エラーが指定すべきバージョンを示します。
celesta: error: no version of acme.codec satisfies *: only pre-releases match; ask for acme.codec@0.10.0-alpha.3
celesta.config.json のないエントリーには、レジストリの依存関係はありません。すべてのプロジェクト用に入れたプラグインだけを使います。
celesta.lock
コマンドは celesta.config.json の隣に celesta.lock を書きます。各プラグインの正確なバージョン、取得元のレジストリ、ターゲットごとのビルドのハッシュ、解決したときの Celesta のバージョンが記録されます。プロジェクトと一緒にコミットし、手で編集しないでください。同じロックからは、同じ Celesta のマイナーバージョン(たとえば 0.9.x)を使うどのコンピューターでも同じプラグインが使われます。
Celesta は、ロックしたバージョンを、--plugin-dir と CELESTA_PLUGIN_PATH のフォルダーのすぐ後、探す順にあるほかのどのフォルダーよりも先に、ダウンロード用のフォルダーから探します。Celesta に同梱のフォルダーよりも先です。ダウンロードしたプラグインは承認の確認なしに動きますが、ファイルが入れたときのままである間だけです。celesta、celesta-exporter、MCP サーバーは、アプリでプロジェクトを信頼したかどうかにかかわらず、プロジェクトのロックを読みます。
コマンド
| コマンド | 内容 |
|---|---|
celesta plugin search <text> |
id か説明にその文字列を含むレジストリのプラグインを、最新バージョンと説明と一緒に一覧表示します。 |
celesta plugin info <id> |
プラグインの公開者と役割、最も新しいバージョンのライセンス(宣言がなければ license: not declared)、各バージョンの対応する Celesta のバージョン・ターゲット・状態(published、deprecated、yanked、withdrawn、blocked (<advisory>))、このプロジェクトがロックしているか、すべてのプロジェクト用に入っているかを表示します。 |
celesta plugin add <id>[@<req>] |
プラグインを plugins.dependencies に加えてロックし、ダウンロードします。要件を省略すると、選んだバージョンを "1.2.3"(1.2.3 以降の 1.x)のように書きます。途中で失敗したときは、celesta.config.json と celesta.lock は元のままです。 |
celesta plugin remove <id> |
プラグインを plugins.dependencies と celesta.lock から外します。ネットワークは使いません。ダウンロードしたものは gc まで残ります。 |
celesta plugin install |
celesta.lock にあるものをダウンロードします。ロックが celesta.config.json と合わないとき(まだない、または要件が変わった)は、先にプロジェクトをロックし直し、まだ合うロック済みのバージョンはそのまま残して、wrote celesta.lock と表示します。 |
celesta plugin install --locked |
ロックにあるものをそのままダウンロードします。ロックを変える必要があれば、変えずに失敗します。 |
celesta plugin install --offline |
ダウンロード済みのものだけを使います。ないものがあれば、最初のプラグインを示して失敗します。 |
celesta plugin install --global <id>[@<req>] |
メディアプラグインを、すべてのプロジェクト用に入れます(レジストリのメディアプラグインを参照)。 |
celesta plugin update [<id>] |
すべてのプラグイン、または指定したプラグインについて、要件が許すいちばん新しいバージョンを選んでロックを書き直し、acme.charts 1.2.3 -> 1.3.0 のように変更を表示します。 |
celesta plugin list |
このプロジェクトがロックしているプラグインと、すべてのプロジェクト用に入れたプラグインを、installed、not installed、no build for <target>、blocked (<advisory>) のどれかと、該当すれば yanked や deprecated の印を付けて一覧表示します。 |
celesta plugin audit |
ロックしているプラグインとすべてのプロジェクト用のプラグインを、セキュリティアドバイザリーとレジストリに照らして確認し、見つかったことを表示します。何もなければ no problems found と表示します(プラグインの情報を取得できなかったときは警告し、no problems found in what could be checked と表示します)。ブロックされたプラグインや配布されなくなったプラグインがあれば失敗します。 |
celesta plugin gc |
どのプロジェクトも使っていないダウンロード済みのバージョンを削除します(ダウンロードを片付けるを参照)。--dry-run を付けると、削除するものを表示するだけです。 |
celesta plugin search chart
celesta plugin info acme.charts
celesta plugin add acme.charts@1.2
celesta plugin remove acme.charts
celesta plugin install
celesta plugin install --locked
celesta plugin install --offline
celesta plugin install --global acme.codec
celesta plugin update acme.charts
celesta plugin list
celesta plugin audit
celesta plugin gc --dry-run
add は、書き込んだものとダウンロードしたものを表示します。
added acme.charts 1.2, locked 1.2.3
installed acme.charts 1.2.3
CI では celesta plugin install --locked を実行してください。コミットしたロックのとおりに入れ、ロックが celesta.config.json と合わないときや、動いている Celesta で読めないバージョンがあるときは失敗するので、コミットしたものと違うバージョンでビルドされることはありません。
レジストリのメディアプラグイン
メディアプラグイン(デコーダー・エンコーダー・マルチプレクサー)はすべてのプロジェクトで使うものなので、--global で一度だけ入れます。Celesta はそれを settings.json に記録し、ユーザーのプラグインフォルダーのすぐ後に探します。
celesta plugin install --global acme.codec
add はメディアプラグインを受け付けず、--global を使うよう案内します。メディアプラグインのバージョンを 1 つのプロジェクトにロックしたいときは、--pin を付けて加えます。
celesta plugin add acme.codec --pin
ピン留めで決まるのは、プロジェクトでその id のどのバージョンを使うかだけです。どのエンコーダーやマルチプレクサーが既定になるかは、引き続き動画を書き出すコンポーネントのとおりです。ある 1 つのシステム向けのプラグインをピン留めしたときなど、このコンピューター向けのビルドがないロック済みのバージョンは、ロックの問題になりません。install はそれを読み飛ばし(skipped acme.codec 1.0.0: no build for linux-x86_64)、celesta-exporter と MCP サーバーは celesta: skipped a plugin: the project locks acme.codec 1.0.0, which has no build for linux-x86_64; another copy of acme.codec is used if one is installed と警告して、すべてのプロジェクト用に入れたものか、その id の別のコピーを使います。
セキュリティアドバイザリー・非推奨・取り下げ
レジストリは、署名したセキュリティアドバイザリーの一覧を公開しています。一覧にあるバージョンのプラグインは、どこで見つかったものでも動きません。デスクトップアプリでも、celesta-exporter でも、MCP サーバーでも同じです。search、info、add、install(--offline のときを除く)、update、list、audit は、実行のたびに一覧を一度取得し、最大 3 秒待って、届かなければ前に取得した一覧を使います。前に取得した一覧はオフラインでも有効です。一覧をまだ取得していないときと、最新の一覧が 7 日より古いときは警告します。
celesta: warning: the security advisory list is 9 days old; plugins under newer advisories may run
オンラインでこれらのコマンドのどれかを実行すると、新しい一覧を取得します。
公開者はバージョンを非推奨(deprecate)にすることがあります。非推奨のバージョンも入りますが、警告が出て、代わりがあればその名前も示されます(acme.charts 1.2.3 is deprecated: … (use acme.graphs instead))。取り下げられた(yank された)バージョンは二度と選ばれませんが、それを指すロックではそのまま残り、ダウンロードもされます。そのときは acme.charts 1.2.3 is locked and has been yanked と警告します。レジストリから撤回されたバージョンは入れられません。アドバイザリーでブロックされたバージョンは、ダウンロード済みでも入れることも使うこともできません。install は理由を示して失敗するので(acme.charts 1.2.3 is blocked by advisory CELESTA-2026-0009; run `celesta plugin update acme.charts`)、celesta plugin update <id> で別のバージョンを選んでください。
書き出しでロックを使えないとき
celesta-exporter と MCP サーバーは、エントリーのプロジェクトの celesta.lock を読みますが、変更もダウンロードもしません。プロジェクトが宣言したプラグインをロックから用意できないと、書き出しは始まる前に失敗します。--json ではエラーコード plugins_unsatisfied になり、メッセージには実行するコマンドが示されます。
| メッセージ | 対処 |
|---|---|
the project declares registry plugins but has no celesta.lock; run `celesta plugin install` |
celesta plugin install を実行し、書き込まれたロックをコミットします。 |
celesta.lock does not match celesta.config.json for acme.charts; run `celesta plugin install` |
要件が変わったか、プロジェクトが宣言しなくなったプラグインがロックにあります。celesta plugin install を実行します。 |
the project's locked plugins are not installed: acme.charts 1.2.3 (it is not installed); run `celesta plugin install` |
ロックしたバージョンがこのコンピューターにダウンロードされていないか、そのファイルが変わっています(its installed files differ from the lock)。celesta plugin install を実行します。理由が it is blocked by advisory … のときは代わりに celesta plugin update <id> を、it does not load with Celesta … のときは celesta plugin update を実行します。 |
<project>/celesta.config.json: plugins.dependencies entry "acme.charts": …(または celesta.config.json を示すほかのメッセージ) |
ファイルが正しい JSON でないか、plugins の要件やターゲットが正しくありません。メッセージが示すところを直します。 |
the project's celesta.lock could not be read: … |
ロックが正しい JSON でないか、新しい Celesta がこの Celesta の読めないロック形式で書いています(… does not read; update Celesta)。手で編集せず、バージョン管理から元に戻すか、メッセージのとおり Celesta を更新します。 |
celesta.lock was resolved with Celesta 0.9.0, and this is Celesta 0.10.0; acme.charts cannot load with it. Run `celesta plugin update` to resolve them again |
別のマイナーバージョンの Celesta で作ったロックです。celesta plugin update でこの Celesta 向けのバージョンを選んでロックを書き直し、コミットします。 |
ロックした id のプラグインが --plugin-dir や CELESTA_PLUGIN_PATH のフォルダーにあれば、ロックしたバージョンの代わりにそちらが使われます。ロックしたバージョンが動けなかったとき(ダウンロードされていないなど)も書き出しは失敗せず、そのコピーで続けて、ロックしたバージョンを使わなかった理由を警告します。作っているプラグインのビルドを、それをロックしたプロジェクトで試すときは、この方法を使います。
ロックしたバージョンを Plugins タブでオフにしたときは、ほかのオフにしたプラグインと同じく次のコピーに譲ります。書き出しは失敗せず、celesta: skipped a plugin: the project locks acme.charts 1.2.3, which is turned off in your settings; another copy of acme.charts is used if one is installed と警告して、探す順で次にある同じ id のコピーを使います。ロックしたバージョンをまた使うには、オンに戻してください。
ダウンロードを片付ける
ダウンロードしたバージョンは、celesta plugin gc で削除するまで、Celesta のダウンロード用のフォルダーに残ります。ユーザーのプラグインフォルダーの隣の registry です(%APPDATA%\Celesta\registry、~/Library/Application Support/Celesta/registry、$XDG_DATA_HOME/celesta/registry)。Celesta は、プラグインをロックしたり入れたりしたプロジェクトを覚えています。gc は、覚えているプロジェクトのロックにあるバージョン、現在のプロジェクトのロックにあるバージョン、すべてのプロジェクト用に入れたバージョンを残します。celesta.lock がなくなったプロジェクトは忘れ、1 時間以上前に途中で終わったダウンロードは削除します。
removed acme.charts 1.0.0
removed 2 unfinished downloads
覚えているプロジェクトのロックを読めないとき、gc は何も削除せず、そのロックを示します。そのロックを直すか削除するか、エラーに示される一覧(ダウンロード用のフォルダーの .projects.json)からそのプロジェクトを外してください。
メディアプラグイン
Celesta 本体の実行ファイルは FFmpeg をリンクしません。FFmpeg の 2 構成のうち、
アプリと Linux イメージに同梱するのは標準の ffmpeg(LGPL)だけです。デコード、
ProRes、VP9、AAC、Opus、PCM、MP4・MOV・WebM の muxer を提供します。個別のダウンロードで
ffmpeg-x264/libx264(GPL の H.264)を追加できます。標準版だけでも H.264 の読み込みと、
ProRes/MOV、WebM(アルファ付き VP9、Opus)の書き出しが使えます。
macOS は avfoundation、Windows は mediafoundation も同梱します。OS のメディア機能を
MIT/Apache-2.0 で利用するプラグインです。H.264 のエンコーダーはユーザーが追加した
x264 より優先され、利用可能なら MP4 の既定の映像エンコーダーになります。
標準 FFmpeg が muxer と AAC を担当します。Linux の MP4 には ffmpeg-x264 が必要です。
どの OS でも x264 を選ぶには ffmpeg-x264/libx264 を明示します。
書き出しガイドもご覧ください。
識別子が変わったのは ffmpeg/libx264 だけです。これを指定するプリセットやコマンドは
ffmpeg-x264/libx264 に変更してください(別名はありません)。ffmpeg/opus と
ffmpeg/vp9 は以前のリリースと同じ識別子です。ローカルビルドでは GPL 構成を含む
システム FFmpeg 8.1.x も使えます。配布用ビルドでライセンスを明示的に検査します。
追加版は libx264 がないビルドも検出します。ソースからのビルドをご覧ください。
追加コーデックのダウンロード
使っている Celesta のリリースの添付ファイルから、OS と CPU アーキテクチャに合う ZIP を選びます。
| ダウンロード | 追加する機能 | 必要な用途 |
|---|---|---|
ffmpeg-x264 |
ffmpeg-x264/libx264(GPL) |
libx264 による H.264。Linux の MP4 に必要 |
ファイル名は Celesta-plugin-ffmpeg-x264-<version>-<os>-<arch>.zip です
(例:Celesta-plugin-ffmpeg-x264-0.9.0-macos-arm64.zip)。アプリと同じリリースを
使ってください。ZIP にはマニフェスト、実行ファイル、必要なネイティブライブラリ、
ライセンス文書をまとめた ffmpeg-x264 フォルダーが 1 つ入ります。
FFmpeg を別途インストールする必要はありません。
ZIP を展開し、そのフォルダーごと上記のユーザープラグインフォルダーへコピーします。
中のファイルを分けないでください。Celesta を開き、Reload Plugins を選んで、
追加したプラグインの実行を許可します。CLI ではアプリで事前に許可するか、
--allow-plugin ffmpeg-x264 を使うか、
--plugin-dir に親フォルダーを指定します。
Linux の MP4 には x264 が必要です。macOS・Windows は同梱の H.264 も使えます。 WebM にはダウンロードは不要です。H.264 のエンコーダーがないときは QuickTime · ffmpeg を 選ぶと ProRes/MOV、WebM · ffmpeg を選ぶと VP9 を書き出せ、静止画も書き出せます。メディアの読み込みは標準版が 担当します。ブラウザーの MP4 書き出しは WebCodecs を使うため、このプラグインは不要です。
ほかのコーデックとコンテナーでは標準の ffmpeg が優先され、ネイティブのコンポーネントは名前を指定したときに使われます。H.264 は例外で、利用可能な場合は AVFoundation と Media Foundation が MP4 の既定の映像エンコーダーになります。それらのデコーダーは FFmpeg が読めないファイルを読みます(macOS の AVFoundation コンポーネントと Windows の Media Foundation コンポーネントをご覧ください)。
メディアプラグインのマニフェストには "roles": ["media"] と "protocol": 2 があり、プラグインが持つコンポーネントを media の下に並べます。どれにも id と表示する名前の name を書きます。
decodersはファイルを読みます。読めるファイルの種類をextensions(ドットなし)に書きます。videoEncodersとaudioEncodersは映像と音声を圧縮します。書き出すコーデックをcodecsに、WebCodecs のコーデック文字列の最初のドットより前の部分(H.264 はavc1、AAC はmp4a)で書きます。映像エンコーダーは、受け取るピクセル形式をinputFormatsに書けます。muxersはファイルを書きます。書けるファイルのextensions、受け付けるコーデックをvideoとaudio(audioのないマルチプレクサーは音声を書きません)、既定で書くコーデックをdefaultVideoとdefaultAudioに書きます。先頭より前に置いた音声を隠せるなら"trimsLeadingAudio": trueを書きます。--loopはこれを使います。priorityは省略できる整数で、省略すると0です。同じ場所(自分で入れたプラグイン、または Celesta に同梱のプラグイン)のプラグインの中では、priorityが大きいプラグインのデコーダーが先に尋ねられ、そのマルチプレクサーとエンコーダーが先に既定として選ばれます。Celesta に同梱のffmpegプラグインは"priority": 1なので、ほかの同梱プラグインより先になります。整数でないpriorityは理由を示したうえで読み飛ばされ、そのプラグインは0として扱われます。
{
"id": "ffmpeg",
"name": "FFmpeg",
"version": "0.9.0",
"celesta": ">=0.9.0, <0.10.0",
"protocol": 2,
"roles": ["media"],
"executable": { "macos-aarch64": "bin/celesta-codec-ffmpeg" },
"media": {
"decoders": [
{ "id": "ffmpeg", "name": "FFmpeg", "extensions": ["mp4", "mov", "webm", "mp3", "wav"] }
],
"videoEncoders": [
{ "id": "prores", "name": "ProRes", "codecs": ["ap4h"], "inputFormats": ["rgba16"] }
],
"audioEncoders": [
{ "id": "aac", "name": "AAC", "codecs": ["mp4a"] }
],
"muxers": [
{ "id": "mp4", "name": "MP4", "extensions": ["mp4"], "video": ["avc1"], "audio": ["mp4a"],
"defaultVideo": "avc1", "defaultAudio": "mp4a", "trimsLeadingAudio": true }
]
}
}
プラグイン自身の name は省略でき、エディターの書き出しページがコンポーネントの横に表示する名前です。省略すると、プラグインの id が使われます。コンポーネントの id はプラグインの id と同じ決まりに従い(プラグインを作るを参照)、同じプラグインの同じ種類のほかのコンポーネントと重なってはいけません。これに反するコンポーネントは理由を示したうえで読み飛ばされ、そのプラグインのほかのコンポーネントは使われます。コンポーネントは ffmpeg-x264/libx264 のように <プラグイン>/<コンポーネント> という名前を持ちます。プラグインを実行するとき、Celesta はそのコンポーネントについて尋ねます。各コンポーネントがこのコンピューターで使えるか(libvpx なしでビルドした FFmpeg は vp9 についてそう答え、理由を添えます)と、その設定です。プラグインはメディアプラグインかコンテンツプラグインのどちらかで、両方の役割を持つマニフェストは読み飛ばされます。以前の "roles": ["codec"] 向けに作られたプラグインは無視され、Celesta はそれでメディアを読みません。お使いの Celesta 向けのリリースを入れるか、ソースビルドでは plugins/ffmpeg をビルドし直してください。
ファイルを読むデコーダー
Celesta は、最初のひとつだけでなく、実行してよいメディアプラグインをすべて使います。ファイルを読むときは、そのファイルの拡張子を挙げたデコーダーに、次の順で尋ねます。
- 自分で入れたプラグインのデコーダー(
--plugin-dir、CELESTA_PLUGIN_PATH、ユーザーのプラグインフォルダー、追加したフォルダーのもの) - Celesta に同梱のプラグインのデコーダー
- プロジェクトのプラグインのデコーダー(プロジェクトを信頼し、プラグインを許可したあと)
それぞれの中では priority の大きいプラグインを先にし、次に上の検索順にプラグインを並べ(そのため Celesta に同梱のプラグインの中では ffmpeg が先)、ひとつのプラグインのデコーダーはマニフェストに書いた順に並べます。どのデコーダーも挙げていない拡張子のファイルや、拡張子のないファイルは、この順ですべてのデコーダーに渡します。プロジェクトのプラグインを最後にするので、プロジェクトのデコーダーにファイルが渡るのは、それより前にあってそのファイルの拡張子を挙げたデコーダーが読まなかったときだけです。プロジェクトのデコーダーしか挙げていない拡張子のファイルは、それらのデコーダーだけに渡ります。同じ理由で、プロジェクトのメディアプラグインは Celesta に同梱のメディアプラグインを置き換えられません。同梱のメディアプラグインと同じ id のプロジェクトのプラグインは使われません。
デコーダーが自分の読むファイルではないと答えたとき、読めなかったとき、そのプログラムが起動しないときは、次のデコーダーに尋ねます。デコーダーのプログラムが時間内に答えなかったときや、書き出しをキャンセルしてプログラムが止められたときは、そこで探すのをやめます。ファイルはそのエラーで失敗し、後のデコーダーには尋ねません。最初にファイルを読めたデコーダーがそのファイルを受け持ち、以後のフレームと音声はそのデコーダーから届きます。そこで後からエラーになっても、ほかのデコーダーには移りません。存在しないとわかっているファイルは、プラグインを起動する前に失敗します。確かめられないパス(たとえばファイルをフォルダーのように辿るパス)は、デコーダーに渡されます。どのデコーダーも読めなかったときは、なるべく詳しいエラーになります。ファイルが見つからない、動画のストリームがない、デコーダーが返した最初のほかのエラー、の順です。どのデコーダーも自分の読むファイルではないと答えただけのときは、no decoder could read <file> (tried ffmpeg/ffmpeg) のように試したデコーダーを挙げ、書き出しはエラーコード unsupported_media で失敗します。
プロジェクトのプラグインがファイルをデコードすると、デスクトップアプリはそれを知らせます。Problems タブに my-decoder decodes 2 files in this project のようなお知らせ(問題ではなく情報)がファイルの一覧と一緒に表示され、Plugins タブのそのプラグインの行には、デコードしているファイルの数が表示されます。
動画を書き出すコンポーネント
書き出しは、--muxer で指定しない限り、出力の拡張子からマルチプレクサーを選びます。Celesta に同梱のプラグイン、次に自分で入れたプラグインの中から、それぞれ priority の順、次に上の検索順で、その拡張子を挙げた最初のマルチプレクサーです(そのため同梱のプラグインの中では ffmpeg が先)。次に、--video-encoder と --audio-encoder で指定しない限り、その defaultVideo と defaultAudio のコーデックでエンコーダーを選びます。マルチプレクサーと同じプラグイン、Celesta に同梱のプラグイン、自分で入れたプラグインの順に(それぞれの中では priority の順に)、そのコーデックを書けて、このコンピューターで使える最初のエンコーダーです。プロジェクトのコンポーネントを使うのは、プロジェクトのプラグインを読み込むアプリだけです。書き出しページで選んだとき((project) が付きます)か、プロジェクトの既定のプリセットが指定しているときに使います(エンコーダーは、そのプロジェクトのマルチプレクサーを選んだときも使います)。コマンドラインと MCP サーバーは、プロジェクトのプラグインを読み込みません。--list-components は入っているコンポーネントを一覧にし、--describe <プラグイン/id> はひとつのコンポーネントの設定を表示します。エンコーダーと設定を選ぶをご覧ください。
cargo install の場合
cargo install で置かれる、自分の実行ファイルと同じフォルダーにある、名前が celesta-codec- で始まるメディアプラグインのプログラム(celesta-codec-ffmpeg など)も、名前の順に、Celesta に同梱のプラグインとして使います。それぞれのプログラムには --manifest でマニフェストを尋ね、見つかったプラグインに(プロジェクトのものを除いて)そのプログラムが答えた id のものがないときだけ使います。そのため、同じ id のプロジェクトのプラグインはこれも置き換えられません。ただし、実行ファイルが target/release のような Cargo のビルドフォルダーにあるときは使いません。ソースビルドでは、自分でビルドしたメディアプラグインを使います(ソースからのビルドをご覧ください)。cargo install で Celesta を入れる場合は、メディアプラグインも入れてアプリと同じフォルダーに置いてください。celesta-editor や celesta-exporter だけを入れてもメディアプラグインは入りません。celesta-codec-ffmpeg が crates.io に公開されるまでは、cargo install --git https://github.com/mika-f/Celesta celesta-codec-ffmpeg でリポジトリから入れます(ソースからのビルドと同じく FFmpeg 8.1.x の開発ライブラリが必要です)。
cargo install では、celesta-codec-ffmpeg-x264 のような追加エンコーダーも対応するライブラリの環境で個別にインストールします。Celesta は実行ファイルの隣にあるそれも同じように検出します。標準プラグインだけでは libx264 による H.264 のエンコードは追加されません。libx264 のない FFmpeg(たとえば Fedora の ffmpeg-free)に対してビルドした celesta-codec-ffmpeg-x264 は --manifest を拒否するので、Celesta はこれを使いません。マニフェストを答えないプログラムは、名前の celesta-codec- より後の部分(ここでは ffmpeg-x264)のプラグインのものとして扱います。このとき ffmpeg-x264/libx264 を指定すると、not installed ではなく skipped at discovery (<プログラム>): --manifest failed (…): <プログラムの出力> という理由で component_unavailable になります。libx264 のある FFmpeg に対して入れ直してください。各メディアプログラムが受け付けるのは --manifest、--check-build、--check-license のいずれか一つか、Celesta が起動するときの引数なしだけです。それ以外の引数では使い方を表示して終了ステータス 2 で終わるので、検査の綴りを間違えても通ってしまうことはありません。
デコーダーがないとき
メディアのデコーダーがひとつもないと、動画と音声は表示も書き出しもできません。Problems タブには No media decoder can run が表示され、その理由(メディアプラグインにこのコンピューター向けのプログラムがない、承認を待っている、オフになっている、見つかったメディアプラグインがデコーダーを持たない、見つからない)を示します。メディアプラグインがひとつもないと、動画を書けるマルチプレクサーがないので、動画の書き出しはすぐにエラーコード unsupported_output で、メディアプラグインの入れ方のヒント付きで失敗します。静止画の書き出しや、メディアプラグインにデコーダーがない動画の書き出しは、動画や音声のファイルを読むときに no_decoder で失敗します。
共有メモリーと別の FFmpeg ビルド
メディアプラグインが対応していれば(ffmpeg プラグインは Celesta 0.10 から対応しています)、動画のフレームはプラグインのパイプではなく、Celesta とプラグインのプロセスが共有するメモリーを通ります。デコーダーから Celesta に届くフレームも、書き出しで動画エンコーダーに渡すフレームも同じです。このメモリーはほかのプロセスやユーザーからは開けません。書き出しでは、共有メモリーでもパイプでも、動画エンコーダーに最大 3 フレームを先に送ります。プラグインが前のフレームをエンコードしている間に、Celesta は次のフレームをレンダリングできます。8K のようなとても大きなフレームでは、待っているフレームが 256 MiB に収まるよう、先に送るフレームを減らします。対応していないプラグインや動画エンコーダー、デコードした 4096×2560 より大きなフレームはパイプを通ります。書き出しで約 3300 万画素を超えるフレーム(8192×4320 など)もパイプを通ります。共有メモリーは、エンコーダーが受け取るいちばん大きな形式(ffmpeg プラグインのエンコーダーでは 16 ビットの RGBA)のフレームを入れられる大きさで、256 MiB までだからです。Celesta 自身が共有メモリーを用意できないとき(システムが作成やプラグインのプロセスへの受け渡しを拒んだとき)もフレームはパイプを通り、Celesta は標準エラー出力に celesta: frames go through the pipe: とその理由を一度だけ表示します。メディアプラグインがこの共有メモリーでうまく動かないときは、Celesta を起動する環境で環境変数 CELESTA_CODEC_SHARED_MEMORY=0 を設定すると、デコードでも書き出しでも、すべてのフレームがパイプを通ります。
別の FFmpeg ビルドを使う場合も、ビルドごとに prefix を分け、ソースからのビルドの環境変数を指定します。node scripts/plugins/build.mts plugins/ffmpeg-x264 --out <ユーザーのプラグインフォルダー> で目的のプラグインをビルドします(標準版では plugins/ffmpeg を指定します)。ユーザーのフォルダーは同梱版より先に探され、アプリは実行前に確認します。LICENSE-GPL-2.0 と GPL-SOURCE-OFFER.md を含むのは ffmpeg-x264 だけです。ffmpeg には LICENSE-LGPL-2.1 と FFMPEG-SOURCE.md が入り、どちらのビルドにも LICENSE-MIT と LICENSE-APACHE が入ります。リポジトリのルートには Celesta 本体の MIT/Apache のライセンス文だけを置き、FFmpeg の GPL/LGPL 文書は対応するプラグイン配下に置いています。配布時も各プラグインの licenses/ に含め、リンクした FFmpeg ビルドの条件であることを区別します。配布する構成に合わせて、ソースと再リンク用の資料も用意してください。
サンプル
リポジトリの examples/plugins に、出発点になるプラグインが 3 つあります。
| プラグイン | 内容 |
|---|---|
flag |
プラグインのプログラムが描くレイヤー。画像を旗のようになびかせ、Celesta がテクスチャ付きメッシュとして描きます。 |
turntable |
プラグインのプログラムが 3D で描くレイヤー。ターンテーブルの上で回る、光を受けてプラグイン自身の WGSL マテリアルでトゥーン調に陰影が付き、アウトラインが描かれた市松模様の立方体を、半透明の板と切り抜いた葉と一緒に、Celesta が奥行きのあるシーンとして描きます。 |
beep-voice |
コンポーネントだけのプラグイン。音声合成エンジンの代わりにゲーム風のビープ音で planDialogue() のセリフを読み上げ、口パクも付ける音声チャンネルです。 |
pnpm install && pnpm run build:runtime # 最初に一度、リポジトリのルートで
node scripts/plugins/build.mts examples/plugins/flag examples/plugins/turntable examples/plugins/beep-voice
node scripts/plugins/build.mts plugins/ffmpeg plugins/ffmpeg-x264 # MP4 を書き出すメディアプラグイン
cargo run -p celesta-exporter -- --react examples/plugins/flag/demo.tsx flag.mp4 --plugin-dir examples/plugins/dist --plugin-dir plugins/dist
cargo run -p celesta-exporter -- --react examples/plugins/turntable/demo.tsx turntable.mp4 --plugin-dir examples/plugins/dist --plugin-dir plugins/dist
2 つ目の --plugin-dir で、エクスポーターにメディアプラグインを渡します。メディアプラグインのビルドには FFmpeg の開発ライブラリが必要です(ソースからのビルドをご覧ください)。
VRM プラグイン
vrm プラグインは、VRM 1.0 のアバター(.vrm)を 3D で描くプラグインです。UniVRM と同じ MToon のトゥーン調の陰影で描き、表情・まばたき・口パク・目線に加えて、モーション(.vrma)を再生し、髪や服を揺らせます。レジストリにある公式プラグインで、macos-aarch64・windows-x86_64・linux-x86_64 のビルドがあり、バージョンは Celesta と同じです。
celesta plugin add vrm # プレリリースではバージョンを指定します:vrm@0.10.0-alpha.4
デスクトップアプリは、信頼したプロジェクト(信頼を保存済みで、celesta.config.json があるもの)の celesta.lock を読み、ロックしたバージョンを実行します。ロックしたプラグインがダウンロードされていないそのようなプロジェクトを開いたときは、ダウンロードするかどうかを尋ねます。
公式のコンポーネントプラグイン aivis-speech・code・lottie・voicevox も同じです。それぞれのページで説明しています。
リポジトリの plugins/vrm からビルドする場合は、ビルドしてから、書き出されたフォルダーをインストールします。
pnpm install && pnpm run build:runtime # 最初に一度、リポジトリのルートで
node scripts/plugins/build.mts plugins/vrm # plugins/dist/vrm に書き出します
plugins/dist/vrm をユーザーのプラグインフォルダーにコピーするか、書き出しのときに --plugin-dir で plugins/dist を指定します。ビルドには、Celesta 本体のビルドと同じく Rust と Node.js が必要です。ソースからビルドしたエクスポーターで動画を書き出すときは、node scripts/plugins/build.mts plugins/vrm plugins/ffmpeg plugins/ffmpeg-x264 でメディアプラグインも同じフォルダーにビルドしてください。こうすると --plugin-dir plugins/dist で両方をエクスポーターに渡せます。メディアプラグインのビルドには FFmpeg の開発ライブラリが必要です。
import { Composition } from '@celesta.studio/react';
import { Vrm } from '@celesta-plugin/vrm';
export default function Root() {
return (
<Composition width={1920} height={1080} fps={30} durationInFrames={180}>
<Vrm src="./avatar.vrm" camera="bust" lookAt="camera" expressions={{ happy: 0.4 }} mouth="a" />
</Composition>
);
}
| props | 内容 |
|---|---|
src |
.vrm ファイル(VRM 1.0)。 |
width・height・aspect |
レイヤーのピクセル数です。両方を指定するか、片方と aspect(幅÷高さ、既定は 16:9)を指定すると、もう片方が決まります。aspect だけなら幅は 1920 のまま、どれもなければ 1920×1080 です。指定した辺も計算した辺も 1〜16384 ピクセルでなければならず、外れると <Vrm> がエラーを投げます。アバターはこの解像度で描かれ、小さなレイヤーを拡大することはありません。 |
expressions |
表情の重み(0〜1)。VRM のプリセット名(happy・angry・sad・relaxed・surprised・aa・blink など)か、モデル独自のカスタム表情の名前で指定します。blink や口の形より優先されます。 |
mouth |
口の形('a'・'i'・'u'・'e'・'o'・'closed')か、{ aa: 0.5, oh: 0.3 } のような母音ごとの重み。5 つの母音(aa・ih・ou・ee・oh)をすべて設定し、指定しなかった母音は 0 になるので、モーションの口の動きは出ません。 |
lipSync・mouthSmoothing |
口パクのトラック(loadLipSync() の結果や、読み上げたセリフの lipSync)。mouth がないときに使い、口の形を mouthSmoothing フレームかけてなめらかに切り替えます(既定は 2、0 で即座に切り替え)。mouth と同じく 5 つの母音をすべて設定するので、声のないところでは口が閉じます。 |
blink |
まばたきのタイミング。キャラクターの立ち絵と同じくシードで決まります。false でまばたきしません。 |
lookAt |
目線の先です。'camera'、アバターの空間の点 [x, y, z]、または度数の { yaw, pitch }(yaw はアバターから見て右が正、pitch は上が正)。なければ正面を向きます。 |
camera |
'full'(既定。全身)、'bust'(腰から上。ヒューマノイドの spine ボーンから)、'face'、またはアバターの空間での { position, target, fov?, near?, far? }(fov は度数、既定は 30)。 |
lights |
{ directional: [{ direction, color, intensity }], ambient }。平行光源は 4 つまで(5 つ目でエラー)、色は #rgb か #rrggbb です。基準ライトを置き換えるので、ambient がなければ環境光は黒になります。lights がなければプラグインの基準ライト(Unity の既定の平行光源を前上方から当て、既定の環境光の色を加えたもの)を使います。光源の intensity と、色に intensity を掛けた値は、32 ビット浮動小数点数で有限に収まらなければならず、外れるとそのフレームは lights.directional[i].intensity を示すエラーになります。 |
motions |
タイムラインに置く VRM アニメーション(.vrma)。[{ src, from?, loop?, fadeIn? }] の形で、from はモーションが始まる、囲んでいるシーケンスのフレーム(既定は 0)、fadeIn は前のモーションから切り替えるのにかけるフレーム数(既定は 0)です。from が有限でない場合と、fadeIn が負か有限でない場合はエラーになります。 |
tracks |
モーションの上から、ヒューマノイドのボーンをキーフレームで回します。{ head: { yaw: [{ frame, value, easing? }, …] }, … } の形で、pitch・yaw・roll は度数、x・y・z は hips だけに指定でき、単位はメートルです。 |
アバターの空間はファイルのままで、単位はメートル、+Y が上、アバターは +Z を向き、左手側が +X、足元はおおむね 0 です。カメラのプリセットは、レイヤーの縦横比に合わせて、基本姿勢で立つアバターを収めます。full は横幅も収めるので、片側に大きく張り出した持ち物があると、アバターが中央からずれます。
モデルを開くと、プラグインはモデルの利用条件をお知らせとして 1 行ずつ出します。作者・ライセンス・各条件です。作ろうとしている動画を禁じていそうな条件は warning になります。アバターを使えるのが作者本人か作者が個別に許諾した人だけの場合、商用利用ができない場合、クレジット表記が必要な場合(動画を公開する場所で誰をクレジットするかも書かれます)です。ファイルに書かれていない条件は VRM 1.0 の既定値として扱われ、既定値はいちばん厳しい側です。どの場合もプラグインはアバターを描きます。使ってよいかどうかを判断するのは利用者です。
ファイルが一人称視点専用とするメッシュ(装着者自身の視点用の、頭のない体など)は、UniVRM の三人称カメラと同じく描きません。ファイルが一つのノードを二度以上指定しているときは、UniVRM と同じく最初の指定が有効になり、それ以降の指定はそれぞれ警告になります。
ほかの警告は、ファイルのうちプラグインが書かれたとおりには使わない部分を知らせます。描かないプリミティブ、マテリアルが使わずに描くテクスチャ、無視するモーフターゲットのバインドです。これらの種類と一人称視点の重複指定は、それぞれ 20 件まで並べ、残りは 1 行で件数を示します(and 12 more primitives that are not drawn)。
マテリアルの発光は、KHR_materials_emissive_strength があればその値で、なければ VRMC_materials_hdr_emissiveMultiplier の値で明るくなります。UniVRM と同じ読み方です。この倍率が有限の数でなければ、そのフィールド名を示してモデルを開くのを断ります。
ファイルが素の glTF PBR で指定しているマテリアル(金属やガラスの部品によくあります)は、今のところベースカラーだけの平らな色で描かれ、その名前がお知らせで示されます。VRM 0.x のファイルにはまだ対応していません。変換の方法を示すメッセージとともに開くのを断るので、UniVRM か VRM Add-on for Blender で VRM 1.0 に変換してください。
1 GiB を超えるファイルと、glTF の JSON が 64 MiB を超えるファイルは開くのを断ります。.vrm の JSON は数 MB です。src には、バッファーを data: URI で埋め込んだ glTF の JSON ファイル(.gltf)も指定できますが、この場合はバッファーも JSON の一部なので、ファイル全体で 64 MiB までです。バッファーや画像を別のファイルに置いたファイルは開くのを断ります。
プラグインはモデルのテクスチャを画像ファイルとしてキャッシュに書き出し、Celesta はそこから読み込みます。キャッシュはユーザーのキャッシュフォルダー(Windows では %LOCALAPPDATA%、macOS では ~/Library/Caches、それ以外では $XDG_CACHE_HOME か ~/.cache)の中の celesta-plugin-vrm です。別の場所に置くには、CELESTA_VRM_TEXTURE_CACHE に絶対パスを設定します。キャッシュが相対パス、シンボリックリンク、フォルダーでないもの、または(Windows 以外で)ほかのユーザーのものかほかのユーザーが書き込めるものであれば、この変数の名前を示してモデルを開くのを断ります。プラグインはモデルを開くたびに、30 日間どのモデルにも使われていない画像を削除し、それでも画像が 2 GiB を超えていれば、使われたのが古いものから削除します。直近 1 日に使われた画像は残すので、別のウィンドウで開いているモデルや並行して動いている書き出しのテクスチャが消えることはありません。削除するのはプラグインが書き出した画像ファイルと、書き込みの途中で異常終了したときに残った一時ファイルだけなので、CELESTA_VRM_TEXTURE_CACHE で指定したフォルダーにあるほかのファイルは残ります。既定のキャッシュを自分で空にするには、Celesta を閉じた状態で celesta-plugin-vrm フォルダーを削除します。自分のフォルダーを指定している場合は、16 進数 64 文字の名前に .png、.jpg、.webp、.tmp が付いたファイルだけを削除します。
デスクトップアプリの Add メニューでは、VRM avatar を選ぶと .vrm ファイルを尋ね、16:9 の枠を描きます。
モーション・コンストレイント・揺れもの
motions は VRM アニメーションのクリップ(.vrma、VRMC_vrm_animation 1.0)を再生し、UniVRM と同じ方法でアバターに当てはめます(リターゲット)。各ボーンはクリップの中と同じだけ基本姿勢から回り、腰(hips)はクリップの移動量を、アバターとクリップの腰の高さの比で拡大・縮小して動きます。モーションは from の順に並び、それぞれ次のモーションが始まるまで再生されます。最初のモーションより前は、アバターは基本姿勢で立っています。loop を付けたモーションは繰り返し、付けなければ最後の姿勢のまま止まります。クリップに表情の重みがあればそれも使いますが、expressions で指定した表情が優先されます。mouth か lipSync を指定すると母音はすべてそちらで決まり、クリップの口の動きは出ません。どちらも指定しなければ、口はクリップのとおりに動きます。
tracks は、モーションのあとに、ボーンを基本姿勢からキーフレームで回します。角度の向きは lookAt と同じ(UniVRM と同じ)で、yaw はアバターから見て右へ向け、pitch は上を向かせ、roll は上側をアバターから見て右へ傾けます。負の値は逆向きで、負の yaw は左へ向き、負の pitch はうつむきます。hips の x・y・z はアバター全体をメートル単位で動かします。キーフレームの frame は囲んでいるシーケンスのフレームで、小数は最も近いフレームに丸めます。次の例は、歩くクリップを再生し、フレーム 90 から 15 フレームかけて待機のクリップに切り替え、そのあと頭を回して左肩越しに振り返り、また前を向きます。
<Vrm
src="./avatar.vrm"
motions={[
{ src: './walk.vrma', loop: true },
{ src: './idle.vrma', from: 90, loop: true, fadeIn: 15 },
]}
tracks={{
head: {
yaw: [
{ frame: 120, value: 0 },
{ frame: 135, value: -40, easing: 'ease-in-out' },
{ frame: 165, value: -40 },
{ frame: 180, value: 0, easing: 'ease-in-out' },
],
},
}}
/>
アバターのノードコンストレイント(ねじれる袖のように、ほかの部位に付いて動く部品)は、毎フレーム UniVRM と同じ順で追従します。揺れもの(スプリングボーン。髪やスカートなど)は、レイヤーの先頭から 60 Hz の固定の刻みで計算するので、どのフレームも、シークして表示しても、順に再生しても、30 fps でも 60 fps で書き出しても同じになります。motions と tracks は、レイヤーのフレームを通じて同じ値にしてください。プラグインは揺れものの計算の途中経過をその組み合わせごとに覚えておくので、フレームごとに値が変わると、毎フレーム揺れものをレイヤーの先頭から計算し直すことになります。フレームごとに変わる値は、揺れものが読まない expressions・mouth・lookAt に入れます。
試せるクリップ:pixiv/three-vrm の test.vrma(packages/three-vrm-animation/examples/models、MIT)と、BOOTH で無料配布されている VRoid プロジェクトの VRMA モーションパック(ピクシブ)。モーションパックの利用条件では、商用利用はできますが、ファイルの再配布はできません。また、動画を公開する場所に「キャラクターアニメーション: ピクシブ株式会社 VRoidプロジェクト」とクレジットを表記することが求められます。動画を公開する前に、それぞれのクリップの利用条件を確かめてください。
突き当たるかもしれない上限:
- 1 つのレイヤーで開けるクリップは 256 種類までで、ファイルは合わせて 1 GiB まで、読み込んだアニメーションのキーも合わせて 1 GiB までです。
- 揺れものはレイヤーの先頭から 4 時間まで計算します。それより後のフレームは、そう示すエラーになります。揺れものの計算が重いアバター(ノードが 1 万ほどあるもの、揺れものとコライダーの当たり判定が数千あるものなど)はそれより短い時間までしか届きません。モデルを開いたときに警告が出て、届かないフレームは届く時間を示すエラーになります。
- 読まないもの:
VRMC_springBone_limitの角度制限(モデルにあれば警告が出て、その関節は制限を超えて揺れます)、クリップのlookAtのアニメーション、クリップの最初以外の glTF アニメーション。揺れものはlookAtや表情には反応しません。 - 足の IK はありません。UniVRM と同じく、基本姿勢がアニメーションより少し高い・低いクリップや、腰の高さのわりに脚が長い・短いアバターでは、足が床に数センチ沈んだり浮いたりすることがあります。
プラグインを作る
プラグインは最大 2 つの部分からなり、どちらも言語を問いません。
- コンポーネント(マニフェストの
moduleとtypes):ES モジュールとその型定義です。Celesta はモジュールをエントリーにバンドルし、その中のreactと@celesta.studio/*の import はアプリ自身のものを使います。プログラムが描くレイヤーは、@celesta.studio/reactの<PluginLayer>で置きます。pluginはプラグインの id、assetsはプログラムが名前で読むファイル、dataはフレームとともに渡す JSON、timeは描く時刻(省略時は囲むシーケンスの時刻)です。ほかの props は、ほかのレイヤーと同じくレイヤーを配置します。音声合成チャンネルはこれだけで作れます。@celesta-plugin/voicevoxと同じくprepare()の中で動き、audioとlipSyncを付けたセリフを返します。 - プログラム(
executable、プラットフォームごと):標準入力でリクエストを読み、標準出力で答えます。レイヤーについては、指定された時刻の 2D のテクスチャ付き三角形メッシュとその色・マスク・合成方法か、3D のシーンを返し、Celesta が描きます。シーンは、スキニングとモーフィングをする三角形のジオメトリーにマテリアルを付けたもので、プログラムが置いたカメラから見て描かれます。Celesta はシーンを奥行きとアンチエイリアス付きで描き、不透明・切り抜き・半透明のマテリアルを扱います。マテリアルは Celesta のライティングなし(unlit)のマテリアルか、プログラムが持ち込むマテリアルです。持ち込むマテリアルは Celesta のマテリアルインターフェースに沿って WGSL で書き、プログラムが送る平行光源と環境光で陰影を付けたり、アウトラインを足したりできます。Celesta はこの WGSL をコンパイルする前に検査します。独自のリソースをバインドすることや、エントリーポイント、ワークグループ変数(var<workgroup>。コンピュートシェーダー専用です)、パイプラインで値を上書きする定数(override)、WGSL があらかじめ宣言している名前(clampやvec4fなど)、celestaで始まる名前(大文字・小文字を問いません)を宣言することはできません。フレームごとに、モデルのマテリアルアニメーションのようにマテリアルのパラメーターを変えることもできます。そのフレームのレイヤーのキャンバスの大きさを、モデルのものの代わりに指定することもできます(各辺 1〜16384 ピクセル)。これで、コンポーネントは欲しい解像度をレイヤーのデータで渡せます。テクスチャは、メッシュ用でもシーン用でも、各辺 1〜8192 ピクセル(GPU の上限)です。Celesta は画像ファイルの大きさを読み込む前に確かめ、これより大きいテクスチャや空のテクスチャはレイヤーのエラーとして断ります。画像ファイルは絶対パスで渡します。プログラムは自分のフォルダーで動きますが、Celesta はファイルを自分のフォルダーから開くため、相対パスはそのテクスチャを示して断ります。モデルの頂点データの数値(位置・法線・テクスチャ座標・接線・ジョイントのウェイトと、モーフターゲットのオフセット)はすべて有限でなければなりません。NaN や無限大を含むモデルは、Celesta が開くときに断ります。メッセージはgeometry 0's normals are not finite at vertex 12のように、ジオメトリー(またはメッシュ)・ストリーム・頂点を示します。フレームはモデル・時刻・レイヤーのデータだけで決まるようにしてください。Celesta が各応答を待つ時間には上限があります。プログラムの起動とフレームは 30 秒、モデルを開くのは 2 分、閉じるのは 5 秒です。どのレイヤーも 300 回続けて描かなかったモデル(60 fps の再生や書き出しで約 5 秒)は Celesta が閉じ、後でレイヤーが描くときにまた開きます。時間内に応答しないプログラムは止められ、標準エラーに最後に書いた行とともに報告されます。次に必要になったときにもう一度起動されます。書き出しを中止すると、その書き出しが動かしているプログラムはフレームの途中でもすぐに止められます。File > Reload Plugins を選んだり別のファイルを開いたりすると、プレビューが動かしていたプログラムも止められます。Celesta は、描き直しや書き出しのときなどに、同じフレームをもう一度求めることがあります。モデルを開いたときには、モデルの利用条件のようなお知らせも返せます。お知らせは上で説明したように表示されます。Rust ならcelesta-pluginクレートを使えます。そのserveは、Windows・macOS・Linux で標準出力を応答だけに使います。プログラムや、プログラムが読み込むライブラリーがほかに標準出力へ書いたものは、標準エラーに出ます。プロトコル自体は長さ付きの素朴な JSON です。
マニフェストのパス(module、types、各 executable)はプラグインのフォルダーからの相対パスで、フォルダーの外を指すことはできません。区切りは / で書いてください。\ もどのプラットフォームでも区切りとして読むので、js\index.js は Windows・macOS・Linux のどれでも同じファイルを指します。
デスクトップアプリの Add メニューにコンポーネントを出すには、マニフェストの components に書きます。
"components": [
{ "name": "Flag", "label": "Flag", "src": "image", "props": { "amplitude": 0.06 } }
]
name はモジュールが export するコンポーネント名で、英大文字で始まり、英字・数字・_ が続きます。label はメニューに表示する名前です(省略すると name)。src("image" または "video")があると Image と同じように追加され、アプリはファイルを尋ねて src・x・y・width を書きます。"src": "model" は、3D モデルのようにプラグインが自分で読むファイルのためのものです。受け取るファイルの種類を extensions に(英小文字と数字、ドットなし、重複なし。["glb"] など)、レイヤーの幅÷高さを aspect に(1/16384〜16384。省略できません)書くと、アプリはその縦横比で枠を描きます。アプリはその種類のファイルだけを受け付け、Image と同じく src・x・y・width を書きます。height は書かないので、コンポーネント自身の既定の縦横比を aspect と同じにしてください。違うと、描いた枠とレイヤーが一致しません。src がなければ四角形として描かれ、x・y・width・height を書きます。props はそのあとに書かれる props です。名前には英字・数字・_ を使い、値は文字列・数値・真偽値のいずれかで、描いた範囲から書く props と同じ名前は使えません。components を持つマニフェストには module も必要です。
マニフェストには必ず celesta を書き、プラグインが動く Celesta のバージョンを ">=0.9.0, <0.10.0" のような Cargo のバージョン範囲で示します。この範囲は、プログラムがプロトコルの上に頼る機能(protocol はメッセージの形式だけを表します。コンテンツプラグインは 1 で、3D シーンのような機能が加わっても 1 のままです。メディアプラグインは 2 です)と、モジュールが使う react や @celesta.studio/* の API の両方を表します。これらの API は Celesta と同じバージョンで同梱されます。0.10.0-beta.1 のような Celesta のプレリリースは、範囲の端が同じバージョンのプレリリースを指すとき(">=0.10.0-beta.1, <0.11.0" など)だけ範囲に入ります。リポジトリの scripts/plugins/build.mts は、ビルドに使った Celesta から、その次のマイナーリリース(1.0 より前)またはメジャーリリースの手前までの範囲を自動で書きます。
マニフェストには license を書けます。プラグインを配布するときのライセンスを SPDX ライセンス式で示します。"MIT"、利用者が選べるときは "MIT OR Apache-2.0"、複数が同時に適用されるときは "(MIT OR Apache-2.0) AND LGPL-2.1-or-later" のように書きます。ソースだけでなく、同梱物を含めた配布物全体のライセンスを書いてください。プロプライエタリなライセンスなど、SPDX のライセンス一覧にないものは、LicenseRef- で始まる独自の識別子を書き、それが何を指すかを licenseRefs に書きます。
{
"license": "GPL-3.0-only OR LicenseRef-Acme-Commercial",
"licenseRefs": {
"LicenseRef-Acme-Commercial": { "name": "Acme Commercial License", "url": "https://acme.example/license" }
}
}
式に書いた LicenseRef- の識別子には、それぞれ name を持つ項目が必要です。url は省略でき、https:// で始めます。Celesta 本体はこれらの項目を読みません。レジストリはバージョンの公開時に検査し、読めないものは拒否します。AND・OR・WITH は大文字で、空白は 1 つずつにし、識別子は SPDX の一覧と同じつづりで、現行のものを使ってください(非推奨の GPL-2.0 ではなく GPL-2.0-only か GPL-2.0-or-later)。レジストリのサイトと celesta plugin info がライセンスを表示し、宣言のないバージョンは未宣言と表示されます。リポジトリのプラグインでは、plugin.json に同じ 2 つのキーを書くと scripts/plugins/build.mts がマニフェストへ写します(licenses キーは別のもので、プラグインの licenses/ フォルダーへコピーするライセンスファイルの一覧です)。
プラグインの id には英小文字・数字・-・_・. を使い、先頭は英小文字か数字にします。builtin は Celesta に組み込みのもののために予約されています。マニフェストで指定するファイルはすべて、プラグインのフォルダー内を指す相対パスにします。.. を含むパスや、フォルダーの外へ向かうリンクは使えません。これに反するプラグイン、celesta の範囲がないか動いている Celesta を含まないプラグイン、protocol が役割のものと違うプラグイン、コンテンツとメディアの両方の役割を持つプラグイン、上の決まりに反するコンポーネントを持つプラグインは、理由を示したうえで読み飛ばされます。
両方の部分の作り方はサンプルの README で説明しています。マニフェストとプロトコルはリポジトリの docs/handoff/2026-11-01-plugin-system.md で、その後の変更(components など)は docs/handoff/2026-11-02-plugin-*.md で、3D のシーンとお知らせは docs/handoff/2026-11-03-plugin-scene-content.md で、プラグインが持ち込むマテリアル(WGSL)・ライト・描画順・アウトラインは docs/handoff/2026-11-03-plugin-scene-materials.md で、VRM プラグインとモデルファイルを受け取るコンポーネントは docs/handoff/2026-11-03-plugin-vrm.md で説明しています。