Mit Sound Show 2 verbinden

Steuern Sie Sound Show 2 mit eigenen Skripten, Hardware-Controllern oder Integrationen. Die WebSocket-API startet abspielbare Elemente, steuert Player und Ausgänge, führt Cues aus und überträgt den aktuellen Zustand an Ihren Controller.

Diese Anleitung beschreibt Protokoll v2. Sie verbinden sich direkt mit Sound Show auf Ihrem Computer oder im lokalen Netzwerk. Ein Website-API-Schlüssel oder Konto-Zugriffstoken ist nicht nötig. Projektbearbeitung und Datei-Uploads gehören nicht zu dieser API.

• Beginnen Sie hier, um eine Verbindung herzustellen und ein Beispiel auszuführen.
• Die Befehlsreferenz beschreibt weitere Steuerelemente.
• Unter Zustand und Ereignisse finden Sie IDs und Informationen zur Anzeige des aktuellen Show-Zustands.

Server aktivieren

1. Öffnen Sie Sound Show 2 auf einem Desktop-Computer und laden Sie Ihr Projekt. Der Host benötigt Pro-Zugang, auch eine aktive Pro-Testphase genügt. Siehe Free und Pro.
2. Öffnen Sie Optionen → Integrationen → Remote-Server oder die Einstellungen im Remote-Panel.
3. Wählen Sie einen Port (Standard: 8080) und ein Passwort mit mindestens sechs Zeichen. Speichern Sie die Einstellungen. Verwenden Sie ein eigenes Passwort für diese Verbindung.
4. Starten Sie den Server mit seiner Verbindungsschaltfläche. Bei leerem Passwort bestätigen Sie die Warnung zum Zugriff ohne Passwort.
5. Kopieren Sie die angezeigte Adresse. Lassen Sie Webseite bereitstellen eingeschaltet, wenn Sie auch die integrierte Browser-Fernbedienung nutzen möchten. Der WebSocket-Endpunkt funktioniert auch ohne diese Option.

Vertrauenswürdiges Netzwerk verwenden

Der Server verwendet unverschlüsseltes HTTP und WebSocket (ws://). Jeder mit Netzwerkzugang und Remote-Passwort kann die Show steuern; ohne Passwort kann sich jeder verbinden, der den Server erreicht. Nutzen Sie ein vertrauenswürdiges privates Netzwerk und geben Sie den Port nicht im öffentlichen Internet frei.

Verbindungsadressen

Browser-Fernbedienung und WebSocket-API verwenden denselben Host und Port.

Zweck	Beispiel auf dem Sound Show-Computer
WebSocket-Verbindung	ws://127.0.0.1:8080/ws
Integrierte Browser-Fernbedienung	http://127.0.0.1:8080/
Serverzustand	http://127.0.0.1:8080/health

Ersetzen Sie auf einem anderen Gerät 127.0.0.1 durch die Adresse des Sound Show-Computers, etwa ws://192.168.1.20:8080/ws. Verwenden Sie Ihren eingestellten Port, falls er von 8080 abweicht. localhost bezeichnet immer das Gerät, auf dem der Client läuft.

Der Zustandsendpunkt liefert ein Objekt wie {"status":"ok","protocol_version":2}. Dies bestätigt die Erreichbarkeit des Servers, authentifiziert aber nicht den Client.

Aus einem Browser verbinden

Sound Show prüft standardmäßig den Origin-Header des Browsers. Er muss eine HTTP-Origin mit dem Serverport und einem akzeptierten Host enthalten: localhost, die erkannte LAN-Adresse oder den konfigurierten angekündigten Host. Die integrierte Fernbedienung unter der angezeigten Sound Show-Adresse verwendet eine akzeptierte Origin.

Eine eigene Seite auf einem anderen Gerät, einer Website oder einem anderen Entwicklungsserver-Port benötigt die unten beschriebene Option Externe Origins erlauben. Native Clients einschließlich des JavaScript-Terminalbeispiels können Origin weglassen und benötigen diese Option nicht.

Externe Origins erlauben

Aktivieren Sie dies, wenn Sie Ihre Browser-Fernbedienung getrennt von Sound Show hosten:

1. Öffnen Sie Optionen → Integrationen → Remote-Server oder die Einstellungen des Remote-Panels.
2. Legen Sie ein Remote-Passwort fest, aktivieren Sie Externe Origins erlauben und übernehmen Sie die Einstellungen. Die Option ist standardmäßig aus. Fehlt sie, aktualisieren Sie Sound Show auf eine Version, die sie enthält.
3. Öffnen Sie die eigene Fernbedienung auf einem Gerät, das den Sound Show-Computer erreicht. Verbinden Sie ihren WebSocket mit der Sound Show-Adresse, nicht mit dem Host Ihrer Seite, und senden Sie die übliche hello-Nachricht mit Passwort.

Ein unter http://192.168.1.30:3000 bereitgestellter Controller kann sich beispielsweise mit Sound Show unter ws://192.168.1.20:8080/ws verbinden. Das Browserskript kann so 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.
  });
}

Ersetzen Sie die Beispieladresse durch Ihren Host und Port. Warten Sie auf den ersten state, bevor Sie Wiedergabesteuerungen aktivieren, und verwenden Sie die Snapshot-Verarbeitung des vollständigen JavaScript-Beispiels. Bewahren Sie das Passwort in der Controller-Sitzung auf, statt es in eine öffentliche Seite einzubetten.

Die Option akzeptiert HTTP- und HTTPS-Seiten-Origins mit anderen Hosts oder Ports. Passwort-Handshake und Pro-Anforderung gelten weiterhin. Änderungen werden beim Speichern sofort wirksam und trennen Clients; verbinden und authentifizieren Sie sich erneut. Auch das Ausschalten beendet vorhandene externe Sitzungen. Die integrierte Browser-Fernbedienung funktioniert bei ausgeschalteter Option.

Passwort bei externen Origins verwenden

Damit darf jede HTTP/HTTPS-Website eine Verbindung versuchen. Ohne Remote-Passwort könnte eine besuchte Website Sound Show steuern, wenn Ihr Browser den Host erreicht. Aktivieren Sie die Option nur bei Bedarf und verwenden Sie weiterhin ein vertrauenswürdiges privates Netzwerk.

Browserbeschränkungen gelten weiterhin. Stellen Sie Ihre Seite für eine einfache LAN-Konfiguration über HTTP bereit. HTTPS-Seiten können unverschlüsseltes ws:// blockieren; die Option bietet keinen sicheren wss://-Endpunkt. Ein HTTPS-Controller benötigt eine browserkompatible sichere Verbindung, etwa einen separat eingerichteten TLS-Proxy. Browser können außerdem eine Berechtigung für das lokale Netzwerk verlangen oder weitere Einschränkungen anwenden. Die Option fügt HTTP-Endpunkten keine CORS-Header hinzu. file://-Seiten und undurchsichtige null-Origins bleiben abgewiesen: Stellen Sie lokale HTML-Dateien über einen HTTP-Server bereit.

Zuerst authentifizieren

Senden Sie direkt nach dem Öffnen des Sockets innerhalb von zehn Sekunden eine JSON-Textnachricht mit dem in Sound Show festgelegten Remote-Passwort:

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

Bei einem bestätigten Server ohne Passwort lassen Sie password weg oder verwenden eine leere Zeichenfolge. features ist optional; mit runtime_snapshots erhält der Client separate Live-Updates für Steuerzustand, Anweisungen, Wiedergabelisten und Elementaktivität.

Bei Erfolg sendet der Server:

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

Darauf folgt automatisch eine vollständige state-Nachricht. Warten Sie darauf, bevor Sie Ziele auswählen oder Show-Befehle senden. Spätere Nachrichten ersetzen den gesamten Zustand oder einen benannten Teil. Es gibt weder einen Abonnementbefehl noch eine Erfolgsbestätigung pro Befehl: Maßgeblich ist der resultierende Zustand.

Bei einem Fehler folgt hello_rejected mit reason und message, anschließend die Trennung. Gründe sind unter anderem invalid_password, unsupported_version und rate_limited. Siehe Fehler und Grenzen.

JavaScript-Client ausprobieren

Speichern Sie dies als soundshow-client.mjs. Verwenden Sie Node.js 22.12 oder neuer; der integrierte WebSocket-Client benötigt keine Pakete. Das Beispiel listet Projektelemente auf und verfolgt den Live-Zustand. Es startet die Wiedergabe nur, wenn Sie eine Element-ID als Befehlszeilenargument übergeben.

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());

Legen Sie in PowerShell Adresse und Remote-Passwort fest und listen Sie die Elemente auf:

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

In einem macOS- oder Linux-Terminal:

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

Schreiben Sie Ihr echtes Passwort nicht in geteilte Skripte. Verwenden Sie bei passwortlosen Servern einen leeren Wert. Beenden Sie das Skript mit Strg+C, kopieren Sie eine Element-ID aus der Tabelle und starten Sie es erneut, um dieses Element einmal auszulösen:

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

Das Beispiel verbindet sich nicht automatisch neu und wiederholt keine Befehle. Ergänzen Sie für einen dauerhaft laufenden Controller die Verbindungswiederherstellung und wählen Sie Befehle aus der Referenz.

Fehlerbehebung

Symptom	Prüfen
Verbindung abgelehnt oder Zeitüberschreitung	Sound Show geöffnet lassen und Server starten. Port, Hostadresse, Firewall und gegenseitige Erreichbarkeit der Geräte prüfen.
Server startet nicht	Pro-Zugang, Verbindungsprotokoll und mögliche Portbelegung durch eine andere Anwendung prüfen.
HTTP 403 beim Verbinden	Pro-Zugang und Browser-Origin prüfen. Für Seiten auf einem anderen Gerät, Port oder einer Website Externe Origins erlauben in Sound Show aktivieren.
Eigene Fernbedienung verbindet sich weiterhin nicht	Sound Show-Hostadresse, Firewall und Browserkonsole prüfen. Die Option umgeht keine Beschränkungen für gemischte Inhalte oder lokale Netzwerke; die oben beschriebene HTTP-LAN-Konfiguration verwenden.
invalid_password	Remote-Server-Passwort verwenden, nicht das Sound Show-Kontopasswort.
unsupported_version	version: 2 senden und /ws verwenden. Sound Show 1-Nachrichten sind inkompatibel.
HTTP 429 oder rate_limited	Schnelle Versuche oder Befehle stoppen und Wiederholungshinweise beachten.
Verbunden, aber kein Zustand	Zuerst hello senden. Auf Ablehnung oder fehlerhaftes JSON prüfen.
Befehl ohne Wirkung	IDs aus dem neuesten Zustand ermitteln; Sperren, Zielverfügbarkeit, Lizenz und error-Nachrichten prüfen.
Controlleranzeige veraltet	Domain-Snapshots und vollständige state-Nachrichten verarbeiten. Stille allein bedeutet keinen Verbindungsverlust.

Von Sound Show 1 umsteigen

Verwenden Sie /ws statt /SoundShow und das kleingeschriebene Feld type statt $type und .NET-Klassennamen. Senden Sie den v2-hello-Handshake. Verwenden Sie Player-IDs und IDs logischer Geräte statt numerischer Player- oder Ausgangsindizes. Symbole sind HTTP-icon_url-Ressourcen; der Zustand kommt als vollständiger oder Domain-Snapshot.