Docs/Live streaming & signaling

Live streaming & signaling

Video flows over WebRTC brokered by a socket.io signaling channel — media never transits the REST API.

Connect

Open a socket.io connection to /socket.io with handshake auth. Guests produce (camera); agents consume (view).

javascript

import { io } from "socket.io-client";

// Guest (camera) connection — code/token come from the invite URL:
// https://seeitlive.io/u/<code>#<token>
const socket = io("wss://api.seeitlive.io", {
  path: "/socket.io",
  auth: {
    code: "aZ3kQ9",
    token: "3n9F1Qk7xY2zR8vB5tW6uL0mC4pD1sA...",
    role: "guest",
  },
});

socket.on("connect", () => {
  socket.emit("getRouterRtpCapabilities", (ack) => {
    if (ack.ok) console.log(ack.data);
  });
});

// Broadcast from the server when another peer's track becomes available.
socket.on("new-producer", ({ producerId, kind }) => {
  // an agent connection would call "consume" here
});

Field	Description
`code`	The invitation code (guest) or agent-view code (agent) — the path segment before the `#` in `inviteUrl` or `agentViewUrl`.
`token`	The secret from the URL fragment after `#` — the invite token for a guest, the agent-view token for an agent.
`role`	`guest` or `agent`.

Roles

Guest — produces — The customer's browser connects with role: "guest" and produces its camera and microphone; it never consumes another peer's media.
Agent — consumes — The agent viewer connects with role: "agent" and consumes the guest's stream. Its agent-view token also grants (or withholds) permission to capture snapshots and draw annotations.

Session lifecycle

When the guest connects, the session's status moves to live and startedAt is set. When the guest disconnects, the status moves to ended, endedAt is set, and the SFU room is torn down — an agent disconnecting doesn't end the session.

Signaling events

The client emits requests and the server acknowledges each with a response — annotation is a fire-and-forget relay with no ack. Broadcasts are pushed by the server to every other peer in the session room.

Client requests

Event	Description
`getRouterRtpCapabilities`	Fetches the mediasoup router's RTP capabilities for the session, creating its SFU room on first use.
`createTransport`	Creates a WebRTC transport on the SFU — a send transport for guests, a receive transport for agents.
`connectTransport`	Completes DTLS negotiation for a transport created with `createTransport`.
`produce`	Guests only. Starts producing a media track on a send transport; other peers are notified via `new-producer`.
`getProducers`	Lists the producers currently available to consume in the session.
`consume`	Agents only. Starts consuming a producer's track on a receive transport.
`resumeConsumer`	Resumes a consumer that was created paused, so media starts flowing.
`annotation`	Relays an AR annotation stroke to the other peers in the session; requires the agent-view token's annotate permission.

Server broadcasts

Event	Description
`peer-joined`	Sent to the room when another peer — guest or agent — connects.
`peer-left`	Sent to the room when another peer disconnects.
`new-producer`	Sent to agents when the guest starts producing a new track, so they know to call `consume`.
`session-ended`	Sent to everyone in the room when the guest disconnects and the session ends.

Prefer the hosted viewer

Most integrations never touch signaling

Most integrations embed agentViewUrl in an iframe and never touch signaling directly — reach for this only when building a fully custom viewer. See Sessions for how to mint an agent token.

Errors Integrations