Fishjam Python Server SDK

210class FishjamClient(Client):
211    """Allows for managing rooms."""
212
213    def __init__(
214        self,
215        fishjam_id: str,
216        management_token: str,
217    ):
218        """Create a FishjamClient instance.
219
220        Does not contact the Fishjam backend — use :meth:`create_and_verify`
221        or :meth:`check_credentials` to verify credentials live.
222
223        Args:
224            fishjam_id: The unique identifier for the Fishjam instance.
225            management_token: The token used for authenticating management operations.
226        """
227        super().__init__(fishjam_id=fishjam_id, management_token=management_token)
228
229    @classmethod
230    def create_and_verify(
231        cls, *, fishjam_id: str, management_token: str
232    ) -> "FishjamClient":
233        """Construct a FishjamClient and verify its credentials against the backend.
234
235        Args:
236            fishjam_id: The unique identifier for the Fishjam instance.
237            management_token: The token used for authenticating management operations.
238
239        Returns:
240            FishjamClient: A client whose credentials have been verified.
241
242        Raises:
243            InvalidFishjamCredentialsError: If the token is rejected.
244        """
245        client = cls(fishjam_id=fishjam_id, management_token=management_token)
246        client.check_credentials()
247        return client
248
249    def check_credentials(self) -> None:
250        """Verify the management token via a single ``/validate`` call.
251
252        Raises:
253            InvalidFishjamCredentialsError: If the token is rejected.
254        """
255        response = credentials_validate_credentials.sync_detailed(client=self.client)
256        self._handle_deprecation_header(response.headers)
257
258        if response.status_code == HTTPStatus.NOT_FOUND:
259            raise InvalidFishjamCredentialsError("Invalid Fishjam credentials")
260
261    def create_peer(
262        self,
263        room_id: str,
264        options: PeerOptions | None = None,
265    ) -> tuple[Peer, str]:
266        """Creates a peer in the room.
267
268        Args:
269            room_id: The ID of the room where the peer will be created.
270            options: Configuration options for the peer. Defaults to None.
271
272        Returns:
273            A tuple containing:
274                - Peer: The created peer object.
275                - str: The peer token needed to authenticate to Fishjam.
276        """
277        options = options or PeerOptions()
278
279        peer_metadata = self.__parse_peer_metadata(options.metadata)
280        peer_options = PeerOptionsWebRTC(
281            metadata=peer_metadata,
282            subscribe_mode=SubscribeMode(options.subscribe_mode),
283        )
284        body = PeerConfigWebRTC(type_=PeerConfigWebRTCType.WEBRTC, options=peer_options)
285
286        resp = cast(
287            PeerDetailsResponse,
288            self._request(room_add_peer, room_id=room_id, body=body),
289        )
290
291        return (resp.data.peer, resp.data.token)
292
293    def create_agent(self, room_id: str, options: AgentOptions | None = None):
294        """Creates an agent in the room.
295
296        Args:
297            room_id: The ID of the room where the agent will be created.
298            options: Configuration options for the agent. Defaults to None.
299
300        Returns:
301            Agent: The created agent instance initialized with peer ID, room ID, token,
302                and Fishjam URL.
303        """
304        options = options or AgentOptions()
305        body = PeerConfigAgent(
306            type_=PeerConfigAgentType.AGENT,
307            options=PeerOptionsAgent(
308                output=AgentOutput(
309                    audio_format=AudioFormat(options.output.audio_format),
310                    audio_sample_rate=AudioSampleRate(options.output.audio_sample_rate),
311                ),
312                subscribe_mode=SubscribeMode(options.subscribe_mode),
313            ),
314        )
315
316        resp = cast(
317            PeerDetailsResponse,
318            self._request(room_add_peer, room_id=room_id, body=body),
319        )
320
321        socket_base_url = self._peer_socket_base_url(resp.data.peer_websocket_url)
322        return Agent(resp.data.peer.id, room_id, resp.data.token, socket_base_url)
323
324    def _peer_socket_base_url(self, peer_websocket_url: str | Unset) -> str:
325        if isinstance(peer_websocket_url, Unset) or not peer_websocket_url:
326            return self._fishjam_url
327
328        url = peer_websocket_url
329        if "://" not in url:
330            url = f"https://{url}"
331        for suffix in ("/socket/peer/websocket", "/socket/agent/websocket"):
332            url = url.removesuffix(suffix)
333        return url
334
335    def create_vapi_agent(
336        self,
337        room_id: str,
338        options: PeerOptionsVapi,
339    ) -> Peer:
340        """Creates a vapi agent in the room.
341
342        Args:
343            room_id: The ID of the room where the vapi agent will be created.
344            options: Configuration options for the vapi peer.
345
346        Returns:
347            - Peer: The created peer object.
348        """
349        body = PeerConfigVAPI(type_=PeerConfigVAPIType.VAPI, options=options)
350
351        resp = cast(
352            PeerDetailsResponse,
353            self._request(room_add_peer, room_id=room_id, body=body),
354        )
355
356        return resp.data.peer
357
358    def create_room(self, options: RoomOptions | None = None) -> Room:
359        """Creates a new room.
360
361        Args:
362            options: Configuration options for the room. Defaults to None.
363
364        Returns:
365            Room: The created Room object.
366        """
367        options = options or RoomOptions()
368
369        if options.video_codec is None:
370            codec = UNSET
371        else:
372            codec = VideoCodec(options.video_codec)
373
374        config = RoomConfig(
375            max_peers=options.max_peers,
376            video_codec=codec,
377            webhook_url=options.webhook_url,
378            room_type=RoomType(options.room_type),
379            public=options.public,
380            batch_webhook_notifications=options.batch_webhook_notifications,
381        )
382
383        room = cast(
384            RoomCreateDetailsResponse, self._request(room_create_room, body=config)
385        ).data.room
386
387        return _to_room(room)
388
389    def get_all_rooms(self) -> list[Room]:
390        """Returns list of all rooms.
391
392        Returns:
393            list[Room]: A list of all available Room objects.
394        """
395        rooms = cast(RoomsListingResponse, self._request(room_get_all_rooms)).data
396
397        return [_to_room(room) for room in rooms]
398
399    def get_room(self, room_id: str) -> Room:
400        """Returns room with the given id.
401
402        Args:
403            room_id: The ID of the room to retrieve.
404
405        Returns:
406            Room: The Room object corresponding to the given ID.
407        """
408        room = cast(
409            RoomDetailsResponse, self._request(room_get_room, room_id=room_id)
410        ).data
411
412        return _to_room(room)
413
414    def delete_peer(self, room_id: str, peer_id: str) -> None:
415        """Deletes a peer from a room.
416
417        Args:
418            room_id: The ID of the room the peer belongs to.
419            peer_id: The ID of the peer to delete.
420        """
421        return self._request(room_delete_peer, id=peer_id, room_id=room_id)
422
423    def delete_room(self, room_id: str) -> None:
424        """Deletes a room.
425
426        Args:
427            room_id: The ID of the room to delete.
428        """
429        return self._request(room_delete_room, room_id=room_id)
430
431    def refresh_peer_token(self, room_id: str, peer_id: str) -> str:
432        """Refreshes a peer token.
433
434        Args:
435            room_id: The ID of the room.
436            peer_id: The ID of the peer whose token needs refreshing.
437
438        Returns:
439            str: The new peer token.
440        """
441        response = cast(
442            PeerRefreshTokenResponse,
443            self._request(room_refresh_token, id=peer_id, room_id=room_id),
444        )
445
446        return response.data.token
447
448    def forward_room_tracks(self, room_id: str, composition_url: str) -> None:
449        """Forwards every track published in the room into a composition.
450
451        The composition composes them into its outputs. Pass the composition's
452        address, as returned by
453        `fishjam.CompositionClient.composition_url`.
454
455        Args:
456            room_id: The ID of the room to forward tracks from.
457            composition_url: The address of the composition to forward tracks to.
458        """
459        self._request(
460            track_forwardings_create,
461            room_id=room_id,
462            body=TrackForwarding(composition_url=composition_url),
463        )
464
465    def livestream_whip_url(self) -> str:
466        """Where to publish a livestream.
467
468        Pair it with a token from
469        `fishjam.FishjamClient.create_livestream_streamer_token`. A composition
470        reaches viewers by sending a WHIP output here.
471
472        Returns:
473            str: The address a WHIP publisher sends the livestream to.
474        """
475        return get_livestream_whip_url(self._fishjam_id)
476
477    def livestream_whep_url(self) -> str:
478        """Where to watch a livestream.
479
480        Pair it with a token from
481        `fishjam.FishjamClient.create_livestream_viewer_token`, sent as a bearer
482        token by the WHEP player.
483
484        Returns:
485            str: The address a WHEP viewer plays the livestream from.
486        """
487        return get_livestream_whep_url(self._fishjam_id)
488
489    def create_livestream_viewer_token(self, room_id: str) -> str:
490        """Generates a viewer token for livestream rooms.
491
492        Args:
493            room_id: The ID of the livestream room.
494
495        Returns:
496            str: The generated viewer token.
497        """
498        response = cast(
499            ViewerToken, self._request(viewer_generate_viewer_token, room_id=room_id)
500        )
501
502        return response.token
503
504    def create_livestream_streamer_token(self, room_id: str) -> str:
505        """Generates a streamer token for livestream rooms.
506
507        Args:
508            room_id: The ID of the livestream room.
509
510        Returns:
511            str: The generated streamer token.
512        """
513        response = cast(
514            StreamerToken,
515            self._request(streamer_generate_streamer_token, room_id=room_id),
516        )
517
518        return response.token
519
520    def create_moq_access(
521        self,
522        publish_path: str | None = None,
523        subscribe_path: str | None = None,
524        ttl: int | None = None,
525    ) -> MoqAccess:
526        """Generates MoQ relay connection details.
527
528        Args:
529            publish_path: Path the access grants publish access to.
530            subscribe_path: Path the access grants subscribe access to.
531            ttl: Token time to live in seconds. Defaults to 3600 (1 hour),
532                maximum is 604800 (7 days).
533
534        Returns:
535            MoqAccess: The relay connection details, containing the
536            ``connection_url`` (with the JWT embedded as a ``?jwt=`` query
537            parameter) and the ``token`` itself.
538        """
539        config = MoqAccessConfig(
540            publish_path=publish_path,
541            subscribe_path=subscribe_path,
542            ttl=ttl if ttl is not None else UNSET,
543        )
544        response = cast(
545            MoqAccess,
546            self._request(moq_create_access, body=config),
547        )
548
549        return response
550
551    def create_recording(
552        self,
553        source: CompositionSource,
554        metadata: dict[str, Any] | None = None,
555    ) -> Recording:
556        """Creates a new recording.
557
558        Capturing starts synchronously, so the returned recording is `active`.
559
560        Args:
561            source: The source of the recording.
562            metadata: Free-form metadata used to organize and filter recordings.
563
564        Returns:
565            Recording: The started recording details.
566        """
567        warnings.warn(
568            "create_recording is deprecated; use create_composition_recording instead.",
569            DeprecationWarning,
570            stacklevel=2,
571        )
572        config = RecordingConfig(
573            source=source, metadata=self.__parse_recording_metadata(metadata)
574        )
575
576        resp = cast(
577            RecordingDetailsResponse,
578            self._request(recording_create_recording, body=config),
579        )
580
581        return resp.data
582
583    def create_composition_recording(
584        self,
585        source: CompositionSource,
586        metadata: dict[str, Any] | None = None,
587    ) -> Recording:
588        """Creates a new recording.
589
590        Capturing starts synchronously, so the returned recording is `active`.
591
592        Args:
593            source: The source of the recording.
594            metadata: Free-form metadata used to organize and filter recordings.
595
596        Returns:
597            Recording: The started recording details.
598        """
599        config = RecordingConfig(
600            source=source, metadata=self.__parse_recording_metadata(metadata)
601        )
602
603        resp = cast(
604            RecordingDetailsResponse,
605            self._request(recording_create_recording, body=config),
606        )
607
608        return resp.data
609
610    def create_template_recording(
611        self,
612        source: TemplateSource,
613        template: FileSource,
614        metadata: dict[str, Any] | None = None,
615    ) -> Recording:
616        """Starts a new recording that renders its own scene from a template.
617
618        The template bundle can weigh at most 1 MiB; only valid template
619        bundles are accepted.
620
621        Args:
622            source: The source of the recording.
623            template: The bundle to render, as bytes or a path to read them from.
624            metadata: Free-form metadata used to organize and filter recordings.
625
626        Returns:
627            Recording: The created recording.
628        """
629        config = RecordingConfig(
630            source=source, metadata=self.__parse_recording_metadata(metadata)
631        )
632
633        resp = cast(
634            RecordingDetailsResponse,
635            self._request(
636                recording_create_recording,
637                body=CreateRecordingFilesBody(
638                    config=config, template=_to_file(template, "template.js")
639                ),
640            ),
641        )
642
643        return resp.data
644
645    def get_recording(self, recording_id: str) -> Recording:
646        """Returns the recording with the given id.
647
648        Args:
649            recording_id: The ID of the recording to retrieve.
650
651        Returns:
652            Recording: The recording corresponding to the given ID.
653        """
654        resp = cast(
655            RecordingDetailsResponse,
656            self._request(recording_get_recording, recording_id=recording_id),
657        )
658
659        return resp.data
660
661    def get_all_recordings(
662        self, metadata: dict[str, Any] | None = None
663    ) -> list[Recording]:
664        """Returns a list of all recordings, optionally filtered by metadata.
665
666        Args:
667            metadata: If given, only recordings whose metadata contains all
668                the given key-value pairs are returned. Nested dicts match
669                nested metadata keys.
670
671        Returns:
672            list[Recording]: A list of all matching recordings.
673        """
674        # the API expects the deepObject query format
675        # (`metadata[key]=value`, `metadata[key][nested]=value`), but the
676        # generated client serializes the filter keys at the top level, so
677        # prefix and flatten them here
678        if metadata is None:
679            metadata_query = UNSET
680        else:
681            metadata_query = ListRecordingsMetadata()
682            self.__flatten_metadata_filter(
683                "metadata", metadata, metadata_query.additional_properties
684            )
685
686        resp = cast(
687            RecordingListResponse,
688            self._request(recording_list_recordings, metadata=metadata_query),
689        )
690
691        return resp.data
692
693    def stop_recording(self, recording_id: str) -> Recording:
694        """Stops an active recording.
695
696        Finalization is asynchronous: the recording stays `active` until the
697        capture is finalized, then becomes `finished`. Stopping a recording
698        that is no longer active is a no-op.
699
700        Args:
701            recording_id: The ID of the recording to stop.
702
703        Returns:
704            Recording: The stopped recording.
705        """
706        resp = cast(
707            RecordingDetailsResponse,
708            self._request(recording_stop_recording, recording_id=recording_id),
709        )
710
711        return resp.data
712
713    def delete_recording(self, recording_id: str) -> None:
714        """Deletes a recording. Its stored media is removed asynchronously.
715
716        A recording that is still `active` cannot be deleted — stop it first
717        or wait for it to finish.
718
719        Args:
720            recording_id: The ID of the recording to delete.
721        """
722        self._request(recording_delete_recording, recording_id=recording_id)
723
724    def subscribe_peer(self, room_id: str, peer_id: str, target_peer_id: str):
725        """Subscribes a peer to all tracks of another peer.
726
727        Args:
728            room_id: The ID of the room.
729            peer_id: The ID of the subscribing peer.
730            target_peer_id: The ID of the peer to subscribe to.
731        """
732        self._request(
733            room_subscribe_peer,
734            room_id=room_id,
735            id=peer_id,
736            peer_id=target_peer_id,
737        )
738
739    def subscribe_tracks(self, room_id: str, peer_id: str, track_ids: list[str]):
740        """Subscribes a peer to specific tracks of another peer.
741
742        Args:
743            room_id: The ID of the room.
744            peer_id: The ID of the subscribing peer.
745            track_ids: A list of track IDs to subscribe to.
746        """
747        self._request(
748            room_subscribe_tracks,
749            room_id=room_id,
750            id=peer_id,
751            body=SubscribeTracksBody(track_ids=track_ids),
752        )
753
754    def __flatten_metadata_filter(
755        self, prefix: str, metadata: dict[str, Any], params: dict[str, Any]
756    ) -> None:
757        for key, value in metadata.items():
758            param_key = f"{prefix}[{key}]"
759            if isinstance(value, dict):
760                self.__flatten_metadata_filter(param_key, value, params)
761            elif value is None:
762                # the generated client drops `None` params; the API compares
763                # values as JSON strings, so send the JSON representation
764                params[param_key] = "null"
765            else:
766                params[param_key] = value
767
768    def __parse_recording_metadata(
769        self, metadata: dict[str, Any] | None
770    ) -> RecordingConfigMetadataType0 | Unset:
771        if metadata is None:
772            return UNSET
773
774        config_metadata = RecordingConfigMetadataType0()
775        for key, value in metadata.items():
776            config_metadata.additional_properties[key] = value
777
778        return config_metadata
779
780    def __parse_peer_metadata(self, metadata: dict | None) -> WebRTCMetadata:
781        peer_metadata = WebRTCMetadata()
782
783        if not metadata:
784            return peer_metadata
785
786        for key, value in metadata.items():
787            peer_metadata.additional_properties[key] = value
788
789        return peer_metadata