Player SDK

@antcdn/live-signaling gives you the live room without any interface. You get events and you draw whatever you like.

It works with any player. It does not depend on the AntCDN player, and it never touches the DOM.

npm install @antcdn/live-signaling

Connect

1
import { connectLiveRoom } from '@antcdn/live-signaling';
2

3
const room = connectLiveRoom({ streamId: 'ls_9f2a' });

connectLiveRoom opens the connection straight away and returns a LiveRoom.

Options

Option	Type	Default	Meaning
`streamId`	`string`	required	The live stream to join.
`baseUrl`	`string`	`https://worker.antcdn.net`	Override for self hosting or local development.
`sessionId`	`string`	generated	Identifies the viewer so they cannot answer twice.
`revealImmediately`	`boolean`	`false`	Show questions on arrival instead of waiting for the video. See below.
`webSocketFactory`	`function`	browser `WebSocket`	Inject a socket, for tests or non browser runtimes.

Events

Subscribe with on. It returns a function that unsubscribes.

1
const stop = room.on('question', (question) => showPoll(question));
2

3
// later
4
stop();

Event	Payload	Meaning
`welcome`	`{ streamId, viewerCount, hasVoted }`	Connected. Includes whatever state the room already had.
`question`	`LiveQuestion`	A question, at the moment it should be shown.
`tally`	`LiveTally`	Running results.
`closed`	`LiveTally`	The host closed the question. These are the final numbers.
`count`	`{ viewerCount }`	Audience size. Coalesced on the server, so this is not chatty.
`error`	`{ code, message }`	The server rejected something.
`status`	`{ connected, reconnecting }`	Transport state, for a reconnecting indicator.

Error codes

Code	Meaning
`already_voted`	This viewer has answered already. Common and harmless.
`no_active_question`	The question is not open. It probably just closed.
`unknown_option`	No option with that index.
`text_not_allowed`	The question does not take written answers.
`text_too_long`	Longer than 280 characters.
`bad_message`	The server could not read the message.

Telling the SDK where playback is

This is the step that makes questions appear at the right moment, and the one most easily missed.

Your player reads timed metadata out of the video. When it does, hand that to room.cue(). The SDK then reveals the question.

1
// Shaka Player
2
shakaPlayer.addEventListener('metadata', (event) => {
3
  const question = questionFromMetadata(event);
4
  if (question) room.cue(question);
5
});

The cue carries the whole question, so cue() shows it immediately. There is no round trip at the moment the question appears, and it still works if the socket has dropped.

If your encoder only gives you an id rather than the full payload, pass the id instead. The SDK then waits for the question to arrive over the socket before showing it:

1
room.cue('lsq_71c4a9');

Caution

If you never call cue(), questions never appear. The SDK holds them on purpose. To show questions as soon as they arrive, set revealImmediately: true. Use that only for hosts and moderators, who are not watching on delay. For ordinary viewers it brings back exactly the early reveal problem cues exist to prevent.

What the cue looks like

The cue is an ID3 TXXX frame whose text is the question as JSON:

{
  "id": "lsq_71c4a9",
  "prompt": "Which build should we ship first?",
  "options": ["The rewrite", "The patch"],
  "allowFreeText": false
}

Most players surface ID3 frames through a metadata event. Read the frame text, parse it, and pass the result to cue():

1
function questionFromMetadata(event) {
2
  const frame = event.payload ?? event;
3
  if (frame.key !== 'TXXX') return null;
4

5
  let question;
6
  try {
7
    question = JSON.parse(frame.data);
8
  } catch {
9
    return null; // unrelated timed metadata in the same stream
10
  }
11

12
  // Check the shape. This arrives from the media, so a malformed payload should be
13
  // dropped rather than drawn.
14
  if (typeof question?.id !== 'string' || !question.id.startsWith('lsq_')) return null;
15
  if (typeof question.prompt !== 'string' || question.prompt === '') return null;
16
  if (!Array.isArray(question.options) || question.options.length === 0) return null;
17
  if (!question.options.every((option) => typeof option === 'string')) return null;
18

19
  return question;
20
}

Other streams may put their own ID3 frames in the same video. Always check the shape before showing anything, or you will draw someone else’s metadata as a question.

Tip

The hosted player already does all of this. You only need this code if you are using a different player. See Using the hosted player.

Answering

1
room.vote(question.id, 1);                          // choose option B
2
room.vote(question.id, 1, 'and here is why');       // choose and write
3
room.vote(question.id, FREE_TEXT_ONLY, 'my answer'); // write only

FREE_TEXT_ONLY is exported from the package and is -1. Written answers are limited to MAX_FREE_TEXT_LENGTH, which is 280 characters, and are only accepted when the question was created with allowFreeText.

A viewer answers once. A second attempt comes back as an error with code already_voted.

Types

1
interface LiveQuestion {
2
  id: string;
3
  prompt: string;
4
  options: string[];
5
  allowFreeText?: boolean;
6
  cued?: boolean;
7
}
8

9
interface LiveTally {
10
  questionId: string;
11
  counts: number[];   // lines up with options
12
  total: number;
13
  textCount?: number; // written answers, counted separately
14
}

counts and total cover the options only. textCount is reported on its own because a written answer is not a choice between the options.

Closing the connection

1
room.close();

Call this when the viewer leaves the page or the player is torn down. The SDK reconnects on its own if the connection drops, so only call close() when you actually mean to stop.

A complete example

1
import { connectLiveRoom } from '@antcdn/live-signaling';
2
// questionFromMetadata is the helper shown above.
3

4
const room = connectLiveRoom({ streamId: 'ls_9f2a' });
5
let current = null;
6

7
room.on('question', (question) => {
8
  current = question;
9
  renderPoll(question);
10
});
11

12
room.on('tally', (tally) => {
13
  if (current && tally.questionId === current.id) renderResults(tally);
14
});
15

16
room.on('closed', (tally) => {
17
  renderFinalResult(tally);
18
  current = null;
19
});
20

21
room.on('error', ({ code, message }) => {
22
  if (code === 'already_voted') return; // harmless
23
  console.warn(message);
24
});
25

26
// Questions appear when playback reaches them.
27
shakaPlayer.addEventListener('metadata', (event) => {
28
  const question = questionFromMetadata(event);
29
  if (question) room.cue(question);
30
});
31

32
onAnswerClick((optionIndex) => room.vote(current.id, optionIndex));
33
window.addEventListener('pagehide', () => room.close());

Replaying over a recording

See Recordings.