Developers
拡張機能 API 1.1 リファレンス
SyncSing Studio / SyncSing NC Lite の拡張機能（プラグイン）が呼べる窓口の一覧です。 全メソッド・イベントを 1 行ずつ並べた表と権限ごとの表は API_LIST_JA.md、機械で読める版は ../schemas/api-1.1.json（どちらもアプリのコードから生成）、メッセージの形は PROTOCOL_JA.md、権限は PERMISSIONS_JA.md を見てください。
- 表の「権限」は manifest の
permissions に書き、利用者が許可したときだけ呼べます。★ は注意が必要な権限（要審査）です。 - 「Lite」に ○ があるものは NC Lite でも使えます（NC Lite で使えないものは
not_available）。 - 必須の引数 は
API_LIST_JA.md の表で * が付いたものです（例: tts.speak の text*）。型・範囲まで含めた正確な定義は ../schemas/api-1.1.json の各メソッドの params（JSON Schema。required が必須）です。 - それ以外の引数は省略でき、省略した項目は変えません（設定を変えるメソッドは、変える項目を 1 つ以上書きます）。
- 知らない引数・必須の引数が無い・型が違う、は窓口が
invalid_params で断ります（data.field に場所）。範囲外も丸めずに断ります。 - 戻り値の形は
api-1.1.json の result です（SDK では C# の 〇〇Result クラス・Python の 〇〇Result TypedDict）。項目は版を上げても 増えることはあっても減りません（知らない項目は無視してください）。 - アプリの画面で禁止されていること（処理中のデバイス変更・キー変更ロック・完成Mix の規約未同意・録音中の録音設定など）は、拡張機能からも同じ理由で断られます（
busy / locked）。 - 戻り値に、トークン・ファイルのパス・視聴者やチャンネルの ID は入りません。
1. 接続・自分のこと（権限なし）
| メソッド | Lite | 引数 | 戻り値・説明 |
|---|
hello | ○ | token・plugin {uuid, version}・api {version}・sdk {name, version}・capabilities | 最初の 1 通（PROTOCOL §2）。granted・denied・settings・dirs・limits |
ping | ○ | — | {}。ホストからも 15 秒ごとに来ます（必ず返事をする） |
api.capabilities | ○ | — | このアプリで呼べるメソッド・イベントの一覧（review: 要審査か） |
app.info | ○ | — | kind（studio / nclite）・version・channel・locale・features・api_version |
events.subscribe | ○ | events: [名前…]・meters {interval_ms: 50〜5000} | subscribed・denied（権限の無いイベント）・seq |
events.unsubscribe | ○ | events: [名前…] | subscribed |
settings.get | ○ | — | settings（manifest で宣言した項目だけ） |
settings.set | ○ | settings: {key: 値} | settings・changed。宣言の型・範囲で確かめて保存 |
panel.update | ○ | panel（contributes.panels の id）・blocks: [...]（40 個まで） | {}。部品は text・status（level: info/ok/warn/error）・kv（items: [[名前, 値]]）・progress（value 0〜1）・timer（text・elapsed_s（送った時点の経過秒）・total_s（省略可。あれば「経過 / 全体」と進み具合の棒）・running（false なら止まったまま）。画面が 1 秒ごとに自分で数字を進めるので、経過時間・残り時間はこれで出す。kv や progress に秒数を入れて送り続けると、画面の取り直しが 2 秒ごとのため飛び飛びに見える）・button（command）・table（header・rows 10 行）・setting（key）・settings（group。その見出しの設定をまとめて出す。省くと全部を見出しごとに折りたたんで出す）・url（text・url・open。この PC の中の http://localhost:ポート/… か http://127.0.0.1:ポート/… だけ。「コピー」ボタンと、open が true なら「開く」ボタンが出て、アプリが既定のブラウザで開きます） |
log.write | ○ | level（debug/info/warn/error）・message（4 KiB） | 返事の要らない通知として送れます。logs\plugin.log に書きます |
2. 通知・提案（notify）
| メソッド | Lite | 引数 | 戻り値・説明 |
|---|
notify.show | ○ | level（info/warn）・title（40 字）・body（200 字） | notification_id。5 秒に 1 件まで。画面には必ず拡張機能の名前が付きます。リンク・HTML は不可 |
notify.propose | ○ | title（80 字）・summary（400 字）・items: [{label, current, proposed, reason}]（20 件） | proposal_id。利用者が「わかった」「却下」を押すとイベント proposal.result（approved / declined） |
notify.dismiss | ○ | proposal_id か notification_id | dismissed。自分が出したものだけ取り下げられます |
3. 読む（state.read・meters.read・chat.read）
| メソッド | Lite | 権限 | 説明 |
|---|
state.get | ○ | state.read | 抜粋の状態: processing（running・strength・denoise・latency_mode・input・recording…）・player（title・video_id・playing・position_s・duration_s・pitch・mixback）・lyrics・broadcast・features・language |
devices.list | ○ | state.read | inputs・monitors・references（機器の名前） |
meters.get | ○ | meters.read | meters {名前: {peak_dbfs, clip}}・running・recording |
effects.get | | state.read | effects（今の設定）・presets・customs・favorites・current_name・last_name |
effects.simple.get | | state.read | エフェクトの「簡単」ダイヤルの状態 |
editfx.get | | state.read | video_id → enabled・templates・template・favorites・player |
bgm.get | | state.read | enabled・volume・auto_duck・duck_level・monitor・state・曲番号（ファイルの場所は出しません） |
entry.get | | state.read | accepting・slots・playing・waiting・active・queue（表示名・状態だけ。視聴者 ID は出しません） |
tts.get | | state.read | 読み上げの enabled・method・歌唱中/発話中の待ち・queued |
dictionary.get | | state.read | 読み方辞書の項目（own: この拡張機能が足したもの） |
dictionary.preview | | state.read | text → 辞書を当てた結果（保存しない） |
mic.chain.get | ○ | state.read | マイク音質の enabled・preset・input_gain_db・presets |
mic.presets.list | ○ | state.read | presets・selected |
mic.simple.get | ○ | state.read | マイク音質の「簡単」ダイヤルの状態 |
lyrics.get | | state.read | track・artist・visible |
chat.history | | chat.read | since（seq）・limit（1〜200）→ items・last_seq。中身はイベント chat.message と同じ形 |
チャットへの投稿 ★（chat.write）
| メソッド | 権限 | 引数・説明 |
|---|
chat.post ★ | chat.write | text（空白をまとめて 200 字まで）・platform（auto＝利用者が連携タブで選んだ配信先。両方なら両方／youtube／twitch）。戻り値 posted（投稿を受け付けた配信先）・failed（[{platform, reason}]）・text。1 つの拡張機能から 10 秒に 1 件まで |
- 投稿するアカウント（配信者本人か Bot）・YouTube で URL を外すかどうかは、利用者の連携タブの設定に従います（拡張機能からは選べません）。
- アプリの画面からの投稿と同じ決まりを通ります: アプリ全体で 60 秒に 30 件まで（
rate_limited）、同じ文を 60 秒以内にもう一度は不可（busy・data.reason: duplicate）。 - 投稿先が選ばれていない・投稿するアカウントが設定されていない・配信につながっていないときは
not_available。 - 拡張機能が投稿したコメントは、受信したときに
chat.message の is_own: true になります（自分の投稿に反応して投稿し続けないようにしてください）。
4. マイク・処理・録音
| メソッド | Lite | 権限 | 引数・説明 |
|---|
mic.set | ○ | mic.control | strength（0〜5）・denoise・voice_tone_db（0〜12）・monitor・latency_mode（normal/low）・lean_buffer・loudness_guard。処理中の strength 変更は busy。遅延モードの変更は処理を読み直します（restarted）。NC Lite は strength だけ |
mic.chain.set | ○ | mic.control | enabled・preset（mic.presets.list の id）・input_gain_db（-24〜24） |
mic.presets.select | ○ | mic.control | preset |
mic.simple.set | ○ | mic.control | dials {名前: 数値}・on {名前: bool}・auto [名前…] |
audio.set_output_gain ★ | | audio.output | gain（10〜400 %）。仮想マイクの出力音量 |
processing.start・processing.stop・processing.toggle ★ | ○ | processing.control | 処理（ノイズ除去）の開始・停止。開始は最大 60 秒かかります。戻り値 running |
recording.start・recording.stop・recording.toggle | | recording.control | 録音。処理が止まっていると busy。戻り値 recording |
recording.set | | recording.control | target_dbfs（-60〜0）・ceiling_db（"off" / -1 / -0.5）・export_stems。録音中は busy |
5. エフェクト・Edit FX
| メソッド | 権限 | 引数・説明 |
|---|
effects.set | effects.control | effects {項目: 値}（effects.get の項目名だけ）。今の設定に重ねて反映 |
effects.load_preset | effects.control | preset（presets の id か custom:<id>） |
effects.set_favorites | effects.control | order（今のお気に入り id の並べ替え）・cycle {id: bool}。足す・消すはできません |
effects.add_favorite | effects.control | name。今の設定をお気に入りに足す |
effects.toggle_current・effects.next_favorite | effects.control | ミニUI・Stream Deck の短押し／長押しと同じ |
effects.simple.set | effects.control | dials・on |
editfx.enable | editfx.manage | enabled |
editfx.save | editfx.manage | template {video_id or url, events, title, song, duration}・overwrite。同じ曲のテンプレートがあると overwrite: true が無いかぎり busy |
editfx.delete・editfx.preview | editfx.manage | video_id（preview は on） |
6. プレイヤー・BGM・歌詞・エントリー
| メソッド | 権限 | 引数・説明 |
|---|
player.play・player.pause ★ | player.control | 内蔵 YouTube |
player.seek ★ | player.control | seconds |
player.set ★ | player.control | youtube_gain・backing_gain（0〜200 %）・mixback（完成Mix の規約に未同意なら locked）・pitch_semitones（-6〜6。キー変更ロック中は locked）・pitch_enabled・pitch_buffer_ms（120/260/450）・sync_trim_ms（±300） |
bgm.set | bgm.control | enabled・volume（0〜150）・auto_duck・duck_level（0〜60）・monitor。曲・フォルダ・外部アプリの選択は変えられません |
bgm.next・bgm.toggle | bgm.control | 次の曲・ON/OFF |
lyrics.search | lyrics.control | track・artist・album → tracks（LRCLIB） |
lyrics.select | lyrics.control | track（search の 1 件）。歌詞の画面が開きます |
lyrics.load_text | lyrics.control | lyrics（64 KiB）・title・artist・duration |
lyrics.set_offset | lyrics.control | seconds（±600）・video_id（省略で今の曲） |
lyrics.toggle | lyrics.control | OBS の歌詞表示 ON/OFF |
entry.action | entry.control | action: accept_toggle・confirm・skip |
7. 読み上げ・辞書
| メソッド | 権限 | 引数・説明 |
|---|
tts.speak ★ | tts.speak | text（300 字）・priority（normal/low）・interrupt_own。3 秒に 1 件まで。歌唱中・発話中の待ちなど本人の設定に従います。戻り値 utterance_id |
tts.stop ★ | tts.speak | utterance_id（省略で自分が入れた全部）。ほかの読み上げは止められません |
tts.reader.toggle・tts.reader.stop_all ★ | tts.control | 読み上げの ON/OFF・全停止 |
dictionary.set_entry | dictionary.write | source・replacement・match_type（contains/exact/prefix）・priority・enabled・entry_id（変えるのは自分が足した項目だけ）。1 つの拡張機能で 200 件まで |
dictionary.remove_entry | dictionary.write | entry_id（自分が足した項目だけ） |
8. 配信画面（統合配信UI）★
| メソッド | 権限 | 引数・説明 |
|---|
overlay.set_items ★ | overlay.draw | overlay（contributes.overlays の id）・title・items: [{type: text, text, label, emphasis} / {type: number, label, value, unit, digits} / {type: progress, label, value 0〜1, text}]（20 個）。1 秒に 10 回まで。HTML・URL・画像は受け取りません。戻り値 layer（表示の ID）。統合配信UI の「＋」に「🧩 拡張機能の名前」として出ます（kind: items の overlay） |
overlay.set_page ★ | overlay.draw | overlay（kind: page の overlay の id）・url（この PC の中の http://127.0.0.1:ポート/… か http://localhost:ポート/…）・title。拡張機能が自分で配るページ（透過の HTML）を、統合配信UI のウィジェットの枠いっぱいに埋め込みます。戻り値 layer |
overlay.clear ★ | overlay.draw | overlay（省略で全部） |
9. OBS（SyncSing 経由。接続情報・ストリームキーは渡しません）
| メソッド | 権限 | 引数・説明 |
|---|
obs.status | obs.read | connected・streaming・recording・obs_version |
obs.request | obs.read | requestType・requestData。読めるのは GetVersion・GetStats・GetStreamStatus・GetRecordStatus・GetVideoSettings・GetSceneList・GetCurrentProgramScene・GetSceneItemList・GetInputList・GetInputKindList・GetOutputList・GetOutputStatus・GetProfileList・GetSceneCollectionList・GetProfileParameter（Output / Video / AdvOut / SimpleOutput の、エンコード・解像度・fps などの設定だけ。録画の保存先・URL などは読めません。読めない項目を指定すると permission_denied で、data.allowed に読める名前の一覧が入ります） |
obs.propose_changes ★ | obs.write | title・note・changes: [{type: video, label, output_width, output_height, fps_numerator, fps_denominator} / {type: profile, label, category, name, value}]（20 件）。提案するだけ で、利用者が画面で「OBS に適用」を押したときにアプリが送ります（配信中・録画中は不可・適用前の設定を保存して「元に戻す」可）。結果はイベント proposal.result（applied・partial・failed・declined・reverted、snapshot_id） |
obs.snapshots ★ | obs.write | 適用前に保存した設定の一覧（id・title・ts・labels） |
変えられる profile の項目: Output/Mode・SimpleOutput の VBitrate・ABitrate・StreamEncoder・Preset・NVENCPreset2・AMDPreset・QSVPreset・EnforceBitrate・AdvOut の Encoder・Rescale・RescaleRes・TrackIndex・Video の FPSType・FPSCommon・FPSInt・OutputCX・OutputCY・ScaleType。
10. 負荷テスト・計測 ★
| メソッド | 権限 | 引数・説明 |
|---|
loadtest.begin ★ | loadtest.run | max_duration_s（10〜1800）・mode（stress / measure）・profile。配信中・配信に接続中・SyncSing の録音中・処理が止まっているときは busy（OBS のローカル録画中は可）。1 秒ごとにイベント loadtest.sample |
loadtest.end ★ | loadtest.run | 集計（dropouts_total・max_processing_ms・over_budget_seconds・OBS の描画落ち・エンコード落ち） |
loadtest.status ★ | loadtest.run | active・elapsed_s・remaining_s |
10-2. 声まわり ★（API 1.1・Studio 0.30.5 / NC Lite 1.6.5 から）
マイクの声を受け取り、配信に乗せる声を置き換えるための窓口です。3 つの権限（audio.capture・audio.mic_route・audio.inject）はどれも要審査で、manifest の api_version を "1.1" にします。同時に使えるのは 1 つの拡張機能だけです（2 つ目は busy）。
- 受け取れるのはノイズ除去 → ゲート → 声の補正の後、エフェクトの前の声だけです。 処理前の音（周りの音）は渡しません。マイクの処理が止まっている間は届きません。
- 地声を消している間に拡張機能が止まる・落ちる・応答しなくなる・権限を取り消される・処理が止まる・利用者が「地声に戻す」を押す と、アプリが必ず元に戻します（拡張機能の協力は要りません）。戻したらイベント
audio.released が届きます。 - アプリのミュート・広告のミュート・音量の上限は拡張機能より後ろで掛かるので、拡張機能から外すことはできません。
- 音は命令用のパイプとは別の 音専用のパイプ で流します（形は PROTOCOL_JA.md §8）。SDK の
client.audio()（Python）/ client.Audio()（C#）が開きます。
| メソッド | Lite | 権限 | 引数・説明 |
|---|
audio.open ★ | ○ | 3 つのどれか | 音専用のパイプを開く。戻り値 pipe・frame_ms（20）・header_bytes（16）・format（s16le-mono）・rates |
audio.close ★ | ○ | — | 声の窓口をすべて閉じ、元に戻す |
audio.stats ★ | ○ | — | listening・replacing・injecting・capture_dropped_hops・inject_dropped_ms・inject_buffered_ms・send_dropped・voicevox_pending |
audio.capture.start ★ | ○ | audio.capture | rate（16000 / 24000 / 48000。既定 16000）。マイクの声が 20 ms ごとに音のパイプに届く。受け取りが遅いと古い分から捨てます |
audio.capture.stop ★ | ○ | audio.capture | 受け取りをやめる |
audio.mic_route.set ★ | ○ | audio.mic_route | to_mix（false でマイクの声を配信・録音・仮想マイクに乗せない。10 ms でなめらかに切り替え）・monitor_original（自分の耳には元の声を返す。既定は配信と同じ音） |
audio.inject.open ★ | ○ | audio.inject | rate（既定 24000）。音のパイプに書いた音を、マイクの処理の後・エフェクトの前に足す（エフェクト・ミュート・音量の上限が掛かる）。貯めは 2 秒まで |
audio.inject.cancel ★ | ○ | audio.inject | id（audio.inject.voicevox の id）。省略で作りかけの文と貯まっている音をすべて捨てる |
audio.inject.voicevox ★ | ○ | audio.inject | text（200 字）・style_id・speed（0.5〜2）・pitch（−0.15〜0.15）・intonation・volume。アプリの VOICEVOX 内蔵音声で少しずつ作り、そのまま配信に乗せる（音は拡張機能に戻りません）。作りかけは 5 件まで。終わると audio.voicevox.done。使ったキャラクターは配信のクレジットに自動で足されます |
audio.voicevox.voices ★ | ○ | audio.inject | 使える声とスタイル（installed）・streaming（少しずつ作れる VOICEVOX Core か） |
audio.inject.voicevox の声は、利用者がアプリで入れた（ダウンロードした）声だけ使えます。入っていない声は not_available。- 置き換え中に音が 3 秒届かないと、アプリの画面に知らせ、
audio.silent が届きます（配信は無音のまま。急に地声が出ないように）。
11. イベント（ホスト → 拡張機能）
| イベント | Lite | 権限 | 中身 |
|---|
meters | ○ | meters.read | meters.get と同じ。interval_ms ごと（最新だけ） |
state.changed | ○ | state.read | changed（変わった区分）・state（その区分） |
processing.changed | ○ | state.read | running |
player.changed | | state.read | state.get の player |
effects.changed | | state.read | enabled・preset・selected |
entry.changed | | state.read | accepting・playing・waiting・slots |
broadcast.changed | | state.read | platform・session_live・broadcast_live・obs_streaming・obs_connected |
chat.message | | chat.read | seq・platform・kind（chat / membership / membership_gift / redemption / follow）・user {hash, name}・text・translation・superchat {type, amount_text, amount, currency}・meta・reward_title・is_owner・is_moderator・is_member・is_own・deleted（user.hash は元に戻せない形。起動前のコメントは chat.history で） |
obs.changed | | obs.read | obs.status と同じ |
loadtest.sample・loadtest.ended | | loadtest.run | 1 秒ごとの計測値・終わったときの集計 |
proposal.result | ○ | notify | proposal_id・result・message・snapshot_id |
settings.changed | ○ | — | 利用者が設定画面で変えた（要求として届くので返事をする） |
events.dropped | ○ | — | 読まなかったので捨てた件数 |
audio.released | ○ | — | 声の窓口が元に戻された。reason（stopped / closed / revoked / processing_stopped / user）・was_replacing（API 1.1） |
audio.silent | ○ | — | 置き換え中なのに音が届いていない。seconds（API 1.1） |
audio.voicevox.done | ○ | — | id・ok・message・first_audio_ms（最初の音までのミリ秒）（API 1.1） |
ホストからの要求（返事が要る）: ping・plugin.activate・plugin.shutdown（5 秒以内に終了）・command.invoke（command・source: panel / deck / mini / shortcut・pressed: short / long、manifest の hold: true のコマンドは down / up も）・tool.run・settings.changed。
12. API 1.1 に無いもの
lyrics.line（歌詞の行が進んだ）・notify.action（通知のボタン）・クラウドの保存領域は、あとの版で考えます。- 認証・鍵・更新・権利判定・規約・視聴者の除外など、アプリの画面だけで行う操作は提供しません（
method_not_found）。
SyncSing Studio