Referencia de comandos

Envía cada comando como un mensaje de texto JSON independiente por una conexión WebSocket autenticada. Empieza por la guía de conexión si aún no has recibido el primer state.

Todos los nombres de campo distinguen mayúsculas de minúsculas. Sustituye los ID de ejemplo por valores del estado más reciente. El servidor aplica las mismas reglas de reproducción, bloqueos y permisos que la aplicación. Confirma el resultado con las instantáneas posteriores; un envío correcto no confirma que el comando se haya ejecutado.

Estado y conexión

Comando	Finalidad
{"type":"request_state"}	Solicitar una nueva instantánea completa, por ejemplo tras perder el estado local. No hace falta consultar periódicamente.
{"type":"ping"}	Recibir {"type":"pong"} si hello_ok.features incluye ping.

Iniciar un elemento reproducible

play_playable

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

playable_id es obligatorio y procede de project.categories[].playables[].id. Un elemento reproducible es un botón del proyecto, como un sonido, vídeo, imagen o instrucción. Al iniciarlo puede crearse un reproductor con otro ID de ejecución.

Campo opcional	Significado y valor predeterminado
action	Acción de inicio de la tabla siguiente; valor predeterminado: start.
next_volume	Porcentaje entero de visualización, de 0 a 100. Predeterminado: control.next_sound_volume.
next_pan	Panorama en porcentaje de -100 (izquierda) a 100 (derecha). Predeterminado: 0 (centro).

Acción	Comportamiento
start	Iniciar con el comportamiento de reproducción configurado.
fade_in	Iniciar con fundido de entrada.
crossfade	Iniciar con la acción de fundido cruzado de la aplicación.
replace	Iniciar con la acción de sustitución de la aplicación.
toggle	Detener los reproductores activos correspondientes, o iniciar si no hay ninguno activo.
toggle_fade	Atenuar hasta detener los reproductores activos correspondientes, o iniciar si no hay ninguno activo.

El comportamiento depende del tipo y configuración del elemento. El comando WebSocket de inicio no tiene campo de dispositivo de salida; usa el enrutamiento y la selección de salida configurados en Sound Show.

Reproducción global

stop_all y fade_out_all

{ "type": "stop_all" }

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

Afectan a los reproductores de sonido y visuales desbloqueados. stop_all detiene de inmediato salvo que indiques una duración positiva. fade_out_all usa el fundido de la aplicación si no se indica duración. Ambos aceptan duration_seconds o duration_ms opcionales; envía una sola unidad cada vez. Las duraciones globales personalizadas se aplican al sonido; los reproductores visuales usan el fundido visual de la aplicación.

pause_all y resume_all

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

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

Pausar reproductores de sonido y visuales desbloqueados, o reanudar los pausados. La opción fade se aplica al sonido; los visuales usan su comportamiento habitual de pausa y reanudación.

Controlar un reproductor en ejecución

Usa players[].id para cada player_id siguiente. El ID de un elemento no sustituye al de un reproductor. Vuelve a identificarlo tras finalizar la reproducción o cambiar de proyecto.

toggle_player_playback

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

Alternar pausa y reanudación. fade es opcional.

toggle_player_loop

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

Alternar la repetición del reproductor en ejecución. Los bloqueados ignoran esta acción. Lee el loop_enabled resultante en su instantánea. No modifica la configuración del elemento en el proyecto.

stop_player y fade_out_player

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

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

Ambos aceptan duration_seconds o duration_ms opcionales. Con una duración positiva, stop_player atenúa hasta detener en vez de detener inmediatamente. fade_out_player usa el fundido predeterminado si no se indica duración.

seek_player

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

También puedes enviar position_percent de 0 a 100. Envía un solo campo de posición cada vez. Los porcentajes se refieren a la línea temporal completa del origen, incluso si el elemento tiene inicio y fin recortados. El resultado se limita a la ventana de reproducción. Una duración desconocida solo permite saltar si un tiempo de fin explícito proporciona una línea temporal finita. Consulta el estado del reproductor.

set_player_volume

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

volume es un porcentaje de visualización de 0 a 100, no una ganancia de audio lineal. Lee volume_percent en las instantáneas para obtener el resultado mostrado.

set_player_muted

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

Usa muted: false para restaurar el sonido. Omite duration_ms o usa 0 para un cambio inmediato; una duración positiva aplica un fundido al silenciar o restaurar. El máximo es 60000 ms.

Controles compartidos y niveles de volumen

set_next_sound_volume

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

Establecer el volumen predeterminado de los próximos inicios como entero de 0 a 100. Actualiza control.next_sound_volume.

set_selected_category

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

Actualizar la selección de categoría compartida. Usa category_id: null para borrarla.

set_volume_level_active y toggle_volume_level

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

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

Obtén level_id de control.volume_level_presets[].id. Para un botón que se mantiene pulsado, envía active: true al pulsar y active: false al soltar por la misma conexión. Usa toggle_volume_level para un botón de alternancia.

La pulsación pertenece a la conexión y se libera al desconectarse. Sound Show aplica las reglas de dirección y fundido del preajuste a su salida seleccionada. control_snapshot comunica inmediatamente el nuevo objetivo activo; las instantáneas de volumen de salida muestran el progreso del fundido.

clear_volume_levels

{ "type": "clear_volume_levels" }

Liberar todos los niveles de volumen controlados a distancia. Es un borrado global, no solo de la pulsación de tu conexión. Para liberar únicamente la tuya, envía set_volume_level_active con active: false.

set_low_volume_active (compatibilidad)

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

Activar el preajuste low, o el primero configurado si low no existe. Las nuevas integraciones deben usar un level_id explícito.

Salidas

Usa logical_devices[].id para indicar una salida lógica de Sound Show. Los ID corresponden al enrutamiento de la aplicación, no a nombres de dispositivos del sistema operativo ni a posiciones 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 es un porcentaje entero de visualización de 0 a 100. Comprueba available en el objetivo antes de ofrecer controles.

Efectos de audio

Descubre los controles compatibles y sus rangos en capabilities.audio_controls. Ofrece un control solo si su descriptor admite el ámbito del objetivo.

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 y value son obligatorios. target.kind es logical_device o player, y target.id es el ID actual de ese objetivo. Los valores son absolutos, en las unidades nativas del descriptor. El servidor valida conjuntamente el rango y la configuración del efecto; un valor dentro del rango puede entrar en conflicto con otro ajuste, como las frecuencias de cruce del ecualizador.

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

Restablecer el default_value actual del descriptor.

Ambos comandos aceptan fade_duration_ms opcional de 0 a 60000; omitirlo o usar 0 aplica inmediatamente. Un comando más reciente para el mismo objetivo y control sustituye el fundido activo. Los reproductores bloqueados se rechazan. El command_id opcional se devuelve en los errores de estos comandos; no genera una respuesta de éxito ni hace seguras las repeticiones automáticas.

Luces del proyecto

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

Usa un ID de lights.lights[].id. value_percent es un nivel absoluto de 0 a 100. fade_duration_ms y command_id son opcionales, con los mismos límites y correlación de errores que los controles de audio. Una nueva escritura en la misma luz sustituye su fundido activo.

Configura primero la luz del proyecto y su conexión QLC+ en Sound Show. El objetivo debe estar disponible; iniciar un fundido también requiere poder leer el nivel actual. El comando respeta el rango, la inversión y los permisos configurados para la luz.

Instrucciones

trigger_current_instruction_go

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

Activar GO en el reproductor de instrucciones actual. Los campos opcionales next_volume y next_pan tienen las mismas unidades y valores predeterminados que en play_playable.

set_instruction_next

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

Ambos campos son obligatorios. player_index es una posición desde cero en instructions.players. Copia path de la instantánea del elemento deseado; ofrece selección si tiene can_set_next: true y una ruta no vacía. Cambia la próxima instrucción sin activar GO ni editar su definición.

Listas de reproducción

Los índices de lista y elemento son posiciones desde cero en el array actual playlists.playlists y en la queue de la lista. Vuelve a obtenerlos tras cambios de estado; un índice guardado puede apuntar a otro elemento después de reordenar.

playlist_play_next

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

Los tres campos son opcionales. Omitir playlist_index usa playlists.current_index; activate_autoplay y crossfade_all tienen false como valor predeterminado.

playlist_play_item

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

Ambos índices son obligatorios. Reproducir ahora el elemento con las reglas normales de reproducción automática, repetición y avance de cola de la aplicación. El crossfade_all: true opcional solicita el comportamiento de clic derecho; su valor predeterminado es false.

set_playlist_autoplay

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

autoplay es obligatorio. Omitir playlist_index usa playlists.current_index. El crossfade_current_sounds opcional tiene false como valor predeterminado.

Temporizadores

Cada comando requiere un timer_index desde cero del array actual de temporizadores.

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

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

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

Usan la configuración del temporizador en Sound Show. Lee mensajes timers_snapshot para mostrar tiempo transcurrido, restante y estado de ejecución.