User Guide on go-rtmp

Recording

Mon, 01 Jan 0001 00:00:00 +0000

Recording#

go-rtmp records published streams to disk automatically. The server selects the container format based on the video codec:

H.264/AVC streams → FLV (Flash Video) container
H.265/HEVC streams → MP4 (ISO BMFF) container

Recording runs alongside live relay — subscribers see the stream in real-time while the server simultaneously writes to disk.

Enabling Recording#

Add the -record-all and -record-dir flags:

./rtmp-server -record-all true -record-dir ./recordings

The directory is created automatically if it doesn’t exist. By default, -record-dir points to recordings in the working directory.

Live Relay

Mon, 01 Jan 0001 00:00:00 +0000

Live Relay#

Live relay is the core of go-rtmp. It enables real-time pub/sub streaming: one publisher sends media to a stream key, and any number of subscribers receive it simultaneously.

How Pub/Sub Works#

The server maintains a stream registry — a thread-safe map of active streams keyed by their full stream key (e.g., live/test).

A publisher connects and issues a publish command for a stream key
The server creates a stream entry in the registry
Subscribers connect and issue play commands for the same stream key
Each media message from the publisher is broadcast to all active subscribers

Only one publisher is allowed per stream key. Attempting to publish to an occupied key results in an error. There is no limit on the number of subscribers.

Multi-Destination Relay

Mon, 01 Jan 0001 00:00:00 +0000

Multi-Destination Relay#

go-rtmp can forward published streams to one or more external RTMP servers. This enables simulcasting, CDN distribution, and backup recording without any transcoding.

Enabling Relay#

Use the -relay-to flag, which can be specified multiple times:

./rtmp-server -listen :1935 \
 -relay-to rtmp://cdn1.example.com/live/key \
 -relay-to rtmp://cdn2.example.com/live/key

Each destination must use the rtmp:// scheme and include a host. Destinations are validated at startup — invalid URLs cause the server to exit with an error.

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Authentication#

go-rtmp supports pluggable token-based authentication to control who can publish and subscribe to streams.

Overview#

Mode	Flag	Best For
`none`	`-auth-mode none` (default)	Open access, backward compatible
`token`	`-auth-mode token`	Small setups, static configuration
`file`	`-auth-mode file`	Medium deployments, live reload
`callback`	`-auth-mode callback`	Full integration with existing auth systems

Authentication is enforced at the publish/play command level — not at connect or handshake. This means the RTMP connection is established first, then auth is checked when the client issues a publish or play command.

Event Hooks

Mon, 01 Jan 0001 00:00:00 +0000

Event Hooks#

go-rtmp fires hooks on RTMP lifecycle events, allowing external systems to react to stream activity in real-time. Hooks are asynchronous — they never block RTMP message processing.

Available Events#

Event	Trigger
`connection_accept`	Client TCP connection accepted
`connection_close`	Client disconnected
`handshake_complete`	RTMP handshake finished
`stream_create`	Stream first created in registry
`stream_delete`	Stream removed (no publishers or subscribers)
`publish_start`	Publisher begins streaming
`publish_stop`	Publisher stops streaming
`play_start`	Subscriber begins playback
`play_stop`	Subscriber stops playback
`codec_detected`	Audio/video codec identified
`subscriber_count`	Subscriber count changed
`auth_failed`	Authentication attempt failed

Event Payload#

Every event is delivered as a JSON object:

RTMPS (TLS)

Mon, 01 Jan 0001 00:00:00 +0000

RTMPS (TLS Encryption)#

RTMPS adds TLS encryption to RTMP connections, protecting stream data in transit. go-rtmp implements RTMPS via TLS termination at the transport layer — the TLS handshake wraps the TCP connection before the RTMP protocol begins, so all protocol layers (handshake, chunks, AMF, commands, media) work identically over both plain and encrypted connections.

How It Works#

Publisher (OBS/FFmpeg)
 │
 │ TLS handshake (rtmps://server:1936)
 ▼
go-rtmp server
 │ tls.NewListener() wraps net.Listener
 │ Returns tls.Conn (implements net.Conn)
 ▼
RTMP protocol (identical to plain RTMP)
 │
 ▼
Subscribers, Recording, Relay, Hooks

The server uses Go’s crypto/tls package with tls.NewListener() to wrap the standard TCP listener. The resulting tls.Conn implements net.Conn, so the entire RTMP stack — handshake, chunk parsing, AMF encoding, command dispatch, and media relay — requires zero changes. TLS is purely a transport concern.

Metrics & Monitoring

Mon, 01 Jan 0001 00:00:00 +0000

Metrics & Monitoring#

go-rtmp exposes live server statistics via an HTTP endpoint using Go’s built-in expvar package. Metrics are thread-safe, have zero overhead when disabled, and require no external dependencies.

Enabling Metrics#

./rtmp-server -metrics-addr :8080

When -metrics-addr is not specified, no HTTP listener is started and there is zero performance overhead.

Querying Metrics#

curl http://localhost:8080/debug/vars

The response is a JSON object containing all rtmp_* and srt_* keys, dynamic endpoints, and Go’s built-in memstats and cmdline variables:

HLS Streaming

Mon, 01 Jan 0001 00:00:00 +0000

HLS Streaming#

go-rtmp outputs RTMP natively. To deliver streams to web browsers, convert to HLS (HTTP Live Streaming) using FFmpeg as a sidecar process.

Architecture#

Publisher (OBS/FFmpeg)
 │
 ▼
go-rtmp server (RTMP on :1935)
 │
 ▼
FFmpeg (subscribes via RTMP, outputs HLS segments)
 │
 ▼
HTTP server (serves .m3u8 + .ts files)
 │
 ▼
Browser (hls.js / native HLS player)

Basic Setup#

Step 1: Start go-rtmp#

./rtmp-server -listen :1935

Step 2: Publish a stream#

From OBS, FFmpeg, or any RTMP client:

SRT Ingest

Mon, 01 Jan 0001 00:00:00 +0000

SRT Ingest#

go-rtmp accepts SRT (Secure Reliable Transport) streams over UDP alongside RTMP. SRT publishers are transparently converted to RTMP format — existing RTMP subscribers can watch SRT sources without any changes.

Enabling SRT#

Add the -srt-listen flag to start the UDP listener:

./rtmp-server -listen :1935 -srt-listen :4200 -log-level info

The server now accepts RTMP on TCP port 1935 and SRT on UDP port 4200 simultaneously.

Publishing via SRT#

FFmpeg#

ffmpeg -re -i test.mp4 -c copy -f mpegts \
 "srt://localhost:4200?streamid=live/test&pkt_size=1316"

OBS Studio#

Settings → Stream → Service: Custom
Server: srt://your-server:4200
Stream Key: live/test

IP Cameras#

Most IP cameras with SRT support can publish directly. Set the SRT destination to:

Multi-Stream

Mon, 01 Jan 0001 00:00:00 +0000

Multi-Stream#

go-rtmp handles multiple simultaneous streams out of the box. Each stream is identified by a unique stream key and operates independently — with its own publisher, subscribers, recording, and authentication. Both RTMP and SRT publishers can run side by side on the same server.

How It Works#

Every stream lives in a central stream registry keyed by stream key (e.g. live/cam1, live/cam2). The rules are simple:

One publisher per key — a stream key can have exactly one active publisher at a time. A second publish attempt to the same key is rejected with an error.
Unlimited subscribers per key — any number of viewers can watch any active stream.
Full isolation — streams do not interact. Publishing to live/cam1 has no effect on live/cam2.
Mixed protocols — RTMP and SRT publishers register in the same registry. Subscribers see no difference.

 Publisher A (RTMP) Publisher B (SRT)
 live/cam1 live/cam2
 │ │
 ▼ ▼
 ┌──────────────────────────────────────┐
 │ Stream Registry │
 │ ┌────────────┐ ┌────────────┐ │
 │ │ live/cam1 │ │ live/cam2 │ │
 │ │ pub + subs │ │ pub + subs │ │
 │ └────────────┘ └────────────┘ │
 └──────────────────────────────────────┘
 │ │ │
 ▼ ▼ ▼
 Viewer 1 Viewer 2 Viewer 3
 (cam1) (cam1) (cam2)

Publishing Multiple Streams#

Each publisher targets a different stream key. You can mix RTMP and SRT freely — just use different keys.