Commandoreferentie

Stuur elk commando als apart JSON-tekstbericht via een geauthenticeerde WebSocket. Begin met de verbindingsgids als je nog geen eerste state hebt ontvangen.

Veldnamen zijn hoofdlettergevoelig. Vervang voorbeeld-ID’s door waarden uit de nieuwste toestand. De server volgt dezelfde afspeelregels, vergrendelingen en functierechten als de app. Controleer volgende snapshots: een geslaagde verzending bevestigt geen uitvoering.

Toestand en verbinding

Commando	Doel
{"type":"request_state"}	Een nieuwe volledige snapshot aanvragen, bijvoorbeeld na verlies van lokale toestand. Periodiek opvragen is niet nodig.
{"type":"ping"}	{"type":"pong"} ontvangen als hello_ok.features de functie ping bevat.

Een element starten

play_playable

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

playable_id is verplicht en komt uit project.categories[].playables[].id. Een afspeelbaar element is een projectknop, bijvoorbeeld een geluid, video, afbeelding of instructie. Starten kan een speler met een andere runtime-ID aanmaken.

Optioneel veld	Betekenis en standaard
action	Startactie hieronder; standaard start.
next_volume	Geheel weergavepercentage, 0–100. Standaard control.next_sound_volume.
next_pan	Panpercentage, -100 (links) tot 100 (rechts). Standaard 0 (midden).

Actie	Gedrag
start	Starten volgens de ingestelde afspeelwijze.
fade_in	Starten met infaden.
crossfade	Starten met de crossfade-actie van de app.
replace	Starten met de vervangactie van de app.
toggle	Bijbehorende actieve spelers stoppen, of starten als er geen actief zijn.
toggle_fade	Bijbehorende actieve spelers uitfaden, of starten als er geen actief zijn.

Het gedrag hangt af van het elementtype en de instellingen. Het WebSocket-startcommando heeft geen veld voor een uitvoerapparaat; gebruik de routering en uitvoerselectie van Sound Show.

Globale afspeelbediening

stop_all en fade_out_all

{ "type": "stop_all" }

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

Deze bedienen niet-vergrendelde audio- en visuele spelers. stop_all stopt direct, tenzij je een positieve duur opgeeft. Zonder duur gebruikt fade_out_all het fadegedrag van de app. Beide accepteren optioneel duration_seconds of duration_ms; stuur één eenheid tegelijk. Eigen globale duren gelden voor audiospelers; visuele spelers volgen de visuele fades van de app.

pause_all en resume_all

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

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

Niet-vergrendelde audio- en visuele spelers pauzeren, of gepauzeerde spelers hervatten. Optioneel fade geldt voor audiospelers; visuele spelers gebruiken hun normale pauze- en hervatgedrag.

Een actieve speler bedienen

Gebruik players[].id voor elke player_id hieronder. Een element-ID vervangt geen speler-ID. Zoek de speler opnieuw na het einde van de weergave of een projectwijziging.

toggle_player_playback

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

Pauzeren/hervatten omschakelen. fade is optioneel.

toggle_player_loop

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

De lusstatus van de actieve speler omschakelen. Vergrendelde spelers negeren dit. Lees de nieuwe loop_enabled uit de spelersnapshot. De configuratie van het projectelement verandert niet.

stop_player en fade_out_player

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

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

Beide accepteren optioneel duration_seconds of duration_ms. Met een positieve duur fade stop_player uit in plaats van direct te stoppen. Zonder duur gebruikt fade_out_player de standaardfade.

seek_player

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

Je kunt ook position_percent van 0 tot 100 sturen. Stuur één positieveld tegelijk. Percentages slaan op de volledige brontijdlijn, ook bij bijgesneden begin- en eindpunten. Het resultaat blijft binnen het afspeelvenster. Bij onbekende duur kun je niet springen, tenzij een expliciete stoptijd een eindige tijdlijn geeft. Zie spelerstoestand.

set_player_volume

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

volume is een weergavepercentage van 0 tot 100, geen lineaire audioversterking. Lees volume_percent uit snapshots voor de weergave.

set_player_muted

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

Gebruik muted: false om dempen uit te schakelen. Laat duration_ms weg of gebruik 0 voor een directe wijziging; een positieve duur fade het dempen of herstellen. Maximum: 60000 ms.

Gedeelde bediening en volumeniveaus

set_next_sound_volume

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

Stel het standaardvolume voor volgende starts in op een geheel getal van 0 tot 100. Dit wijzigt control.next_sound_volume.

set_selected_category

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

Wijzig de gedeelde categorieselectie. Gebruik category_id: null om die te wissen.

set_volume_level_active en toggle_volume_level

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

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

Neem level_id uit control.volume_level_presets[].id. Stuur voor een ingedrukte knop active: true bij indrukken en active: false bij loslaten via dezelfde verbinding. Gebruik toggle_volume_level voor een schakelknop.

Het vasthouden hoort bij jouw verbinding en eindigt bij verbreken. Sound Show past richting en faderegels van de preset toe op de geselecteerde uitgang. control_snapshot meldt het nieuwe actieve doel direct; uitgangsvolumesnapshots tonen het fadeverloop.

clear_volume_levels

{ "type": "clear_volume_levels" }

Alle op afstand bediende volumeniveaus loslaten. Dit wist globaal, niet alleen jouw eigen vasthoudactie. Stuur set_volume_level_active met active: false om alleen je eigen actie los te laten.

set_low_volume_active (compatibiliteit)

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

Activeer preset low, of de eerste ingestelde preset als low ontbreekt. Nieuwe integraties gebruiken een expliciete level_id.

Uitgangen

Gebruik logical_devices[].id voor een logische Sound Show-uitgang. ID’s verwijzen naar approutering, niet naar apparaatnamen van het besturingssysteem of numerieke posities.

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 is een geheel weergavepercentage van 0 tot 100. Controleer de vlag available van het doel voordat je bediening aanbiedt.

Audio-effecten

Vind ondersteunde bediening en bereiken via capabilities.audio_controls. Bied een bediening alleen aan als de descriptor het doeltype ondersteunt.

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 en value zijn verplicht. target.kind is logical_device of player; target.id is de actuele doel-ID. Waarden zijn absoluut, in de oorspronkelijke eenheden van de descriptor. De server controleert bereik en betrokken effectinstellingen samen: een waarde binnen bereik kan nog conflicteren met bijvoorbeeld EQ-scheidingsfrequenties.

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

Herstel de huidige default_value van de descriptor.

Beide accepteren optioneel fade_duration_ms van 0 tot 60000; weglaten of 0 werkt direct. Een nieuw commando voor hetzelfde doel en dezelfde bediening vervangt de actieve fade. Vergrendelde spelers worden geweigerd. Optioneel command_id komt terug in fouten, maar maakt geen succesantwoord en maakt automatisch herhalen niet veilig.

Projectverlichting

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

Gebruik een ID uit lights.lights[].id. value_percent is een absoluut niveau van 0 tot 100. fade_duration_ms en command_id zijn optioneel met dezelfde grenzen en foutkoppeling als audio. Een nieuwe schrijfactie naar dezelfde lamp vervangt de actieve fade.

Configureer eerst de projectlamp en QLC+-verbinding in Sound Show. Het doel moet beschikbaar zijn; een fade starten vereist ook een leesbaar huidig niveau. Het commando respecteert ingesteld bereik, inversie en functietoegang.

Instructies

trigger_current_instruction_go

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

Activeer GO op de huidige instructiespeler. Optionele next_volume en next_pan hebben dezelfde eenheden en standaardwaarden als bij play_playable.

set_instruction_next

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

Beide velden zijn verplicht. player_index is een positie vanaf nul in instructions.players. Kopieer path uit de gewenste itemsnapshot; bied selectie aan bij can_set_next: true en een niet-leeg pad. Dit wijzigt de volgende instructie zonder GO te activeren of de definitie te bewerken.

Afspeellijsten

Lijst- en itemindexen zijn posities vanaf nul in de huidige playlists.playlists-array en de queue van een lijst. Bepaal ze opnieuw na wijzigingen; een opgeslagen index kan na herschikken naar iets anders wijzen.

playlist_play_next

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

Alle drie velden zijn optioneel. Zonder playlist_index wordt playlists.current_index gebruikt; activate_autoplay en crossfade_all zijn standaard false.

playlist_play_item

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

Beide indexen zijn verplicht. Speel het item nu af volgens de normale regels voor automatisch afspelen, lussen en wachtrijvoortgang. Optioneel crossfade_all: true vraagt het rechtsklikgedrag van de app; standaard false.

set_playlist_autoplay

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

autoplay is verplicht. Zonder playlist_index wordt playlists.current_index gebruikt. Optioneel crossfade_current_sounds is standaard false.

Timers

Elk commando vereist een timer_index vanaf nul uit de huidige timerarray.

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

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

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

Deze gebruiken de timerinstellingen in Sound Show. Lees timers_snapshot-berichten om verstreken tijd, resterende tijd en de actieve status te tonen.