fishjam-python-server-sdk

name	fishjam-python-server-sdk
description	Python server SDK for Fishjam — backends that create rooms, mint peer tokens, receive server notifications, and run voice agents. Use when writing a Python backend (FastAPI, Flask, Starlette, aiohttp) that talks to Fishjam, decorates a notification handler, decodes a Fishjam webhook, or builds an AI voice agent in Python. Trigger on: 'fishjam-server-sdk', 'pip install fishjam-server-sdk', 'from fishjam import', 'fishjam.FishjamClient', 'FishjamNotifier', 'on_server_notification', 'receive_binary', 'fishjam Agent', 'AgentSession', 'PeerOptions', 'RoomOptions', 'AgentOptions', 'AgentOutputOptions', 'OutgoingAudioTrackOptions', 'create_room', 'create_peer', 'create_agent', 'create_vapi_agent', 'create_livestream_streamer_token', 'create_moq_token', 'subscribe_peer', 'fastapi fishjam', 'flask fishjam', 'fishjam python', 'gemini fishjam python'. Python 3.10+. The REST client is synchronous; notifier and agent are async.
license	Apache-2.0

Fishjam Python Server SDK

fishjam-server-sdk on PyPI; import fishjam. Server-side Python SDK for Fishjam.

Read ../platform/SKILL.md first. It defines rooms, peers, tracks, the two-tier token model, and the WS-vs-webhook tradeoff that the Python SDK is built on.

Sync REST + async events

The architecture differs from the JS SDK in one important way:

• FishjamClient is synchronous. Methods like create_room, create_peer, delete_peer are plain def, not async def. Call them from sync routes or via run_in_executor from async contexts.
• FishjamNotifier is async (asyncio + websockets). Use @notifier.on_server_notification and await notifier.connect().
• Agent is async (async context manager — async with agent.connect() as session: ...).
• receive_binary(raw_bytes) is sync — call it directly inside an async route handler or a sync one.

Install + minimal flow

pip install fishjam-server-sdk
# or: uv add fishjam-server-sdk
# or: poetry add fishjam-server-sdk

import os
from fishjam import FishjamClient, PeerOptions

fishjam_client = FishjamClient(
    fishjam_id=os.environ['FISHJAM_ID'],
    management_token=os.environ['FISHJAM_MANAGEMENT_TOKEN'],
)

room = fishjam_client.create_room()
peer, peer_token = fishjam_client.create_peer(
    room.id,
    PeerOptions(metadata={'userId': 'user-123'}),
)
# ship `peer_token` to your client

Components

Component	What it does	Reference
FishjamClient (sync)	REST — rooms, peers, agents, livestream/MoQ tokens, subscribe modes.	client.md
FishjamNotifier (async)	Persistent WebSocket; one handler via decorator gets every event.	notifier.md
receive_binary(bytes) (sync)	Decode an HTTP webhook body to a typed event.	webhooks.md
Agent + AgentSession (async)	Server-side voice agent — async iter over incoming, await track.send_chunk(...).	agent.md

When to read which reference

Task	Reference
Any REST method on FishjamClient	client.md
Background WS task receiving events	notifier.md
HTTP route receiving webhook payloads	webhooks.md
Build a voice agent in Python	agent.md
Wire Gemini Live to an agent	gemini-integration.md
FastAPI / Flask wiring patterns	fastapi.md
Issue livestream / MoQ tokens	livestream-and-moq.md
Use manual subscribe mode	selective-subscriptions.md

Key rules

• Python 3.10+ required. SDK uses match, structural typing, PEP 604 unions.
• FishjamClient is sync. Calling it from async def works (it's a quick HTTP round-trip) but if you're in a hot async path consider await asyncio.to_thread(fishjam_client.create_peer, ...).
• FishjamNotifier does NOT auto-reconnect. Its connect() coroutine runs until the WS closes. Wrap it in a supervisor loop.
• One handler per notifier. @notifier.on_server_notification only stores the last function you decorate. Multi-dispatch in your one handler via match on the message type.
• Notifier handler can be sync or async. Both work — await result if inspect.isawaitable(result).
• Webhook decoding is sync. receive_binary(await req.body()) is fine inside an async FastAPI route.
• Agent is async-only. async with agent.connect() as session: is the only entry point.
• Management token stays on the server. Standard rule — never leak.

References

File	When to read
client.md	FishjamClient — every method, dataclass, error type.
notifier.md	FishjamNotifier, wait_ready, the decorator pattern, pattern-matching on event types.
webhooks.md	receive_binary, FastAPI / Flask receivers, security patterns.
agent.md	Agent, AgentSession, OutgoingAudioTrackOptions, receive() async iterator.
gemini-integration.md	fishjam.integrations.gemini, the GeminiIntegration singleton.
fastapi.md	FastAPI patterns (Depends-injected client, async webhook route, background notifier).
livestream-and-moq.md	create_livestream_streamer_token, create_livestream_viewer_token, create_moq_token.
selective-subscriptions.md	subscribe_peer / subscribe_tracks with subscribe_mode='manual' rooms.