Referência de comandos

Envie cada comando como uma mensagem de texto JSON separada numa ligação WebSocket autenticada. Consulte o guia de ligação se ainda não recebeu o primeiro state.

Todos os nomes de campos distinguem maiúsculas de minúsculas. Substitua os IDs dos exemplos pelos valores do estado mais recente. O servidor aplica as mesmas regras de reprodução, bloqueios e permissões da aplicação. Confirme o resultado nos instantâneos seguintes; o envio bem-sucedido não confirma a execução do comando.

Estado e ligação

Comando	Objetivo
{"type":"request_state"}	Pedir um novo instantâneo completo, por exemplo após perder o estado local. Não é necessário consultar periodicamente.
{"type":"ping"}	Receber {"type":"pong"} se hello_ok.features incluir ping.

Iniciar um elemento reproduzível

play_playable

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

playable_id é obrigatório e vem de project.categories[].playables[].id. Um elemento reproduzível é um botão do projeto, como um som, vídeo, imagem ou instrução. Ao iniciá-lo, pode ser criado um leitor com outro ID de execução.

Campo opcional	Significado e predefinição
action	Ação de início indicada abaixo; predefinição: start.
next_volume	Percentagem inteira de apresentação, de 0 a 100. Predefinição: control.next_sound_volume.
next_pan	Panorâmica em percentagem, de -100 (esquerda) a 100 (direita). Predefinição: 0 (centro).

Ação	Comportamento
start	Iniciar com o comportamento de reprodução configurado.
fade_in	Iniciar com entrada gradual.
crossfade	Iniciar com a ação de transição cruzada da aplicação.
replace	Iniciar com a ação de substituição da aplicação.
toggle	Parar os leitores ativos correspondentes, ou iniciar se não houver nenhum ativo.
toggle_fade	Atenuar até parar os leitores ativos correspondentes, ou iniciar se não houver nenhum ativo.

O comportamento depende do tipo e da configuração do elemento. O comando WebSocket de início não tem campo de dispositivo de saída; use o encaminhamento e a seleção de saída configurados no Sound Show.

Reprodução global

stop_all e fade_out_all

{ "type": "stop_all" }

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

Afetam os leitores de som e visuais desbloqueados. stop_all para imediatamente, exceto se indicar uma duração positiva. fade_out_all usa a transição da aplicação quando não é indicada uma duração. Ambos aceitam duration_seconds ou duration_ms opcionais; envie apenas uma unidade de cada vez. Durações globais personalizadas aplicam-se aos leitores de som; os visuais usam a transição visual da aplicação.

pause_all e resume_all

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

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

Pausar leitores de som e visuais desbloqueados ou retomar os pausados. A opção fade aplica-se aos leitores de som; os visuais usam o comportamento normal de pausa e retoma.

Controlar um leitor em execução

Use players[].id em cada player_id abaixo. Um ID de elemento não substitui um ID de leitor. Identifique novamente o leitor após terminar a reprodução ou mudar de projeto.

toggle_player_playback

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

Alternar entre pausa e retoma. fade é opcional.

toggle_player_loop

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

Alternar a repetição do leitor em execução. Os leitores bloqueados ignoram esta ação. Leia o loop_enabled resultante no instantâneo do leitor. Isto não altera a configuração do elemento no projeto.

stop_player e fade_out_player

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

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

Ambos aceitam duration_seconds ou duration_ms opcionais. Com duração positiva, stop_player atenua até parar em vez de parar imediatamente. fade_out_player usa a transição predefinida quando não é indicada duração.

seek_player

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

Em alternativa, envie position_percent de 0 a 100. Envie um único campo de posição de cada vez. As percentagens referem-se à linha temporal completa da origem, mesmo que o elemento tenha início e fim recortados. O resultado fica limitado à janela de reprodução. Uma duração desconhecida só permite procurar uma posição se um fim explícito fornecer uma linha temporal finita. Consulte o estado do leitor.

set_player_volume

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

volume é uma percentagem de apresentação de 0 a 100, não um ganho de áudio linear. Leia volume_percent nos instantâneos para obter o resultado apresentado.

set_player_muted

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

Use muted: false para repor o som. Omita duration_ms ou use 0 para alterar imediatamente; uma duração positiva silencia ou repõe o som gradualmente. O máximo é 60000 ms.

Controlos partilhados e níveis de volume

set_next_sound_volume

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

Definir o volume predefinido dos próximos inícios para um inteiro de 0 a 100. Isto atualiza control.next_sound_volume.

set_selected_category

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

Atualizar a seleção de categoria partilhada. Use category_id: null para a limpar.

set_volume_level_active e toggle_volume_level

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

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

Obtenha level_id em control.volume_level_presets[].id. Para um botão de pressão contínua, envie active: true ao premir e active: false ao soltar pela mesma ligação. Use toggle_volume_level para um botão de alternância.

A pressão contínua pertence à ligação e termina quando esta se desliga. O Sound Show aplica as regras de direção e transição da predefinição à saída selecionada. control_snapshot comunica imediatamente o novo alvo ativo; os instantâneos de volume da saída mostram o progresso da transição.

clear_volume_levels

{ "type": "clear_volume_levels" }

Libertar todos os níveis de volume controlados remotamente. A limpeza é global, não apenas da pressão associada à sua ligação. Para libertar apenas a sua, envie antes set_volume_level_active com active: false.

set_low_volume_active (compatibilidade)

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

Ativar a predefinição low, ou a primeira configurada se low não existir. Novas integrações devem usar um level_id explícito.

Saídas

Use logical_devices[].id para indicar uma saída lógica do Sound Show. Os IDs referem-se ao encaminhamento da aplicação, não aos nomes dos dispositivos do sistema operativo nem a posições numéricas.

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 é uma percentagem inteira de apresentação de 0 a 100. Verifique a opção available do alvo antes de disponibilizar controlos.

Efeitos de áudio

Descubra os controlos suportados e os intervalos em capabilities.audio_controls. Disponibilize um controlo apenas se o descritor suportar o âmbito do alvo.

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 e value são obrigatórios. target.kind é logical_device ou player, e target.id é o ID atual desse alvo. Os valores são absolutos, nas unidades nativas do descritor. O servidor valida em conjunto o intervalo e as definições do efeito; um valor dentro do intervalo pode ainda entrar em conflito com outra definição, como as frequências de separação do equalizador.

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"
}

Repor o default_value atual do descritor.

Ambos os comandos aceitam fade_duration_ms opcional de 0 a 60000; a omissão ou 0 aplica imediatamente. Um comando mais recente para o mesmo alvo e controlo substitui a transição ativa. Os leitores bloqueados são rejeitados. O command_id opcional é devolvido nos erros destes comandos; não cria uma resposta de sucesso nem torna seguras as repetições automáticas.

Luzes do projeto

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"
}

Use um ID de lights.lights[].id. value_percent é um nível absoluto de 0 a 100. fade_duration_ms e command_id são opcionais, com os mesmos limites e correlação de erros dos controlos de áudio. Uma nova escrita na mesma luz substitui a transição ativa.

Configure primeiro a luz e a ligação QLC+ no Sound Show. O alvo tem de estar disponível; iniciar uma transição também exige que o nível atual possa ser lido. O comando respeita o intervalo, a inversão e o acesso às funcionalidades configurados.

Instruções

trigger_current_instruction_go

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

Acionar GO no leitor de instruções atual. Os campos opcionais next_volume e next_pan têm as mesmas unidades e predefinições de play_playable.

set_instruction_next

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

Ambos os campos são obrigatórios. player_index é uma posição a partir de zero em instructions.players. Copie path do instantâneo do elemento pretendido; permita selecionar elementos com can_set_next: true e caminho não vazio. Isto altera a próxima instrução sem acionar GO nem editar a definição.

Listas de reprodução

Os índices de lista e elemento são posições a partir de zero no array atual playlists.playlists e na queue da lista. Volte a obtê-los após mudanças de estado; um índice guardado pode apontar para outro elemento após reordenação.

playlist_play_next

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

Os três campos são opcionais. Omitir playlist_index usa playlists.current_index; activate_autoplay e crossfade_all têm false como predefinição.

playlist_play_item

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

Ambos os índices são obrigatórios. Reproduzir o elemento agora com as regras normais de reprodução automática, repetição e avanço da fila da aplicação. O crossfade_all: true opcional pede o comportamento de clique direito; a predefinição é false.

set_playlist_autoplay

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

autoplay é obrigatório. Omitir playlist_index usa playlists.current_index. O crossfade_current_sounds opcional tem false como predefinição.

Temporizadores

Cada comando exige um timer_index a partir de zero do array atual de temporizadores.

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

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

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

Usam a configuração do temporizador no Sound Show. Leia mensagens timers_snapshot para apresentar tempo decorrido, tempo restante e estado de execução.