Se connecter à Sound Show 2

Pilotez Sound Show 2 depuis votre propre script, contrôleur matériel ou intégration. L’API WebSocket permet de déclencher des éléments, de contrôler les lecteurs et les sorties, d’exécuter des cues et de transmettre l’état en direct à votre contrôleur.

Ce guide décrit le protocole v2. La connexion se fait directement à Sound Show sur votre ordinateur ou votre réseau local. Aucune clé d’API du site ni aucun jeton de compte n’est nécessaire. La modification de projets et l’envoi de fichiers ne font pas partie de cette API.

• Commencez ici pour vous connecter et essayer un exemple.
• Consultez la référence des commandes pour ajouter des contrôles.
• Consultez l’état et les événements pour trouver les identifiants et afficher l’état du spectacle.

Activer le serveur

1. Ouvrez Sound Show 2 sur un ordinateur et chargez votre projet. L’hôte doit disposer d’un accès Pro, y compris un essai Pro actif. Voir Free et Pro.
2. Ouvrez Options → Intégrations → Serveur distant. Vous pouvez aussi utiliser le panneau Distant et son bouton de réglages.
3. Choisissez un port (8080 par défaut) et un mot de passe d’au moins six caractères. Enregistrez les réglages. Utilisez un mot de passe propre à cette connexion.
4. Démarrez le serveur avec son bouton de connexion. Si le mot de passe est vide, confirmez l’avertissement d’accès sans mot de passe.
5. Copiez l’adresse affichée par Sound Show. Gardez Servir la page web activé pour utiliser aussi la télécommande intégrée au navigateur ; le point d’accès WebSocket fonctionne également avec cette option désactivée.

Utilisez un réseau de confiance

Le serveur utilise HTTP et WebSocket sans chiffrement (ws://). Toute personne ayant accès au réseau et au mot de passe distant peut piloter le spectacle ; sans mot de passe, toute personne pouvant joindre le serveur peut se connecter. Utilisez un réseau privé de confiance et n’exposez pas son port sur Internet.

Adresses de connexion

La télécommande du navigateur et l’API WebSocket partagent le même hôte et le même port.

Usage	Exemple sur l’ordinateur Sound Show
Connexion WebSocket	ws://127.0.0.1:8080/ws
Télécommande intégrée au navigateur	http://127.0.0.1:8080/
État du serveur	http://127.0.0.1:8080/health

Depuis un autre appareil, remplacez 127.0.0.1 par l’adresse de l’ordinateur Sound Show, par exemple ws://192.168.1.20:8080/ws. Utilisez votre port configuré s’il diffère de 8080. localhost désigne toujours l’appareil qui exécute votre client.

Le point d’accès de santé renvoie un objet tel que {"status":"ok","protocol_version":2}. Il confirme que le serveur est joignable, mais n’authentifie pas votre client.

Se connecter depuis un navigateur

Par défaut, Sound Show vérifie l’en-tête Origin du navigateur. Il doit s’agir d’une origine HTTP utilisant le port du serveur et un hôte accepté : localhost, l’adresse LAN détectée ou l’hôte annoncé configuré. Ouvrir la télécommande intégrée à l’adresse affichée par Sound Show fournit une origine acceptée.

Une page personnalisée hébergée sur un autre appareil, site ou port de développement nécessite l’option Autoriser les origines externes décrite ci-dessous. Les clients natifs, dont l’exemple JavaScript en terminal de cette page, peuvent omettre Origin et n’ont pas besoin de cette option.

Autoriser les origines externes

Activez cette option si vous hébergez votre propre télécommande web séparément de Sound Show :

1. Dans Sound Show, ouvrez Options → Intégrations → Serveur distant, ou les réglages du panneau Distant.
2. Définissez un mot de passe distant, activez Autoriser les origines externes et appliquez les réglages. L’option est désactivée par défaut. Si elle manque, mettez Sound Show à jour vers une version qui la propose.
3. Ouvrez votre télécommande sur un appareil pouvant joindre l’ordinateur Sound Show. Connectez son WebSocket à l’adresse de Sound Show, et non à celle qui héberge votre page, puis envoyez le message hello habituel avec le mot de passe.

Par exemple, un contrôleur servi à l’adresse http://192.168.1.30:3000 peut se connecter à Sound Show à l’adresse ws://192.168.1.20:8080/ws. Votre script de navigateur peut commencer ainsi :

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.
  });
}

Remplacez l’adresse d’exemple par votre hôte et votre port. Attendez le premier state avant d’activer les commandes de lecture, puis utilisez la logique de traitement des instantanés de l’exemple JavaScript complet. Conservez le mot de passe dans la session du contrôleur plutôt que dans une page publique.

L’option accepte les origines de pages HTTP et HTTPS avec des hôtes ou ports différents. L’authentification par mot de passe et l’accès Pro restent obligatoires selon la configuration. Enregistrer un changement de cette option l’applique immédiatement et déconnecte les clients : reconnectez-vous et authentifiez-vous à nouveau. La désactiver termine aussi les sessions externes existantes. La télécommande intégrée fonctionne avec l’option désactivée.

Utilisez un mot de passe avec les origines externes

Cette option permet à tout site HTTP/HTTPS de tenter une connexion. Sans mot de passe distant, un site visité pourrait piloter Sound Show si votre navigateur peut joindre l’hôte. Activez l’option seulement si nécessaire et restez sur un réseau privé de confiance.

Les restrictions du navigateur restent applicables. Pour une installation LAN simple, servez votre page en HTTP. Une page HTTPS peut bloquer une connexion ws:// non chiffrée ; cette option ne fournit pas de point d’accès sécurisé wss://. Un contrôleur HTTPS nécessite une connexion sécurisée compatible avec le navigateur, par exemple un proxy TLS configuré séparément. Le navigateur peut aussi demander une autorisation d’accès au réseau local ou imposer d’autres restrictions. L’option n’ajoute pas d’en-têtes CORS aux points d’accès HTTP. Les pages file:// et les origines opaques null restent refusées : servez plutôt le fichier HTML local avec un serveur HTTP.

S’authentifier d’abord

Envoyez un message texte JSON dès l’ouverture du socket, dans les dix secondes. Incluez le mot de passe distant configuré dans Sound Show :

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

Pour un serveur dont l’accès sans mot de passe a été confirmé, omettez password ou utilisez une chaîne vide. features est facultatif ; demander runtime_snapshots fournit des mises à jour séparées de l’état des contrôles, des instructions, des listes de lecture et de l’activité des éléments.

En cas de succès, le serveur envoie :

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

Un message state complet suit automatiquement. Attendez-le avant de choisir une cible ou d’envoyer des commandes de spectacle. Les messages suivants remplacent soit tout l’état, soit une partie nommée. Il n’existe ni commande d’abonnement ni accusé de réussite par commande : l’état obtenu fait autorité.

En cas d’échec, attendez-vous à recevoir hello_rejected avec reason et message, puis à être déconnecté. Les motifs comprennent invalid_password, unsupported_version et rate_limited. Voir erreurs et limites.

Essayer un client JavaScript

Enregistrez ce code dans soundshow-client.mjs. Exécutez-le avec Node.js 22.12 ou ultérieur ; il utilise le client WebSocket intégré et ne nécessite aucun paquet. Il liste les éléments du projet et suit l’état en direct. Il ne lance la lecture que si vous passez un identifiant d’élément en argument de ligne de commande.

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

Dans PowerShell, définissez l’adresse et le mot de passe distant, puis listez les éléments :

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

Dans un terminal macOS ou Linux :

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

N’incluez pas votre vrai mot de passe dans les scripts partagés. Pour un serveur sans mot de passe, utilisez une valeur vide. Arrêtez le script avec Ctrl+C, copiez un identifiant d’élément du tableau et relancez-le pour déclencher cet élément une seule fois :

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

Cet exemple ne se reconnecte pas automatiquement et ne rejoue pas les commandes. Pour un contrôleur utilisé durablement, ajoutez le comportement de récupération de connexion et choisissez les commandes dans la référence.

Dépannage

Symptôme	Vérifications
Connexion refusée ou délai dépassé	Gardez Sound Show ouvert et démarrez le serveur. Vérifiez le port, l’adresse, le pare-feu et la communication entre les deux appareils sur le réseau.
Le serveur ne démarre pas	Vérifiez l’accès Pro, le journal de connexion et si une autre application utilise déjà le port.
HTTP 403 à la connexion	Vérifiez l’accès Pro et l’origine du navigateur. Pour une page hébergée sur un autre appareil, port ou site, activez Autoriser les origines externes dans Sound Show.
La télécommande personnalisée ne se connecte toujours pas après l’autorisation des origines externes	Vérifiez l’adresse de l’hôte Sound Show, le pare-feu et la console du navigateur. L’option ne contourne pas les restrictions de contenu mixte ou de réseau local ; utilisez la configuration LAN en HTTP décrite ci-dessus.
invalid_password	Utilisez le mot de passe du serveur distant, pas celui du compte Sound Show.
unsupported_version	Envoyez version: 2 et utilisez /ws. Les messages Sound Show 1 sont incompatibles.
HTTP 429 ou rate_limited	Arrêtez les tentatives ou commandes rapides et suivez les conseils de nouvelle tentative.
Connecté, mais aucun état	Envoyez d’abord hello. Recherchez un refus ou du JSON mal formé.
Une commande est sans effet	Résolvez les identifiants depuis le dernier état ; vérifiez les verrouillages, la disponibilité de la cible, la licence et les messages error.
L’affichage du contrôleur n’est plus à jour	Traitez les instantanés de domaine ainsi que les messages state complets. L’absence de messages ne signifie pas à elle seule une perte de connexion.

Migrer depuis Sound Show 1

Utilisez /ws à la place de /SoundShow, et le champ type en minuscules à la place de $type et des noms de classes .NET. Envoyez la négociation hello v2. Utilisez des identifiants de lecteur et de périphérique logique plutôt que des indices numériques de lecteur ou de sortie. Les icônes sont des ressources HTTP icon_url ; l’état arrive sous forme d’instantanés complets ou par domaine.