Skip to content

API.md

Latest commit

 

History

History
111 lines (83 loc) · 3.34 KB

API.md

File metadata and controls

111 lines (83 loc) · 3.34 KB
Raw

Protocollo WebSocket e API RadioDJ

GRSTelePrompter non espone una REST API propria. Usa HTTP per pubblicare file statici e due protocolli WebSocket distinti.

WebSocket della dashboard RadioDJ

Endpoint predefinito:

ws://<host>:8081

Il server invia frame di testo contenenti JSON. Il client non deve inviare comandi.

Payload OK

{
  "status": "OK",
  "timestamp": 1783090800000,
  "artist": "Artista",
  "title": "Titolo",
  "album": "Album",
  "year": "2026",
  "category": "MUSIC",
  "subcategory": "POP",
  "intro": "0:08",
  "cueIntroRaw": 12.4,
  "introCountdownSec": 8,
  "elapsed": "0:04",
  "remaining": "3:26",
  "duration": "3:30",
  "sentAt": 1783090800000,
  "nextTracks": [
    {
      "artist": "Artista successivo",
      "title": "Prossimo titolo",
      "intro": "0:10",
      "duration": "3:05",
      "isSweep": false,
      "category": "MUSIC",
      "subcategory": "POP"
    }
  ]
}
Campo Tipo Significato
status stringa Sempre OK per un brano valido
timestamp, sentAt numero Unix time in millisecondi, generato dal backend
artist, title, album, year stringa Metadati, con placeholder se assenti
category, subcategory stringa o null Classificazione RadioDJ
intro stringa Countdown intro formattato m:ss
cueIntroRaw numero Cue intro originale in secondi
introCountdownSec numero Secondi residui prima del cue intro
elapsed, remaining, duration stringa Tempi normalizzati m:ss
nextTracks array Tracce successive richieste a /pitem

introCountdownSec è calcolato come:

remaining - (duration - cueIntroRaw)

Il risultato viene limitato a zero e arrotondato nel payload.

Payload NO_TRACK

Quando /np non contiene SongData.Title, il server invia:

{ "status": "NO_TRACK" }

In caso di errore completo della richiesta /np, l'errore viene scritto in console e non viene inviato un payload di errore. Se fallisce una singola /pitem, la posizione corrispondente contiene placeholder.

Chiamate in uscita verso RadioDJ

Il backend effettua richieste GET:

<RADIODJ_BASE_URL>/np?auth=<RADIODJ_AUTH>
<RADIODJ_BASE_URL>/pitem?auth=<RADIODJ_AUTH>&arg=<indice>

Il parametro auth è omesso quando RADIODJ_AUTH è vuoto. L'ordine dei parametri può variare; non deve essere considerato parte del contratto.

Le risposte attese sono XML con radice SongData. I campi letti includono Artist, Title, Album, Year, Duration, Elapsed, Remaining, CueIntro, SwName, CatName, Category, Cat, SubCategory, Subcategory e TrackType.

Una traccia successiva viene marcata isSweep=true se SwName contiene SWEEP oppure se tipo/sottocategoria è JINGLE o SWEEP.

WebSocket dei messaggi speaker

Endpoint predefinito:

ws://<host>:3020

Il protocollo è testo libero:

  • qualsiasi client può inviare una stringa;
  • il server memorizza l'ultimo valore ricevuto;
  • il valore viene trasmesso a tutti i client aperti;
  • un nuovo client riceve immediatamente l'ultimo valore;
  • non sono previsti envelope JSON, conferme o codici di errore.

Compatibilità

Il protocollo non è versionato. Qualunque modifica a nomi, tipi o semantica dei campi deve aggiornare contemporaneamente backend, frontend, questo documento e il changelog.