명령 참조

인증된 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는 앱의 라우팅을 가리키며 운영체제 장치 이름이나 숫자 위치가 아닙니다.

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 메시지에서 읽어 표시하세요.