Ligar ao Sound Show 2

Controle o Sound Show 2 a partir do seu script, controlador físico ou integração. A API WebSocket permite iniciar elementos, controlar leitores e saídas, executar cues e transmitir o estado em direto ao controlador.

Este guia descreve o protocolo v2. A ligação é direta ao Sound Show no computador ou na rede local. Não precisa de uma chave de API do site nem de um token de acesso da conta. A edição de projetos e o envio de ficheiros não fazem parte desta API.

• Comece aqui para ligar e executar um exemplo.
• Consulte a referência de comandos para adicionar controlos.
• Consulte estado e eventos para encontrar identificadores e apresentar o estado atual do espetáculo.

Ativar o servidor

1. Abra o Sound Show 2 num computador e carregue o projeto. O anfitrião precisa de acesso Pro, incluindo uma avaliação Pro ativa. Consulte Free e Pro.
2. Abra Opções → Integrações → Servidor remoto, ou o painel Remoto e o respetivo botão de definições.
3. Escolha uma porta (8080 por predefinição) e uma palavra-passe com pelo menos seis caracteres. Guarde as definições e use uma palavra-passe exclusiva para esta ligação.
4. Inicie o servidor pelo botão de ligação. Se deixar a palavra-passe vazia, confirme o aviso de acesso sem palavra-passe.
5. Copie o endereço apresentado. Mantenha Disponibilizar página web ativo para usar também o controlo remoto integrado no navegador; o ponto de acesso WebSocket funciona com essa opção desativada.

Utilize uma rede de confiança

O servidor utiliza HTTP e WebSocket sem encriptação (ws://). Quem tiver acesso à rede e a palavra-passe remota pode controlar o espetáculo; sem palavra-passe, qualquer pessoa que alcance o servidor pode ligar-se. Utilize uma rede privada de confiança e não exponha a porta na Internet pública.

Endereços de ligação

O controlo remoto no navegador e a API WebSocket partilham o anfitrião e a porta.

Finalidade	Exemplo no computador do Sound Show
Ligação WebSocket	ws://127.0.0.1:8080/ws
Controlo remoto integrado no navegador	http://127.0.0.1:8080/
Estado do servidor	http://127.0.0.1:8080/health

Noutro dispositivo, substitua 127.0.0.1 pelo endereço do computador do Sound Show, por exemplo ws://192.168.1.20:8080/ws. Use a porta configurada se diferir de 8080. localhost refere-se sempre ao dispositivo onde o cliente está a executar.

O ponto de acesso de estado devolve um objeto como {"status":"ok","protocol_version":2}. Confirma que o servidor está acessível, mas não autentica o cliente.

Ligar a partir de um navegador

Por predefinição, o Sound Show verifica o cabeçalho Origin do navegador. Tem de ser uma origem HTTP com a porta do servidor e um anfitrião aceite: localhost, o endereço LAN detetado ou o anfitrião anunciado configurado. Abrir o controlo remoto integrado no endereço apresentado pelo Sound Show fornece uma origem aceite.

Uma página própria alojada noutro dispositivo, site ou porta de desenvolvimento precisa da opção Permitir origens externas, descrita abaixo. Clientes nativos, incluindo o exemplo JavaScript de terminal desta página, podem omitir Origin e não precisam da opção.

Permitir origens externas

Ative esta opção quando alojar o seu controlo remoto web separadamente do Sound Show:

1. Abra Opções → Integrações → Servidor remoto, ou as definições do painel Remoto.
2. Defina uma palavra-passe remota, ative Permitir origens externas e aplique as definições. A opção está desativada por predefinição. Se não existir, atualize para uma versão do Sound Show que a inclua.
3. Abra a página do controlo remoto num dispositivo que alcance o computador do Sound Show. Ligue o WebSocket ao endereço do Sound Show, não ao anfitrião da página, e envie a mensagem hello habitual com a palavra-passe.

Por exemplo, um controlador servido em http://192.168.1.30:3000 pode ligar ao Sound Show em ws://192.168.1.20:8080/ws. O script do navegador pode começar assim:

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

Substitua o endereço de exemplo pelo seu anfitrião e porta. Espere pelo primeiro state antes de ativar controlos de reprodução e use o processamento de instantâneos do exemplo JavaScript completo. Mantenha a palavra-passe na sessão do controlador, sem a incorporar numa página pública.

A opção aceita origens de páginas HTTP e HTTPS com outros anfitriões ou portas. A negociação com palavra-passe e o requisito Pro continuam a aplicar-se. Guardar uma alteração aplica-a imediatamente e desliga os clientes; volte a ligar e a autenticar. Desativar a opção também termina as sessões externas existentes. O controlo remoto integrado funciona com a opção desativada.

Use uma palavra-passe com origens externas

Isto permite que qualquer site HTTP/HTTPS tente ligar-se. Sem palavra-passe remota, um site visitado pode controlar o Sound Show se o navegador alcançar o anfitrião. Ative a opção apenas quando necessário e continue a usar uma rede privada de confiança.

As restrições do navegador continuam a aplicar-se. Numa configuração LAN simples, sirva a página por HTTP. Uma página HTTPS pode bloquear uma ligação ws:// sem encriptação; esta opção não disponibiliza um ponto de acesso seguro wss://. Um controlador HTTPS precisa de uma ligação segura compatível com o navegador, como um proxy TLS configurado à parte. O navegador também pode exigir permissão para a rede local ou impor outras restrições. A opção não adiciona cabeçalhos CORS aos pontos de acesso HTTP. Páginas file:// e origens opacas null continuam rejeitadas: disponibilize o ficheiro HTML local através de um servidor HTTP.

Autenticar primeiro

Envie uma mensagem de texto JSON imediatamente após abrir o socket, no prazo de dez segundos. Inclua a palavra-passe remota configurada no Sound Show:

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

Num servidor sem palavra-passe cujo acesso foi confirmado, omita password ou use uma cadeia vazia. features é opcional; pedir runtime_snapshots fornece atualizações separadas dos controlos, instruções, listas de reprodução e atividade dos elementos.

Se tiver êxito, o servidor envia:

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

Segue-se automaticamente uma mensagem state completa. Espere por ela antes de selecionar alvos ou enviar comandos de espetáculo. As mensagens posteriores substituem todo o estado ou uma parte identificada. Não há comando de subscrição nem confirmação de sucesso por comando: o estado resultante é a referência.

Em caso de falha, recebe hello_rejected com reason e message, seguido de desconexão. Os motivos incluem invalid_password, unsupported_version e rate_limited. Consulte erros e limites.

Experimentar um cliente JavaScript

Guarde como soundshow-client.mjs e execute com Node.js 22.12 ou posterior. Utiliza o cliente WebSocket integrado e não precisa de pacotes. Lista os elementos do projeto e acompanha o estado em direto. Só inicia a reprodução se passar um identificador de elemento como argumento da linha 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());

No PowerShell, defina o endereço e a palavra-passe remota e liste os elementos:

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

Num 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ão coloque a sua palavra-passe real em scripts partilhados. Num servidor sem palavra-passe, use um valor vazio. Pare o script com Ctrl+C, copie um identificador de elemento da tabela e execute novamente para o iniciar uma vez:

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

O exemplo não volta a ligar automaticamente nem repete comandos. Antes de criar um controlador permanente, adicione a recuperação de ligação e escolha comandos na referência.

Resolução de problemas

Sintoma	O que verificar
Ligação recusada ou tempo excedido	Mantenha o Sound Show aberto e inicie o servidor. Verifique porta, endereço, firewall e comunicação entre os dispositivos na rede.
O servidor não inicia	Verifique o acesso Pro, o registo de ligação e se outra aplicação ocupa a porta.
HTTP 403 ao ligar	Verifique o acesso Pro e a origem do navegador. Para uma página noutro dispositivo, porta ou site, ative Permitir origens externas no Sound Show.
O controlo remoto próprio continua sem ligar	Verifique o endereço do anfitrião Sound Show, a firewall e a consola do navegador. A opção não contorna restrições de conteúdo misto ou de rede local; use a configuração LAN por HTTP descrita acima.
invalid_password	Use a palavra-passe do servidor remoto, não a da conta Sound Show.
unsupported_version	Envie version: 2 e use /ws. As mensagens do Sound Show 1 são incompatíveis.
HTTP 429 ou rate_limited	Pare as tentativas ou comandos rápidos e siga as orientações para repetir a tentativa.
Ligado, mas sem estado	Envie primeiro hello. Procure uma rejeição ou JSON inválido.
Um comando não tem efeito	Resolva os identificadores a partir do estado mais recente; verifique bloqueios, disponibilidade do alvo, licença e mensagens error.
A apresentação do controlador fica desatualizada	Processe instantâneos de domínio e mensagens state completas. O silêncio, por si só, não significa perda de ligação.

Migrar do Sound Show 1

Use /ws em vez de /SoundShow e o campo type em minúsculas em vez de $type e nomes de classes .NET. Envie a negociação hello v2. Use identificadores de leitores e dispositivos lógicos em vez de índices numéricos de leitores ou saídas. Os ícones são recursos HTTP icon_url; o estado chega em instantâneos completos ou de domínio.