SyncSing Studio
Developers

拡張機能を作る

SyncSing Studio 拡張機能（プラグイン）開発キット（API 1.1）

C#（.NET Framework 4.8）が正式な SDK です。SyncSing の公式の拡張機能（配信チェック・チャットエフェクト）も、この SDK でつないでいます。問い合わせ・不具合の対応は C# を優先します。迷ったら C# の雛形から始めてください。

Python は参考の SDK です。開発キットの版を出すたびに Windows で雛形のビルドと試験を通していますが、公式の拡張機能では使っていないので、C# より見つかりにくい不具合が残っている可能性があります。

SyncSing Studio / SyncSing NC Lite の拡張機能を作るための資料・部品・雛形です。 拡張機能は アプリとは別のプロセス（EXE） として動き、名前付きパイプでアプリの窓口（拡張機能 API）を呼びます。 考え方は OBS のプラグインに近く、動かし方は別プロセスです。

大事: 拡張機能は既定で隔離して動かします（Windows の AppContainer）。 読めるのは自分の EXE のフォルダと Windows・.NET などの公開された場所だけ、書けるのは data_dir・log_dir だけです。 通信は manifest の network.hosts に何か書いたときだけインターネットへ出られます（宛先までは絞れません。LAN・localhost への 接続と待ち受けはできません）。ほかのアプリの中身を読むこともできません。 localhost でサーバーを立てる・ほかのプロセスの情報を読む など、隔離すると動かないものは、要審査の権限 system.unrestricted （隔離せずに動かす）を宣言します。この権限を許可された拡張機能は 隔離されません。そのときのファイル・通信の決まりは 作者が守る約束（開発者規約）で、審査と署名の取り消しで担保します（PERMISSIONS_JA.md）。

どの SDK を使うか

中身

フォルダ・ファイル内容
dotnet/SyncSing.Plugin.Sdk/正式な SDK。C#（.NET Framework 4.8）用。公式の拡張機能もこれでつなぐ。SyncSingPlugin.cs（接続・hello・要求と返事・イベント・ホストからの要求）と、全メソッドの型付き API SyncSingApi.g.cs（client.Api.MicSet(strength: 3)。戻り値も MicSetResult などの型付き。自動生成）
python/参考の SDK。Python 用。syncsing_plugin_sdk.py（接続）と、全メソッドの型付き API syncsing_api.py（Api(client).mic_set(strength=3)。戻り値の形は MicSetResult などの TypedDict。自動生成）。標準ライブラリだけ
templates/dotnet-basic/C# の雛形（いちばん小さな拡張機能）。build.ps1 で開発フォルダ dist\ ができます
templates/python-basic/Python の雛形。python/ の 2 ファイルを同梱し、PyInstaller で EXE にまとめて使います
tools/syncsing_plugin.pyコマンドラインの道具 syncsing-plugin（create・validate・test・pack・whoami・uuid・submit・status）
schemas/manifest.json の JSON Schema と、api-1.1.json（全メソッドの引数・戻り値、イベントの中身、権限を JSON Schema で。別の言語の SDK を作るときの元にできます）
LICENSESDK（dotnet/・python/・tools/・schemas/）は MIT、雛形（templates/）は 0BSD
docs/API_LIST_JA.md（全メソッド・イベントの一覧と権限ごとの表）・API_REFERENCE_JA.md（引数と戻り値）・PERMISSIONS_JA.md（権限）・PROTOCOL_JA.md・MANIFEST_JA.md・DISTRIBUTION_JA.md

作ってから配るまで

  1. 開発者規約に同意する — SyncSing Studio の 設定 → 拡張機能 →「開発者規約」。開発者モードを ON にするときにも聞かれます。 開発・配布には SyncSing Identity のアカウントが要ります（開発者としての登録は誰でもできます）。
  2. 開発者モードを ON — SyncSing Studio の 設定 → 拡張機能 → 開発者モード（SyncSing Identity でのログインが要ります）。 説明文に、manifest の author.identity_id に書く、あなたの Identity ID が出ます。
  3. 雛形から作る — python sdk/tools/syncsing_plugin.py create <フォルダ> --template dotnet-basic（または python-basic）。 manifest.json の uuid は、配る前にサーバーが発行した UUID にします（python sdk/tools/syncsing_plugin.py uuid <フォルダ> で発行して書き換えます。早めに済ませておくと、設定やデータが途中で切り替わりません）。 **uuid は新しい拡張機能を作る最初の 1 回だけです。** uuid は拡張機能を見分ける値なので、変えると「更新」ではなく「別の拡張機能」になり、前の版を入れた人に更新が届きません。manifest にもう uuid があるときは uuid コマンドは断ります（別の拡張機能として作り直すときだけ --force）。
  4. 開発フォルダを登録 — 設定 → 拡張機能 →「開発フォルダを登録」で、manifest.json のあるフォルダ（雛形なら dist\）を選び、権限を許可します。 EXE か manifest.json を作り直すと自動で再起動します。ログは「ログを開く」。
  5. 確かめる — python sdk/tools/syncsing_plugin.py validate <フォルダ>（manifest とパッケージの、アプリと同じ検査）と、 python sdk/tools/syncsing_plugin.py test <フォルダ>（ビルドした EXE をアプリ役につないで、起動・hello・コマンドへの返事・ 呼んだメソッドの引数が約束どおりか・終了までを確かめます。--deny 権限 で、権限を断られたときの動きも確かめられます）。 test はつなぎ方と形の確認なので、中身の動きは SyncSing Studio の開発者モードで確かめてください。
  6. まとめる — python sdk/tools/syncsing_plugin.py pack <フォルダ> で .ssplugin（署名前の zip）ができます。
  7. 署名を受ける — python sdk/tools/syncsing_plugin.py submit <.ssplugin>。開発者トークンは 設定 → 拡張機能 →「開発者トークンを発行」で出します（--token か環境変数 SYNCSING_DEVELOPER_TOKEN）。公式サイトへの載せ方は --listing none|free|paid（DISTRIBUTION_JA.md）。審査に回ったものは、済んだあとに status <受付番号> <.ssplugin> で署名済みのファイル（…-signed.ssplugin）を受け取ります。 - 標準の権限だけ の拡張機能は「登録済み」の署名がその場で付き、作者が自分で配れます（審査はありません）。 - 注意が必要な権限（要審査） を 1 つでも使う拡張機能は審査に出します。審査には、同梱する EXE・DLL のソースを含む 全ソース と、動作を確かめる手順の提出が必要です。提出物は審査にだけ使い、公開しません。 - 公式サイトに載るのは審査済みの拡張機能だけです。有料で売るときは BOOTH などで作者が自分で販売します（LinkStudio は販売・決済・返金に関わりません）。
  8. 入れる — 利用者は 設定 → 拡張機能 →「拡張機能を入れる（.ssplugin）」。初めてのときは拡張機能の利用規約への同意と、権限の許可を求められます。

守ること（要点。詳しくは開発者規約）

隔離されていても・いなくても、次は 作者が守る約束 です（破ると審査で落ちる・署名を取り消されます）。 隔離の中で動かないときは、まず syncsing_plugin.py test（Windows では隔離して起動します）で確かめてください。

版を上げるとき

uuid はそのまま（uuid コマンドは使わない）。manifest の version を上げて、次の順に進めます。

  1. python sdk/tools/syncsing_plugin.py whoami（トークンの作者 ID が manifest の author.identity_id と同じか）
  2. ビルド
  3. python sdk/tools/syncsing_plugin.py pack <フォルダ>
  4. （要審査の権限を使うとき）全ソースの zip を作る
  5. python sdk/tools/syncsing_plugin.py submit <.ssplugin>（--source・--steps）

同じ名前の拡張機能を別の uuid で出そうとすると、サーバーが duplicate_name で断ります（uuid を発行し直してしまったときの事故を防ぐため）。そのときは manifest の uuid を前の版の uuid に戻してください。本当に別の拡張機能として出すときだけ submit --new-plugin を付けます。

対応するアプリ

開発キットAPISyncSing StudioSyncSing NC Lite
1.01.0拡張機能に対応した版から拡張機能に対応した版から（マイクまわりの権限だけ）
1.11.0同上（CLI に uuid・status、command.invoke・tool.run はすぐ返事をする決まりを PROTOCOL に）同上
1.21.0同上（C#・Python の SDK: イベントを届いた順に処理、Panel(...).Send / client.panel(...).send、押された記録と所要時間を plugin.log に、読み取りスレッドからの Call を例外に）同上
1.31.00.30.0 から（manifest に assistant: アシスタント向けの説明・開く先・画像。書かなければ 0.30.0 より前でも動きます。validate が画像の中身も確かめる）同上（アシスタントは Studio だけ）
1.3.11.0同上（Python の SDK: Windows の名前付きパイプをオーバーラップ（非同期）で開くように。読み取りスレッドが待っている間に hello が送れず固まり、OSError: [Errno 22] になる不具合を修正）同上
1.3.21.0同上（正式な SDK を C# に、Python は参考に（「どの SDK を使うか」）。公式の拡張機能を C# の SDK でつなぐ形に作り直した（配信チェック・チャットエフェクト 0.7.0）。C# の PluginClient.Connect に capabilities を渡せるように。雛形 python-basic: 動作を確かめた版を Python 3.14・PyInstaller 6.22.3 に、build.ps1 は py -3.14 で動かし -PythonVersion で変えられる）同上
1.4.01.1声まわり（API 1.1）: マイクの声（処理後）を受け取る audio.capture・地声を配信に乗せない audio.mic_route・音や VOICEVOX の声を乗せる audio.inject（3 つとも要審査）。音専用のパイプを C# の Audio()・Python の audio() で開く。hello で伝える版を manifest の api_version にした（1.0 の拡張機能は古いアプリでもそのまま動く）。コマンドの hold（押している間だけ）、設定の種類 voicevox_style（VOICEVOX の声を選ぶ）Studio 0.30.5・NC Lite 1.6.5（API 1.1 を使うとき）

開発キット 1.3.2 までは API 1.0。1.4.0 から API 1.1（声まわり）で、audio.* を使う拡張機能は manifest の api_version を "1.1"、min_app_version を 0.30.5 以上・min_nclite_version を 1.6.5 以上にします（使わない拡張機能は "1.0" のままで、古いアプリでも動きます）。1.3 の assistant を書いた拡張機能は、SyncSing Studio 0.30.0 以上（min_app_version を 0.30.0 以上に）・NC Lite 1.6.0 以上（min_nclite_version を 1.6.0 以上に）が要ります。1.0 / 1.1 で作った拡張機能はそのまま動きますが、PanelUpdate を別スレッドから何度も呼んでいるものは 1.2 の Panel(...).Send に替えることをおすすめします。

アプリが対応する API の版は app.info の api_version と、hello の返事の api_version で分かります。

ライセンス

この資料は開発キットに入っているものと同じ内容です。拡張機能の作成・配布には拡張機能 開発者規約が適用されます。