GB28181 National Standard Protocol

GB28181 is the Chinese national standard “Technical Requirements for Information Transmission, Exchange, and Control of Security Surveillance Video Monitoring Network Systems” (GB/T 28181), widely used for interoperability in video surveillance systems. Monibuca V6 provides full GB28181 signaling and media support.

Basic Information

Property	Value
Signaling Protocol	SIP (UDP/TCP selectable)
Signaling Port	5060 (default)
Media Protocol	RTP over UDP
Media Port	10000-20000 (default range)
Publish	✅ Supported (device pushes to platform)
Subscribe	✅ Supported (platform requests stream from device)
Latency	1-3 seconds
Feature Flag	gb28181

Features

• Device registration and management: Supports device registration, heartbeat keep-alive, and catalog queries
• Live video: Supports real-time video preview from devices
• PTZ control: Supports pan, tilt, zoom, iris, and preset positions
• Channel management: Supports multi-channel devices with independent management per channel
• Platform cascading: Supports upper/lower platform interconnection
• Recording query and playback: Supports device-side recording retrieval and remote playback
• Recording download: Supports downloading historical recordings from devices
• WebSocket notifications: Real-time push notifications for device status changes

Configuration

Feature Activation

Cargo.toml

[features]
gb28181 = ["dep:plugin-gb28181"]

Configuration File

gb28181:
  enable: true
  sip:
    - domain: "3402000000"
      domain_id: "34020000002000000001"
      username: "34020000002000000001"
      password: "your_sip_password"
      digest_retry_limit: 2
      digest_stale_retry_limit: 2
      lan_ip: "192.168.1.100"
      wan_ip: "203.0.113.1"
      port: 5060
      network: udp
  rtp_port_min: 10000
  rtp_port_max: 20000
  heartbeat_timeout: 60
  register_timeout: 300
  download_storage_path: "./downloads"
  download_retention_days: 7

SIP Server Configuration

Option	Type	Default	Description
domain	string	"3402000000"	SIP domain (administrative division code)
domain_id	string	"34020000002000000001"	SIP domain ID (20-digit code)
username	string?	null	Digest auth username (optional)
password	string?	null	Digest auth password (optional)
digest_retry_limit	u8	2	Max retries for normal 401 digest challenges
digest_stale_retry_limit	u8	2	Max retries for stale=true digest challenges
lan_ip	string	"127.0.0.1"	SIP LAN IP
wan_ip	string	"127.0.0.1"	SIP public IP (for NAT traversal)
port	u16	5060	SIP signaling port
network	string	"udp"	Network protocol (udp or tcp)

Global Configuration

Option	Type	Default	Description
enable	bool	true	Whether to enable the plugin
rtp_port_min	u16	10000	RTP media port range start
rtp_port_max	u16	20000	RTP media port range end
heartbeat_timeout	u64	60	Heartbeat timeout (seconds)
register_timeout	u64	300	Registration timeout (seconds)
download_storage_path	string	"./downloads"	Recording download storage path
download_retention_days	i64	7	Download file retention days

Tip

RTP ports are allocated on demand and do not pre-occupy all ports. Available ports are allocated from the port pool only when establishing media sessions.

Device Integration

Device ID Encoding Rules

GB28181 device IDs follow a 20-digit encoding scheme:

Center code (8 digits) + Industry code (2 digits) + Type code (3 digits) + Sequence (7 digits)

For example: 34020000001320000001

• 34020000: Administrative division code (Anhui Province)
• 00: Industry code
• 132: Type code (IPC camera)
• 0000001: Sequence number

Device Registration Flow

Device                       Monibuca (SIP Server)
  |                                  |
  |  -------- REGISTER ---------->   |
  |  <------- 401 Unauthorized ---   |
  |  -------- REGISTER (Auth) --->   |
  |  <------- 200 OK -----------     |
  |                                  |
  |  -------- Heartbeat(MESSAGE) ->  |
  |  <------- 200 OK -----------     |
  |                                  |

Device Configuration Example

On the camera or NVR’s GB28181 configuration page, fill in the following information:

Parameter	Value	Description
SIP Server ID	34020000002000000001	Corresponds to domain_id in configuration
SIP Server Domain	3402000000	Corresponds to domain in configuration
SIP Server Address	192.168.1.100	Monibuca server IP
SIP Server Port	5060	Corresponds to port in configuration
Device ID	34020000001320000001	The device’s own 20-digit code
Transport Protocol	UDP	Corresponds to network in configuration

PTZ Control

Supported PTZ operations:

Operation	Description
Direction Control	Up, down, left, right, upper-left, lower-left, upper-right, lower-right
Zoom Control	Zoom in, zoom out
Iris Control	Open, close
Presets	Set, call, delete preset positions

PTZ control is invoked via HTTP API. See the GB28181 API documentation for details.

Channel Management

GB28181 devices can have multiple channels (e.g., an NVR with multiple cameras attached). Monibuca supports:

• Automatic channel discovery (via Catalog query)
• Independent live preview per channel
• Independent PTZ control per channel
• Real-time channel status updates

Platform Cascading

Monibuca can act as a lower-level platform, registering with an upper-level platform and pushing stream data:

Lower-level devices → Monibuca (Lower-level platform) → Upper-level platform

Cascading features include:

• Registering with the upper-level platform
• Responding to catalog queries from the upper-level platform
• Pushing live streams to the upper-level platform on demand
• Synchronizing device status changes

Recording Query and Playback

Query Device-Side Recordings

Query historical recording lists on device storage via GB28181 signaling, with support for filtering by time range and recording type.

Remote Playback

Supports pulling historical recordings from devices for playback, including:

• Normal playback
• Fast forward / slow motion
• Seek
• Pause / resume

Recording Download

Supports downloading historical recordings from devices to local storage. Downloaded files are automatically saved to the configured storage path upon completion.

WebSocket Notifications

The GB28181 plugin provides a WebSocket interface for real-time device event push notifications:

const ws = new WebSocket('ws://localhost:8080/gb28181/ws');
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('GB28181 event:', data);
};

Event types include: device online, device offline, channel update, alarm notification, etc.

Cross-Protocol Playback

Streams pushed by GB28181 devices can be played back through other protocols:

# Play device stream via HTTP-FLV
ffplay http://localhost:8080/flv/gb28181/34020000001320000001.flv

# Play via HLS
ffplay http://localhost:8080/hls/gb28181/34020000001320000001/index.m3u8

# Play via RTMP
ffplay rtmp://localhost:1935/gb28181/34020000001320000001

Firewall Configuration

Deploying GB28181 services requires opening the following ports:

# SIP signaling port
sudo ufw allow 5060/udp

# RTP media port range
sudo ufw allow 10000:20000/udp

Caution

If deploying in a NAT environment, ensure wan_ip is configured correctly; otherwise devices may not be able to send media streams to the correct address.