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
| Type |
Direction |
Cost |
Use case |
conference |
many ↔ many |
base |
Meetings, classrooms, interactive webinars |
audio_only |
many ↔ many (audio only) |
75% off |
Voice rooms, podcasts, town halls |
livestream |
one → many |
20% off |
Live events, broadcasts, sports |
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)
- Backend → Fishjam:
createPeer(roomId) authenticated with the management token.
- Fishjam → Backend: returns
{ peer, peerToken }.
- Backend → Client: ships
peerToken to the frontend (never the management token).
- Client → Fishjam:
joinRoom({ peerToken }).
- 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
| File |
When to read |
glossary.md |
Define a term (room, peer, track, agent, etc.) precisely. |
room-types.md |
Pick conference vs audio_only vs livestream. Cost matrix. Codec defaults. |
auth-model.md |
Token types, lifetimes, refresh, livestream / MoQ tokens, full auth flow. |
sandbox-vs-production.md |
Use the Sandbox API for dev; migrate to a real backend. |
notifier-vs-webhook.md |
Pick WebSocket notifier or webhook receiver. |
notifications-taxonomy.md |
All 18 SDK-surfaced server notification events with payload shapes. |
rest-endpoints.md |
Raw HTTP surface — flat endpoint list, auth header, deprecation header. |
lifecycle-flow.md |
End-to-end client↔backend↔Fishjam sequence. |
llms-and-docs.md |
Pointers to upstream docs, llms.txt, OpenAPI spec, protobuf, dashboard. |
1---2name: fishjam-platform3description: "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'."4license: MIT5metadata:6 source: https://skillmd.com/skills/software-mansion-labs/fishjam-platform7---89# Fishjam Platform1011Software 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.1213This 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.1415A 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`.1617## Key concepts at a glance1819- **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.20- **Peer** — a participant in a room. Can be a `webrtc` client, an `agent` (server-side program), or a `vapi` voice agent.21- **Track** — one audio or video stream from a peer (camera, mic, screen share, etc.). One peer can publish multiple tracks.22- **Streamer / Viewer** — livestream-room-specific peer roles (one streamer, many viewers).23- **Fishjam ID** — your instance identifier; goes in both backend and client config.24- **Management Token** — long-lived admin secret; backend only.25- **Peer Token** — 24h, scoped to one peer in one room; safe for clients.2627Full definitions: `glossary.md`.2829## Room types3031| Type | Direction | Cost | Use case |32| ------------ | ------------------------ | ----------- | ------------------------------------------ |33| `conference` | many ↔ many | base | Meetings, classrooms, interactive webinars |34| `audio_only` | many ↔ many (audio only) | **75% off** | Voice rooms, podcasts, town halls |35| `livestream` | one → many | **20% off** | Live events, broadcasts, sports |3637`audio_only_livestream` is 75% off the livestream rate (equivalently, 80% off conference) — the cheapest mode for one-to-many audio.3839Detail + decision matrix: `room-types.md`.4041## Auth flow (5-step sketch)42431. **Backend → Fishjam:** `createPeer(roomId)` authenticated with the **management token**.442. **Fishjam → Backend:** returns `{ peer, peerToken }`.453. **Backend → Client:** ships `peerToken` to the frontend (never the management token).464. **Client → Fishjam:** `joinRoom({ peerToken })`.475. **Fishjam:** completes the WebRTC handshake; the peer is now in the room.4849Full diagram + token-refresh + livestream + MoQ tokens: `auth-model.md`.5051## Sandbox vs production5253- **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).54- **Production** — your own backend running a server SDK. Required for any real-world deployment.5556Migration recipe: `sandbox-vs-production.md`.5758## Notifications: WebSocket or webhook?5960Both 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:6162- **Long-lived worker, single process** → `FishjamWSNotifier` / `FishjamNotifier` (persistent socket).63- **Serverless, scaled out, behind a load balancer** → webhooks (set `webhookUrl` per room, decode binary protobuf).6465Detail: `notifier-vs-webhook.md` and `notifications-taxonomy.md`.6667## Key rules6869- Management token **never** leaves the backend. If it leaks, regenerate it.70- Peer tokens expire **24 hours** after creation. Refresh via `refreshPeerToken` / `refresh_peer_token` if you need longer.71- 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.72- 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.73- Livestream rooms accept exactly **one video track + one audio track**. Additional tracks are silently dropped.7475## References7677| File | When to read |78| --------------------------- | ------------------------------------------------------------------------------- |79| `glossary.md` | Define a term (room, peer, track, agent, etc.) precisely. |80| `room-types.md` | Pick `conference` vs `audio_only` vs `livestream`. Cost matrix. Codec defaults. |81| `auth-model.md` | Token types, lifetimes, refresh, livestream / MoQ tokens, full auth flow. |82| `sandbox-vs-production.md` | Use the Sandbox API for dev; migrate to a real backend. |83| `notifier-vs-webhook.md` | Pick WebSocket notifier or webhook receiver. |84| `notifications-taxonomy.md` | All 18 SDK-surfaced server notification events with payload shapes. |85| `rest-endpoints.md` | Raw HTTP surface — flat endpoint list, auth header, deprecation header. |86| `lifecycle-flow.md` | End-to-end client↔backend↔Fishjam sequence. |87| `llms-and-docs.md` | Pointers to upstream docs, llms.txt, OpenAPI spec, protobuf, dashboard. |