SquawkWebSocket Library

The easiest way to integrate with Squawk is using the SquawkWebSocket library. This standalone ES module handles WebSocket connections, audio playback, and stream management.

Library Location: dist/lib/listener_websocket.js

Quick Start

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

  const audioContext = new (window.AudioContext || window.webkitAudioContext)();
  const client = new SquawkWebSocket('wss://example.com/api/ws', audioContext);

  client.on('connected', () => {
    console.log('Connected!');
    client.subscribe(['asset:equities']);
  });

  client.on('stream_start', (msg) => {
    console.log('Stream started:', msg.keywords);
  });

  client.connect();
</script>

API Reference

Constructor

new SquawkWebSocket(url: string, audioContext: AudioContext)

Methods

connect() Connect to the WebSocket server
disconnect() Disconnect from the server
subscribe(keywords) Subscribe to keywords
unsubscribe(keywords) Unsubscribe from keywords
ping() Send a keepalive ping
get_status() Get current connection status
unlock_audio() Unlock audio after user gesture (call in response to click/tap)
is_audio_locked() Check if audio is locked due to autoplay policy
on(event, handler) Listen for events

Events

connected WebSocket connected
disconnected WebSocket disconnected
stream_start Audio stream started (receives StreamStartMessage)
stream_end Audio stream ended
subscribed Subscription confirmed
clip_received Historical clip received
audio_locked Autoplay blocked - user interaction needed. Call unlock_audio() after user gesture.
audio_unlocked Audio successfully unlocked after user interaction
error Error occurred
status_change Connection status changed

WebSocket Endpoint

WS /api/ws

Connect to this endpoint to establish a WebSocket connection for receiving audio streams. The server accepts text commands (JSON) and sends both text messages (JSON metadata) and binary messages (audio data).

Client-to-Server Messages

Subscribe

Subscribe to one or more keywords to receive matching audio streams.

{
  "type": "subscribe",
  "keywords": ["asset:equities", "region:us"]
}

Unsubscribe

Remove subscriptions for specific keywords.

{
  "type": "unsubscribe",
  "keywords": ["asset:equities"]
}

Ping

Keep the connection alive. The server will respond with a pong.

{
  "type": "ping"
}

Server-to-Client Messages

Stream Start

Sent when a broadcaster starts streaming audio matching your subscribed keywords.

{
  "type": "stream_start",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "keywords": ["asset:equities"],
  "content_type": "audio/webm;codecs=opus",
  "timestamp": "2024-01-15T10:30:00Z"
}

Stream End

Sent when the broadcaster stops streaming.

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

Clip

Sent when a historical clip is available. Followed by binary audio data.

{
  "type": "clip",
  "clip_id": "clip-123",
  "keywords": ["asset:equities"],
  "content_type": "audio/webm",
  "size_bytes": 102456,
  "timestamp": "2024-01-15T10:00:00Z"
}

Subscribed

Confirmation that your subscription was registered.

{
  "type": "subscribed",
  "keywords": ["asset:equities"]
}

Error

Sent when an error occurs.

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

Binary Audio Data

After a stream_start message, the server sends binary audio chunks as ArrayBuffer messages. The SquawkWebSocket library automatically handles these and feeds them to the audio element.

Similarly, after a clip message, the next binary message contains the complete clip audio data.

Live Demo

This demo uses the SquawkWebSocket library to connect to /api/ws and subscribes to asset:equities. When a broadcaster transmits with this keyword, audio will play automatically.

Disconnected