Room System

The Monibuca V6 room system consists of four parts:

1. Room Service (engine built-in) — Provides core room lifecycle management
2. Live Plugin — Live room extension features
3. Meeting Plugin — Meeting room extension features
4. CustomerService Plugin — 1v1 customer service call features

Room is a Built-in Service, Not a Plugin

The Room Service is integrated directly into the engine (src/room/), enabled via the room feature through conditional compilation. It does not implement the Plugin trait; instead, the engine directly manages its initialization and lifecycle. Live, Meeting, and CustomerService, as independent plugins, register async callbacks (RoomCallbacks) with the Room Service through the RoomApi trait.

How to Enable

# Enable Room Service (required)
# The room feature is enabled via conditional compilation in Cargo.toml

# Enable Live Room plugin
features = ["live"]

# Enable Meeting Room plugin
features = ["meeting"]

# Enable Customer Service plugin
features = ["customer-service"]

# Enable all at once
features = ["live", "meeting", "customer-service"]

Architecture Design

graph TB
    subgraph RS["Room Service (Engine Built-in)"]
        Core["Room create/destroy/join/leave<br/>WebSocket/heartbeat/auth/reporting"]
        API["RoomApi trait + ExtensionManager<br/>Plugins register RoomCallbacks async callbacks<br/>Plugin operations: broadcast/lock/mute/kick/ban/lobby"]
    end

    subgraph Plugins["Plugin Extensions"]
        Live["LiveExtension (Live Room)<br/>manages_own_sessions: true"]
        Meeting["MeetingExtension (Meeting Room)<br/>manages_own_sessions: false"]
    end

    Core --> API
    API --> Live
    API --> Meeting
    API --> CS["CustomerServiceExtension (Customer Service)<br/>manages_own_sessions: true<br/>max_users: 2"]
    Live -->|"room_api.broadcast_to_room()<br/>room_api.add_ban()<br/>room_api.remove_user()"| RS
    Meeting -->|"room_api.set_room_locked()<br/>room_api.set_lobby_enabled()<br/>room_api.admit_user()"| RS
    CS -->|"room_api.broadcast_to_room()<br/>room_api.remove_user()"| RS

Room Service Core Features

• Room creation, joining, leaving, and destruction
• User management and authentication (external HTTP verification)
• WebSocket connection management and real-time signaling
• Heartbeat detection (auto-kick on timeout)
• Chat rate limiting
• Behavior reporting and statistics

RoomApi — The Sole Contract Between Plugins and Engine

Plugins obtain Arc<dyn RoomApi> via EngineContext.room_api() for:

Registering callbacks (during init()):

• register_callbacks(RoomType::Live, RoomCallbacks { ... })
• Callbacks are invoked asynchronously by the engine when room lifecycle events occur

Operating on rooms (in callbacks or HTTP handlers):

• broadcast_to_room() — Broadcast messages
• set_room_locked() / set_room_recording() — Room state
• remove_user() — Kick user
• add_ban() / remove_ban() — Ban management
• add_chat_mute() / remove_chat_mute() — Chat mute
• set_lobby_enabled() / admit_user() / reject_user() — Lobby (waiting room)

WebSocket Connection

Clients connect to the Room Service via WebSocket for real-time signaling communication:

ws://host:port/room/{room_id}?token={auth_token}

WebSocket messages use JSON format, differentiated by the action field:

{
  "action": "join_room",
  "room_id": "100001",
  "user_id": "user_001",
  "user_name": "John"
}

Common Signaling

Action	Direction	Description
join_room	C→S	Join room
leave_room	C→S	Leave room
heartbeat	C→S	Heartbeat keepalive
chat	C→S	Chat message (broadcast after rate limiting)
action	C→S	Permission operations (lock, record, kick, etc.)
media_state	C→S	Update media state
user_joined	S→C	A user has joined the room
user_left	S→C	A user has left the room
room_closed	S→C	Room has been closed
error	S→C	Error notification

Unmatched message types are forwarded to the ExtensionManager, where they are handled by plugin-registered on_message callbacks.

Message Processing Sequence

sequenceDiagram
    participant C as Client
    participant H as RoomWsHandler
    participant RS as RoomService
    participant EM as ExtensionManager
    participant Ext as Plugin Extension

    C->>H: ws: { action, room_id, ... }

    alt action = "join"
        H->>RS: verify_user()
        RS-->>H: ok
        H->>RS: Room.add_user()
        H->>EM: on_user_join callback
    else action = "leave"
        H->>EM: on_user_leave callback
        H->>RS: Room.remove_user()
    else action = "chat"
        H->>RS: rate_limit → Room.broadcast_text()
    else action = "action"
        H->>H: permission check → ActionExecutor
    else other (custom)
        H->>EM: on_message callback
        EM->>Ext: plugin parses as LiveEvent / MeetingEvent
    end

---

Live Room Plugin (Live)

The Live plugin provides rich interactive features for live streaming scenarios. For comprehensive documentation, see Live Room Plugin.

Feature List

• Live room lifecycle: Preparing → Living → Paused → Ended
• Co-hosting system: Supports host-audience interactive co-hosting
• Gift system: Gift sending with combo support, broadcast via RoomApi.broadcast_to_room()
• PK battles: Host-vs-host PK battle functionality
• Bot viewers: Simulated viewers (for testing)
• Data persistence: Live room data stored in database
• Moderation capabilities: Kick, ban, and chat mute via RoomApi

Live Room Signaling

Action	Direction	Description
start_live	C→S	Start live stream
stop_live	C→S	End live stream
pause_live	C→S	Pause live stream
resume_live	C→S	Resume live stream
send_gift	C→S	Send gift
gift_received	S→C	Gift notification (broadcast)
send_danmaku	C→S	Send bullet comment
link_mic_request	C→S	Request co-hosting
link_mic_accept	C→S	Accept co-hosting
link_mic_reject	C→S	Reject co-hosting
link_mic_end	C→S	End co-hosting
pk_invite	C→S	Send PK invitation
pk_accept	C→S	Accept PK
pk_end	C→S	End PK

Configuration

live:
  gift:
    combo_timeout: 5            # Combo timeout (seconds)
    max_combo_count: 999        # Maximum combo count
  link_mic:
    max_participants: 6         # Maximum co-hosting participants
    timeout: 30                 # Co-hosting invitation timeout (seconds)

---

Meeting Room Plugin (Meeting)

The Meeting plugin provides comprehensive meeting management features for video conferencing scenarios. For comprehensive documentation, see Meeting Room Plugin.

Feature List

• Agenda management: Meeting agenda creation and control
• Timer: Meeting and speaking timers
• Real-time transcription: Speech-to-text (requires external ASR service)
• AI meeting summary: Automatic meeting minutes generation
• Task extraction: Extract action items from meeting content
• Recording control: Control recording via RoomApi.set_room_recording()
• Lobby (waiting room): Managed via RoomApi.set_lobby_enabled() + admit_user() / reject_user()

Meeting Room Signaling

Action	Direction	Description
start_meeting	C→S	Start meeting
end_meeting	C→S	End meeting
mute_participant	C→S	Mute participant (via RoomApi)
unmute_participant	C→S	Unmute participant
kick_participant	C→S	Kick participant (via RoomApi)
raise_hand	C→S	Raise hand
lower_hand	C→S	Lower hand
start_recording	C→S	Start recording (via RoomApi)
stop_recording	C→S	Stop recording
start_transcription	C→S	Start transcription
share_screen	C→S	Share screen
lock_room	C→S	Lock/unlock room (via RoomApi)
toggle_lobby	C→S	Toggle lobby (via RoomApi)
admit_user	C→S	Admit user (via RoomApi)
reject_user	C→S	Reject user (via RoomApi)
ban_user	C→S	Ban user (via RoomApi)
participant_muted	S→C	Participant muted notification
participant_kicked	S→C	Participant kicked notification
transcription_result	S→C	Transcription result push

Configuration

meeting:
  max_participants: 50          # Maximum number of participants
  enable_lobby: true            # Enable lobby (waiting room)
  enable_recording: true        # Allow recording
  enable_transcription: false   # Enable transcription
  timer:
    max_duration: 7200          # Maximum meeting duration (seconds)
    warning_before_end: 300     # Warning N seconds before end

---

Customer Service Plugin (CustomerService)

The CustomerService plugin provides professional support for 1v1 customer service call scenarios. For comprehensive documentation, see Customer Service Plugin.

Feature List

• 1v1 calls: Each session is limited to 2 participants (agent + customer), max_users: 2
• Session management: Create, assign agent, close, statistics
• No-login customer side: Customers enter directly via link without registration
• Audio mixing: Agent side can mix local audio files into the stream (background music, notification sounds)
• Satisfaction rating: Customers can provide star ratings after the call ends

Customer Service Signaling

Action	Direction	Description
accept_call	C→S	Agent accepts the call
end_call	C→S	Hang up the call
transfer_call	C→S	Transfer to another agent
hold_call	C→S	Hold the call
resume_call	C→S	Resume the call
call_accepted	S→C	Call has been answered
call_ended	S→C	Call has ended
call_transferred	S→C	Call has been transferred

Configuration

customer_service:
  max_sessions: 1000          # Maximum concurrent sessions
  session_timeout: 3600       # Session timeout (seconds)
  enable_recording: false     # Enable call recording

For detailed HTTP API reference, see Customer Service API.

---

Reporting and Statistics

The Room Service includes a comprehensive three-tier reporting system that automatically collects audio/video quality data and user behavior data, providing essential support for operations and troubleshooting.

Key Highlight

The reporting system is a major capability upgrade in V6. Through heartbeat reports that continuously capture bitrate/framerate/packet loss and other quality metrics, combined with Admin dashboards, developers can quickly diagnose audio/video issues while operations teams can monitor site-wide live streaming status. See Monitoring & Operations for full details.

Three-Tier Reporting

Report Type	Trigger	Core Content	Storage Table
Heartbeat	Periodic (every few seconds)	Audio/video bitrate, framerate, resolution, packet loss, freeze, RTT	report_heartbeats + report_heartbeat_downstream
Leave Room	When user leaves	Session duration, device info, SDK version, join context	report_leave_rooms
KV	Event-driven	Success rate & latency for 15+ events (join/publish/subscribe, etc.)	report_kv

Data Query API

Endpoint	Description
GET /room_stats/{room_id}	Detailed room statistics (heartbeat+leave+KV), supports start_time / end_time params
GET /all_room_stats	Site-wide aggregate statistics with all room sessions and summaries
GET /daily_stats	Daily trend data (sessions, users, peak concurrent, streaming duration)

Admin Dashboard Integration

Reporting data powers three dashboards in the Admin console:

• Stream Detail: Real-time bitrate/framerate waveforms + historical trend charts for individual streams
• Room Report: Sender-receiver pair bitrate comparison, freeze analysis, event timelines
• Live Dashboard: Site-wide real-time overview, 7-day trends, risk detection, popularity ranking

Data Retention Configuration

room:
  live:
    report_retention_days: 15   # Keep last 15 days (0 = keep forever)

Background cleanup tasks automatically delete expired records. Reporting data is persisted via ReportStorage to the database, with automatic fallback to in-memory storage when the database is unavailable.