Live Room

The Live Room plugin (Live) provides real-time interactive live streaming capabilities for Monibuca V6. Suitable for talent shows, social live streaming, e-commerce live streaming, and other scenarios.

Core Features

1 Streamer + N Viewers: Support 100+ concurrent viewers, no limit on audience size
Real-time Interaction System:
- Gift system & Combo support
- Co-hosting system (Link-Mic), streamer can invite viewers to co-host
- PK battles for real-time competition between streamers
Bot Viewers: Simulated viewers for testing and demonstration
Danmaku (Bullet Comments): Bullet comment posting, rate limiting, content filtering
Data Persistence: Live room information, gift records, and viewer data stored in database
Moderation Capabilities: Kick users, ban, chat mute, and other streamer permissions

How to Enable

features = ["live"]

# Live plugin depends on Room Service
# room feature is automatically enabled

Architecture Design

graph TB
    subgraph Live["LivePlugin"]
        SM["SessionManager<br/>Live room info, gift system"]
        GiftSys["GiftSystem<br/>Combo detection"]
        LinkMic["LinkMicSystem<br/>Co-hosting request queue"]
        RobotMgr["RobotManager<br/>Simulated viewers"]
        DB["Data Persistence<br/>Rooms, gifts, viewers"]
    end

    subgraph RS["Room Service"]
        Room["Room Management<br/>Streamer + Viewers"]
        WS["WebSocket<br/>Signaling"]
        API["RoomApi"]
    end

    subgraph Media["Media Layer"]
        WHIP["WebRTC WHIP<br/>Publish"]
        WHEP["WebRTC WHEP<br/>Subscribe"]
    end

    Live -->|register_callbacks| RS
    SM --> DB
    GiftSys --> SM
    LinkMic --> SM
    RobotMgr --> Room
    Room --> API
    API -->|broadcast_to_room<br/>add_ban, remove_user| Live
    WS --> Live
    WHIP --> Media
    WHEP --> Media

Live Room Lifecycle

Preparing → Living → Paused → Ended

Status	Description
`Preparing`	Live preparation, not yet started
`Living`	Live in progress, viewers can join
`Paused`	Live paused, viewers retained, can resume later
`Ended`	Live ended, room closed

Signaling Protocol

Basic Signaling

Action	Direction	Description
`start_live`	C→S	Streamer starts live
`stop_live`	C→S	Streamer ends live
`pause_live`	C→S	Streamer pauses live
`resume_live`	C→S	Streamer resumes live

Gift Signaling

Action	Direction	Description
`send_gift`	C→S	Viewer sends gift
`gift_received`	S→C	Gift notification (broadcast)

Co-hosting Signaling

Action	Direction	Description
`link_mic_request`	C→S	Viewer requests co-hosting
`link_mic_accept`	C→S	Streamer accepts co-hosting
`link_mic_reject`	C→S	Streamer rejects co-hosting
`link_mic_end`	C→S	Co-hosting ends
`link_mic_timeout`	S→C	Co-hosting invitation timeout

PK Battle Signaling

Action	Direction	Description
`pk_invite`	C→S	Streamer A invites Streamer B for PK
`pk_accept`	C→S	Streamer B accepts PK
`pk_reject`	C→S	Streamer B rejects PK
`pk_end`	C→S	End PK
`pk_score_update`	S→C	PK score real-time update (broadcast)

Danmaku Signaling

Action	Direction	Description
`send_danmaku`	C→S	Send bullet comment
`danmaku`	S→C	Danmaku notification (broadcast)

Gift System

Sending Gifts

{
  "action": "send_gift",
  "room_id": "live_100001",
  "gift_id": "rocket",
  "count": 1,
  "combo_id": "combo_abc123"
}

Combo Mechanism

Gifts support combos. Clients use the same combo_id when sending the same gift multiple times in a short period:

// Gift 1
{
  "action": "send_gift",
  "gift_id": "rocket",
  "count": 1,
  "combo_id": "combo_xyz789"
}

// Gift 2 (same combo)
{
  "action": "send_gift",
  "gift_id": "rocket",
  "count": 1,
  "combo_id": "combo_xyz789"
}

// Server response
{
  "action": "gift_received",
  "gift_id": "rocket",
  "combo_count": 2,
  "combo_id": "combo_xyz789"
}

Combo Timeout

If no more gifts sent within timeout period → combo ends
Clients can display “×N combo” animation
Supports configurable maximum combo count limit

Co-hosting System

Co-hosting Flow

Viewer requests → Streamer accepts/rejects → Establish WebRTC connection → Co-hosting → End

Request Co-hosting

{
  "action": "link_mic_request",
  "room_id": "live_100001"
}

Streamer Accepts Co-hosting

{
  "action": "link_mic_accept",
  "room_id": "live_100001",
  "target_user_id": "user_789"
}

Co-hosting Configuration

live:
  link_mic:
    max_participants: 6         # Maximum co-hosting participants (including streamer)
    timeout: 30                 # Co-hosting invitation timeout (seconds)
    auto_end_on_decline: true   # Auto cleanup on decline

PK Battle

PK Flow

Streamer A invites Streamer B → Streamer B accepts/rejects → Establish PK room → Real-time scoring → End

Initiate PK

{
  "action": "pk_invite",
  "target_anchor_id": "anchor_123"
}

Real-time Scoring

During PK, the system calculates both sides’ scores in real-time based on:

Gift Contribution: Gifts sent by viewers
Danmaku Interaction: Number and activity of bullet comments
Time Coefficient: PK duration weighting

PK Configuration

live:
  pk:
    enable: true                # Enable PK feature
    timeout: 300                # PK invitation timeout (seconds)
    duration: 600               # Single PK duration (seconds)
    scoring:
      gift_multiplier: 1.5      # Gift contribution multiplier
      danmaku_weight: 0.1       # Danmaku weight

Bot Viewers

Purpose

Test live features: Simulate real viewer behavior
Demo: Increase live room activity
Load testing: Evaluate system capacity

Bot Behaviors

{
  "action": "add_robots",
  "room_id": "live_100001",
  "count": 50,
  "behaviors": {
    "gift_probability": 0.3,     // 30% probability to send gift
    "danmaku_probability": 0.5,  // 50% probability to send danmaku
    "link_mic_probability": 0.05 // 5% probability to request co-hosting
  }
}

Danmaku System

Sending Danmaku

{
  "action": "send_danmaku",
  "content": "Great stream!"
}

Danmaku Features

Rate Limiting: Prevents spam
Content Filtering: Sensitive word filtering
User Levels: Different limits for VIP users
Auto-cleanup: Automatically delete expired danmaku

Rate Limiting Configuration

live:
  danmaku:
    max_per_minute: 10          # Maximum 10 per minute
    max_length: 200             # Maximum length
    cooldown: 2                 # Minimum interval between danmaku (seconds)

HTTP API

Create Live Room

curl -X POST http://localhost:8080/live/rooms \
  -H "Content-Type: application/json" \
  -d '{
    "anchor_id": "anchor_001",
    "title": "Tonight Show",
    "cover_url": "https://example.com/cover.jpg"
  }'

Get Live Rooms List

curl http://localhost:8080/live/rooms

Get Live Room Details

curl http://localhost:8080/live/rooms/{room_id}

Get Gift Statistics

curl http://localhost:8080/live/rooms/{room_id}/gift-stats

Database Persistence

Live Rooms Table `live_rooms`

Field	Type	Description
`id`	string	Room ID
`anchor_id`	string	Streamer ID
`title`	string	Live title
`status`	enum	Live status
`start_time`	timestamp	Start time
`end_time`	timestamp	End time
`viewer_count`	int	Viewer count
`total_gift_amount`	decimal	Total gift amount

Gift Records Table `live_gifts`

Field	Type	Description
`id`	string	Gift ID
`room_id`	string	Room ID
`sender_id`	string	Sender ID
`gift_type`	string	Gift type
`count`	int	Count
`amount`	decimal	Amount
`created_at`	timestamp	Creation time

Configuration Reference

live:
  # Gift system
  gift:
    combo_timeout: 5            # Combo timeout (seconds)
    max_combo_count: 999        # Maximum combo count

  # Co-hosting system
  link_mic:
    max_participants: 6         # Maximum co-hosting participants
    timeout: 30                 # Invitation timeout (seconds)

  # PK battle
  pk:
    enable: true
    timeout: 300                # Invitation timeout (seconds)
    duration: 600               # Battle duration (seconds)

  # Danmaku system
  danmaku:
    max_per_minute: 10
    max_length: 200
    cooldown: 2

  # Database
  database:
    enable: true                # Enable persistence
    table_prefix: "live_"       # Table name prefix

  # Bot viewers
  robot:
    enable: true                # Enable bots
    max_robots: 10000           # Maximum robots

Web-SDK Integration

Basic Connection

const room = document.getElementById('room') as MbRoom;
const publisher = document.getElementById('publisher') as MbPublisher;

// Connect to live room
room.setAttribute('ws-url', 'ws://localhost:8080/room?type=live');
room.setAttribute('room-id', 'live_100001');

// Streamer publish
await publisher.startCapture({ audio: true, video: true });
await publisher.startPublish();

Send Gift

const room = document.getElementById('room') as MbRoom;

// Send gift
room.sendMessage({
  action: 'send_gift',
  gift_id: 'rocket',
  count: 1,
  combo_id: 'combo_123'
});

Request Co-hosting

// Request co-hosting
room.sendMessage({
  action: 'link_mic_request'
});

// Listen for co-hosting acceptance
room.addEventListener('link_mic_accept', (event) => {
  // Establish co-hosting WebRTC connection
  await publisher.startPublish();
});

Danmaku Interaction

// Send danmaku
room.sendMessage({
  action: 'send_danmaku',
  content: 'Go streamer!'
});

// Listen for danmaku
room.addEventListener('danmaku', (event) => {
  console.log(`${event.username}: ${event.content}`);
});

Demo Project

Complete Live Room Demo is located at web-sdk/packages/demo/live/:

live/
├── src/
│   ├── pages/
│   │   ├── Lobby/index.tsx         # Live room list
│   │   ├── LiveRoom/index.tsx      # Live room (streamer/viewer)
│   │   └── GiftPanel/index.tsx     # Gift panel
│   ├── components/
│   │   ├── Danmaku/index.tsx       # Danmaku component
│   │   ├── Viewers/index.tsx       # Viewer list
│   │   └── GiftEffect/index.tsx    # Gift effects
│   ├── services/api.ts             # API wrapper
│   └── types/index.ts              # Type definitions
├── package.json                    # port: 5474
└── vite.config.ts

Start Demo

cd web-sdk/packages/demo/live
pnpm install
pnpm dev
# Visit http://localhost:5474

Streamer Entry

http://localhost:5474?role=anchor&anchor_id=anchor_001

Viewer Entry

http://localhost:5474?role=viewer&room_id=live_100001

Mobile Adaptation

Demo automatically detects device type. For mobile devices:

Full-screen portrait video
Floating danmaku bar at bottom
Floating gift/interaction buttons on right (safe area)
Swipe up to show gift panel
Long press to send danmaku

Live Room

Core Features

How to Enable

Architecture Design

Live Room Lifecycle

Signaling Protocol

Basic Signaling

Gift Signaling

Co-hosting Signaling

PK Battle Signaling

Danmaku Signaling

Gift System

Sending Gifts

Combo Mechanism

Combo Timeout

Co-hosting System

Co-hosting Flow

Request Co-hosting

Streamer Accepts Co-hosting

Co-hosting Configuration

PK Battle

PK Flow

Initiate PK

Real-time Scoring

PK Configuration

Bot Viewers

Purpose

Bot Behaviors

Danmaku System

Sending Danmaku

Danmaku Features

Rate Limiting Configuration

HTTP API

Create Live Room

Get Live Rooms List

Get Live Room Details

Get Gift Statistics

Database Persistence

Live Rooms Table live_rooms

Gift Records Table live_gifts

Configuration Reference

Web-SDK Integration

Basic Connection

Send Gift

Request Co-hosting

Danmaku Interaction

Demo Project

Start Demo

Streamer Entry

Viewer Entry

Mobile Adaptation

Live Rooms Table `live_rooms`

Gift Records Table `live_gifts`