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.

Library Location: dist/lib/broadcast_standalone.js

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. 

<script type="module">
  import { BroadcastStream } from './dist/lib/broadcast_standalone.js';

  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', 'bonds'];
  await stream.start_recording(channels);

  // Stop streaming
  stream.stop();
</script>

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)
url The ingest endpoint URL (e.g., '/api/ingest')
Methods
start_recording(channels: string[]) Start recording and streaming. Channels are prefixed with 'asset:' and sent as keywords
stop() Stop recording and close the stream
Properties
streaming: boolean Whether currently streaming
BroadcastStreamCallbacks
on_status_change(status: ConnectionStatus) Called when connection status changes: 'disconnected' | 'connected' | 'streaming' | 'error'
on_listener_count(count: number) Called when stream ends with the number of listeners who received the audio
on_error(message: string) Called when an error occurs
on_recording_complete?(stats: object) Optional. Called when recording completes with bytes_streamed and dispatched_to stats
on_level_change?(level: number) Optional. Called with audio level 0.0-1.0 for VU meter updates

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
start(timeslice?: number) Start recording. Timeslice is chunk duration in ms (default: 100)
stop() Stop recording and release microphone
Properties
is_recording: boolean Whether currently recording
mime_type: string | null The MIME type being used for recording (e.g., "audio/webm;codecs=opus")

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
start(timeslice?: number) Start recording from the provided stream
stop() Stop recording

RecorderCallbacks

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

on_chunk(data: ArrayBuffer) Called for each audio chunk (based on timeslice)
on_stop() Called when recording stops
on_error(message: string) Called on errors (e.g., microphone denied)
on_level_change(level: number) Called with audio level 0.0-1.0 for VU meter

WebSocket Ingest Endpoint

WS /api/ingest/stream

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

  1. Connect WebSocket to /api/ingest/stream
  2. Send authentication message with broadcaster credentials
  3. Send stream start message with keywords
  4. Stream binary audio chunks
  5. Send stream end message when done

Client-to-Server Messages

Authenticate

Must be sent immediately after connection. Replace with your actual broadcaster credentials.

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

Stream Start

Signals the start of a broadcast. Keywords determine which listeners receive the audio.

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

Stream End

Signals the end of the broadcast.

{
  "type": "stream_end"
}

Ping

Keep the connection alive.

{
  "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

Authenticated

Authentication successful.

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

Stream Started

Server acknowledges stream start.

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

Stream Ended

Server acknowledges stream end.

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

Error

Sent when an error occurs.

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

Live Demo

This demo uses the BroadcastStream class to record and stream to /api/ingest. Select channels below, then start recording to broadcast.

Select Channels:
Ready
Audio Level