Developer Guide on go-rtmp

Architecture

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

Architecture#

High-Level Data Flow#

Every RTMP connection follows this path:

TCP Accept → Handshake → Control Burst → Command RPC → Media Relay/Recording

TCP Accept — the server accepts an inbound TCP connection
Handshake — client and server exchange C0/C1/C2 ↔ S0/S1/S2 packets to establish the session
Control Burst — both sides exchange Window Acknowledgement Size, Set Peer Bandwidth, and Set Chunk Size
Command RPC — AMF0-encoded commands (connect, createStream, publish/play) negotiate the stream
Media Relay/Recording — audio (TypeID 8) and video (TypeID 9) messages flow through the relay to subscribers and optionally to disk as FLV

Architecture Diagram#

 ┌──────────────────────────────────┐
 │ TCP Listener(s) │
 │ Plain (:1935) + TLS (:1936) │
 └──────────┬───────────────────────┘
 │ Accept()
 ▼
 ┌──────────────────────────────────┐
 │ Handshake Layer │
 │ C0/C1/C2 ↔ S0/S1/S2 exchange │
 └──────────┬───────────────────────┘
 │
 ▼
 ┌──────────────────────────────────┐
 │ Chunk Layer │
 │ Message ↔ Chunk fragmentation │
 └──────────┬───────────────────────┘
 │
 ┌──────────┴───────────────────────┐
 │ │
 ┌─────▼─────┐ ┌──────▼──────┐
 │ Commands │ │ Media │
 │ (TypeID │ │ (TypeID │
 │ 20) │ │ 8=audio │
 │ │ │ 9=video) │
 └─────┬──────┘ └──────┬──────┘
 │ │
 ┌─────▼──────┐ ┌──────▼──────┐
 │ RPC Layer │ │Media Dispatch│
 │ connect │ │ Record │
 │ createStream│ │ Broadcast │
 │ publish │ │ Relay │
 │ play │ │ │
 └──────┬─────┘ └─────────────┘
 │
 ┌──────▼──────┐
 │ Event Hooks │
 └─────────────┘

Package Map#

Package	Purpose	Key Types
`internal/rtmp/handshake`	RTMP v3 handshake (C0/C1/C2 ↔ S0/S1/S2)	`Handshake`, `State`
`internal/rtmp/chunk`	Message ↔ chunk fragmentation/reassembly	`Reader`, `Writer`, `ChunkHeader`, `Message`
`internal/rtmp/amf`	AMF0 binary codec	`EncodeAll()`, `DecodeAll()`
`internal/rtmp/control`	Control messages (types 1-6)	`Decode()`, `Handle()`, `Context`
`internal/rtmp/rpc`	Command parsing & response building	`Dispatcher`, `ConnectCommand`, `PublishCommand`
`internal/rtmp/conn`	Connection lifecycle	`Connection`, `Session`
`internal/rtmp/server`	Listener, stream registry, pub/sub	`Server`, `Registry`, `Stream`, `Config`
`internal/rtmp/server/auth`	Token-based authentication validators	`Validator`, `TokenValidator`, `FileValidator`, `CallbackValidator`
`internal/rtmp/server/hooks`	Event notification	`HookManager`, `Event`, `Hook`
`internal/rtmp/media`	Audio/video parsing, codec detection (Enhanced RTMP), FLV recording	`Recorder`, `CodecDetector`
`internal/rtmp/relay`	Multi-destination relay	`DestinationManager`, `Destination`
`internal/rtmp/metrics`	Expvar counters	`ConnectionsActive`, `BytesIngested`
`internal/rtmp/client`	Minimal RTMP client for testing	`Client`
`internal/errors`	Domain-specific error types	`ProtocolError`, `ChunkError`, `AMFError`
`internal/logger`	Structured logging	`Init()`, `Logger()`

Connection Lifecycle#

Here’s what happens step-by-step when OBS connects and starts streaming:

Design Principles

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

Design Principles#

These principles guide every decision in the go-rtmp codebase. When in doubt, refer back to these.

Correctness Over Features#

Every byte on the wire must match the RTMP specification. We will not ship a feature that compromises protocol correctness. If there’s a conflict between “works with most clients” and “matches the spec,” the spec wins. Golden binary vectors enforce this — every encoder and decoder is tested against exact byte sequences.

Testing Guide

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

Testing Guide#

Running Tests#

All Tests#

go test ./...

All Tests with Race Detector#

go test -race ./...

The race detector is mandatory for CI. It catches data races that would otherwise be invisible.

Package-Level Tests#

Run tests for a specific protocol layer:

go test ./internal/rtmp/handshake/ # Handshake FSM
go test ./internal/rtmp/chunk/ # Chunk reader/writer
go test ./internal/rtmp/amf/ # AMF0 codec
go test ./internal/rtmp/control/ # Control messages
go test ./internal/rtmp/rpc/ # Command dispatch
go test ./internal/rtmp/conn/ # Connection lifecycle
go test ./internal/rtmp/server/ # Server integration
go test ./internal/rtmp/server/auth/ # Authentication
go test ./internal/rtmp/server/hooks/ # Event hooks
go test ./internal/rtmp/media/ # Media handling + recording
go test ./internal/rtmp/relay/ # Multi-destination relay
go test ./internal/rtmp/metrics/ # Expvar counters
go test ./internal/errors/ # Error types

Integration Tests#

go test ./tests/integration/ -count=1

The -count=1 flag disables test caching, ensuring tests always run fresh.

Contributing

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

Contributing#

Workflow#

Fork the repository on GitHub
Create a feature branch from main:
```
git checkout -b feature/NNN-description
```
Where NNN is the issue number (if applicable).
Make your changes — write tests first, then implementation
Verify everything passes (see below)
Submit a Pull Request back to main

Branch Naming#

Use the pattern feature/NNN-description:

feature/042-rtmps-support
feature/099-configurable-backpressure
fix/117-amf0-null-decode
docs/update-troubleshooting

Commit Messages#

Follow Conventional Commits:

feat(relay): add reconnection with exponential backoff
fix(chunk): handle extended timestamp in FMT 3 continuation
test: add golden vectors for H.265 sequence headers
docs: update CLI reference with new auth flags
refactor(amf): simplify object end detection

Scopes match package names: handshake, chunk, amf, control, rpc, conn, server, auth, hooks, media, relay, metrics.