Fishjam Platform

Fishjam Platform

Software Mansion's hosted WebRTC streaming toolkit. Fishjam takes care of media servers, peer networking, and codec negotiation so applications can build video conferencing, audio chat, and one-to-many livestreaming with sub-second latency.

This sub-skill defines the domain model, auth, room types, and notifications that every SDK builds on. Read it first; then drop into the SDK sub-skill you need.

A production Fishjam app always has a backend (server SDK) + a client (client SDK). The backend mints peer tokens; the client uses them to connect. For prototyping you can skip the backend with the Sandbox API — see sandbox-vs-production.md.

Key concepts at a glance

• Room — a collection of peers exchanging tracks. Three primary room types: conference (default, bidirectional), audio_only (75% cheaper, video silently dropped), livestream (one streamer, many viewers, <300 ms). audio_only_livestream combines the audio-only and livestream discounts.
• Peer — a participant in a room. Can be a webrtc client, an agent (server-side program), or a vapi voice agent.
• Track — one audio or video stream from a peer (camera, mic, screen share, etc.). One peer can publish multiple tracks.
• Streamer / Viewer — livestream-room-specific peer roles (one streamer, many viewers).
• Fishjam ID — your instance identifier; goes in both backend and client config.
• Management Token — long-lived admin secret; backend only.
• Peer Token — 24h, scoped to one peer in one room; safe for clients.

Full definitions: glossary.md.

Room types

audio_only_livestream is 75% off the livestream rate (equivalently, 80% off conference) — the cheapest mode for one-to-many audio.

Detail + decision matrix: room-types.md.

Auth flow (5-step sketch)

1. Backend → Fishjam: createPeer(roomId) authenticated with the management token.
2. Fishjam → Backend: returns { peer, peerToken }.
3. Backend → Client: ships peerToken to the frontend (never the management token).
4. Client → Fishjam: joinRoom({ peerToken }).
5. Fishjam: completes the WebRTC handshake; the peer is now in the room.

Full diagram + token-refresh + livestream + MoQ tokens: auth-model.md.

Sandbox vs production

• Sandbox API — no-auth HTTP backend hosted by Fishjam. For prototyping only. Generated URL must never be shipped in a production build (anyone with it can create rooms on your behalf).
• Production — your own backend running a server SDK. Required for any real-world deployment.

Migration recipe: sandbox-vs-production.md.

Notifications: WebSocket or webhook?

Both deliver the same 18-event set surfaced by the SDKs (room/peer/track/streamer/viewer/channel lifecycle — the underlying protobuf ServerMessage carries additional oneof fields the SDKs intentionally ignore). Pick by deployment shape:

• Long-lived worker, single process → FishjamWSNotifier / FishjamNotifier (persistent socket).
• Serverless, scaled out, behind a load balancer → webhooks (set webhookUrl per room, decode binary protobuf).

Detail: notifier-vs-webhook.md and notifications-taxonomy.md.

Key rules

• Management token never leaves the backend. If it leaks, regenerate it.
• Peer tokens expire 24 hours after creation. Refresh via refreshPeerToken / refresh_peer_token if you need longer.
• Sandbox API URL is not a secret in the cryptographic sense, but anyone holding it can create rooms — treat it like a dev credential and rotate from the Dashboard if exposed.
• Conference is the default room type. Use audio_only for voice apps (much cheaper). Use livestream only when one peer broadcasts and others only watch.
• Livestream rooms accept exactly one video track + one audio track. Additional tracks are silently dropped.

References