Référence des commandes

Envoyez chaque commande dans un message texte JSON distinct sur une connexion WebSocket authentifiée. Consultez le guide de connexion si vous n’avez pas encore reçu votre premier state.

Les noms de champs sont sensibles à la casse. Remplacez les identifiants d’exemple par ceux du dernier état. Le serveur applique les règles de lecture, les verrouillages et les droits de l’application. Confirmez le résultat avec les instantanés suivants : un envoi réussi ne confirme pas l’exécution.

État et connexion

Commande	Rôle
{"type":"request_state"}	Demander un nouvel instantané complet, notamment après une perte d’état local. Une interrogation périodique est inutile.
{"type":"ping"}	Recevoir {"type":"pong"} si hello_ok.features contient ping.

Déclencher un élément

play_playable

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

playable_id est obligatoire et provient de project.categories[].playables[].id. Un élément est un bouton du projet : son, vidéo, image ou instruction, par exemple. Son déclenchement peut créer un lecteur avec un autre identifiant d’exécution.

Champ facultatif	Sens et valeur par défaut
action	Action ci-dessous ; start par défaut.
next_volume	Pourcentage d’affichage entier, 0–100. Par défaut : control.next_sound_volume.
next_pan	Panoramique de -100 (gauche) à 100 (droite). Par défaut : 0 (centre).

Action	Comportement
start	Démarrer selon le comportement de lecture configuré.
fade_in	Démarrer avec un fondu d’entrée.
crossfade	Démarrer avec l’action de fondu enchaîné de l’application.
replace	Démarrer avec l’action de remplacement de l’application.
toggle	Arrêter les lecteurs actifs correspondants, ou démarrer s’il n’y en a aucun.
toggle_fade	Faire sortir en fondu les lecteurs actifs correspondants, ou démarrer s’il n’y en a aucun.

Le comportement dépend du type d’élément et de sa configuration. La commande de déclenchement WebSocket n’a pas de champ de périphérique de sortie ; utilisez le routage et la sélection de sortie configurés dans Sound Show.

Lecture globale

stop_all et fade_out_all

{ "type": "stop_all" }

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

Ces commandes affectent les lecteurs audio et visuels non verrouillés. stop_all arrête immédiatement, sauf si une durée positive est fournie. Sans durée, fade_out_all utilise le fondu configuré dans l’application. Toutes deux acceptent duration_seconds ou duration_ms, facultatifs : envoyez une seule unité à la fois. Les durées globales personnalisées concernent les lecteurs audio ; les lecteurs visuels suivent le comportement de fondu visuel de l’application.

pause_all et resume_all

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

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

Mettre en pause les lecteurs audio et visuels non verrouillés, ou reprendre les lecteurs en pause. Le paramètre facultatif fade concerne l’audio ; les lecteurs visuels utilisent leur pause et reprise habituelles.

Contrôler un lecteur actif

Utilisez players[].id pour chaque player_id ci-dessous. Un identifiant d’élément ne remplace pas un identifiant de lecteur. Retrouvez le lecteur après la fin de la lecture ou un changement de projet.

toggle_player_playback

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

Basculer entre pause et reprise. fade est facultatif.

toggle_player_loop

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

Inverser l’état de boucle du lecteur actif. Les lecteurs verrouillés ignorent cette action. Lisez le loop_enabled résultant dans l’instantané du lecteur. La configuration de l’élément du projet reste inchangée.

stop_player et fade_out_player

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

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

Toutes deux acceptent duration_seconds ou duration_ms, facultatifs. Avec une durée positive, stop_player effectue un fondu de sortie au lieu d’un arrêt immédiat. Sans durée, fade_out_player utilise le fondu par défaut.

seek_player

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

Vous pouvez aussi envoyer position_percent, de 0 à 100. Envoyez un seul champ de position à la fois. Le pourcentage porte sur toute la timeline source, même si les points de début et de fin sont rognés. Le résultat est borné à la fenêtre de lecture. Une durée inconnue empêche le déplacement, sauf si une fin explicite définit une timeline finie. Voir état des lecteurs.

set_player_volume

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

volume est un pourcentage d’affichage de 0 à 100, pas un gain audio linéaire. Lisez volume_percent dans les instantanés pour afficher le résultat.

set_player_muted

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

Utilisez muted: false pour rétablir le son. Omettez duration_ms ou utilisez 0 pour un changement immédiat ; une durée positive applique un fondu à la coupure ou au rétablissement. Maximum : 60000 ms.

Contrôles partagés et niveaux de volume

set_next_sound_volume

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

Définir le volume par défaut des prochains déclenchements avec un entier de 0 à 100. Cela met à jour control.next_sound_volume.

set_selected_category

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

Modifier la catégorie sélectionnée en commun. Utilisez category_id: null pour effacer la sélection.

set_volume_level_active et toggle_volume_level

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

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

Prenez level_id dans control.volume_level_presets[].id. Pour un bouton maintenu, envoyez active: true à l’appui et active: false au relâchement sur la même connexion. Pour un bouton à bascule, utilisez toggle_volume_level.

Le maintien appartient à votre connexion et prend fin à sa déconnexion. Sound Show applique la direction et les règles de fondu du préréglage à sa sortie sélectionnée. control_snapshot annonce immédiatement la nouvelle cible active ; les instantanés de volume de sortie montrent la progression du fondu.

clear_volume_levels

{ "type": "clear_volume_levels" }

Relâcher tous les niveaux de volume commandés à distance. L’effacement est global, pas limité au maintien de votre connexion. Pour ne relâcher que le vôtre, envoyez plutôt set_volume_level_active avec active: false.

set_low_volume_active (compatibilité)

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

Activer le préréglage low, ou le premier configuré si low n’existe pas. Les nouvelles intégrations doivent fournir un level_id explicite.

Sorties

Utilisez logical_devices[].id pour cibler une sortie logique Sound Show. Les identifiants désignent le routage de l’application, pas les noms de périphériques du système ni leurs positions numériques.

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 est un pourcentage d’affichage entier de 0 à 100. Vérifiez available sur la cible avant de proposer des contrôles.

Effets audio

Découvrez les contrôles et leurs plages dans capabilities.audio_controls. Ne proposez un contrôle que si son descripteur prend en charge le type de cible voulu.

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 et value sont obligatoires. target.kind vaut logical_device ou player, et target.id est l’identifiant actuel de la cible. Les valeurs sont absolues, dans les unités natives du descripteur. Le serveur vérifie ensemble la plage et les réglages d’effet concernés : même dans sa plage, une valeur peut entrer en conflit avec un autre réglage, comme les fréquences de séparation de l’égaliseur.

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

Rétablir la valeur actuelle default_value du descripteur.

Les deux commandes acceptent fade_duration_ms, facultatif, de 0 à 60000 ; omis ou à 0, le changement est immédiat. Une commande plus récente pour la même cible et le même contrôle remplace le fondu actif. Les lecteurs verrouillés sont refusés. Le command_id facultatif est repris dans les erreurs ; il ne crée pas de réponse de succès et ne rend pas sûres les nouvelles tentatives automatiques.

Lumières du projet

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

Utilisez un identifiant de lights.lights[].id. value_percent est un niveau absolu de 0 à 100. fade_duration_ms et command_id sont facultatifs, avec les mêmes bornes et le même rapprochement des erreurs que les contrôles audio. Une nouvelle écriture sur la même lumière remplace son fondu actif.

Configurez d’abord la lumière du projet et sa connexion QLC+ dans Sound Show. La cible doit être disponible ; démarrer un fondu exige aussi un niveau actuel lisible. La commande respecte la plage, l’inversion et les droits configurés pour la lumière.

Instructions

trigger_current_instruction_go

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

Déclencher GO sur le lecteur d’instructions courant. Les paramètres facultatifs next_volume et next_pan ont les mêmes unités et valeurs par défaut que pour play_playable.

set_instruction_next

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

Les deux champs sont obligatoires. player_index est une position à partir de zéro dans instructions.players. Copiez path depuis l’instantané de l’élément ; proposez la sélection aux éléments ayant can_set_next: true et un chemin non vide. Cela change l’instruction suivante sans déclencher GO ni modifier sa définition.

Listes de lecture

Les indices de liste et d’élément sont des positions à partir de zéro dans le tableau actuel playlists.playlists et la queue d’une liste. Retrouvez-les après un changement d’état : un indice conservé peut désigner un autre élément après un réordonnancement.

playlist_play_next

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

Les trois champs sont facultatifs. Sans playlist_index, playlists.current_index est utilisé ; activate_autoplay et crossfade_all valent false par défaut.

playlist_play_item

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

Les deux indices sont obligatoires. Lire maintenant l’élément selon les règles normales de lecture automatique, de boucle et d’avancement de file. L’option crossfade_all: true demande le comportement du clic droit ; elle vaut false par défaut.

set_playlist_autoplay

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

autoplay est obligatoire. Sans playlist_index, playlists.current_index est utilisé. L’option crossfade_current_sounds vaut false par défaut.

Minuteries

Chaque commande exige un timer_index à partir de zéro dans le tableau courant des minuteries.

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

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

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

Ces commandes utilisent la configuration de la minuterie dans Sound Show. Lisez les messages timers_snapshot pour afficher le temps écoulé, le temps restant et l’état de marche.