Broadcaster Documentation

Authentication

All connections require a valid JWT token. Obtain a token by logging in via POST /api/auth/login with username and password. The token must be included in all requests:

HTTP Ingest (BroadcastStream)

Include an Authorization: Bearer <jwt> header in the POST request to /api/ingest. The built-in BroadcastStream adds this automatically when using the app.

WebSocket Ingest

Append ?token=<jwt> to the WebSocket URL:

const wsUrl = 'wss://example.com/api/ingest/stream?token=' + encodeURIComponent(token)
const ws = new WebSocket(wsUrl)

Get a Token

SquawkBroadcast Library

The easiest way to integrate with Squawk broadcasting is using the BroadcastStream class. This standalone ES module handles microphone access, audio recording, and HTTP streaming to the Squawk ingest endpoint.

Quick Start with BroadcastStream

BroadcastStream is the recommended high-level API for broadcasting. It manages the microphone, streams audio to /api/ingest, and provides connection status updates.

import { BroadcastStream } from 'https://example.com/lib/broadcast_standalone.js'

// Store token for auth_headers()
const token = 'your_jwt_token'
sessionStorage.setItem('squawk_token', token)

const stream = new BroadcastStream('/api/ingest', {
  on_status_change: (status) => {
    console.log('Status:', status) // 'disconnected' | 'connected' | 'streaming' | 'error'
    document.getElementById('status').textContent = status
  },
  on_listener_count: (count) => {
    console.log('Stream reached', count, 'listeners')
  },
  on_error: (message) => {
    console.error('Error:', message)
  },
  on_recording_complete: (stats) => {
    console.log(`Streamed ${stats.bytes_streamed} bytes to ${stats.dispatched_to} listeners`)
  },
  on_level_change: (level) => {
    // Update VU meter (0.0 to 1.0)
    document.getElementById('level').style.width = `${level * 100}%`
  },
})

// Start streaming to specific channels
const channels = ['equities', 'fixed_income']
await stream.start_recording(channels)

// Stop streaming
stream.stop()

API Reference

BroadcastStream

High-level class that manages the complete broadcast workflow. Handles microphone access, HTTP streaming to the ingest endpoint, and connection state management.

Constructor

new BroadcastStream(url: string, callbacks: BroadcastStreamCallbacks)

Methods

Properties

BroadcastStreamCallbacks

MicrophoneRecorder

High-level recorder that handles microphone access and audio recording. Manages the MediaStream lifecycle and provides a simple start/stop interface.

Constructor

new MicrophoneRecorder(callbacks: RecorderCallbacks)

Methods

Properties

AudioRecorder

Lower-level recorder that works with an existing MediaStream. Use this if you need more control over the audio source.

Constructor

new AudioRecorder(stream: MediaStream, callbacks: RecorderCallbacks)

Methods

RecorderCallbacks

All callbacks are optional but at minimum you should handle on_chunk.

WebSocket Ingest Endpoint

Connect to this endpoint to stream audio to the Squawk server as a broadcaster. The server expects a JSON authentication message followed by binary audio chunks.

Connection Flow

Client-to-Server Messages

{
  "type": "auth",
  "broadcaster_id": "your_broadcaster_id",
  "api_key": "your_api_key"
}

{
  "type": "stream_start",
  "keywords": ["asset:equities", "region:us"],
  "content_type": "audio/webm;codecs=opus"
}

{
  "type": "stream_end"
}

{
  "type": "ping"
}

Binary Audio Data

After sending the stream_start message, send audio chunks as binary ArrayBuffer messages. The server accepts WebM/Opus format. Use the MicrophoneRecorder class to handle recording and chunking.

Server-to-Client Messages

{
  "type": "authenticated",
  "broadcaster_id": "your_broadcaster_id"
}

{
  "type": "stream_started",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "keywords": ["asset:equities"]
}

{
  "type": "stream_ended",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "type": "error",
  "message": "Invalid authentication"
}

Live Demo