Fishjam Python Server Sdk

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

When to read which reference

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