API Reference

Complete API reference for all classes, methods, and types in the Python Janus Client library.

Session Classes

JanusSession

janus_client.session.JanusSession

Janus session for managing WebRTC connections and plugins.

A session represents a connection to the Janus server and manages plugin handles and message routing.

__init__

__init__(base_url: str = '', api_secret: Optional[str] = None, token: Optional[str] = None, transport: Optional[JanusTransport] = None) -> None

Initialize a new Janus session.

Parameters:

Name	Type	Description	Default
base_url	str	Base URL for the Janus server.	''
api_secret	Optional[str]	Optional API secret for authentication.	None
token	Optional[str]	Optional token for authentication.	None
transport	Optional[JanusTransport]	Optional custom transport instance.	None

__str__

__str__() -> str

Return string representation of the session.

__aenter__ async

__aenter__() -> JanusSession

Enter async context manager and connect transport.

__aexit__ async

__aexit__(exc_type, exc_value, exc_tb) -> None

Exit async context manager and clean up resources.

create async

create() -> None

Initialize session resources and start keepalive.

destroy async

destroy() -> None

Release session resources and stop keepalive.

Should be called when the session is no longer needed. All plugins should be destroyed before calling this method.

send async

send(message: dict, handle_id: Optional[int] = None) -> MessageTransaction

Send a message through this session.

Parameters:

Name	Type	Description	Default
message	dict	The message to send to Janus.	required
handle_id	Optional[int]	Optional plugin handle ID for plugin-specific messages.	None

Returns:

Type	Description
MessageTransaction	MessageTransaction for tracking the response.

Raises:

Type	Description
Exception	If session is not properly initialized.

keepalive async

keepalive() -> None

Send periodic keepalive messages to maintain the session.

Sends keepalive messages every 30 seconds to prevent the session from timing out due to inactivity.

on_receive async

on_receive(response: dict) -> None

Handle incoming messages from Janus.

Routes messages to the appropriate plugin handle or processes session-level messages.

Parameters:

Name	Type	Description	Default
response	dict	The response message from Janus.	required

attach_plugin async

attach_plugin(plugin: JanusPlugin) -> int

Attach a plugin to this session.

Creates a plugin handle on the Janus server and registers it with this session for message routing.

Parameters:

Name	Type	Description	Default
plugin	JanusPlugin	The plugin instance to attach.	required

Returns:

Type	Description
int	The plugin handle ID assigned by Janus.

Raises:

Type	Description
PluginAttachFail	If the plugin attachment fails.

detach_plugin

detach_plugin(plugin_handle: JanusPlugin) -> None

Remove a plugin handle from this session.

Parameters:

Name	Type	Description	Default
plugin_handle	JanusPlugin	The plugin handle to remove.	required

Raises:

Type	Description
KeyError	If plugin handle is not found in session.

PluginAttachFail Exception

janus_client.session.PluginAttachFail

Bases: Exception

Exception raised when plugin attachment fails.

Parameters:

Name	Type	Description	Default
response	dict	The error response from Janus server.	required

Plugin Classes

Base Plugin Class

janus_client.plugin_base.JanusPlugin

Bases: ABC

Base class for implementing Janus plugins.

Important: Each plugin instance can only hold ONE WebRTC peer connection. If you need multiple peer connections, create multiple plugin instances. Access the peer connection via the pc property.

name class-attribute instance-attribute

name: str = 'janus.plugin.base.dummy'

Plugin name that must match the plugin name in Janus server.

__session instance-attribute

__session: JanusSession

Session instance this plugin is attached to.

__pc instance-attribute

__pc: RTCPeerConnection

WebRTC PeerConnection for this plugin handle.

__id instance-attribute

__id: Optional[int] = None

Plugin handle ID assigned by Janus.

__pc_config instance-attribute

__pc_config: Optional[RTCConfiguration] = pc_config

Stored configuration for recreating peer connections.

id property

id: Optional[int]

Get the plugin handle ID.

Returns:

Type	Description
Optional[int]	The plugin handle ID assigned by Janus, or None if not attached.

pc property

pc: RTCPeerConnection

Get the WebRTC peer connection for this plugin.

pc_config property

pc_config: Optional[RTCConfiguration]

Get the peer connection configuration used by this plugin.

__init__

__init__(pc_config: Optional[RTCConfiguration] = None) -> None

Initialize the plugin with optional peer connection configuration.

Parameters:

Name	Type	Description	Default
pc_config	Optional[RTCConfiguration]	Complete RTCConfiguration object for the peer connection. If provided, ice_servers parameter is ignored.	None

Examples:

config = RTCConfiguration(
    iceServers=[
        RTCIceServer(urls='stun:stun.l.google.com:19302'),
        RTCIceServer(
            urls='turn:turn.example.com:3478',
            username='user',
            credential='pass'
        )
    ]
)
plugin = MyPlugin(pc_config=config)

reset_connection async

reset_connection() -> None

Reset the peer connection.

Closes the existing peer connection and creates a new one with the same configuration that was provided during plugin initialization.

Warning

This should only be used when you need to completely restart the WebRTC connection. In most cases, you should create a new plugin instance instead of resetting the connection on an existing instance.

Example

# Close existing connection and create a new one
await plugin.reset_connection()

# The pc property now returns the new connection
new_pc = plugin.pc

attach async

attach(session: JanusSession) -> None

Attach this plugin to a Janus session.

Parameters:

Name	Type	Description	Default
session	JanusSession	The JanusSession to attach this plugin to.	required

Raises:

Type	Description
Exception	If plugin is already attached to a session.

destroy async

destroy() -> None

Destroy the plugin handle and clean up resources.

send async

send(message: dict) -> MessageTransaction

Send a message to this plugin handle.

Automatically attaches the plugin handle ID to the message.

Parameters:

Name	Type	Description	Default
message	dict	JSON serializable dictionary to send to the plugin.	required

Returns:

Type	Description
MessageTransaction	MessageTransaction for tracking the response.

Raises:

Type	Description
Exception	If plugin is not attached to a session.

on_receive abstractmethod async

on_receive(response: dict) -> None

Handle asynchronous events from Janus.

This method must be implemented by subclasses to handle plugin-specific messages and events.

Parameters:

Name	Type	Description	Default
response	dict	The response message from Janus.	required

create_jsep async

create_jsep(pc: RTCPeerConnection, trickle: bool = False) -> dict

Create a JSEP object from a peer connection's local description.

Parameters:

Name	Type	Description	Default
pc	RTCPeerConnection	The RTCPeerConnection to extract the description from.	required
trickle	bool	Whether to enable trickle ICE.	False

Returns:

Type	Description
dict	A JSEP dictionary containing SDP, type, and trickle settings.

on_receive_jsep async

on_receive_jsep(jsep: dict) -> None

Handle incoming JSEP (WebRTC signaling) messages.

Sets the remote description on the peer connection from the received JSEP offer or answer.

Parameters:

Name	Type	Description	Default
jsep	dict	The JSEP message containing SDP and type.	required

Raises:

Type	Description
Exception	If the peer connection is in closed state.

trickle async

trickle(sdpMLineIndex: int, candidate: Optional[str] = None) -> None

Send WebRTC ICE candidates to Janus using trickle ICE.

Parameters:

Name	Type	Description	Default
sdpMLineIndex	int	The SDP media line index for the candidate.	required
candidate	Optional[str]	The ICE candidate string, or None to signal end of candidates.	None

EchoTest Plugin

janus_client.plugin_echotest.JanusEchoTestPlugin

Bases: JanusPlugin

Janus EchoTest plugin implementation.

close_stream async

close_stream()

Close stream

This should cause the stream to stop and a done event to be received.

VideoCall Plugin

janus_client.plugin_video_call.JanusVideoCallPlugin

Bases: JanusPlugin

Janus VideoCall plugin client.

This plugin provides peer-to-peer video calling capabilities through the Janus gateway. It supports user registration, call initiation/acceptance, media control, and proper WebRTC signaling.

Example

session = JanusSession(base_url="wss://example.com/janus")
plugin = JanusVideoCallPlugin()

async with session:
    await plugin.attach(session)

    # Register a username
    await plugin.register("alice")

    # Set up event handlers
    def on_incoming_call(data):
        print(f"Incoming call from {data['username']}")
        # Handle incoming call...

    plugin.on_event(VideoCallEventType.INCOMINGCALL, on_incoming_call)

    # Make a call
    player = MediaPlayer("input.mp4")
    recorder = MediaRecorder("output.mp4")
    await plugin.call("bob", player, recorder)

    await plugin.destroy()

username property

username: Optional[str]

Get the registered username.

in_call property

in_call: bool

Check if currently in a call.

__init__

__init__(**kwargs: Any) -> None

Initialize the VideoCall plugin.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Keyword arguments passed to JanusPlugin constructor. Supports pc_config parameter for WebRTC configuration.	{}

Examples:

Basic usage:

plugin = JanusVideoCallPlugin()

With WebRTC configuration:

from aiortc import RTCConfiguration, RTCIceServer

config = RTCConfiguration(iceServers=[
    RTCIceServer(urls='stun:stun.l.google.com:19302')
])
plugin = JanusVideoCallPlugin(pc_config=config)

on_event

on_event(event_type: VideoCallEventType, handler: Callable[[Dict[str, Any]], Awaitable]) -> None

Register an event handler for VideoCall events.

Parameters:

Name	Type	Description	Default
event_type	VideoCallEventType	The type of event to handle.	required
handler	Callable[[Dict[str, Any]], Awaitable]	Callback function to handle the event.	required

on_receive async

on_receive(response: Dict[str, Any]) -> None

Handle incoming messages from Janus.

Parameters:

Name	Type	Description	Default
response	Dict[str, Any]	The response message from Janus.	required

list_users async

list_users(timeout: float = 15.0) -> List[str]

List all registered users.

Parameters:

Name	Type	Description	Default
timeout	float	Request timeout in seconds.	15.0

Returns:

Type	Description
List[str]	List of registered usernames.

Raises:

Type	Description
VideoCallError	If the request fails.
TimeoutError	If the request times out.

register async

register(username: str, timeout: float = 15.0) -> bool

Register a username for receiving calls.

Parameters:

Name	Type	Description	Default
username	str	The username to register.	required
timeout	float	Request timeout in seconds.	15.0

Returns:

Type	Description
bool	True if registration was successful.

Raises:

Type	Description
VideoCallError	If registration fails.
TimeoutError	If the request times out.

call async

call(username: str, player: Optional[MediaPlayer] = None, recorder: Optional[MediaRecorder] = None, trickle: bool = False, timeout: float = 30.0) -> bool

Initiate a call to another user.

Parameters:

Name	Type	Description	Default
username	str	The username to call.	required
player	Optional[MediaPlayer]	Media player for outgoing media.	None
recorder	Optional[MediaRecorder]	Media recorder for incoming media.	None
trickle	bool	Whether to use trickle ICE.	False
timeout	float	Request timeout in seconds.	30.0

Returns:

Type	Description
bool	True if the call was initiated successfully.

Raises:

Type	Description
VideoCallError	If the call fails.
TimeoutError	If the request times out.

accept async

accept(jsep: Dict[str, str], player: Optional[MediaPlayer] = None, recorder: Optional[MediaRecorder] = None, trickle: bool = False, timeout: float = 30.0) -> bool

Accept an incoming call.

Parameters:

Name	Type	Description	Default
player	Optional[MediaPlayer]	Media player for outgoing media.	None
recorder	Optional[MediaRecorder]	Media recorder for incoming media.	None
trickle	bool	Whether to use trickle ICE.	False
timeout	float	Request timeout in seconds.	30.0

Returns:

Type	Description
bool	True if the call was accepted successfully.

Raises:

Type	Description
VideoCallError	If accepting the call fails.
TimeoutError	If the request times out.

set_media async

set_media(audio: Optional[bool] = None, video: Optional[bool] = None, bitrate: Optional[int] = None, record: Optional[bool] = None, filename: Optional[str] = None, substream: Optional[int] = None, temporal: Optional[int] = None, fallback: Optional[int] = None, jsep: Optional[Dict[str, Any]] = None, timeout: float = 15.0) -> bool

Configure media settings for the call.

Parameters:

Name	Type	Description	Default
audio	Optional[bool]	Enable/disable audio.	None
video	Optional[bool]	Enable/disable video.	None
bitrate	Optional[int]	Bitrate limit in bps.	None
record	Optional[bool]	Enable/disable recording.	None
filename	Optional[str]	Base filename for recording.	None
substream	Optional[int]	Substream to receive (0-2) for simulcast.	None
temporal	Optional[int]	Temporal layers to receive (0-2) for simulcast.	None
fallback	Optional[int]	Fallback time in microseconds for simulcast.	None
jsep	Optional[Dict[str, Any]]	Optional JSEP for renegotiation.	None
timeout	float	Request timeout in seconds.	15.0

Returns:

Type	Description
bool	True if settings were applied successfully.

Raises:

Type	Description
VideoCallError	If the request fails.
TimeoutError	If the request times out.

hangup async

hangup(timeout: float = 15.0) -> bool

Hang up the current call.

Parameters:

Name	Type	Description	Default
timeout	float	Request timeout in seconds.	15.0

Returns:

Type	Description
bool	True if hangup was successful.

Raises:

Type	Description
VideoCallError	If the request fails.
TimeoutError	If the request times out.

destroy async

destroy() -> None

Destroy the plugin and clean up all resources.

VideoCallError Exception

janus_client.plugin_video_call.VideoCallError

Bases: Exception

Exception raised for VideoCall plugin errors.

VideoCallEventType Enum

janus_client.plugin_video_call.VideoCallEventType

Bases: Enum

Types of events that can be received from the VideoCall plugin.

VideoRoom Plugin

janus_client.plugin_video_room.JanusVideoRoomPlugin

Bases: JanusPlugin

Janus VideoRoom plugin client.

This plugin provides multi-party video conferencing capabilities through WebRTC. It supports both publishing (sending media) and subscribing (receiving media) modes.

Each plugin instance can be used as either a publisher or subscriber, but not both simultaneously. For applications that need both capabilities, create separate plugin instances.

Example

# Publisher example
session = JanusSession(base_url="wss://example.com/janus")
publisher = JanusVideoRoomPlugin()

async with session:
    await publisher.attach(session)

    # Join as publisher
    await publisher.join_as_publisher(room=1234, display="Alice")

    # Register event handler
    def on_publishers(data):
        print(f"New publishers: {data['publishers']}")

    publisher.on_event(VideoRoomEventType.PUBLISHERS, on_publishers)

    # Publish media
    player = MediaPlayer("input.mp4")
    await publisher.publish(player)

    # Leave room
    await publisher.leave()
    await publisher.destroy()

# Subscriber example
subscriber = JanusVideoRoomPlugin()
async with session:
    await subscriber.attach(session)

    # Subscribe to a publisher
    recorder = MediaRecorder("output.mp4")
    await subscriber.subscribe_to_publisher(
        room=1234,
        streams=[{"feed": 123}],
        recorder=recorder
    )

    await subscriber.destroy()

room_id property

room_id: Optional[int]

Get the current room ID.

publisher_id property

publisher_id: Optional[int]

Get the current publisher ID.

private_id property

private_id: Optional[int]

Get the current private ID.

display_name property

display_name: Optional[str]

Get the current display name.

participant_type property

participant_type: Optional[ParticipantType]

Get the current participant type.

is_publishing property

is_publishing: bool

Check if currently publishing media.

webrtcup_event property

webrtcup_event: Event

Return webrtc up event

__init__

__init__(**kwargs: Any) -> None

Initialize the VideoRoom plugin.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Keyword arguments passed to JanusPlugin constructor. Supports pc_config parameter for WebRTC configuration.	{}

Examples:

Basic usage:

plugin = JanusVideoRoomPlugin()

With WebRTC configuration:

from aiortc import RTCConfiguration, RTCIceServer

config = RTCConfiguration(iceServers=[
    RTCIceServer(urls='stun:stun.l.google.com:19302')
])
plugin = JanusVideoRoomPlugin(pc_config=config)

on_receive async

on_receive(response: Dict[str, Any]) -> None

Handle incoming messages from Janus.

Parameters:

Name	Type	Description	Default
response	Dict[str, Any]	The response message from Janus.	required

on_event

on_event(event_type: VideoRoomEventType, handler: Callable[[Dict[str, Any]], None]) -> None

Register an event handler for VideoRoom events.

Parameters:

Name	Type	Description	Default
event_type	VideoRoomEventType	The type of event to handle.	required
handler	Callable[[Dict[str, Any]], None]	Callback function to handle the event.	required

create_room async

create_room(room_id: Optional[int] = None, description: Optional[str] = None, secret: Optional[str] = None, pin: Optional[str] = None, is_private: bool = False, publishers: int = 3, bitrate: Optional[int] = None, fir_freq: int = 0, audiocodec: Optional[str] = None, videocodec: Optional[str] = None, record: bool = False, rec_dir: Optional[str] = None, permanent: bool = False, admin_key: Optional[str] = None, timeout: float = 15.0, **kwargs: Any) -> int

Create a new VideoRoom.

Parameters:

Name	Type	Description	Default
room_id	Optional[int]	Unique room ID (auto-generated if not provided).	None
description	Optional[str]	Room description.	None
secret	Optional[str]	Secret for room management.	None
pin	Optional[str]	PIN required to join the room.	None
is_private	bool	Whether the room should be private.	False
publishers	int	Maximum number of concurrent publishers.	3
bitrate	Optional[int]	Maximum video bitrate for publishers.	None
fir_freq	int	FIR frequency for keyframe requests.	0
audiocodec	Optional[str]	Allowed audio codecs (comma-separated).	None
videocodec	Optional[str]	Allowed video codecs (comma-separated).	None
record	bool	Whether to record the room.	False
rec_dir	Optional[str]	Directory for recordings.	None
permanent	bool	Whether to save room to config file.	False
admin_key	Optional[str]	Admin key if required by server.	None
timeout	float	Maximum time to wait for response.	15.0
**kwargs	Any	Additional room configuration parameters.	{}

Returns:

Type	Description
int	The created room ID.

Raises:

Type	Description
VideoRoomError	If creation fails.
TimeoutError	If request times out.

destroy_room async

destroy_room(room_id: int, secret: Optional[str] = None, permanent: bool = False, timeout: float = 15.0) -> None

Destroy a VideoRoom.

Parameters:

Name	Type	Description	Default
room_id	int	The room ID to destroy.	required
secret	Optional[str]	Room secret if required.	None
permanent	bool	Whether to remove from config file.	False
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
VideoRoomError	If destruction fails.
TimeoutError	If request times out.

list_rooms async

list_rooms(admin_key: Optional[str] = None, timeout: float = 15.0) -> List[Dict[str, Any]]

List available rooms.

Parameters:

Name	Type	Description	Default
admin_key	Optional[str]	Optional admin key for accessing private rooms.	None
timeout	float	Maximum time to wait for response.	15.0

Returns:

Type	Description
List[Dict[str, Any]]	List of room information dictionaries.

Raises:

Type	Description
VideoRoomError	If request fails.
TimeoutError	If request times out.

list_participants async

list_participants(room_id: int, timeout: float = 15.0) -> List[Dict[str, Any]]

List participants in a room.

Parameters:

Name	Type	Description	Default
room_id	int	The room ID to query.	required
timeout	float	Maximum time to wait for response.	15.0

Returns:

Type	Description
List[Dict[str, Any]]	List of participant information dictionaries.

Raises:

Type	Description
VideoRoomError	If request fails.
TimeoutError	If request times out.

exists async

exists(room_id: int, timeout: float = 15.0) -> bool

Check if a room exists.

Parameters:

Name	Type	Description	Default
room_id	int	The room ID to check.	required
timeout	float	Maximum time to wait for response.	15.0

Returns:

Type	Description
bool	True if the room exists, False otherwise.

Raises:

Type	Description
VideoRoomError	If request fails.
TimeoutError	If request times out.

join_as_publisher async

join_as_publisher(room_id: int, publisher_id: Optional[int] = None, display: Optional[str] = None, token: Optional[str] = None, timeout: float = 15.0) -> Dict[str, Any]

Join a room as a publisher. Emits VideoRoomEventType.JOINED event.

Parameters:

Name	Type	Description	Default
room_id	int	The room ID to join.	required
publisher_id	Optional[int]	Unique publisher ID (auto-generated if not provided).	None
display	Optional[str]	Display name for the publisher.	None
token	Optional[str]	Invitation token if room has ACL.	None
timeout	float	Maximum time to wait for response.	15.0

Returns:

Type	Description
Dict[str, Any]	Join response containing room info and current publishers.

Raises:

Type	Description
VideoRoomError	If join fails.
TimeoutError	If request times out.

publish async

publish(player: MediaPlayer, audiocodec: Optional[str] = None, videocodec: Optional[str] = None, bitrate: Optional[int] = None, record: bool = False, filename: Optional[str] = None, descriptions: Optional[List[Dict[str, str]]] = None, trickle: bool = False, timeout: float = 30.0) -> dict

Publish media streams to the room.

Parameters:

Name	Type	Description	Default
player	MediaPlayer	MediaPlayer for outgoing media streams.	required
audiocodec	Optional[str]	Preferred audio codec.	None
videocodec	Optional[str]	Preferred video codec.	None
bitrate	Optional[int]	Bitrate cap for REMB.	None
record	bool	Whether to record this publisher.	False
filename	Optional[str]	Base filename for recordings.	None
descriptions	Optional[List[Dict[str, str]]]	Stream descriptions for UI rendering.	None
trickle	bool	Whether to use trickle ICE.	False
timeout	float	Maximum time to wait for response.	30.0

Raises:

Type	Description
VideoRoomError	If publish fails.
TimeoutError	If request times out.

unpublish async

unpublish(timeout: float = 15.0) -> None

Stop publishing media.

Parameters:

Name	Type	Description	Default
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
VideoRoomError	If unpublish fails.
TimeoutError	If request times out.

configure async

configure(bitrate: Optional[int] = None, keyframe: bool = False, record: Optional[bool] = None, filename: Optional[str] = None, display: Optional[str] = None, streams: Optional[List[Dict[str, Any]]] = None, descriptions: Optional[List[Dict[str, str]]] = None, timeout: float = 15.0) -> None

Configure publisher settings.

Parameters:

Name	Type	Description	Default
bitrate	Optional[int]	New bitrate cap.	None
keyframe	bool	Whether to request a keyframe.	False
record	Optional[bool]	Whether to record this publisher.	None
filename	Optional[str]	Base filename for recordings.	None
display	Optional[str]	New display name.	None
streams	Optional[List[Dict[str, Any]]]	Stream-specific configurations.	None
descriptions	Optional[List[Dict[str, str]]]	Updated stream descriptions.	None
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
VideoRoomError	If configure fails.
TimeoutError	If request times out.

subscribe_to_publisher async

subscribe_to_publisher(room_id: int, streams: List[Dict[str, Any]], recorder: Optional[MediaRecorder] = None, private_id: Optional[int] = None, use_msid: bool = False, autoupdate: bool = True, trickle: bool = False, timeout: float = 30.0) -> Dict[str, Any]

Subscribe to publisher streams.

Parameters:

Name	Type	Description	Default
room_id	int	The room ID containing the publishers.	required
streams	List[Dict[str, Any]]	List of stream configurations to subscribe to. Each stream should have at least a 'feed' key with publisher ID.	required
recorder	Optional[MediaRecorder]	MediaRecorder for incoming media streams.	None
private_id	Optional[int]	Private ID for association with publisher.	None
use_msid	bool	Whether to include msid referencing the publisher.	False
autoupdate	bool	Whether to auto-update on publisher changes.	True
trickle	bool	Whether to use trickle ICE.	False
timeout	float	Maximum time to wait for response.	30.0

Returns:

Type	Description
Dict[str, Any]	Subscription information.

Raises:

Type	Description
VideoRoomError	If subscription fails.
TimeoutError	If request times out.

start async

start(trickle: bool = False, timeout: float = 15.0) -> None

Start receiving media (send JSEP answer).

Parameters:

Name	Type	Description	Default
trickle	bool	Whether to use trickle ICE.	False
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
VideoRoomError	If start fails.
TimeoutError	If request times out.

pause async

pause(timeout: float = 15.0) -> None

Pause media delivery.

Parameters:

Name	Type	Description	Default
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
VideoRoomError	If pause fails.
TimeoutError	If request times out.

subscribe async

subscribe(streams: List[Dict[str, Any]], timeout: float = 15.0) -> None

Subscribe to additional streams.

Parameters:

Name	Type	Description	Default
streams	List[Dict[str, Any]]	List of new streams to subscribe to.	required
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
VideoRoomError	If subscription fails.
TimeoutError	If request times out.

unsubscribe async

unsubscribe(streams: List[Dict[str, Any]], timeout: float = 15.0) -> None

Unsubscribe from streams.

Parameters:

Name	Type	Description	Default
streams	List[Dict[str, Any]]	List of streams to unsubscribe from.	required
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
VideoRoomError	If unsubscription fails.
TimeoutError	If request times out.

switch_publisher async

switch_publisher(streams: List[Dict[str, Any]], timeout: float = 15.0) -> None

Switch to different publisher streams without renegotiation.

Parameters:

Name	Type	Description	Default
streams	List[Dict[str, Any]]	List of stream switches to perform. Each should have 'feed', 'mid', and 'sub_mid' keys.	required
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
VideoRoomError	If switch fails.
TimeoutError	If request times out.

leave async

leave(timeout: float = 15.0) -> None

Leave the room.

Parameters:

Name	Type	Description	Default
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
VideoRoomError	If leave fails.
TimeoutError	If request times out.

kick_participant async

kick_participant(room_id: int, participant_id: int, secret: str, timeout: float = 15.0) -> None

Kick a participant from the room.

Parameters:

Name	Type	Description	Default
room_id	int	The room ID.	required
participant_id	int	ID of participant to kick.	required
secret	str	Room secret for authorization.	required
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
VideoRoomError	If kick fails.
TimeoutError	If request times out.

moderate_participant async

moderate_participant(room_id: int, participant_id: int, mid: str, mute: bool, secret: str, timeout: float = 15.0) -> None

Moderate a participant's media stream.

Parameters:

Name	Type	Description	Default
room_id	int	The room ID.	required
participant_id	int	ID of participant to moderate.	required
mid	str	Media line ID to moderate.	required
mute	bool	Whether to mute (True) or unmute (False).	required
secret	str	Room secret for authorization.	required
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
VideoRoomError	If moderation fails.
TimeoutError	If request times out.

destroy async

destroy() -> None

Destroy the plugin and clean up all resources.

VideoRoomError Exception

janus_client.plugin_video_room.VideoRoomError

Bases: Exception

Exception raised for VideoRoom plugin errors.

VideoRoomEventType Enum

janus_client.plugin_video_room.VideoRoomEventType

Bases: Enum

Types of events that can be received from the VideoRoom plugin.

ParticipantType Enum

janus_client.plugin_video_room.ParticipantType

Bases: Enum

Types of participants in a VideoRoom.

TextRoom Plugin

janus_client.plugin_textroom.JanusTextRoomPlugin

Bases: JanusPlugin

Janus TextRoom plugin client.

This plugin provides text-based communication through WebRTC DataChannels. It supports multiple rooms, public and private messaging, and room management. From my observation, the datachannel is only created after a room is joined, so the first join request cannot be sent through datachannel.

Example

session = JanusSession(base_url="wss://example.com/janus")
plugin = JanusTextRoomPlugin()

async with session:
    await plugin.attach(session)
    await plugin.setup()

    # Join a room
    participants = await plugin.join_room(room=1234, username="alice")

    # Register message handler
    def on_message(data):
        print(f"Message from {data['from']}: {data['text']}")

    plugin.on_event(TextRoomEventType.MESSAGE, on_message)

    # Send a message
    await plugin.send_message(room=1234, text="Hello, world!")

    # Leave the room
    await plugin.leave_room(room=1234)

    await plugin.destroy()

__init__

__init__(**kwargs: Any) -> None

Initialize the TextRoom plugin.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Keyword arguments passed to JanusPlugin constructor. Supports pc_config parameter for WebRTC configuration.	{}

Examples:

Basic usage:

plugin = JanusTextRoomPlugin()

With WebRTC configuration:

from aiortc import RTCConfiguration, RTCIceServer

config = RTCConfiguration(iceServers=[
    RTCIceServer(urls='stun:stun.l.google.com:19302')
])
plugin = JanusTextRoomPlugin(pc_config=config)

on_receive async

on_receive(response: Dict[str, Any]) -> None

Handle incoming messages from Janus.

Parameters:

Name	Type	Description	Default
response	Dict[str, Any]	The response message from Janus.	required

on_event

on_event(event_type: TextRoomEventType, handler: Callable[[Dict[str, Any]], None]) -> None

Register an event handler for TextRoom events.

Parameters:

Name	Type	Description	Default
event_type	TextRoomEventType	The type of event to handle.	required
handler	Callable[[Dict[str, Any]], None]	Callback function to handle the event.	required

setup async

setup(timeout: float = 30.0) -> None

Initialize the WebRTC connection for the TextRoom plugin.

This must be called before joining rooms or sending messages.

Parameters:

Name	Type	Description	Default
timeout	float	Maximum time to wait for setup completion.	30.0

Raises:

Type	Description
TimeoutError	If setup doesn't complete within timeout.
TextRoomError	If setup fails.

list_rooms async

list_rooms(admin_key: Optional[str] = None, timeout: float = 15.0) -> List[Dict[str, Any]]

List available rooms.

Parameters:

Name	Type	Description	Default
admin_key	Optional[str]	Optional admin key for accessing private rooms.	None
timeout	float	Maximum time to wait for response.	15.0

Returns:

Type	Description
List[Dict[str, Any]]	List of room information dictionaries.

Raises:

Type	Description
TimeoutError	If request times out.
TextRoomError	If request fails.

list_participants async

list_participants(room: int, timeout: float = 15.0) -> List[Dict[str, Any]]

List participants in a room.

Parameters:

Name	Type	Description	Default
room	int	The room ID to query.	required
timeout	float	Maximum time to wait for response.	15.0

Returns:

Type	Description
List[Dict[str, Any]]	List of participant information dictionaries.

Raises:

Type	Description
TimeoutError	If request times out.
TextRoomError	If request fails.

create_room async

create_room(room: Optional[int] = None, description: Optional[str] = None, secret: Optional[str] = None, pin: Optional[str] = None, is_private: bool = True, history: int = 0, post: Optional[str] = None, admin_key: Optional[str] = None, permanent: bool = False, timeout: float = 15.0) -> int

Create a new TextRoom.

Parameters:

Name	Type	Description	Default
room	Optional[int]	Room ID to assign (optional, auto-generated if not provided).	None
description	Optional[str]	Room description.	None
secret	Optional[str]	Secret for room management.	None
pin	Optional[str]	PIN required to join the room.	None
is_private	bool	Whether the room should be private.	True
history	int	Number of messages to store as history.	0
post	Optional[str]	HTTP backend URL for message forwarding.	None
admin_key	Optional[str]	Admin key if required by server.	None
permanent	bool	Whether to save room to config file.	False
timeout	float	Maximum time to wait for response.	15.0

Returns:

Type	Description
int	The created room ID.

Raises:

Type	Description
TimeoutError	If request times out.
TextRoomError	If creation fails.

destroy_room async

destroy_room(room: int, secret: Optional[str] = None, permanent: bool = False, timeout: float = 15.0) -> None

Destroy a TextRoom.

Parameters:

Name	Type	Description	Default
room	int	The room ID to destroy.	required
secret	Optional[str]	Room secret if required.	None
permanent	bool	Whether to remove from config file.	False
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
TimeoutError	If request times out.
TextRoomError	If destruction fails.

join_room async

join_room(room: int, username: str, display: Optional[str] = None, pin: Optional[str] = None, token: Optional[str] = None, history: bool = True, timeout: float = 15.0) -> List[Dict[str, Any]]

Join a TextRoom.

Parameters:

Name	Type	Description	Default
room	int	The room ID to join.	required
username	str	Unique username for this participant.	required
display	Optional[str]	Display name for this participant.	None
pin	Optional[str]	Room PIN if required.	None
token	Optional[str]	Invitation token if room has ACL.	None
history	bool	Whether to retrieve message history.	True
timeout	float	Maximum time to wait for response.	15.0

Returns:

Type	Description
List[Dict[str, Any]]	List of current participants in the room.

Raises:

Type	Description
TimeoutError	If request times out.
TextRoomError	If join fails.

leave_room async

leave_room(room: int, timeout: float = 15.0) -> None

Leave a TextRoom.

Parameters:

Name	Type	Description	Default
room	int	The room ID to leave.	required
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
TimeoutError	If request times out.
TextRoomError	If leave fails.

send_message async

send_message(room: int, text: str, to: Optional[str] = None, tos: Optional[List[str]] = None, ack: bool = True, timeout: float = 15.0) -> None

Send a message in a TextRoom.

Parameters:

Name	Type	Description	Default
room	int	The room ID to send the message to.	required
text	str	The message text to send.	required
to	Optional[str]	Username to send private message to (optional).	None
tos	Optional[List[str]]	List of usernames to send private message to (optional).	None
ack	bool	Whether to wait for acknowledgment.	True
timeout	float	Maximum time to wait for acknowledgment.	15.0

Raises:

Type	Description
TimeoutError	If request times out.
TextRoomError	If send fails.

send_announcement async

send_announcement(room: int, text: str, secret: str, timeout: float = 15.0) -> None

Send an announcement to a TextRoom.

Parameters:

Name	Type	Description	Default
room	int	The room ID to send the announcement to.	required
text	str	The announcement text.	required
secret	str	Room secret for authorization.	required
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
TimeoutError	If request times out.
TextRoomError	If send fails.

kick_participant async

kick_participant(room: int, username: str, secret: str, timeout: float = 15.0) -> None

Kick a participant from a TextRoom.

Parameters:

Name	Type	Description	Default
room	int	The room ID.	required
username	str	Username of participant to kick.	required
secret	str	Room secret for authorization.	required
timeout	float	Maximum time to wait for response.	15.0

Raises:

Type	Description
TimeoutError	If request times out.
TextRoomError	If kick fails.

TextRoomError Exception

janus_client.plugin_textroom.TextRoomError

Bases: Exception

Exception raised for TextRoom plugin errors.

TextRoomEventType Enum

janus_client.plugin_textroom.TextRoomEventType

Bases: Enum

Types of events that can be received from the TextRoom plugin.

Transport Classes

Base Transport Class

janus_client.transport.JanusTransport

Bases: ABC

Janus transport protocol interface for managing sessions and transactions.

Attributes:

Name	Type	Description
connected	bool	Boolean indicating if the transport is currently connected.

connected instance-attribute

connected: bool = False

Must set this property when connected or disconnected

info async

info() -> Dict

Get information about the Janus server.

Returns:

Type	Description
Dict	Dictionary containing server information including version,
Dict	name, supported plugins, and other server details.

Note

This method may be overridden by specific transport implementations (e.g., HTTP transport) to provide transport-specific behavior.

ping async

ping() -> Dict

Send a ping request to the Janus server.

Returns:

Type	Description
Dict	Dictionary containing the pong response from the server.

Raises:

Type	Description
TimeoutError	If no pong response is received within 15 seconds.

dispatch_session_created async

dispatch_session_created(session_id: int) -> None

Handle session creation event.

Parameters:

Name	Type	Description	Default
session_id	int	The unique identifier of the newly created session.	required

dispatch_session_destroyed async

dispatch_session_destroyed(session_id: int) -> None

Handle session destruction event.

Parameters:

Name	Type	Description	Default
session_id	int	The unique identifier of the destroyed session.	required

__init__

__init__(base_url: str, api_secret: Optional[str] = None, token: Optional[str] = None, **kwargs: dict)

Initialize a new Janus transport instance.

Parameters:

Name	Type	Description	Default
base_url	str	The base URL of the Janus server (e.g., 'ws://localhost:8188'). Trailing slashes will be automatically removed.	required
api_secret	Optional[str]	Optional API secret for shared static secret authentication. If provided, will be included in all requests to the server.	None
token	Optional[str]	Optional token for shared token-based authentication. If provided, will be included in all requests to the server.	None
**kwargs	dict	Additional keyword arguments passed to transport implementations.	{}

connect async

connect() -> None

Establish connection to the Janus server.

Raises:

Type	Description
Exception	If connection establishment fails.

disconnect async

disconnect() -> None

Close connection and release resources.

send async

send(message: Dict, session_id: Optional[int] = None, handle_id: Optional[int] = None) -> MessageTransaction

Send a message to the Janus server.

Parameters:

Name	Type	Description	Default
message	Dict	JSON serializable dictionary containing the message to send. Must include a 'janus' field specifying the message type.	required
session_id	Optional[int]	Optional session ID to include in the message for session-specific requests.	None
handle_id	Optional[int]	Optional handle ID to include in the message for plugin-specific requests.	None

Returns:

Type	Description
MessageTransaction	MessageTransaction object that can be used to wait for and retrieve
MessageTransaction	the server's response to this message.

Raises:

Type	Description
Exception	If the message is missing the required 'janus' field.

receive async

receive(response: dict) -> None

Process an incoming response from the Janus server.

Parameters:

Name	Type	Description	Default
response	dict	Dictionary containing the response from the Janus server.	required

create_session async

create_session(session: JanusSession) -> int

Create a new Janus session.

Parameters:

Name	Type	Description	Default
session	JanusSession	The JanusSession object to associate with the new session ID.	required

Returns:

Type	Description
int	The unique session ID assigned by the Janus server.

Raises:

Type	Description
Exception	If session creation fails or the server returns an error.

destroy_session async

destroy_session(session_id: int) -> None

Destroy a Janus session and clean up resources.

Parameters:

Name	Type	Description	Default
session_id	int	The unique identifier of the session to destroy.	required

Note

This method should not be called directly from client code. Use the destroy() method on the JanusSession object instead.

register_transport staticmethod

register_transport(protocol_matcher: Callable, transport_cls: JanusTransport) -> None

Register a transport implementation for automatic selection.

Parameters:

Name	Type	Description	Default
protocol_matcher	Callable	A callable that takes a base_url string and returns True if this transport can handle that URL protocol.	required
transport_cls	JanusTransport	The JanusTransport subclass to register for the matching protocol.	required

create_transport staticmethod

create_transport(base_url: str, api_secret: Optional[str] = None, token: Optional[str] = None, config: Dict = {}) -> JanusTransport

Create an appropriate transport instance based on the URL protocol.

Automatically selects and instantiates the correct transport implementation based on the base_url protocol. This method is typically called by JanusSession to create the transport automatically.

Parameters:

Name	Type	Description	Default
base_url	str	The base URL of the Janus server. The protocol determines which transport implementation is used.	required
api_secret	Optional[str]	Optional API secret for shared static secret authentication.	None
token	Optional[str]	Optional token for shared token-based authentication.	None
config	Dict	Additional configuration parameters to pass to the transport constructor.	{}

Returns:

Type	Description
JanusTransport	An instance of the appropriate JanusTransport subclass for communicating
JanusTransport	with the Janus server.

Raises:

Type	Description
Exception	If no transport implementation matches the URL protocol.
Exception	If multiple transport implementations match the URL protocol.

HTTP Transport

janus_client.transport_http.JanusTransportHTTP

Bases: JanusTransport

Janus transport through HTTP

WebSocket Transport

janus_client.transport_websocket.JanusTransportWebsocket

Bases: JanusTransport

Janus transport through HTTP

Manage Sessions and Transactions