Verbinding maken met Sound Show 2

Bedien Sound Show 2 vanuit je eigen script, hardwarecontroller of integratie. De WebSocket-API kan elementen starten, spelers en uitgangen bedienen, cues uitvoeren en de actuele toestand terugsturen naar je controller.

Deze gids beschrijft protocol v2. Je maakt rechtstreeks verbinding met Sound Show op je computer of lokale netwerk. Een website-API-sleutel of accounttoegangstoken is niet nodig. Projecten bewerken en bestanden uploaden vallen buiten deze API.

• Begin hier om verbinding te maken en een voorbeeld uit te voeren.
• Voeg bediening toe met de commandoreferentie.
• Gebruik toestand en gebeurtenissen om ID’s te vinden en de actuele showtoestand weer te geven.

De server inschakelen

1. Open Sound Show 2 op een desktopcomputer en laad je project. De host heeft Pro-toegang nodig, waaronder een actieve Pro-proefperiode. Zie Free en Pro.
2. Open Opties → Integraties → Externe server. Je kunt ook het paneel Afstandsbediening en de instellingenknop gebruiken.
3. Kies een poort (standaard 8080) en een wachtwoord van minstens zes tekens. Sla de instellingen op en gebruik een uniek wachtwoord voor deze verbinding.
4. Start de server met de verbindingsknop. Laat je het wachtwoord leeg, bevestig dan de waarschuwing voor toegang zonder wachtwoord.
5. Kopieer het adres dat Sound Show toont. Laat Webpagina aanbieden aan voor de ingebouwde browserafstandsbediening; het WebSocket-eindpunt werkt ook als die optie uitstaat.

Gebruik een vertrouwd netwerk

De server gebruikt onversleuteld HTTP en WebSocket (ws://). Iedereen met netwerktoegang en het serverwachtwoord kan de show bedienen; zonder wachtwoord kan iedereen die de server bereikt verbinding maken. Gebruik een vertrouwd privénetwerk en stel de poort niet open op het openbare internet.

Verbindingsadressen

De browserafstandsbediening en WebSocket-API delen dezelfde host en poort.

Doel	Voorbeeld op de Sound Show-computer
WebSocket-verbinding	ws://127.0.0.1:8080/ws
Ingebouwde browserafstandsbediening	http://127.0.0.1:8080/
Serverstatus	http://127.0.0.1:8080/health

Vervang op een ander apparaat 127.0.0.1 door het adres van de Sound Show-computer, bijvoorbeeld ws://192.168.1.20:8080/ws. Gebruik je ingestelde poort als die afwijkt van 8080. localhost verwijst altijd naar het apparaat waarop je client draait.

Het statuseindpunt geeft een object zoals {"status":"ok","protocol_version":2} terug. Dit bevestigt de bereikbaarheid van de server, maar authenticeert je client niet.

Verbinden vanuit een browser

Standaard controleert Sound Show de Origin-header van de browser. Dit moet een HTTP-origin zijn met de serverpoort en een toegestane host: localhost, het gedetecteerde LAN-adres of de ingestelde geadverteerde host. De ingebouwde afstandsbediening openen op het getoonde Sound Show-adres levert een toegestane origin op.

Een eigen pagina op een ander apparaat, een andere website of ontwikkelserverpoort vereist de onderstaande optie Externe origins toestaan. Native clients, inclusief het JavaScript-terminalvoorbeeld op deze pagina, kunnen Origin weglaten en hebben deze optie niet nodig.

Externe origins toestaan

Schakel dit in als je een eigen browserafstandsbediening apart van Sound Show host:

1. Open in Sound Show Opties → Integraties → Externe server, of de instellingen van het afstandsbedieningspaneel.
2. Stel een wachtwoord in, schakel Externe origins toestaan in en pas de instellingen toe. De optie staat standaard uit. Werk Sound Show bij als jouw versie deze optie nog niet heeft.
3. Open je afstandsbedieningspagina op een apparaat dat de Sound Show-computer kan bereiken. Verbind de WebSocket met het adres van Sound Show, niet met de host van je pagina, en stuur het gebruikelijke hello-bericht met het wachtwoord.

Een controller op http://192.168.1.30:3000 kan bijvoorbeeld verbinden met Sound Show op ws://192.168.1.20:8080/ws. Je browserscript kan zo beginnen:

const remotePassword = window.prompt("Sound Show remote password");
if (remotePassword !== null) {
  const socket = new WebSocket("ws://192.168.1.20:8080/ws");
  socket.addEventListener("open", () => {
    socket.send(JSON.stringify({
      type: "hello", version: 2, password: remotePassword,
      features: ["runtime_snapshots"],
    }));
  });
  socket.addEventListener("message", (event) => {
    const message = JSON.parse(event.data);
    console.log(message); // Handle hello_rejected, errors, and snapshots here.
  });
}

Vervang het voorbeeldadres door je eigen host en poort. Wacht op de eerste state voordat je afspeelknoppen inschakelt en gebruik de snapshotverwerking uit het volledige JavaScript-voorbeeld. Bewaar het wachtwoord in de controllersessie, niet in een openbare pagina.

De optie accepteert origins van HTTP- en HTTPS-pagina’s met andere hosts of poorten. De wachtwoordhandshake en Pro-vereiste blijven gelden. Een wijziging opslaan wordt direct toegepast en verbreekt clientverbindingen; verbind en authenticeer opnieuw. Uitschakelen beëindigt ook bestaande externe sessies. De ingebouwde browserafstandsbediening werkt met de optie uit.

Gebruik een wachtwoord bij externe origins

Hierdoor kan elke HTTP/HTTPS-website een verbinding proberen. Zonder serverwachtwoord kan een bezochte website Sound Show bedienen als je browser de host kan bereiken. Schakel dit alleen in als het nodig is en blijf een vertrouwd privénetwerk gebruiken.

Browserbeperkingen blijven gelden. Gebruik HTTP voor een eenvoudige LAN-opstelling. Een HTTPS-pagina kan een onversleutelde ws://-verbinding blokkeren; deze optie levert geen beveiligd wss://-eindpunt. Een HTTPS-controller heeft een browsergeschikte beveiligde verbinding nodig, bijvoorbeeld een apart ingestelde TLS-proxy. Browsers kunnen ook toestemming voor het lokale netwerk vereisen of andere netwerkbeperkingen opleggen. De optie voegt geen CORS-headers aan HTTP-eindpunten toe. Pagina’s via file:// en ondoorzichtige null-origins blijven geweigerd: bied een lokaal HTML-bestand aan via een HTTP-server.

Eerst authenticeren

Stuur direct na het openen van de socket één JSON-tekstbericht, binnen tien seconden. Gebruik het serverwachtwoord uit Sound Show:

{
  "type": "hello",
  "version": 2,
  "password": "your-remote-password",
  "features": ["runtime_snapshots"]
}

Bij een bevestigde server zonder wachtwoord kun je password weglaten of een lege tekenreeks gebruiken. features is optioneel; met runtime_snapshots ontvangt je client aparte updates voor bediening, instructies, afspeellijsten en activiteit van elementen.

Bij succes stuurt de server:

{
  "type": "hello_ok",
  "protocol_version": 2,
  "requested_version": 2,
  "state_mode": "full_snapshot",
  "features": ["ping", "runtime_snapshots"]
}

Daarna volgt automatisch een volledig state-bericht. Wacht daarop voordat je een doel kiest of showcommando’s stuurt. Latere berichten vervangen de volledige toestand of een benoemd onderdeel. Er is geen abonnementscommando en geen succesbevestiging per commando: de resulterende toestand is bepalend.

Bij mislukking volgt hello_rejected met reason en message, waarna de verbinding wordt verbroken. Mogelijke redenen zijn invalid_password, unsupported_version en rate_limited. Zie fouten en limieten.

Een JavaScript-client proberen

Sla dit op als soundshow-client.mjs en voer het uit met Node.js 22.12 of nieuwer. De ingebouwde WebSocket-client vereist geen pakketten. Het voorbeeld toont de projectelementen en volgt de actuele toestand. Afspelen begint alleen als je een element-ID als opdrachtregelargument meegeeft.

const url = process.env.SOUNDSHOW_REMOTE_URL ?? "ws://127.0.0.1:8080/ws";
const password = process.env.SOUNDSHOW_REMOTE_PASSWORD ?? "";
const playableId = process.argv[2];
const ws = new WebSocket(url);
let state = null;
let firstSnapshot = true;

const domains = {
  control_snapshot: "control",
  players_snapshot: "players",
  instructions_snapshot: "instructions",
  playlists_snapshot: "playlists",
  playable_runtime_snapshot: "playable_runtime",
  logical_devices_snapshot: "logical_devices",
  timers_snapshot: "timers",
  audio_controls_snapshot: "audio_controls",
  lights_snapshot: "lights",
};

function send(command) {
  if (!state || ws.readyState !== WebSocket.OPEN) {
    throw new Error("Wait for the first state snapshot before sending commands.");
  }
  ws.send(JSON.stringify(command));
}

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({
    type: "hello", version: 2, password, features: ["runtime_snapshots"],
  }));
});

ws.addEventListener("message", (event) => {
  const message = JSON.parse(event.data);
  if (message.type === "hello_rejected" || message.type === "error") {
    console.error(message.reason ?? message.code ?? "error", message.message);
    return;
  }
  if (message.type === "state") {
    state = message.state; // Replace the entire state, even after a project change.
  } else {
    const domain = domains[message.type];
    if (!state || !domain) return; // Ignore unknown additive message types.
    if ((domain === "audio_controls" || domain === "lights") &&
        message.revision < (state[domain]?.revision ?? -1)) return;
    state = { ...state, [domain]: message[domain] };
  }

  if (firstSnapshot) {
    firstSnapshot = false;
    const playables = (state.project?.categories ?? []).flatMap((category) =>
      category.playables.map((p) => ({
        id: p.id, name: p.name, kind: p.kind, category: category.name,
      }))
    );
    console.table(playables);
    if (playableId) {
      if (playables.some((p) => p.id === playableId)) {
        send({ type: "play_playable", playable_id: playableId, action: "start" });
      } else {
        console.error("That playable ID is not in the current project.");
      }
    }
    console.log("Connected. Press Ctrl+C to disconnect.");
  }
  // Use `state` here to update your controller after every snapshot.
});

ws.addEventListener("error", () => console.error("Connection failed. Check the server address and settings."));
ws.addEventListener("close", (event) => {
  state = null;
  console.log("Disconnected:", event.code, event.reason);
});
process.on("SIGINT", () => ws.close());

Stel in PowerShell het adres en serverwachtwoord in en toon de elementen:

$env:SOUNDSHOW_REMOTE_URL = 'ws://127.0.0.1:8080/ws'
$env:SOUNDSHOW_REMOTE_PASSWORD = 'your-remote-password'
node soundshow-client.mjs

In een macOS- of Linux-terminal:

export SOUNDSHOW_REMOTE_URL='ws://127.0.0.1:8080/ws'
export SOUNDSHOW_REMOTE_PASSWORD='your-remote-password'
node soundshow-client.mjs

Zet je echte wachtwoord niet in gedeelde scripts. Gebruik een lege waarde voor een server zonder wachtwoord. Stop het script met Ctrl+C, kopieer een element-ID uit de tabel en voer het opnieuw uit om dat element eenmaal te starten:

node soundshow-client.mjs "paste-a-playable-id-here"

Het voorbeeld verbindt niet automatisch opnieuw en herhaalt geen commando’s. Voeg voor een langdurig actieve controller verbindingsherstel toe en kies commando’s uit de referentie.

Problemen oplossen

Probleem	Controle
Verbinding geweigerd of time-out	Houd Sound Show open en start de server. Controleer poort, hostadres, firewall en netwerkbereikbaarheid tussen beide apparaten.
De server start niet	Controleer Pro-toegang, het verbindingslog en of een andere app de poort gebruikt.
HTTP 403 bij verbinden	Controleer Pro-toegang en browserorigin. Zet voor een pagina op een ander apparaat, poort of website Externe origins toestaan aan in Sound Show.
De eigen afstandsbediening verbindt nog steeds niet	Controleer het Sound Show-hostadres, de firewall en browserconsole. De optie omzeilt geen beperkingen voor gemengde inhoud of lokale netwerken; gebruik de beschreven HTTP-LAN-opstelling.
invalid_password	Gebruik het serverwachtwoord, niet je Sound Show-accountwachtwoord.
unsupported_version	Stuur version: 2 en gebruik /ws. Sound Show 1-berichten zijn incompatibel.
HTTP 429 of rate_limited	Stop snelle herhaalpogingen of commando’s en volg het advies voor opnieuw proberen.
Verbonden maar geen toestand	Stuur eerst hello. Zoek naar een afwijzing of ongeldige JSON.
Een commando heeft geen effect	Bepaal ID’s uit de nieuwste toestand; controleer vergrendelingen, doelbeschikbaarheid, licentie en error-berichten.
Het scherm van de controller loopt achter	Verwerk domeinsnapshots én volledige state-berichten. Stilte betekent op zichzelf geen verbroken verbinding.

Overstappen vanaf Sound Show 1

Gebruik /ws in plaats van /SoundShow en het veld type in kleine letters in plaats van $type en .NET-klassenamen. Stuur de v2-hello-handshake. Gebruik speler-ID’s en logische-apparaat-ID’s in plaats van numerieke speler- of uitgangsindexen. Pictogrammen zijn HTTP-icon_url-bronnen; de toestand komt als volledige of domeinsnapshots.