From 3984302f4609df052c00055653f3a51ae1401494 Mon Sep 17 00:00:00 2001 From: p1003 Date: Wed, 10 Dec 2025 15:06:27 +0100 Subject: [PATCH 1/2] update 0.23.0 python docs --- .../api/server-python/fishjam.md | 134 +++++++++++++++--- 1 file changed, 113 insertions(+), 21 deletions(-) diff --git a/versioned_docs/version-0.23.0/api/server-python/fishjam.md b/versioned_docs/version-0.23.0/api/server-python/fishjam.md index 2a1e6b92..52ec5b7b 100644 --- a/versioned_docs/version-0.23.0/api/server-python/fishjam.md +++ b/versioned_docs/version-0.23.0/api/server-python/fishjam.md @@ -18,13 +18,17 @@ custom_edit_url: null ```python class FishjamClient(Client): ``` -Allows for managing rooms +Allows for managing rooms. ### __init__ ```python def __init__(fishjam_id: str, management_token: str) ``` -Create a FishjamClient instance, providing the fishjam id and management token. +Create a FishjamClient instance. + +Args: +- fishjam_id: The unique identifier for the Fishjam instance. +- management_token: The token used for authenticating management operations. ### create_peer ```python @@ -34,12 +38,16 @@ def create_peer( options: PeerOptions | None = None ) -> tuple[Peer, str] ``` -Creates peer in the room +Creates a peer in the room. -Returns a tuple (`Peer`, `PeerToken`) - the token is needed by Peer -to authenticate to Fishjam. +Args: +- room_id: The ID of the room where the peer will be created. +- options: Configuration options for the peer. Defaults to None. -The possible options to pass for peer are `PeerOptions`. +Returns: +- A tuple containing: + - Peer: The created peer object. + - str: The peer token needed to authenticate to Fishjam. ### create_agent ```python @@ -49,7 +57,15 @@ def create_agent( 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_room ```python @@ -58,62 +74,112 @@ def create_room( options: RoomOptions | None = None ) -> Room ``` -Creates a new room -Returns the created `Room` +Creates a new room. + +Args: +- options: Configuration options for the room. Defaults to None. + +Returns: +- Room: The created Room object. ### get_all_rooms ```python def get_all_rooms(self) -> list[Room] ``` -Returns list of all rooms +Returns list of all rooms. + +Returns: +- list[Room]: A list of all available Room objects. ### get_room ```python def get_room(self, room_id: str) -> Room ``` -Returns room with the given id +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 ```python def delete_peer(self, room_id: str, peer_id: str) -> None ``` -Deletes peer +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 ```python def delete_room(self, room_id: str) -> None ``` -Deletes a room +Deletes a room. + +Args: +- room_id: The ID of the room to delete. ### refresh_peer_token ```python def refresh_peer_token(self, room_id: str, peer_id: str) -> str ``` -Refreshes peer token +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 ```python def create_livestream_viewer_token(self, room_id: str) -> str ``` -Generates viewer token for livestream rooms +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 ```python def create_livestream_streamer_token(self, room_id: str) -> str ``` -Generates streamer token for livestream rooms +Generates a streamer token for livestream rooms. + +Args: +- room_id: The ID of the livestream room. + +Returns: +- str: The generated streamer token. ### subscribe_peer ```python def subscribe_peer(self, room_id: str, peer_id: str, target_peer_id: str) ``` -Subscribe a peer to all tracks of another peer. +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 ```python def subscribe_tracks(self, room_id: str, peer_id: str, track_ids: list[str]) ``` -Subscribe a peer to specific tracks of another peer. +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**: @@ -218,7 +284,12 @@ additional_keys: list[str] ```python class PeerOptions: ``` -Options specific to a WebRTC Peer +Options specific to a WebRTC Peer. + +Attributes: +- enable_simulcast: Enables the peer to use simulcast. +- metadata: Peer metadata. +- subscribe_mode: Configuration of peer's subscribing policy. ### __init__ ```python @@ -256,7 +327,15 @@ Configuration of peer's subscribing policy ```python class RoomOptions: ``` -Description of a room options +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. ### __init__ ```python @@ -310,7 +389,11 @@ True if livestream viewers can omit specifying a token. ```python class AgentOptions: ``` -Options specific to a WebRTC Peer +Options specific to a WebRTC Peer. + +Attributes: +- output: Configuration for the agent's output options. +- subscribe_mode: Configuration of peer's subscribing policy. ### __init__ ```python @@ -341,6 +424,10 @@ 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__ ```python def __init__( @@ -369,7 +456,12 @@ audio_sample_rate: Literal[16000, 24000] = 16000 ```python class Room: ``` -Description of the room state +Description of the room state. + +Attributes: +- config: Room configuration. +- id: Room ID. +- peers: List of all peers. ### __init__ ```python From 6e9da264951c0f2014df33429492336bc4d0b5a6 Mon Sep 17 00:00:00 2001 From: p1003 Date: Wed, 10 Dec 2025 16:28:46 +0100 Subject: [PATCH 2/2] updated docstrings --- .../api/server-python/fishjam.md | 23 +++- .../api/server-python/fishjam/agent.md | 102 ++++++++++++------ 2 files changed, 88 insertions(+), 37 deletions(-) diff --git a/versioned_docs/version-0.23.0/api/server-python/fishjam.md b/versioned_docs/version-0.23.0/api/server-python/fishjam.md index 52ec5b7b..8f7ac61d 100644 --- a/versioned_docs/version-0.23.0/api/server-python/fishjam.md +++ b/versioned_docs/version-0.23.0/api/server-python/fishjam.md @@ -195,7 +195,7 @@ Allows for receiving WebSocket messages from Fishjam. ```python def __init__(fishjam_id: str, management_token: str) ``` -Create FishjamNotifier instance, providing the fishjam id and management token. +Create a FishjamNotifier instance with an ID and management token. ### on_server_notification ```python @@ -204,14 +204,19 @@ def on_server_notification( handler: Union[Callable[[Union[ServerMessageRoomCreated, ServerMessageRoomDeleted, ServerMessageRoomCrashed, ServerMessagePeerAdded, ServerMessagePeerDeleted, ServerMessagePeerConnected, ServerMessagePeerDisconnected, ServerMessagePeerMetadataUpdated, ServerMessagePeerCrashed, ServerMessageStreamConnected, ServerMessageStreamDisconnected, ServerMessageViewerConnected, ServerMessageViewerDisconnected, ServerMessageTrackAdded, ServerMessageTrackRemoved, ServerMessageTrackMetadataUpdated]], NoneType], Callable[[Union[ServerMessageRoomCreated, ServerMessageRoomDeleted, ServerMessageRoomCrashed, ServerMessagePeerAdded, ServerMessagePeerDeleted, ServerMessagePeerConnected, ServerMessagePeerDisconnected, ServerMessagePeerMetadataUpdated, ServerMessagePeerCrashed, ServerMessageStreamConnected, ServerMessageStreamDisconnected, ServerMessageViewerConnected, ServerMessageViewerDisconnected, ServerMessageTrackAdded, ServerMessageTrackRemoved, ServerMessageTrackMetadataUpdated]], Coroutine[Any, Any, None]]] ) ``` -Decorator used for defining handler for Fishjam Notifications +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 ```python def connect(self) ``` -A coroutine which connects FishjamNotifier to Fishjam and listens for -all incoming messages from the Fishjam. +Connects to Fishjam and listens for all incoming messages. It runs until the connection isn't closed. @@ -236,9 +241,17 @@ def receive_binary( binary: bytes ) -> Union[ServerMessageRoomCreated, ServerMessageRoomDeleted, ServerMessageRoomCrashed, ServerMessagePeerAdded, ServerMessagePeerDeleted, ServerMessagePeerConnected, ServerMessagePeerDisconnected, ServerMessagePeerMetadataUpdated, ServerMessagePeerCrashed, ServerMessageStreamConnected, ServerMessageStreamDisconnected, ServerMessageViewerConnected, ServerMessageViewerDisconnected, ServerMessageTrackAdded, ServerMessageTrackRemoved, ServerMessageTrackMetadataUpdated, NoneType] ``` -Transform received protobuf notification to adequate notification instance. +Transforms a received protobuf notification into a notification instance. + The available notifications are listed in `fishjam.events` module. +Args: +- binary: The raw binary data received from the webhook. + +Returns: +- AllowedNotification | None: The parsed notification object, or None if + the message type is not supported. + --- ## PeerMetadata ```python diff --git a/versioned_docs/version-0.23.0/api/server-python/fishjam/agent.md b/versioned_docs/version-0.23.0/api/server-python/fishjam/agent.md index 0a5a008c..74a0b740 100644 --- a/versioned_docs/version-0.23.0/api/server-python/fishjam/agent.md +++ b/versioned_docs/version-0.23.0/api/server-python/fishjam/agent.md @@ -13,17 +13,28 @@ custom_edit_url: null class Agent: ``` Allows for connecting to a Fishjam room as an agent peer. + Provides callbacks for receiving audio. +Attributes: +- id: The unique identifier of the agent. +- room_id: The ID of the room the agent is connecting to. + ### __init__ ```python def __init__(id: str, room_id: str, token: str, fishjam_url: str) ``` -Create Agent instance, providing the fishjam id and management token. +Creates an Agent instance. This constructor should not be called directly. Instead, you should call :func:`fishjam.FishjamClient.create_agent`. +Args: +- id: The unique identifier for the agent. +- room_id: The ID of the room the agent will join. +- token: The authentication token for the agent. +- fishjam_url: The URL of the Fishjam instance. + ### id ```python id @@ -40,26 +51,30 @@ room_id ```python def connect(self) ``` -Connect the agent to Fishjam to start receiving messages. +Connects the agent to Fishjam to start receiving messages. Incoming messages from Fishjam will be routed to handlers defined with :func:`on_track_data`. -:raises AgentAuthError: authentication failed +Yields: +- AgentSession: An active session for sending media and handling events. + +Raises: +- AgentAuthError: If authentication with the Fishjam server fails. --- ## AgentError ```python class AgentError(Exception): ``` -Base exception class for all agent exceptions +Base exception class for all agent exceptions. --- ## AgentSession ```python class AgentSession: ``` - +Represents an active connection session for an Agent. ### __init__ ```python @@ -68,7 +83,11 @@ def __init__( websocket: websockets.asyncio.client.ClientConnection ) ``` +Initializes the AgentSession. +Args: +- agent: The Agent instance owning this session. +- websocket: The active websocket connection. ### agent ```python @@ -82,23 +101,32 @@ def receive( self ) -> AsyncIterator[AgentResponseTrackData] ``` -Returns an infinite async iterator over the incoming messages from Fishjam to -the agent. +Returns an async iterator over incoming messages from Fishjam. + +Yields: +- IncomingAgentMessage: The next message received from the server. ### add_track ```python -def add_track(self, options: fishjam.agent.agent.OutgoingAudioTrackOptions) +def add_track( + self, + options: fishjam.agent.agent.OutgoingAudioTrackOptions +) -> fishjam.agent.agent.OutgoingTrack ``` -Adds a track to the connected agent, with the specified options and metadata. +Adds a track to the connected agent with the specified options. + +Args: +- options: Configuration options and metadata for the new track. -Returns an instance of :class:`OutgoingTrack`, which can be used to send data -over the added track. +Returns: +- OutgoingTrack: An object used to send data over the added track. ### disconnect ```python def disconnect(self) ``` Ends the agent session by closing the websocket connection. + Useful when you don't use the context manager to obtain the session. --- @@ -106,7 +134,7 @@ Useful when you don't use the context manager to obtain the session. ```python class AgentAuthError(fishjam.agent.errors.AgentError): ``` -Agent failed to authenticate properly +Agent failed to authenticate properly. ### __init__ ```python @@ -133,8 +161,14 @@ IncomingTrackData = ```python class OutgoingTrack: ``` -Represents an outgoing track of an agent connected to Fishjam, -created by :func:`Agent.add_track`. +Represents an outgoing track of an agent connected to Fishjam. + +This is created by :func:`Agent.add_track`. + +Attributes: +- id: The global identifier of the track. +- session: The agent the track belongs to. +- options: The parameters used to create the track. ### __init__ ```python @@ -150,38 +184,40 @@ def __init__( ```python id: str ``` -The global identifier of the track. + ### session ```python session: fishjam.agent.agent.AgentSession ``` -The agent the track belongs to. + ### options ```python options: fishjam.agent.agent.OutgoingAudioTrackOptions ``` -The parameters used to create the track. + ### send_chunk ```python def send_chunk(self, data: bytes) ``` -Send a chunk of audio to Fishjam on this track. +Sends a chunk of audio to Fishjam on this track. Peers connected to the room of the agent will receive this data. +Args: +- data: The raw audio bytes to send. + ### interrupt ```python def interrupt(self) ``` -Interrupt current track. - -Any audio that has been sent, but not played -will be cleared and be prevented from playing. +Interrupts the current track. -Audio sent after the interrupt will be played normally. +Any audio that has been sent, but not played, will be cleared and +prevented from playing. Audio sent after the interrupt will be played +normally. --- ## OutgoingAudioTrackOptions @@ -190,6 +226,13 @@ class OutgoingAudioTrackOptions: ``` Parameters of an outgoing audio track. +Attributes: +- encoding: The encoding of the audio source. Defaults to raw 16-bit PCM. +- sample_rate: The sample rate of the audio source. Defaults to 16000. +- channels: The number of channels in the audio source. Supported values are + 1 (mono) and 2 (stereo). Defaults to 1 (mono). +- metadata: Custom metadata for the track. Must be JSON-encodable. + ### __init__ ```python def __init__( @@ -206,32 +249,27 @@ def __init__( encoding: TrackEncoding = ``` -The encoding of the audio source. -Defaults to raw 16-bit PCM. + ### sample_rate ```python sample_rate: Literal[16000, 24000] = 16000 ``` -The sample rate of the audio source. -Defaults to 16000. + ### channels ```python channels: Literal[1, 2] = 1 ``` -The number of channels in the audio source. -Supported values are 1 (mono) and 2 (stereo). -Defaults to 1 (mono) + ### metadata ```python metadata: dict[str, typing.Any] | None = None ``` -Custom metadata for the track. -Must be JSON-encodable. + ---