Conectarse a Sound Show 2

Controla Sound Show 2 desde tu propio script, controlador físico o integración. La API WebSocket permite iniciar elementos, controlar reproductores y salidas, ejecutar cues y enviar el estado en directo al controlador.

Esta guía describe el protocolo v2. Se conecta directamente a Sound Show en tu ordenador o red local. No necesitas una clave de API del sitio ni un token de acceso de cuenta. La edición de proyectos y la subida de archivos quedan fuera de esta API.

• Empieza aquí para conectarte y ejecutar un ejemplo.
• Consulta la referencia de comandos para añadir controles.
• Consulta estado y eventos para encontrar identificadores y mostrar el estado actual del espectáculo.

Activar el servidor

1. Abre Sound Show 2 en un ordenador de escritorio y carga el proyecto. El equipo anfitrión necesita acceso Pro, incluida una prueba Pro activa. Consulta Free y Pro.
2. Abre Opciones → Integraciones → Servidor remoto, o usa el panel Remoto y su botón de ajustes.
3. Elige un puerto (8080 por defecto) y una contraseña de al menos seis caracteres. Guarda los ajustes y usa una contraseña exclusiva para esta conexión.
4. Inicia el servidor con su botón de conexión. Si dejas la contraseña vacía, confirma la advertencia de acceso sin contraseña.
5. Copia la dirección que muestra Sound Show. Mantén Servir página web activado para usar también el control remoto integrado en el navegador; el punto de acceso WebSocket funciona con esa opción desactivada.

Usa una red de confianza

El servidor utiliza HTTP y WebSocket sin cifrar (ws://). Cualquiera con acceso a la red y la contraseña remota puede controlar el espectáculo; sin contraseña, cualquiera que alcance el servidor puede conectarse. Usa una red privada de confianza y no expongas el puerto a Internet.

Direcciones de conexión

El control remoto del navegador y la API WebSocket comparten equipo y puerto.

Finalidad	Ejemplo en el ordenador de Sound Show
Conexión WebSocket	ws://127.0.0.1:8080/ws
Control remoto integrado en el navegador	http://127.0.0.1:8080/
Estado del servidor	http://127.0.0.1:8080/health

Desde otro dispositivo, sustituye 127.0.0.1 por la dirección del ordenador de Sound Show, por ejemplo ws://192.168.1.20:8080/ws. Usa tu puerto configurado si difiere de 8080. localhost siempre se refiere al dispositivo que ejecuta el cliente.

El punto de acceso de estado devuelve un objeto como {"status":"ok","protocol_version":2}. Confirma que el servidor es accesible, pero no autentica al cliente.

Conectarse desde un navegador

Sound Show comprueba por defecto la cabecera Origin del navegador. Debe ser un origen HTTP con el puerto del servidor y un host aceptado: localhost, la dirección LAN detectada o el host anunciado configurado. Abrir el control remoto integrado en la dirección mostrada por Sound Show proporciona un origen aceptado.

Una página propia alojada en otro dispositivo, sitio o puerto de desarrollo necesita la opción Permitir orígenes externos descrita abajo. Los clientes nativos, incluido el ejemplo JavaScript de terminal de esta página, pueden omitir Origin y no necesitan esa opción.

Permitir orígenes externos

Activa esta opción si alojas tu control remoto web por separado de Sound Show:

1. Abre Opciones → Integraciones → Servidor remoto, o los ajustes del panel Remoto.
2. Establece una contraseña remota, activa Permitir orígenes externos y aplica los ajustes. La opción está desactivada por defecto. Si falta, actualiza Sound Show a una versión que la incluya.
3. Abre tu página de control remoto en un dispositivo que alcance el ordenador de Sound Show. Conecta el WebSocket a la dirección de Sound Show, no al servidor de tu página, y envía el mensaje hello habitual con la contraseña.

Por ejemplo, un controlador servido en http://192.168.1.30:3000 puede conectarse a Sound Show en ws://192.168.1.20:8080/ws. El script del navegador puede empezar así:

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

Sustituye la dirección de ejemplo por tu equipo y puerto. Espera al primer state antes de activar los controles de reproducción y usa el procesamiento de instantáneas del ejemplo JavaScript completo. Guarda la contraseña en la sesión del controlador, sin incrustarla en una página pública.

La opción acepta orígenes de páginas HTTP y HTTPS con otros equipos o puertos. La negociación con contraseña y el requisito Pro siguen vigentes. Guardar un cambio lo aplica inmediatamente y desconecta los clientes; vuelve a conectarte y autenticarte. Desactivarla también termina las sesiones externas existentes. El control remoto integrado funciona con la opción desactivada.

Usa contraseña con orígenes externos

Esto permite que cualquier sitio HTTP/HTTPS intente conectarse. Sin contraseña remota, un sitio visitado podría controlar Sound Show si el navegador alcanza el equipo. Activa la opción solo cuando la necesites y sigue usando una red privada de confianza.

Las restricciones del navegador siguen vigentes. Para una instalación LAN sencilla, sirve tu página por HTTP. Una página HTTPS puede bloquear una conexión ws:// sin cifrar; esta opción no proporciona un punto de acceso seguro wss://. Un controlador HTTPS necesita una conexión segura compatible con el navegador, por ejemplo un proxy TLS configurado aparte. Los navegadores también pueden exigir permiso de red local o imponer otras restricciones. La opción no añade cabeceras CORS a los puntos de acceso HTTP. Las páginas file:// y los orígenes opacos null siguen rechazándose: sirve el archivo HTML local mediante un servidor HTTP.

Autenticarse primero

Envía un mensaje de texto JSON inmediatamente después de abrir el socket, en un plazo de diez segundos. Incluye la contraseña remota configurada en Sound Show:

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

En un servidor cuyo acceso sin contraseña se haya confirmado, omite password o usa una cadena vacía. features es opcional; pedir runtime_snapshots proporciona actualizaciones separadas de controles, instrucciones, listas de reproducción y actividad de los elementos.

Si tiene éxito, el servidor envía:

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

Después llega automáticamente un mensaje state completo. Espéralo antes de seleccionar destinos o enviar comandos del espectáculo. Los mensajes posteriores sustituyen todo el estado o una parte identificada. No hay comando de suscripción ni confirmación de éxito por comando: el estado resultante es la referencia.

Si falla, recibirás hello_rejected con reason y message, seguido de desconexión. Los motivos incluyen invalid_password, unsupported_version y rate_limited. Consulta errores y límites.

Probar un cliente JavaScript

Guarda esto como soundshow-client.mjs y ejecútalo con Node.js 22.12 o posterior. Usa el cliente WebSocket integrado y no necesita paquetes. Lista los elementos del proyecto y sigue el estado en directo. Solo inicia la reproducción si pasas un identificador de elemento como argumento de línea de comandos.

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

En PowerShell, configura la dirección y la contraseña remota y lista los elementos:

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

En un terminal de macOS o Linux:

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

No incluyas tu contraseña real en scripts compartidos. Usa un valor vacío para un servidor sin contraseña. Detén el script con Ctrl+C, copia un identificador de la tabla y ejecútalo otra vez para activar ese elemento una sola vez:

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

El ejemplo no vuelve a conectarse automáticamente ni repite comandos. Para un controlador permanente, añade la recuperación de conexión y elige comandos de la referencia.

Solución de problemas

Síntoma	Qué comprobar
Conexión rechazada o tiempo agotado	Mantén Sound Show abierto e inicia el servidor. Revisa puerto, dirección, cortafuegos y comunicación de ambos dispositivos en la red.
El servidor no arranca	Revisa el acceso Pro, el registro de conexión y si otra aplicación ocupa el puerto.
HTTP 403 al conectar	Revisa el acceso Pro y el origen del navegador. Para una página en otro dispositivo, puerto o sitio, activa Permitir orígenes externos en Sound Show.
El control remoto propio sigue sin conectar	Revisa la dirección del equipo Sound Show, el cortafuegos y la consola del navegador. La opción no evita restricciones de contenido mixto o red local; usa la configuración LAN por HTTP descrita arriba.
invalid_password	Usa la contraseña del servidor remoto, no la de tu cuenta Sound Show.
unsupported_version	Envía version: 2 y usa /ws. Los mensajes de Sound Show 1 son incompatibles.
HTTP 429 o rate_limited	Detén los intentos o comandos rápidos y sigue las indicaciones para reintentar.
Conectado, pero sin estado	Envía primero hello. Comprueba si hay un rechazo o JSON mal formado.
Un comando no tiene efecto	Obtén los identificadores del estado más reciente; revisa bloqueos, disponibilidad del destino, licencia y mensajes error.
La pantalla del controlador se queda desactualizada	Procesa instantáneas de dominio y mensajes state completos. El silencio por sí solo no significa desconexión.

Migrar desde Sound Show 1

Usa /ws en lugar de /SoundShow, y el campo type en minúsculas en lugar de $type y nombres de clases .NET. Envía la negociación hello v2. Usa identificadores de reproductores y dispositivos lógicos en lugar de índices numéricos de reproductores o salidas. Los iconos son recursos HTTP icon_url; el estado llega en instantáneas completas o de dominio.