fishjam-platform

name: fishjam-platform description: "Fishjam platform fundamentals — domain model and auth shared by all SDKs. Covers glossary (room, peer, track, agent, streamer, viewer), the four room types (conference / audio_only / livestream / audio_only_livestream), two-tier auth (management vs peer tokens), Sandbox vs production, WebSocket-vs-webhook notifications and the 18-event taxonomy, REST endpoint list, and the end-to-end auth/join flow. Read this first for any Fishjam task. Trigger on: 'Fishjam', 'fishjam.io', 'fishjam.swmansion.com', 'fishjam dashboard', 'management token', 'peer token', 'sandbox API', 'useSandbox', 'room manager', 'livestream room', 'audio-only room', 'conference room', 'Fishjam ID', 'room types', 'auth flow', 'webhook', 'webhookUrl', 'FishjamWSNotifier', 'FishjamNotifier', 'notifier vs webhook', 'ServerMessage', 'peerAdded', 'peerConnected', 'roomCreated', 'refreshPeerToken', 'rest endpoint', 'OpenAPI', 'llms.txt'." license: MIT

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