Skip to main content
Version: Next

fishjam

Submodules​

FishjamClient​

class FishjamClient(Client):

Allows for managing rooms.

init​

def __init__(fishjam_id: str, management_token: str)

Create a FishjamClient instance.

Does not contact the Fishjam backend — use :meth:create_and_verify or :meth:check_credentials to verify credentials live.

Args:

  • fishjam_id: The unique identifier for the Fishjam instance.
  • management_token: The token used for authenticating management operations.

create_and_verify​

def create_and_verify(
    cls,
    *,
    fishjam_id: str,
    management_token: str
) -> FishjamClient

Construct a FishjamClient and verify its credentials against the backend.

Args:

  • fishjam_id: The unique identifier for the Fishjam instance.
  • management_token: The token used for authenticating management operations.

Returns:

  • FishjamClient: A client whose credentials have been verified.

Raises:

  • InvalidFishjamCredentialsError: If the token is rejected.

check_credentials​

def check_credentials(self) -> None

Verify the management token via a single /validate call.

Raises:

  • InvalidFishjamCredentialsError: If the token is rejected.

create_peer​

def create_peer(
    self,
    room_id: str,
    options: PeerOptions | None = None
) -> tuple[Peer, str]

Creates a peer in the room.

Args:

  • room_id: The ID of the room where the peer will be created.
  • options: Configuration options for the peer. Defaults to None.

Returns:

  • A tuple containing:
    • Peer: The created peer object.
    • str: The peer token needed to authenticate to Fishjam.

create_agent​

def create_agent(
    self,
    room_id: str,
    options: AgentOptions | None = None
)

Creates an agent in the room.

Args:

  • room_id: The ID of the room where the agent will be created.
  • options: Configuration options for the agent. Defaults to None.

Returns:

  • Agent: The created agent instance initialized with peer ID, room ID, token, and Fishjam URL.

create_vapi_agent​

def create_vapi_agent(
    self,
    room_id: str,
    options: PeerOptionsVapi
) -> Peer

Creates a vapi agent in the room.

Args:

  • room_id: The ID of the room where the vapi agent will be created.
  • options: Configuration options for the vapi peer.

Returns:

    • Peer: The created peer object.

create_room​

def create_room(
    self,
    options: RoomOptions | None = None
) -> Room

Creates a new room.

Args:

  • options: Configuration options for the room. Defaults to None.

Returns:

  • Room: The created Room object.

get_all_rooms​

def get_all_rooms(self) -> list[Room]

Returns list of all rooms.

Returns:

  • list[Room]: A list of all available Room objects.

get_room​

def get_room(self, room_id: str) -> Room

Returns room with the given id.

Args:

  • room_id: The ID of the room to retrieve.

Returns:

  • Room: The Room object corresponding to the given ID.

delete_peer​

def delete_peer(self, room_id: str, peer_id: str) -> None

Deletes a peer from a room.

Args:

  • room_id: The ID of the room the peer belongs to.
  • peer_id: The ID of the peer to delete.

delete_room​

def delete_room(self, room_id: str) -> None

Deletes a room.

Args:

  • room_id: The ID of the room to delete.

refresh_peer_token​

def refresh_peer_token(self, room_id: str, peer_id: str) -> str

Refreshes a peer token.

Args:

  • room_id: The ID of the room.
  • peer_id: The ID of the peer whose token needs refreshing.

Returns:

  • str: The new peer token.

create_livestream_viewer_token​

def create_livestream_viewer_token(self, room_id: str) -> str

Generates a viewer token for livestream rooms.

Args:

  • room_id: The ID of the livestream room.

Returns:

  • str: The generated viewer token.

create_livestream_streamer_token​

def create_livestream_streamer_token(self, room_id: str) -> str

Generates a streamer token for livestream rooms.

Args:

  • room_id: The ID of the livestream room.

Returns:

  • str: The generated streamer token.

create_moq_access​

def create_moq_access(
    self,
    publish_path: str | None = None,
    subscribe_path: str | None = None
) -> MoqAccess

Generates MoQ relay connection details.

Args:

  • publish_path: Path the access grants publish access to.
  • subscribe_path: Path the access grants subscribe access to.

Returns:

  • MoqAccess: The relay connection details, containing the
  • connection_url (with the JWT embedded as a ?jwt= query
  • parameter) and the token itself.

subscribe_peer​

def subscribe_peer(self, room_id: str, peer_id: str, target_peer_id: str)

Subscribes a peer to all tracks of another peer.

Args:

  • room_id: The ID of the room.
  • peer_id: The ID of the subscribing peer.
  • target_peer_id: The ID of the peer to subscribe to.

subscribe_tracks​

def subscribe_tracks(self, room_id: str, peer_id: str, track_ids: list[str])

Subscribes a peer to specific tracks of another peer.

Args:

  • room_id: The ID of the room.
  • peer_id: The ID of the subscribing peer.
  • track_ids: A list of track IDs to subscribe to.

Inherited Members​

  • Client:
    • client
    • warnings_shown

FishjamNotifier​

class FishjamNotifier:

Allows for receiving WebSocket messages from Fishjam.

init​

def __init__(fishjam_id: str, management_token: str)

Create a FishjamNotifier instance with an ID and management token.

on_server_notification​

def on_server_notification(
    self,
    handler: Union[Callable[[Union[ServerMessageRoomCreated, ServerMessageRoomDeleted, ServerMessageRoomCrashed, ServerMessagePeerAdded, ServerMessagePeerDeleted, ServerMessagePeerConnected, ServerMessagePeerDisconnected, ServerMessagePeerMetadataUpdated, ServerMessagePeerCrashed, ServerMessageStreamerConnected, ServerMessageStreamerDisconnected, ServerMessageChannelAdded, ServerMessageChannelRemoved, ServerMessageViewerConnected, ServerMessageViewerDisconnected, ServerMessageTrackAdded, ServerMessageTrackRemoved, ServerMessageTrackMetadataUpdated]], NoneType], Callable[[Union[ServerMessageRoomCreated, ServerMessageRoomDeleted, ServerMessageRoomCrashed, ServerMessagePeerAdded, ServerMessagePeerDeleted, ServerMessagePeerConnected, ServerMessagePeerDisconnected, ServerMessagePeerMetadataUpdated, ServerMessagePeerCrashed, ServerMessageStreamerConnected, ServerMessageStreamerDisconnected, ServerMessageChannelAdded, ServerMessageChannelRemoved, ServerMessageViewerConnected, ServerMessageViewerDisconnected, ServerMessageTrackAdded, ServerMessageTrackRemoved, ServerMessageTrackMetadataUpdated]], Coroutine[Any, Any, None]]]
)

Decorator for defining a handler for Fishjam notifications.

Args:

  • handler: The function to be registered as the notification handler.

Returns:

  • NotificationHandler: The original handler function (unmodified).

connect​

def connect(self)

Connects to Fishjam and listens for all incoming messages.

It runs until the connection isn't closed.

The incoming messages are handled by the functions defined using the on_server_notification decorator.

The handler have to be defined before calling connect, otherwise the messages won't be received.

wait_ready​

def wait_ready(self) -> None

Waits until the notifier is connected and authenticated to Fishjam.

If already connected, returns immediately.

decode_server_notifications​

def decode_server_notifications(
    binary: bytes
) -> List[Union[ServerMessageRoomCreated, ServerMessageRoomDeleted, ServerMessageRoomCrashed, ServerMessagePeerAdded, ServerMessagePeerDeleted, ServerMessagePeerConnected, ServerMessagePeerDisconnected, ServerMessagePeerMetadataUpdated, ServerMessagePeerCrashed, ServerMessageStreamerConnected, ServerMessageStreamerDisconnected, ServerMessageChannelAdded, ServerMessageChannelRemoved, ServerMessageViewerConnected, ServerMessageViewerDisconnected, ServerMessageTrackAdded, ServerMessageTrackRemoved, ServerMessageTrackMetadataUpdated]]

Decode a received protobuf payload into a list of notifications.

Handles both single notifications and batches transparently: a single notification is returned as a one-element list, a batch is unpacked into its members (in order), and anything unsupported yields an empty list.

The available notifications are listed in the fishjam.events module.

Args:

  • binary: The raw binary data received from the webhook.

Returns:

  • list[AllowedNotification]: The decoded notifications, in order. Empty when the payload carries no supported notification.

receive_binary​

def receive_binary(
    binary: bytes
) -> Union[ServerMessageRoomCreated, ServerMessageRoomDeleted, ServerMessageRoomCrashed, ServerMessagePeerAdded, ServerMessagePeerDeleted, ServerMessagePeerConnected, ServerMessagePeerDisconnected, ServerMessagePeerMetadataUpdated, ServerMessagePeerCrashed, ServerMessageStreamerConnected, ServerMessageStreamerDisconnected, ServerMessageChannelAdded, ServerMessageChannelRemoved, ServerMessageViewerConnected, ServerMessageViewerDisconnected, ServerMessageTrackAdded, ServerMessageTrackRemoved, ServerMessageTrackMetadataUpdated, List[Union[ServerMessageRoomCreated, ServerMessageRoomDeleted, ServerMessageRoomCrashed, ServerMessagePeerAdded, ServerMessagePeerDeleted, ServerMessagePeerConnected, ServerMessagePeerDisconnected, ServerMessagePeerMetadataUpdated, ServerMessagePeerCrashed, ServerMessageStreamerConnected, ServerMessageStreamerDisconnected, ServerMessageChannelAdded, ServerMessageChannelRemoved, ServerMessageViewerConnected, ServerMessageViewerDisconnected, ServerMessageTrackAdded, ServerMessageTrackRemoved, ServerMessageTrackMetadataUpdated]], NoneType]

Transforms a received protobuf notification into a notification instance.

.. deprecated::

  • Use decode_server_notifications instead, which always returns a list
  • and handles batched payloads with a single, consistent return type.

The available notifications are listed in fishjam.events module.

Args:

  • binary: The raw binary data received from the webhook.

Returns:

  • AllowedNotification: A single notification when the payload carries one.
  • list[AllowedNotification]: The unpacked notifications, in order, when the payload is a batch (webhook batching enabled).
  • None: When the payload is not a supported notification.

PeerMetadata​

class PeerMetadata:

Custom metadata set by the peer

Example:

  • {'name': 'FishjamUser'}

init​

def __init__()

Method generated by attrs for class PeerMetadata.

additional_properties​

additional_properties: dict[str, typing.Any]

to_dict​

def to_dict(self) -> dict[str, typing.Any]

from_dict​

def from_dict(cls: type[~T], src_dict: Mapping[str, typing.Any]) -> ~T

additional_keys​

additional_keys: list[str]

PeerOptions​

class PeerOptions:

Options specific to a WebRTC Peer.

Attributes:

  • metadata: Peer metadata.
  • subscribe_mode: Configuration of peer's subscribing policy.

init​

def __init__(
    metadata: dict[str, typing.Any] | None = None,
    subscribe_mode: Literal['auto', 'manual'] = 'auto'
)

metadata​

metadata: dict[str, typing.Any] | None = None

Peer metadata

subscribe_mode​

subscribe_mode: Literal['auto', 'manual'] = 'auto'

Configuration of peer's subscribing policy

PeerOptionsVapi​

class PeerOptionsVapi:

Options specific to the VAPI peer

Attributes:

  • api_key (str): VAPI API key
  • call_id (str): VAPI call ID
  • subscribe_mode (SubscribeMode | Unset): Configuration of peer's subscribing policy

init​

def __init__(
    api_key: str,
    call_id: str,
    subscribe_mode: SubscribeMode | Unset = <Unset object>
)

Method generated by attrs for class PeerOptionsVapi.

api_key​

api_key: str

call_id​

call_id: str

subscribe_mode​

subscribe_mode: SubscribeMode | Unset

to_dict​

def to_dict(self) -> dict[str, typing.Any]

from_dict​

def from_dict(cls: type[~T], src_dict: Mapping[str, typing.Any]) -> ~T

RoomOptions​

class RoomOptions:

Description of a room options.

Attributes:

  • max_peers: Maximum amount of peers allowed into the room.
  • video_codec: Enforces video codec for each peer in the room.
  • webhook_url: URL where Fishjam notifications will be sent.
  • room_type: The use-case of the room. If not provided, this defaults to conference.
  • public: True if livestream viewers can omit specifying a token.
  • batch_webhook_notifications: If true, webhook notifications for this room are coalesced into a single NotificationBatch per HTTP send instead of one request per notification.

init​

def __init__(
    max_peers: int | None = None,
    video_codec: Optional[Literal['h264', 'vp8']] = None,
    webhook_url: str | None = None,
    room_type: Literal['conference', 'audio_only', 'livestream', 'full_feature', 'broadcaster', 'audio_only_livestream'] = 'conference',
    public: bool = False,
    batch_webhook_notifications: bool = False
)

max_peers​

max_peers: int | None = None

Maximum amount of peers allowed into the room

video_codec​

video_codec: Optional[Literal['h264', 'vp8']] = None

Enforces video codec for each peer in the room

webhook_url​

webhook_url: str | None = None

URL where Fishjam notifications will be sent

room_type​

room_type: Literal['conference', 'audio_only', 'livestream', 'full_feature', 'broadcaster', 'audio_only_livestream'] = 'conference'

The use-case of the room. If not provided, this defaults to conference.

public​

public: bool = False

True if livestream viewers can omit specifying a token.

batch_webhook_notifications​

batch_webhook_notifications: bool = False

Coalesce webhook notifications into a single NotificationBatch per send.

AgentOptions​

class AgentOptions:

Options specific to an Agent Peer.

Attributes:

  • output: Configuration for the agent's output options.
  • subscribe_mode: Configuration of peer's subscribing policy.

init​

def __init__(
    output: AgentOutputOptions = <factory>,
    subscribe_mode: Literal['auto', 'manual'] = 'auto'
)

output​

output: AgentOutputOptions

subscribe_mode​

subscribe_mode: Literal['auto', 'manual'] = 'auto'

AgentOutputOptions​

class AgentOutputOptions:

Options of the desired format of audio tracks going from Fishjam to the agent.

Attributes:

  • audio_format: The format of the audio stream (e.g., 'pcm16').
  • audio_sample_rate: The sample rate of the audio stream.

init​

def __init__(
    audio_format: Literal['pcm16'] = 'pcm16',
    audio_sample_rate: Literal[16000, 24000] = 16000
)

audio_format​

audio_format: Literal['pcm16'] = 'pcm16'

audio_sample_rate​

audio_sample_rate: Literal[16000, 24000] = 16000

Room​

class Room:

Description of the room state.

Attributes:

  • config: Room configuration.
  • id: Room ID.
  • peers: List of all peers.

init​

def __init__(
    config: RoomConfig,
    id: str,
    peers: list[Peer]
)

config​

config: RoomConfig

Room configuration

id​

id: str

Room ID

peers​

peers: list[Peer]

List of all peers

Peer​

class Peer:

Describes peer status

Attributes:

  • id (str): Assigned peer id Example: 4a1c1164-5fb7-425d-89d7-24cdb8fff1cf.
  • metadata (None | PeerMetadata): Custom metadata set by the peer Example: {'name': 'FishjamUser'}.
  • status (PeerStatus): Informs about the peer status Example: disconnected.
  • subscribe_mode (SubscribeMode): Configuration of peer's subscribing policy
  • subscriptions (Subscriptions): Describes peer's subscriptions in manual mode
  • tracks (list[Track]): List of all peer's tracks
  • type_ (PeerType): Peer type Example: webrtc.

init​

def __init__(
    id: str,
    metadata: None | PeerMetadata,
    status: PeerStatus,
    subscribe_mode: SubscribeMode,
    subscriptions: Subscriptions,
    tracks: list[Track],
    type_: PeerType
)

Method generated by attrs for class Peer.

id​

id: str

metadata​

metadata: None | PeerMetadata

status​

status: PeerStatus

subscribe_mode​

subscribe_mode: SubscribeMode

subscriptions​

subscriptions: Subscriptions

tracks​

tracks: list[Track]

type_​

type_: PeerType

additional_properties​

additional_properties: dict[str, typing.Any]

to_dict​

def to_dict(self) -> dict[str, typing.Any]

from_dict​

def from_dict(cls: type[~T], src_dict: Mapping[str, typing.Any]) -> ~T

additional_keys​

additional_keys: list[str]

MoqAccess​

class MoqAccess:

Connection details for a MoQ relay client

Attributes:

  • connection_url (str): Relay connection URL with the JWT embedded as a ?jwt= query parameter. Pass directly to a MoQ client SDK. Example: https://relay.fishjam.io/abc123?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....
  • token (str): JWT authorizing the MoQ relay connection, also embedded in connection_url Example: eyJhbGciOiJIUz I1NiIsInR5cCI6IkpXVCJ9.eyJyb290IjoiZmlzaGphbSIsInB1dCI6WyJteS1zdHJlYW0iXSwiZ2V0IjpbXSwiaWF0IjoxNzEzMzYwMDAwLCJle HAiOjE3MTMzNjM2MDB9.abc123.

init​

def __init__(connection_url: str, token: str)

Method generated by attrs for class MoqAccess.

connection_url​

connection_url: str

token​

token: str

additional_properties​

additional_properties: dict[str, typing.Any]

to_dict​

def to_dict(self) -> dict[str, typing.Any]

from_dict​

def from_dict(cls: type[~T], src_dict: Mapping[str, typing.Any]) -> ~T

additional_keys​

additional_keys: list[str]

MissingFishjamIdError​

class MissingFishjamIdError(ValueError):

Inappropriate argument value (of correct type).

InvalidFishjamCredentialsError​

class InvalidFishjamCredentialsError(fishjam.errors.HTTPError):