Overview

Real-time WebSocket API with lazy-spawned monitoring loops

The WebSocket API provides real-time, bidirectional communication with Cntrl Bridge. Unlike HTTP polling, updates are pushed to you instantly.

Why WebSocket?

Real-time Updates

Get system stats, media changes, and process lists pushed instantly.

Bidirectional

Send commands (media control, process kill) and receive responses in the same connection.

Zero Overhead

Monitoring loops only run when clients are subscribed. No CPU usage when idle.

Granular Control

Subscribe to exactly what you need. Only receive CPU data? Only subscribe to CPU.

Architecture: Lazy Loop Spawning

Efficient by Design

Cntrl Bridge uses demand-based monitoring. No polling loops run until a client subscribes. When the last subscriber disconnects, loops stop automatically.

Idle state (no WebSocket clients):
  └─ Zero monitoring loops running
  └─ Zero CPU overhead
  └─ Same as HTTP-only mode

First "stats" subscriber connects:
  └─ Stats monitoring loop spawns
  └─ Data broadcasts every 1 second

Last "stats" subscriber disconnects:
  └─ Stats loop stops automatically
  └─ Back to zero CPU usage

Benefits

Connection

Endpoint: ws://<host>:<port>/api/ws

const ws = new WebSocket("ws://192.168.1.100:9990/api/ws");

ws.onopen = () => {
  // Subscribe to topics you need
  ws.send(
    JSON.stringify({
      op: "subscribe",
      data: { topics: ["stats", "media"] },
    }),
  );
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log(message.type, message.data);
};

Topics

Stats \ System performance metrics (CPU, memory, GPU, disks, network). Media \ Now playing info, playback control, and volume changes. Processes \ Running processes list and process management.

Quick Reference

Subscribe

{ "op": "subscribe", "data": { "topics": ["stats", "media", "processes"] } }

Event Types

Default Intervals

Configurable

Intervals can be changed in config.json under websocket.stats.interval_ms, etc.