gortsplib: the RTSP protocol engine behind a Go media stack

RTSP as a library rather than a media server

RTSP is the control protocol that sits in front of streaming media, and the code that speaks it tends to spread across session state, interleaved binary frames, timeout handling and a dozen codec specific quirks. gortsplib keeps that machinery inside a Go module so an application can call it instead of reimplementing it. The repository describes the project as an RTSP client and server library for the Go programming language, and the feature list is grouped into three parts: client, server and utilities.

That grouping is the whole design in one line. There is no bundled daemon here, no configuration file for paths and no default admin password. You get a library that can open a session against a camera, read frames, hold a stream open for other clients, or publish into a remote server, and everything above that line is code you write. The utilities section goes further and offers parsing of RTSP elements plus encoding and decoding of RTP packets into and out of codec specific frames, which is where most of the real work in any streaming service happens anyway.

For an engineer this shape is the point. Embedding the protocol in an existing Go service avoids a second runtime, a second deployment and a second authentication model, which is exactly the arrangement the author wanted: the project says it was written for MediaMTX, and the repository layout shows the library split into root level client and server files plus a pkg directory where the shared format and protocol pieces live.

Three transports and a tunnel that changes the shape of the session

The interesting engineering sits in the transport layer. The feature list says that a client reading from a server can use UDP, UDP multicast or TCP, and can switch transport protocol automatically. That switching is not a nicety: RTSP negotiation between a camera and a consumer frequently settles on a transport that then fails in a particular network, and automatic fallback keeps a session alive without the caller reimplementing negotiation logic. The same list says the client can read selected media streams rather than everything the server offers, and can pause or seek without disconnecting.

The root level file names mirror that structure. client_transport.go and server_multicast_writer_format.go sit next to conn_transport.go and session_transport.go, while client_udp_listener.go, server_udp_listener.go and server_tcp_listener.go handle the sockets. Tunneling is separated out in client_tunnel_http.go, client_tunnel_websocket.go and the matching server_tunnel files, which makes sense because RTSP-over-HTTP and RTSP-over-WebSocket change how requests reach the server rather than how media flows.

Secure variants are treated the same way as plain RTSP. The client list includes RTSPS, SRTP and SRTCP, and the server list repeats them, so the same library can terminate encrypted sessions and carry encrypted media. wrapped_srtp_context.go in the root directory and the pion/srtp/v3 dependency in go.mod show where that work sits.

One format layer shared by client, server and proxy

A recurring design decision in streaming codebases is to duplicate codec handling for the read path and the write path. gortsplib avoids that by naming the format layer in several places at once: client_format.go, server_session_format.go, server_stream_format.go and server_multicast_writer_format.go all appear in the repository layout, and the utilities entry promises encoding and decoding of RTP packets into and from codec specific frames.

The practical consequence is that a proxy does not need two conversions. The proxy example directory exists alongside the client and server examples, and the client-play-format-h264-mpeg4audio-to-disk example name suggests a program that decodes H264 video and MPEG4 audio in one session. Two transports that a proxy must bridge, such as TCP in and UDP out, then share the same frame objects.

The dependency list explains why. go.mod requires github.com/bluenviron/mediacommon/v2 at v2.9.6 for the shared media plumbing, github.com/pion/rtp at v1.10.5 for RTP packet handling, github.com/pion/rtcp at v1.2.19 for receiver reports, github.com/pion/sdp/v3 for session description parsing and github.com/gorilla/websocket at v1.5.3 for the WebSocket tunnel. gortsplib therefore builds on the pion RTP stack rather than reimplementing packet serialisation, and it uses mediacommon for the frame level types that sit between RTP and codecs.

Adding the dependency and reading the example tree

There is no install script in the documentation and no container image to pull. The project is consumed the way any Go module is consumed, by importing its module path, which the go.mod file declares as:

module github.com/bluenviron/gortsplib/v5
go 1.26.0

The same file pins the protocol level dependencies that a direct import will drag in:

require (
	github.com/bluenviron/mediacommon/v2 v2.9.6
	github.com/pion/rtp v1.10.5
	github.com/pion/rtcp v1.2.19
	github.com/pion/sdp/v3 v3.0.20
	github.com/gorilla/websocket v1.5.3
)

Note the major version suffix in the module path. The /v5 segment is not a package name, it is the Go rule that lets a project publish incompatible major versions under one import path, so any code you port from an older gortsplib release will need its import lines rewritten. The README also states that Go 1.26 or newer is required.

Your first real use is a program in the examples directory. The example index in the README lists them by name, and the three that cover the core loop look like this:

- [client-query](examples/client-query/main.go)
- [client-play](examples/client-play/main.go)
- [proxy](examples/proxy/main.go)

client-query asks a server which media streams exist without playing anything, which is the cheapest way to confirm that authentication and networking already work. client-play is the reader path, and proxy is the bridge that forwards one session into another. The repository ships roughly fifty example directories under examples/, each named after the operation it demonstrates, so the naming itself is a map of the API surface.

Timestamps are exposed rather than buried in the transport

Presentation timestamp and NTP time are easy to lose in a streaming pipeline, because they usually arrive as side data on a packet and get dropped by any code that treats packets as opaque buffers. gortsplib lists both explicitly on the client read path and on the server record path, as separate bullets: get PTS of inbound packets and get NTP of inbound packets. The client-play-timestamp example directory exists to show it, and the client_play_options example covers the related case of choosing which streams to pull.

This matters for anyone building recording, synchronisation or analytics on top of RTSP. If the timestamp is a first class value returned alongside the packet rather than something you parse out of the payload yourself, then multi stream alignment and wall clock correlation stop being per project workarounds. It also explains why the repository carries stats files at three levels: client_stats.go, conn_stats.go and session_stats.go for the client side, and server_stream_stats.go for the server side.

The other client side features worth noting are narrower but real: write to ONVIF back channels, so a client can send talkback audio to a camera, and read ONVIF back channels on the server side. That capability is what the client-play-backchannel, server-play-backchannel and proxy-backchannel examples demonstrate. Two way audio through RTSP is a niche that most general purpose streaming stacks handle poorly, and the presence of three dedicated examples says the author expected people to need it.

Where the library stops and what the documentation does not cover

The honest limits are visible in the repository itself. Anyone planning an H264 pipeline should check the format package documentation directly for encoder and decoder support.

Other boundaries follow from the design. gortsplib is a protocol library, so it has no concept of a stream registry, no authentication policy beyond validating client credentials on the server side, and no notion of a user or a password database. The server feature list mentions validating client credentials, and the server-auth example shows a handler for it, but deciding who is allowed to connect stays with the application. There is also no playback of media to users over HTTP in the feature list; the tunnelling support covers RTSP-over-HTTP and RTSP-over-WebSocket for RTSP clients, which is not the same thing as transcoding a stream to browser friendly formats.

Finally, the repository has no GitHub releases. The upstream versioning signal is the /v5 suffix on the module path, which means upgrades arrive as ordinary module version bumps rather than as tagged releases with changelogs.

MediaMTX versus gortsplib: engine or complete product

The README names MediaMTX as the project gortsplib was written for, and links to it in the opening line. That relationship is the clearest alternative to consider, and the difference is one of level rather than of quality.

MediaMTX is the application that a media server operator runs. gortsplib is the protocol implementation that application is built from. If you want a ready-made RTSP endpoint rather than a library you wire into your own service, using the finished application is the direct route. If you want RTSP behaviour inside a Go service that already has its own scheduling, its own storage and its own control plane, then a library is the only sensible shape, and gortsplib is written by the same author who builds the application, so the two stay conceptually aligned.

The proxy example is worth reading with this in mind. A proxy that forwards media between a source and a destination is exactly the kind of glue that MediaMTX provides as a product feature, yet gortsplib ships it as an example program, which tells you the library leaves stream routing to the caller. Choosing the library means accepting responsibility for reconnect logic, for how many concurrent sessions to allow, and for the failure behaviour when a camera disappears mid stream.

Licence, tooling and the cost of staying current

The licence field on the repository says MIT, so linking the library into a commercial product carries no copyleft obligation. MIT asks for the notice and licence text to travel with the software, and it places no restriction on the fields of use, so a proprietary media product can depend on it without publishing its own source. This is a licensing observation rather than legal advice, and anyone with a specific distribution model should confirm the terms for their own situation.

The build tooling tells you how the project is tested. The Makefile names three container images: golang:1.27-alpine3.24 as the base, golangci/golangci-lint:v2.14.0 for linting and node:24-alpine3.24 for the scripts directory. The available actions are listed in the help target:

help:
	@echo "usage: make [action]"

The published action names are format, test, test-32, test-e2e and lint. A 32-bit test target and an end to end test target indicate that protocol behaviour is checked on more than one architecture and across a real client and server pair, which matters for a library that manipulates interleaved binary frames.

There is a small inconsistency to note between the tooling and the module. go.mod declares go 1.26.0, while the Makefile builds inside golang:1.27-alpine3.24. The module floor is 1.26, so 1.27 is a comfortable build image, but if your own service pins Go 1.26 exactly, the build image suggests the maintainer works on a newer release. On maintenance: the repository is not archived and the last push was on 2026-10-19, so the code is being changed. With no tagged releases, the practical upgrade path is reviewing the module version bump and running the test suite.

Editorial conclusion

gortsplib suits engineers who need precise control over RTSP sessions, custom transports or timestamp handling inside a Go service, and it is the wrong choice for anyone who wants a running media server, since the application, authentication policy and stream registry all live outside the library. Before adopting it, check two things against your own code: the module path ends in /v5, so a v4 import will not resolve, and Go 1.26.0 is the declared minimum in go.mod, which fixes the floor for every machine that builds your service. If your requirement is a working RTSP endpoint rather than a library you control, the MediaMTX project that this code was written for is the shorter path.

Frequently asked questions

Official sources

1. bluenviron/gortsplib on GitHub
2. Issues
3. License: MIT
4. README