命令参考

通过已认证的 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" }

从 control.volume_level_presets[].id 获取 level_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。

输出

使用 logical_devices[].id 指定 Sound Show 的逻辑输出。ID 指向应用的路由，并非操作系统设备名称或数字位置。

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 中从零开始的位置。从所需项的快照复制 path；只有 can_set_next: true 且路径非空的项才应提供选择功能。这只更改下一条指令，不会触发 GO 或编辑定义。

播放列表

播放列表和项目索引是当前 playlists.playlists 数组及列表 queue 中从零开始的位置。状态变化后请重新获取；重新排序后，保存的索引可能指向另一个项目。

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。

计时器

每条命令都需要当前计时器数组中从零开始的 timer_index。

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

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

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

这些命令使用 Sound Show 中的计时器配置。读取 timers_snapshot 消息以显示已用时间、剩余时间和运行状态。