owl

English | 中文

Out-of-the-Box Video Surveillance Platform

GoWVP is an open-source GB28181 solution implemented in Go, a network video platform based on the GB28181-2022 standard that also supports 2016/2011 versions, with ONVIF/RTMP/RTSP protocol support.

Live Demo

• Online Demo Platform :)

Use Cases

• Browser-based camera video playback without plugins
• Support for GB28181-compliant devices (IP cameras, platforms, NVRs, etc.)
• Support for non-GB28181 devices (RTSP, RTMP, streaming devices, etc.) - maximize your existing equipment
• Cross-network video preview
• Deployment via Docker, Docker Compose, or Kubernetes

Open Source Libraries

Thanks to @panjjo for the open-source library panjjo/gosip. GoWVP's SIP signaling is based on this library. Due to underlying encapsulation requirements, it's not a direct dependency but rather included in the pkg package.

Two streaming media servers are supported:

• @夏楚 ZLMediaKit

• lalmax-pro - For Go streaming media needs, contact email [email protected]

  • No environment requirements, no static library installation needed, cross-platform compilation support
  • Custom feature development available
  • G711 (G711A/G711U) to AAC transcoding support

Project framework based on @ixugo's goddd

For commercial licensing, please contact WeChat: golangxx. Unauthorized modifications must open-source both frontend and backend source code under the GPL license.

FAQ

Where are the frontend resources? How to load the web interface?

Click to download www.zip package

Download (packaged) frontend resources and place them in the project root directory, named www to load properly.

Any learning materials about the code?

GB/T28181 Open Source Diary[1]: Complete Practice from 0 to Implementing GB28181 Protocol

GB/T28181 Open Source Diary[2]: Setting Up Server, Solving CORS, API Integration

GB/T28181 Open Source Diary[3]: Building Monitoring Dashboard with React Components

GB/T28181 Open Source Diary[4]: Using ESLint for Development

GB/T28181 Open Source Diary[5]: Completing Forms with react-hook-form

GB/T28181 Open Source Diary[6]: Quick Integration of jessibuca.js Player in React

GB/T28181 Open Source Diary[7]: Implementing RTMP Authentication and Playback

GB/T28181 Open Source Diary[8]: Quick Guide to GB28181 Development

Any usage documentation?

RTMP

RTMP Push/Pull Stream Rules

How to Use OBS RTMP Push Stream to GB/T28181 Platform

Hikvision Camera RTMP Push Stream to Open Source GB/T28181 Platform

Dahua Camera RTMP Push Stream to Open Source GB/T28181 Platform

GB/T28181

7 Ways to Register GB28181 Devices

Black screen when playing

Check "Quick Desktop" - "ZLM settings button (top right)" - "GB28181 stream receiving default address" Ensure this address is accessible by the surveillance device.

Check "Quick Desktop" - "ZLM settings button (top right)" - "Hook IP" Can ZLM access GoWVP? For Docker combined version, use 127.0.0.1. For separate deployment, use explicit IP address.

Channel list shows fewer channels than actual count

By design. More than 4 channels should be viewed in the management page, or click "View More" on the right.

Using nginx reverse proxy, returned playback addresses don't work or snapshots don't load

Configure the following parameters in reverse proxy (replace domain with your actual one):

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Prefix "https://gowvp.com";

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection "upgrade";

How to use other databases?

In the configs/config.toml configuration file, modify database.dsn

[Recommended] SQLite should be a local disk path, default is configs/data.db

[Recommended] PostgreSQL format: postgres://postgres:[email protected]:5432/gb28181?sslmode=disable

MySQL format: mysql://root:[email protected]:5432/gb28181?sslmode=disable

PostgreSQL and MySQL format pattern: ://:@:/?sslmode=disable

How to disable AI?

AI detection is enabled by default, detecting 5 frames per second.

You can disable AI detection by setting disabledAI = true in configs/config.toml

Third-Party Authentication

GoWVP supports forwarding authentication requests to a third-party service, ideal for environments with an existing unified authentication system (SSO, OAuth2, corporate account systems, etc.).

Sequence Diagram

Use Cases

• Your organization has a unified login system and you want GoWVP to reuse existing sessions without requiring users to log in again
• Enterprise intranet environments that need to integrate with LDAP, CAS, OAuth2, or other authentication providers
• API gateway handles authentication and you want to pass the verification result through to GoWVP

Configuration

Set AuthURL to your third-party authentication service address in configs/config.toml:

[Server.HTTP]
  AuthURL = "https://your-auth-server.com/api/verify"

How It Works

Once AuthURL is configured, all requests are verified through the third-party authentication service. GoWVP forwards the original request headers and body as a POST to the specified URL. A 200 response means authentication passes; any other status code means failure, and the response body is returned directly to the client.

Note: The third-party auth service must respond within 10 seconds, otherwise the request is considered timed out.

Documentation

GoWVP Online API Documentation

ZLM Documentation github.com/ZLMediaKit/ZLMediaKit

// >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

You've made it this far!

Give us a ⭐ star!

// >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

Docker

Video Guide

How to Build or Run the Project

How to Deploy with Docker Compose

Docker Hub

GoWVP & ZLMediaKit Combined Image (Recommended)

docker-compose.yml

…

Quick Start

If you're a Go developer familiar with Docker, you can download the source code and run locally.

Prerequisites

• Golang
• Docker & Docker Compose
• Make

Steps

1. Clone this repository
2. Modify WebHookIP in configs/config.toml to your LAN IP
3. Run make build/linux && docker compose up -d
4. A zlm.conf folder is auto-created. Get the API secret from config.ini and fill it in configs/config.toml under Secret
5. Run docker compose restart
6. Access http://localhost:15123 in your browser

How to Contribute?

1. Fork this project
2. Set your editor's run/debug output directory to the project root
3. Make changes, submit a PR with description of modifications

Features

• Out-of-the-box with responsive web management
• Multiple protocol output: FLV, WS-FLV, HLS, WebRTC, RTSP, RTMP
• LAN/Internet/Multi-layer NAT/Special network environment deployment
• SQLite database for quick deployment
• PostgreSQL/MySQL database support
• Auto offline/reconnect on service restart
• GB/T 28181
  • Device registration with 7 connection methods
  • UDP and TCP signaling transport modes
  • Device time synchronization
  • PTZ control support
  • Information queries support
    • Device catalog query
    • Device info query
    • Device basic config query (e.g., timeout 3s × 3 retries = ~9+x seconds for offline detection)
  • Live streaming from devices
  • UDP and TCP passive stream transport modes
  • On-demand streaming to save bandwidth (auto-stop after 30s without viewers)
  • H264 and H265 video codec support
  • g711a/g711u/aac audio codec support
  • Snapshots
  • CORS support
• ONVIF device access and playback (client)
• ONVIF virtual device / server (expose channels to Home Assistant, etc.)
• RTMP push streaming support
• RTSP pull streaming support
• AI algorithm analysis and alerting support
• Cloud Recording playback (owl)
• ONVIF PTZ control support
• Chinese and English language support

OWL PRO

• Multi-screen split preview
• Multi-screen SD card recording playback (camera built-in recording)
• Recording file download
• Remote device reboot
• Main and sub stream switching
• Proprietary owl player with broad H265 stream playback compatibility (FLV only)

ONVIF Virtual Device (Server)

GoWVP can act as an ONVIF Network Video Transmitter so integrators (e.g. Home Assistant) can add it like a camera and pull RTSP URLs for platform channels.

Ports and firewall (LAN)

ONVIF SOAP endpoints (same HTTP port as the web UI):

• POST http://:15123/onvif/device_service
• POST http://:15123/onvif/media_service

Authentication uses Server.Username / Server.Password in configs/config.toml (WS-Security PasswordDigest or PasswordText), same defaults as web login (admin / admin).

Home Assistant (manual add):

• Host: http://:15123/onvif/device_service
• Username / password: values from config.toml Server.Username / Server.Password

Auto-discovery: After startup, GoWVP answers WS-Discovery Probe on UDP 3702. Set Media.IP (or Sip.Host) in configs/config.toml to your LAN IP so XAddrs is reachable from Home Assistant.

Not the same as GET /onvif/discover: that API lets GoWVP scan the LAN for external ONVIF cameras (client role).

Webhook Alert Push & Receive

GoWVP supports pushing alert events to external systems via HTTP Webhook, and receiving pushes from other GoWVP instances for master-slave cascading deployments.

Endpoint

Configuration (configs/config.toml)

[Server.Webhook]
  # Target URL array; embed the secret as a query parameter
  Targets = [
    "http://192.168.1.100:15123/webhook/events?secret=your-recv-secret",
  ]
  # Max retries, 0 = built-in default of 3
  MaxRetry = 3
  # Channel buffer size per target, 0 = built-in default of 64
  BufferSize = 64
  # Secret for validating incoming webhook requests (auto-generated on first launch)
  RecvSecret = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Authentication

/webhook/events accepts two authentication methods (either one suffices):