Befehlsreferenz

Senden Sie jeden Befehl als separate JSON-Textnachricht über eine authentifizierte WebSocket-Verbindung. Beginnen Sie mit der Verbindungsanleitung, wenn Sie noch keinen ersten state erhalten haben.

Bei allen Feldnamen zählt die Groß- und Kleinschreibung. Ersetzen Sie Beispiel-IDs durch Werte aus dem neuesten Zustand. Es gelten dieselben Wiedergaberegeln, Sperren und Funktionsberechtigungen wie in der App. Prüfen Sie das Ergebnis anhand nachfolgender Snapshots; erfolgreiches Senden bestätigt nicht die Ausführung.

Zustand und Verbindung

Befehl	Zweck
{"type":"request_state"}	Einen neuen vollständigen Snapshot anfordern, etwa nach Verlust des lokalen Zustands. Regelmäßiges Abfragen ist unnötig.
{"type":"ping"}	{"type":"pong"} empfangen, wenn hello_ok.features den Eintrag ping enthält.

Ein Spielelement starten

play_playable

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

playable_id ist erforderlich und stammt aus project.categories[].playables[].id. Ein Spielelement ist eine Projektschaltfläche, etwa für Ton, Video, Bild oder Anweisung. Beim Start kann ein Player mit einer anderen Laufzeit-ID entstehen.

Optionales Feld	Bedeutung und Standard
action	Startaktion aus der folgenden Tabelle; Standard: start.
next_volume	Ganzzahliger Anzeigeprozentsatz von 0 bis 100. Standard: control.next_sound_volume.
next_pan	Panorama in Prozent von -100 (links) bis 100 (rechts). Standard: 0 (Mitte).

Aktion	Verhalten
start	Mit dem konfigurierten Wiedergabeverhalten starten.
fade_in	Mit Einblenden starten.
crossfade	Mit der Crossfade-Aktion der App starten.
replace	Mit der Ersetzen-Aktion der App starten.
toggle	Passende aktive Player stoppen oder starten, wenn keiner aktiv ist.
toggle_fade	Passende aktive Player ausblenden oder starten, wenn keiner aktiv ist.

Das Verhalten hängt von Typ und Konfiguration des Spielelements ab. Der WebSocket-Startbefehl hat kein Feld für ein Ausgabegerät; verwenden Sie das konfigurierte Routing und die Ausgangsauswahl in Sound Show.

Globale Wiedergabe

stop_all und fade_out_all

{ "type": "stop_all" }

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

Diese Befehle betreffen entsperrte Audio- und visuelle Player. stop_all stoppt sofort, außer Sie geben eine positive Dauer an. fade_out_all verwendet ohne Dauer das Fade-Verhalten der App. Beide akzeptieren optional duration_seconds oder duration_ms; senden Sie jeweils nur eine Einheit. Eigene globale Dauern gelten für Audio-Player; visuelle Player verwenden das visuelle Fade-Verhalten der App.

pause_all und resume_all

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

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

Entsperrte Audio- und visuelle Player pausieren oder pausierte Player fortsetzen. Das optionale Flag fade gilt für Audio-Player; visuelle Player verwenden ihr normales Pause- und Fortsetzungsverhalten.

Einen laufenden Player steuern

Verwenden Sie für jedes folgende player_id players[].id. Eine Spielelement-ID ersetzt keine Player-ID. Ermitteln Sie den Player erneut, nachdem die Wiedergabe endet oder das Projekt wechselt.

toggle_player_playback

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

Zwischen Pause und Fortsetzen wechseln. fade ist optional.

toggle_player_loop

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

Den Schleifenmodus des laufenden Players umschalten. Gesperrte Player ignorieren diese Aktion. Lesen Sie den resultierenden Wert loop_enabled im Player-Snapshot. Die Spielelement-Konfiguration im Projekt bleibt unverändert.

stop_player und fade_out_player

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

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

Beide akzeptieren optional duration_seconds oder duration_ms. Mit positiver Dauer blendet stop_player aus, statt sofort zu stoppen. fade_out_player verwendet ohne Dauer den Standard-Fade.

seek_player

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

Alternativ position_percent von 0 bis 100 senden. Senden Sie jeweils nur ein Positionsfeld. Prozentwerte beziehen sich auf die gesamte Quellzeitachse, auch bei zugeschnittenem Anfang und Ende. Das Ergebnis wird auf das Wiedergabefenster begrenzt. Bei unbekannter Dauer ist ein Sprung nur möglich, wenn eine ausdrückliche Endzeit eine endliche Zeitachse ergibt. Siehe Player-Zustand.

set_player_volume

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

volume ist ein Anzeigeprozentsatz von 0 bis 100, kein linearer Audioverstärkungsfaktor. Lesen Sie volume_percent aus Snapshots für das angezeigte Ergebnis.

set_player_muted

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

Mit muted: false die Stummschaltung aufheben. Ohne duration_ms oder mit 0 erfolgt die Änderung sofort; eine positive Dauer blendet die Stummschaltung ein oder aus. Höchstens 60000 ms.

Gemeinsame Steuerung und Lautstärkepegel

set_next_sound_volume

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

Die Standardlautstärke zukünftiger Starts als Ganzzahl von 0 bis 100 festlegen. Dies aktualisiert control.next_sound_volume.

set_selected_category

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

Die gemeinsame Kategorieauswahl ändern. Mit category_id: null aufheben.

set_volume_level_active und toggle_volume_level

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

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

level_id stammt aus control.volume_level_presets[].id. Für eine gehaltene Taste beim Drücken active: true und beim Loslassen active: false über dieselbe Verbindung senden. Für eine einrastende Taste toggle_volume_level verwenden.

Das Halten gehört zu Ihrer Verbindung und endet bei deren Trennung. Sound Show wendet Richtungs- und Fade-Regeln des Presets auf dessen gewählten Ausgang an. control_snapshot meldet sofort das neue aktive Ziel; Ausgangslautstärke-Snapshots zeigen den Fade-Fortschritt.

clear_volume_levels

{ "type": "clear_volume_levels" }

Alle ferngesteuerten Lautstärkepegel freigeben. Dies gilt global, nicht nur für Ihre Verbindung. Um nur Ihr eigenes Halten zu beenden, senden Sie stattdessen set_volume_level_active mit active: false.

set_low_volume_active (Kompatibilität)

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

Das Preset low aktivieren, oder das erste konfigurierte Preset, wenn low fehlt. Neue Integrationen sollten eine ausdrückliche level_id verwenden.

Ausgänge

Mit logical_devices[].id einen logischen Ausgang von Sound Show ansprechen. Die IDs beziehen sich auf das App-Routing, nicht auf Gerätenamen des Betriebssystems oder numerische Positionen.

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 ist ein ganzzahliger Anzeigeprozentsatz von 0 bis 100. Prüfen Sie das Flag available des Ziels, bevor Sie Bedienelemente anbieten.

Audioeffekte

Unterstützte Regler und Bereiche stehen in capabilities.audio_controls. Bieten Sie einen Regler nur an, wenn sein Deskriptor den Bereich Ihres Ziels unterstützt.

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 und value sind erforderlich. target.kind ist logical_device oder player; target.id ist die aktuelle ID dieses Ziels. Werte sind absolut in den nativen Einheiten des Deskriptors. Der Server prüft Bereich und betroffene Effekteinstellungen gemeinsam; selbst ein Wert innerhalb eines Bereichs kann anderen Einstellungen widersprechen, etwa EQ-Trennfrequenzen.

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

Auf den aktuellen default_value des Deskriptors zurücksetzen.

Beide Befehle akzeptieren optional fade_duration_ms von 0 bis 60000; ohne Angabe oder mit 0 gilt die Änderung sofort. Ein neuerer Befehl für dasselbe Ziel und denselben Regler ersetzt einen laufenden Fade. Gesperrte Player werden abgewiesen. Optionales command_id wird bei diesen Befehlen in Fehlern zurückgegeben; es erzeugt weder eine Erfolgsantwort noch sichere automatische Wiederholungen.

Projektlichter

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

Verwenden Sie eine ID aus lights.lights[].id. value_percent ist ein absoluter Pegel von 0 bis 100. fade_duration_ms und command_id sind optional und haben dieselben Grenzen und dieselbe Fehlerzuordnung wie Audioregler. Ein neuer Schreibvorgang für dasselbe Licht ersetzt dessen laufenden Fade.

Konfigurieren Sie zuerst das Projektlicht und seine QLC+-Verbindung in Sound Show. Das Ziel muss verfügbar sein; zum Start eines Fades muss auch der aktuelle Pegel lesbar sein. Der Befehl beachtet den konfigurierten Bereich, die Invertierung und den Funktionszugriff.

Anweisungen

trigger_current_instruction_go

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

GO beim aktuellen Anweisungsplayer auslösen. Optionale next_volume und next_pan haben dieselben Einheiten und Standardwerte wie bei play_playable.

set_instruction_next

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

Beide Felder sind erforderlich. player_index ist eine bei null beginnende Position in instructions.players. Kopieren Sie path aus dem Snapshot des gewünschten Elements; bieten Sie die Auswahl bei can_set_next: true und einem nicht leeren Pfad an. Dies ändert die nächste Anweisung, ohne GO auszulösen oder die Definition zu bearbeiten.

Playlists

Playlist- und Elementindizes sind bei null beginnende Positionen im aktuellen Array playlists.playlists und in queue einer Playlist. Ermitteln Sie sie nach Zustandsänderungen neu; nach einer Umsortierung kann ein gespeicherter Index auf ein anderes Element zeigen.

playlist_play_next

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

Alle drei Felder sind optional. Ohne playlist_index gilt playlists.current_index; activate_autoplay und crossfade_all sind standardmäßig false.

playlist_play_item

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

Beide Indizes sind erforderlich. Das Element sofort mit den normalen Autoplay-, Schleifen- und Warteschlangenregeln der App abspielen. Optionales crossfade_all: true fordert das Rechtsklick-Verhalten der App an; Standard ist false.

set_playlist_autoplay

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

autoplay ist erforderlich. Ohne playlist_index gilt playlists.current_index. Optionales crossfade_current_sounds ist standardmäßig false.

Timer

Jeder Befehl erfordert einen bei null beginnenden timer_index aus dem aktuellen Timer-Array.

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

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

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

Diese Befehle verwenden die Timer-Konfiguration in Sound Show. Lesen Sie timers_snapshot-Nachrichten zur Anzeige von verstrichener Zeit, Restzeit und Laufzustand.