RoomOptions

RoomOptions is a configuration class that defines how an AI agent connects to and behaves within a VideoSDK meeting room. It serves as the primary interface for customizing agent behavior, meeting connection parameters, and session management settings.

Introduction

The RoomOptions class is the central configuration point for VideoSDK AI agents, providing comprehensive control over how agents join meetings, interact with participants, and manage their sessions. This configuration is passed to the JobContext during agent initialization and influences all aspects of the agent's behavior within the meeting environment.

Core Features

• Meeting Connection: Configure room ID, authentication, and transport mode for VideoSDK meetings
• Agent Identity: Set display name, participant ID, and visual representation
• Session Management: Control automatic session termination and timeouts
• Media Capabilities: Enable vision processing, meeting recording, and background audio
• Telemetry: Configure traces, metrics, and log collection/export
• Transport Modes: Support for VideoSDK, WebSocket, and WebRTC transports
• Development Tools: Playground mode for testing and development
• Error Handling: Custom error handling callbacks
• Avatar Integration: Support for virtual avatars

Basic Example

main.py

from videosdk.agents import RoomOptions, JobContext  
  
# Basic configuration  
room_options = RoomOptions(  
    room_id="your-meeting-id",  
    name="My AI Agent",  
    playground=True  
)  
  
# Create job context 
context = JobContext(room_options=room_options)

Parameters

Parameters that you can pass with RoomOptions:

Connection & Identity

Parameter	Type	Default	Description
room_id	Optional[str]	None	Unique identifier for the VideoSDK meeting
auth_token	Optional[str]	None	VideoSDK authentication token
name	Optional[str]	"Agent"	Display name of the agent in the meeting
agent_participant_id	Optional[str]	None	Custom participant ID for the agent
join_meeting	Optional[bool]	True	Whether agent should join the meeting
signaling_base_url	Optional[str]	"api.videosdk.live"	VideoSDK signaling server URL

Media & Features

Parameter	Type	Default	Description
playground	bool	True	Enable playground mode for easy testing
vision	bool	False	Enable video processing capabilities
recording	bool	False	Enable meeting recording. When True, audio is always recorded via the track API. Use recording_options to additionally record camera video or screen share.
recording_options	Optional[RecordingOptions]	None	Fine-grained control over what is recorded alongside audio (see RecordingOptions)
background_audio	bool	False	Enable background audio (e.g., thinking sounds)
avatar	Optional[Any]	None	Virtual avatar for visual representation

Session Management

Parameter	Type	Default	Description
auto_end_session	bool	True	Automatically end session when participants leave
session_timeout_seconds	Optional[int]	5	Seconds to wait before ending the session after the last participant leaves
no_participant_timeout_seconds	Optional[int]	90	Seconds to wait for the first participant to join before automatically shutting down. Set to None to wait indefinitely.
on_room_error	Optional[Callable]	None	Error handling callback function

Telemetry & Logging

Parameter	Type	Default	Description
traces	Optional[TracesOptions]	TracesOptions()	OpenTelemetry trace export configuration
metrics	Optional[MetricsOptions]	MetricsOptions()	Metrics collection and export configuration
logs	Optional[LoggingOptions]	LoggingOptions()	Log collection and export configuration
send_logs_to_dashboard	bool	False	Send logs to VideoSDK dashboard
dashboard_log_level	str	"INFO"	Log level for dashboard logs
send_analytics_to_pubsub	Optional[bool]	False	Send analytics data via PubSub

Transport Configuration

Parameter	Type	Default	Description
transport_mode	Optional[str | TransportMode]	"videosdk"	Transport mode: "videosdk", "websocket", or "webrtc"
websocket	Optional[WebSocketConfig]	WebSocketConfig()	WebSocket transport configuration
webrtc	Optional[WebRTCConfig]	WebRTCConfig()	WebRTC transport configuration

---

TracesOptions

Parameter	Type	Default	Description
enabled	bool	True	Enable trace collection
export_url	Optional[str]	None	Custom export endpoint URL
export_headers	Optional[Dict[str, str]]	None	Custom headers for the export endpoint

MetricsOptions

Parameter	Type	Default	Description
enabled	bool	True	Enable metrics collection
export_url	Optional[str]	None	Custom export endpoint URL
export_headers	Optional[Dict[str, str]]	None	Custom headers for the export endpoint

LoggingOptions

Parameter	Type	Default	Description
enabled	bool	False	Enable log export
level	str	"INFO"	Log level filter (DEBUG, INFO, WARNING, ERROR)
export_url	Optional[str]	None	Custom export endpoint URL
export_headers	Optional[Dict[str, str]]	None	Custom headers for the export endpoint

WebSocketConfig

Parameter	Type	Default	Description
port	int	8080	Port for the WebSocket server
path	str	"/ws"	Endpoint path for the WebSocket connection

WebRTCConfig

Parameter	Type	Default	Description
signaling_url	Optional[str]	None	Signaling server URL (required for WebRTC mode)
signaling_type	str	"websocket"	Type of signaling transport
ice_servers	Optional[list]	[{"urls": "stun:stun.l.google.com:19302"}]	ICE server configuration for NAT traversal

RecordingOptions

Controls what is recorded in addition to audio when recording=True. Audio is always recorded via the track API when recording=True; these fields opt in to additional streams.

Parameter	Type	Default	Description
video	bool	False	Also record the agent's camera video track (composite audio+video via participant recording API)
screen_share	bool	False	Also record the screen-share track. Requires vision=True.

main.py

from videosdk.agents import RoomOptions, RecordingOptions

# Audio-only recording (default when recording_options is omitted)
room_options = RoomOptions(
    room_id="your-room-id",
    recording=True,
)

# Audio + screen share recording
room_options = RoomOptions(
    room_id="your-room-id",
    vision=True,          # required for screen share recording
    recording=True,
    recording_options=RecordingOptions(screen_share=True),
)

# Composite audio + video (participant recording API)
room_options = RoomOptions(
    room_id="your-room-id",
    recording=True,
    recording_options=RecordingOptions(video=True),
)

note

recording_options.screen_share=True requires vision=True because vision subscribes to the video/share streams needed for screen recording. Setting screen_share=True without vision=True raises a ValueError at startup.

Transport Modes

The RoomOptions supports three transport modes:

main.py

from videosdk.agents import RoomOptions, WebSocketConfig, WebRTCConfig

# Default: VideoSDK transport
room_options = RoomOptions(room_id="your-meeting-id")

# WebSocket transport
room_options = RoomOptions(
    transport_mode="websocket",
    websocket=WebSocketConfig(port=8080, path="/ws")
)

# WebRTC transport
room_options = RoomOptions(
    transport_mode="webrtc",
    webrtc=WebRTCConfig(signaling_url="wss://your-signaling-server.com")
)

Telemetry Configuration

Configure traces, metrics, and logging for observability:

main.py

from videosdk.agents import RoomOptions, TracesOptions, MetricsOptions, LoggingOptions

room_options = RoomOptions(
    room_id="your-meeting-id",
    traces=TracesOptions(
        enabled=True,
        export_url="https://your-otel-collector.com/v1/traces",
        export_headers={"Authorization": "Bearer your-token"}
    ),
    metrics=MetricsOptions(
        enabled=True,
        export_url="https://your-otel-collector.com/v1/metrics"
    ),
    logs=LoggingOptions(
        enabled=True,
        level="DEBUG"
    )
)

Additional Resources

Playground Mode

A testing environment to experiment with different agent configurations

Vision Integration

Enable agents to receive and process video input from the meeting

Recording Capabilities

Record agent sessions for analysis and quality assurance

Avatar

Use Avatar for visually engaging AI Voice Agent