コマンドリファレンス

各コマンドは、認証済みの WebSocket 接続で個別の JSON テキストメッセージとして送信します。最初の state をまだ受信していない場合は、接続ガイドから始めてください。

フィールド名はすべて大文字と小文字を区別します。例の ID を最新の状態の値に置き換えてください。サーバーはアプリと同じ再生規則、ロック、機能へのアクセス権を適用します。結果は後続のスナップショットで確認してください。送信成功は実行の確認応答ではありません。

状態と接続

コマンド	用途
{"type":"request_state"}	ローカルの状態を失った場合などに、完全なスナップショットを再取得します。定期的なポーリングは不要です。
{"type":"ping"}	hello_ok.features に ping が含まれていれば、{"type":"pong"} を受信します。

再生要素を起動する

play_playable

{
  "type": "play_playable",
  "playable_id": "playable-id",
  "action": "start",
  "next_volume": 70,
  "next_pan": 0
}

playable_id は必須で、project.categories[].playables[].id から取得します。再生要素は、音声、動画、画像、命令などのプロジェクト内のボタンです。起動すると、別の実行時 ID を持つプレーヤーが作成される場合があります。

任意フィールド	意味と既定値
action	下表の起動アクション。既定値は start。
next_volume	表示用の整数百分率。0～100、既定値は control.next_sound_volume。
next_pan	パンの百分率。-100（左）～100（右）、既定値は 0（中央）。

アクション	動作
start	設定された再生動作で起動します。
fade_in	フェードインで起動します。
crossfade	アプリのクロスフェード動作で起動します。
replace	アプリの置き換え動作で起動します。
toggle	対応する実行中プレーヤーを停止します。なければ起動します。
toggle_fade	対応する実行中プレーヤーをフェードアウトします。なければ起動します。

動作は再生要素の種類と設定によって異なります。WebSocket の起動コマンドには出力デバイスのフィールドはありません。Sound Show で設定されたルーティングと出力選択を使用します。

全体の再生制御

stop_all と fade_out_all

{ "type": "stop_all" }

{ "type": "fade_out_all", "duration_ms": 1500 }

ロックされていない音声・映像プレーヤーに適用されます。stop_all は正の時間を指定しない限り即座に停止します。fade_out_all は時間を省略するとアプリのフェード動作を使用します。どちらも任意の duration_seconds または duration_ms を受け付けますが、一度に一方の単位だけを送信してください。全体に指定する時間は音声プレーヤーに適用され、映像プレーヤーはアプリの映像フェード動作を使用します。

pause_all と resume_all

{ "type": "pause_all", "fade": false }

{ "type": "resume_all", "fade": false }

ロックされていない音声・映像プレーヤーを一時停止、または一時停止中のプレーヤーを再開します。任意の fade フラグは音声プレーヤーに適用されます。映像プレーヤーは通常の一時停止・再開動作を使用します。

実行中のプレーヤーを操作する

以下のすべての player_id には players[].id を使用します。再生要素の ID はプレーヤー ID の代わりにはなりません。再生終了後やプロジェクト変更後はプレーヤーを再取得してください。

toggle_player_playback

{ "type": "toggle_player_playback", "player_id": "player-id", "fade": false }

一時停止と再開を切り替えます。fade は任意です。

toggle_player_loop

{ "type": "toggle_player_loop", "player_id": "player-id" }

実行中プレーヤーのループ状態を切り替えます。ロックされたプレーヤーはこの操作を無視します。結果の loop_enabled はプレーヤーのスナップショットで確認します。プロジェクトの再生要素の設定は変更しません。

stop_player と fade_out_player

{ "type": "stop_player", "player_id": "player-id" }

{ "type": "fade_out_player", "player_id": "player-id", "duration_seconds": 2 }

どちらも任意の duration_seconds または duration_ms を受け付けます。正の時間を指定した stop_player は即時停止せずフェードアウトします。fade_out_player は時間を省略すると既定のフェードを使います。

seek_player

{ "type": "seek_player", "player_id": "player-id", "position_seconds": 12.5 }

代わりに 0～100 の position_percent も送信できます。位置フィールドは一度に一つだけ送信します。百分率は、開始・終了位置をトリミングしていてもソース全体のタイムラインを基準とします。結果はプレーヤーの再生範囲内に制限されます。長さが不明な場合は、明示的な終了時刻で有限のタイムラインが得られる場合のみシークできます。プレーヤーの状態を参照してください。

set_player_volume

{ "type": "set_player_volume", "player_id": "player-id", "volume": 65 }

volume は 0～100 の表示用百分率で、線形の音声ゲインではありません。表示結果にはスナップショットの volume_percent を使ってください。

set_player_muted

{ "type": "set_player_muted", "player_id": "player-id", "muted": true, "duration_ms": 1000 }

ミュート解除には muted: false を使います。duration_ms を省略するか 0 にすると即座に変更し、正の時間ではミュート・解除をフェードします。上限は 60000 ms です。

共有コントロールと音量レベル

set_next_sound_volume

{ "type": "set_next_sound_volume", "volume": 70 }

今後の起動に使う既定音量を 0～100 の整数に設定します。control.next_sound_volume を更新します。

set_selected_category

{ "type": "set_selected_category", "category_id": "category-id" }

共有のカテゴリー選択を更新します。解除には category_id: null を使います。

set_volume_level_active と toggle_volume_level

{ "type": "set_volume_level_active", "level_id": "speech", "active": true }

{ "type": "toggle_volume_level", "level_id": "speech" }

level_id は control.volume_level_presets[].id から取得します。押している間だけ有効なボタンでは、押下時に active: true、解放時に active: false を同じ接続で送信します。切り替え式のボタンには toggle_volume_level を使います。

押下状態は接続に属し、切断すると解除されます。Sound Show はプリセットの方向とフェードの規則を選択された出力に適用します。control_snapshot は新しい有効ターゲットを即座に通知し、出力音量のスナップショットはフェードの進行を示します。

clear_volume_levels

{ "type": "clear_volume_levels" }

遠隔操作中の音量レベルをすべて解除します。自分の接続だけでなく全体に適用されます。自分の押下状態だけを解除するには、代わりに set_volume_level_active を active: false で送信します。

set_low_volume_active（互換性用）

{ "type": "set_low_volume_active", "active": true }

low プリセットを有効にします。low がなければ最初に設定されたプリセットを使います。新しい連携では明示的な level_id を使用してください。

出力

Sound Show の論理出力を指定するには logical_devices[].id を使います。ID はアプリのルーティングを指し、OS のデバイス名や数値位置ではありません。

select_logical_device

{ "type": "select_logical_device", "logical_device_id": "main" }

set_logical_device_volume

{ "type": "set_logical_device_volume", "logical_device_id": "main", "volume": 80 }

volume は 0～100 の整数の表示用百分率です。操作を提供する前にターゲットの available フラグを確認してください。

音声エフェクト

対応するコントロールと範囲は capabilities.audio_controls から取得します。ディスクリプターが対象のスコープに対応している場合のみ操作を提供してください。

set_audio_control

{
  "type": "set_audio_control",
  "target": { "kind": "logical_device", "id": "main" },
  "control_id": "five_eq.high_mid_gain_db",
  "value": -6,
  "fade_duration_ms": 750,
  "command_id": "eq-change-1"
}

target、control_id、value は必須です。target.kind は logical_device または player で、target.id はそのターゲットの現在の ID です。値はディスクリプターのネイティブ単位による絶対値です。サーバーは範囲と影響するエフェクト設定をまとめて検証します。範囲内の値でも、EQ のクロスオーバーなど他の設定と競合する場合があります。

reset_audio_control

{
  "type": "reset_audio_control",
  "target": { "kind": "player", "id": "player-id" },
  "control_id": "pan",
  "fade_duration_ms": 500,
  "command_id": "pan-reset-1"
}

ディスクリプターの現在の default_value に戻します。

どちらも 0～60000 の任意の fade_duration_ms を受け付け、省略または 0 なら即座に適用します。同じターゲットとコントロールへの新しいコマンドは進行中のフェードを置き換えます。ロックされたプレーヤーは拒否されます。任意の command_id はこれらのコマンドのエラーに含まれますが、成功応答を生成したり、自動再試行を安全にしたりするものではありません。

プロジェクトの照明

set_project_light_level

{
  "type": "set_project_light_level",
  "project_light_id": "project-light-id",
  "value_percent": 72,
  "fade_duration_ms": 1200,
  "command_id": "light-change-1"
}

lights.lights[].id の ID を使います。value_percent は 0～100 の絶対レベルです。fade_duration_ms と command_id は任意で、音声コントロールと同じ範囲およびエラー関連付けの規則に従います。同じ照明への新しい書き込みは進行中のフェードを置き換えます。

先に Sound Show でプロジェクトの照明と QLC+ 接続を設定します。ターゲットは利用可能である必要があり、フェード開始時は現在のレベルも読み取れる必要があります。コマンドは設定された範囲、反転、機能へのアクセス権を尊重します。

命令

trigger_current_instruction_go

{ "type": "trigger_current_instruction_go", "next_volume": 70, "next_pan": 0 }

現在の命令プレーヤーで GO を実行します。任意の next_volume と next_pan の単位と既定値は play_playable と同じです。

set_instruction_next

{ "type": "set_instruction_next", "player_index": 0, "path": [1, 0] }

両フィールドが必須です。player_index は instructions.players 内の 0 始まりの位置です。対象項目のスナップショットから path をコピーします。can_set_next: true でパスが空でない項目に選択操作を提供してください。次の命令だけを変更し、GO の実行や定義の編集は行いません。

プレイリスト

プレイリストと項目のインデックスは、現在の playlists.playlists 配列とプレイリストの queue 内の 0 始まりの位置です。状態変更後は再取得してください。並べ替え後、保存したインデックスが別の項目を指す場合があります。

playlist_play_next

{ "type": "playlist_play_next", "playlist_index": 0, "activate_autoplay": true, "crossfade_all": false }

三つとも任意です。playlist_index を省略すると playlists.current_index を使います。activate_autoplay と crossfade_all の既定値は false です。

playlist_play_item

{ "type": "playlist_play_item", "playlist_index": 0, "item_index": 2, "crossfade_all": false }

両インデックスが必須です。アプリの通常の自動再生、ループ、キュー進行規則で項目を即座に再生します。任意の crossfade_all: true は右クリック動作を要求し、既定値は false です。

set_playlist_autoplay

{ "type": "set_playlist_autoplay", "playlist_index": 0, "autoplay": true, "crossfade_current_sounds": false }

autoplay は必須です。playlist_index を省略すると playlists.current_index を使います。任意の crossfade_current_sounds の既定値は false です。

タイマー

各コマンドには現在のタイマー配列の 0 始まりの timer_index が必要です。

{ "type": "start_timer", "timer_index": 0 }

{ "type": "pause_timer", "timer_index": 0 }

{ "type": "reset_timer", "timer_index": 0 }

Sound Show のタイマー設定を使用します。経過時間、残り時間、実行状態は timers_snapshot メッセージを読んで表示してください。