API WebSocket

Endpoint

• URL : ws://127.0.0.1:8765
• Loopback uniquement - jamais exposé sur le réseau externe
• Origines autorisées : null (OBS Browser Source), file:// (production Electron), http://127.0.0.1:5173 (Vite dev)

Pour connecter un overlay OBS, voir la page dédiée.

Types de messages

Type	Direction	Description
command	client → serveur	Envoyer une action à une feature
response	serveur → client émetteur	Résultat de la commande
update	serveur → tous les clients	Diffusion d'état (broadcast)
error	serveur → tous les clients	Erreur runtime

Envoyer une commande

{
  "type": "command",
  "feature": "timer",
  "action": "start",
  "user": "OverlayTimer",
  "data": {
    "minutes": 5,
    "seconds": 0
  }
}

Champ	Requis	Description
type	Oui	Toujours "command"
feature	Oui	Identifiant du module
action	Oui	Action à exécuter
user	Non	Trace l'origine overlay dans les logs
data	Non	Paramètres de l'action

Tous les payloads sont validés par des schémas Zod (discriminated unions). Un payload invalide retourne immédiatement un VALIDATION_ERROR.

Réponse succès

{
  "type": "response",
  "feature": "timer",
  "action": "start",
  "ok": true,
  "source": "overlay",
  "origin": "OverlayTimer",
  "data": {
    "feature": "timer",
    "action": "start",
    "timestamp": "2026-03-10T21:00:00.000Z"
  },
  "timestamp": "2026-03-10T21:00:00.001Z"
}

Réponse erreur

{
  "type": "response",
  "feature": "timer",
  "action": "start",
  "ok": false,
  "source": "overlay",
  "code": "VALIDATION_ERROR",
  "message": "Timer duration must be greater than zero",
  "timestamp": "2026-03-10T21:00:00.001Z"
}

Codes d'erreur :

Code	Cause
VALIDATION_ERROR	Payload malformé, action inconnue, ou paramètre invalide
FEATURE_NOT_FOUND	Module non supporté par le runtime
INTERNAL_ERROR	Erreur d'exécution dans le handler (page non chargée, etc.)

Update broadcast

Diffusé automatiquement à tous les clients connectés à chaque changement d'état :

{
  "type": "update",
  "feature": "timer",
  "data": {
    "running": true,
    "durationSeconds": 300,
    "remainingSeconds": 297,
    "endAtMs": 1760000000000
  },
  "timestamp": "2026-03-10T21:00:03.000Z"
}

Matrice d'actions

timer

Action	Parametres
start	data.minutes (int), data.seconds (int)
stop	-
reset	-
get_state	-
set_overlay_config	data.enabled (bool), data.position (OverlayPosition), data.theme (string)

khinsider_radio

Action	Parametres
play / pause / next	-
shuffle	data.enabled (bool, optionnel)
volume	data.value (0–100)
get_state / activate / deactivate / diagnostic	-

smtc

Action	Parametres
start_monitoring / stop_monitoring / get_state	-
play / pause / toggle_play / next / previous / prev	-
set_overlay_config	data.enabled (bool), data.radioSource (auto | khinsider | smtc), data.position (OverlayPosition), data.showArtwork (bool), data.showProgress (bool), data.theme (RadioOverlayTheme)
select_source	data.radioSource (memes valeurs)

twitch

Action	Parametres
connect / disconnect	-
status / get_profile	-
planning:sync	- (synchronise le planning local avec Twitch)
planning:get_weeks	- (retourne le calendrier sur 9 semaines)
planning:create	data.startTime (RFC3339), data.durationMinutes (int), data.timezone (IANA), data.title (string), data.categoryId (string), data.categoryName (string), data.isRecurring (bool)
planning:update	data.id (string), plus optionnel : data.twitchId, data.startTime, data.durationMinutes, data.title, data.categoryId, data.categoryName, data.isCancelled
planning:delete	data.id (string), data.twitchId (string, optionnel)
twitch:search_categories	data.query (string)

discord_rpc

Action	Parametres
connect / disconnect / status	-

system

Action	Parametres
shutdown	- (IPC uniquement, pas autorise via WS)

Les actions systeme sont restreintes a l'IPC pour des raisons de securite. Les clients WebSocket ne peuvent pas declencher d'operations systeme.

Valeurs OverlayPosition

Le type OverlayPosition accepte l'un des 9 points d'ancrage :

top-left       top-center       top-right
middle-left    center           middle-right
bottom-left    bottom-center    bottom-right

Configuration d'overlay

Les features timer et smtc supportent une action set_overlay_config (smtc pilote l'unique overlay musique, qui couvre KHInsider et le lecteur systeme). Cela permet aux overlays et au dashboard de configurer la visibilite, la position et le theme sans redemarrer l'app. La configuration est persistee et diffusee a tous les clients connectes via l'evenement update de la feature.

Contrats d'etat

SmtcState

{
  connected: boolean
  isPlaying: boolean
  title: string
  artist: string
  albumTitle?: string
  artworkUrl?: string
  progressMs: number
  durationMs: number
  radioSource: 'khinsider' | 'smtc'
  mediaApp: string          // app id detecte (AUMID Windows / bus MPRIS), '' si inconnu
  mediaAppLabel: string     // libelle humain, '' si inconnu
  lastUpdatedAt: number
  platform?: string  // 'win32' | 'linux' | 'darwin'
  overlayConfig: {
    enabled: boolean
    radioSource: 'auto' | 'khinsider' | 'smtc'
    position: OverlayPosition
    showArtwork: boolean
    showProgress: boolean
    theme: RadioOverlayTheme
  }
}

KhinsiderState

{
  active: boolean
  isPlaying: boolean
  isShuffleEnabled?: boolean
  volume: number
  title: string
  game: string
  coverUrl: string
  currentTimeSeconds?: number
  durationSeconds?: number
  history: { title: string, game: string, coverUrl: string }[]
}

TimerState

{
  running: boolean;
  durationSeconds: number;
  remainingSeconds: number;
  endAtMs: number | null;
  overlayConfig: {
    enabled: boolean;
    position: OverlayPosition;
    theme: "streamoos" | "minimal-dark";
  }
}

TwitchState

{
  active: boolean
  connected: boolean
  displayName: string
  avatarUrl: string
  broadcasterId?: string
  planningWeeks?: PlanningWeek[]  // calendrier 9 semaines (voir types planning)
  lastAlert?: TwitchAlertData
  alertConfig?: TwitchAlertConfig
  eventSubConnected?: boolean
  recentEvents?: RecentEventsMap
}