@nolag/stream

Live stream engagement with comments, reactions, and polls.

Overview

@nolag/stream adds realtime viewer engagement to any live stream. Viewers post comments, fire reaction bursts and vote in polls. Hosts see live viewer counts and can open and close polls on the fly. Reactions are aggregated into bursts, so a wave of emoji becomes one animation rather than a thousand. Your app owns one core NoLag client and injects it into NoLagStream; the wrapper attaches its behaviour to that connection. The video itself is yours; this SDK carries the interaction around it.

Key Features

• Comment stream with per-viewer author info
• Reaction bursts aggregated over a time window
• Live polls with vote tallies, closed with closePoll()
• Viewer counts per stream, from room presence
• Viewer roles (viewer, moderator, host) carried in presence
• Audience routing with filters, for example comments per language

How It Works

NoLagStream attaches to an injected @nolag/js-sdk client. Calling joinStream(name) returns a StreamRoom for the room name, subscribes to three topics in it and sets the viewer's presence there: comments for viewer comments, _reactions for emoji, and polls for poll creation, votes and close events. A comment store keeps recent comments in memory, and a poll manager tracks the active poll and its running totals.

Everything is published with echo: false: a viewer's own comments, reactions and votes are applied locally (a sent comment fires commentSent) and never come back from the broker.

Nothing is stored on the broker. A viewer who joins sees comments, reactions and poll events published from that moment on. Two consequences for polls:

• Each client counts the votes it receives itself. A viewer who joins after a poll opened does not know the poll and ignores its votes until a later poll event about it arrives; the close event carries the closer's totals.
• Nothing stops a viewer voting more than once. If votes must be counted exactly, count them on your backend, for example from a trigger webhook on polls configured in @nolag/core, which receives every published vote (see Webhooks).

Topics to grant

Grant these either in kraken's static token file or in a @nolag/core project document. See Static auth and Project document for the full formats.

{
  "tokens": {
    "viewer-token-1": {
      "actorTokenId": "viewer-1",
      "projectId": "demo-project",
      "organizationId": "demo-org",
      "actorType": "user",
      "allowedTopics": [
        {
          "pattern": "stream/live-stream/#",
          "permission": "pubSub",
          "app_id": "stream-app",
          "room_id": "room-live-stream",
          "room_slug": "live-stream"
        }
      ],
      "allowedLobbies": [{ "lobby_slug": "online", "lobby_id": "stream-online" }]
    }
  }
}

The blueprint's online lobby lists no rooms. In a @nolag/core project document, give it the stream rooms as above: core only shows a lobby to actors that can reach at least one of its rooms, so a lobby with no rooms is visible to nobody.

Things that matter with the static file:

• Every viewer token needs the same app_id.
• Viewer counts come from presence, and presence only works in rooms that have a rule carrying both room_slug and room_id.
• Without the allowedLobbies entry the lobby subscribe is refused: the wrapper emits an error (not_authorized) and ready() only resolves after the core SDK's 10 second lobby timeout.

Installation

npm install @nolag/stream @nolag/js-sdk

Quick Start

import { NoLag } from '@nolag/js-sdk'
import { NoLagStream } from '@nolag/stream'

const client = NoLag('viewer-token-1', { url: 'ws://localhost:8080/ws' })

const stream = new NoLagStream({
  client,
  appName: 'stream', // the App Slug you granted
  username: 'Alice',
  role: 'viewer',    // 'viewer' | 'moderator' | 'host'
})

await client.connect()   // the app owns the connection
await stream.ready()     // wrapper setup complete

const room = stream.joinStream('live-stream')

// Viewer count for this stream, from room presence (includes you)
room.on('viewerCountChanged', (count) => {
  console.log('Viewers:', count)
})

// Your own comment is added locally and fires commentSent
room.on('commentSent', (c) => console.log('Sent:', c.text))
room.sendComment('This is amazing!')

// Comments from other viewers
room.on('comment', (c) => {
  console.log(`[${c.username}]: ${c.text}`)
})

// Reactions arrive as bursts aggregated over reactionWindow (default 3000 ms)
room.sendReaction('🔥')
room.on('reaction', ({ emoji, count }) => {
  console.log(`${count}x ${emoji}`)
})

// Open a poll (typically from the host). It stays open until closePoll().
const poll = room.createPoll({
  question: 'Which feature next?',
  options: ['Dark mode', 'Mobile app', 'API access'],
})

// Vote by zero-based option index
room.votePoll(poll.id, 1)

room.on('pollUpdated', (p) => {
  console.log('Results:', p.options.map((o) => `${o.text}: ${o.votes}`))
})

// Close it when you are done
room.closePoll(poll.id)

// Teardown: the wrapper releases its handlers; the app closes the socket.
stream.detach()
client.disconnect()

Routing by audience

Filters split a stream's comments and polls by audience, for example by language. Reactions stay stream-wide.

// A Spanish-speaking viewer receives only comments and polls tagged 'es'
const esRoom = stream.joinStream('live-stream', { filters: ['es'] })

// Tag a comment for that audience
esRoom.sendComment('¡Increíble!', { filter: 'es' })

A viewer that joins without filters receives everything, including tagged comments. Filters are routing, not access control; see Filters.

Reconnects

When the core client reconnects, the wrapper re-subscribes the online lobby, re-sets its presence in every joined stream and then emits reconnected. It does not re-subscribe the comments, _reactions and polls topics: it was written for a broker that restores subscriptions on its own. Do not rely on that with kraken (see Production); re-issue the subscriptions yourself:

stream.on('reconnected', () => {
  for (const room of stream.getRooms()) {
    const ctx = client.setApp('stream').setRoom(room.name)
    const { comments, polls } = room.filters
    ctx.subscribe('comments', comments.length > 0 ? { filters: comments } : {})
    ctx.subscribe('polls', polls.length > 0 ? { filters: polls } : {})
    ctx.subscribe('_reactions')
  }
})

The wrapper's message handlers stay registered on the client, so subscribing again is enough. Comments and poll events published while the client was away are not delivered later.

API Reference

NoLagStream

The main class. Attaches to the injected core client and manages the app-wide viewer list and the stream rooms.

Constructor Options

Events

StreamRoom

Returned by joinStream(). Handles comments, reactions, polls, and per-stream viewer presence.

Events

Types