Server overview

Build RTSP servers using the Server struct and handler interface.

The Server struct is the entry point for building an RTSP server with gortsplib. It handles incoming TCP connections, optional UDP transports, multicast distribution, and TLS. You control server behavior by implementing one or more ServerHandler* interfaces and assigning them to Server.Handler.

Server fields

RTSPAddress is the only required field. All other fields are optional.

Transport

Field	Type	Default	Description
RTSPAddress	string	—	Required. TCP address the server listens on (e.g. :8554).
UDPRTPAddress	string	""	UDP address for receiving/sending RTP packets. Must be set together with UDPRTCPAddress to enable UDP transport.
UDPRTCPAddress	string	""	UDP address for receiving/sending RTCP packets. Must be set together with UDPRTPAddress.
MulticastIPRange	string	""	CIDR range of multicast IPs. Must be set together with MulticastRTPPort and MulticastRTCPPort to enable UDP-multicast transport.
MulticastRTPPort	int	0	Port for multicast RTP packets. Must be an even number.
MulticastRTCPPort	int	0	Port for multicast RTCP packets. Must equal MulticastRTPPort + 1.

Timeouts

Field	Type	Default	Description
ReadTimeout	time.Duration	10s	Timeout for read operations on a connection.
WriteTimeout	time.Duration	10s	Timeout for write operations on a connection.
IdleTimeout	time.Duration	60s	Timeout for idle connections and sessions with no activity.

Security

Field	Type	Default	Description
TLSConfig	*tls.Config	nil	When set, the server accepts only TLS (RTSPS) connections and automatically negotiates SRTP/SRTCP for media encryption.
AuthMethods	[]auth.VerifyMethod	Basic + Digest MD5	Authentication methods accepted by VerifyCredentials. Digest SHA-256 is excluded by default to maintain FFmpeg compatibility.

Tuning

Field	Type	Default	Description
UDPReadBufferSize	int	OS default	Size of the UDP read buffer. Increase to reduce packet loss under high load.
WriteQueueSize	int	256	Size of the outbound packet queue. Must be a power of two.
MaxPacketSize	int	1472	Maximum size of outbound RTP/RTCP packets. Must not exceed the IPv4/UDP MTU (1472 bytes).
DisableRTCPSenderReports	bool	false	Disable automatic RTCP sender reports.

Handler

Field	Type	Description
Handler	ServerHandler	A value that implements one or more ServerHandler* interfaces. The server calls the corresponding methods when events occur.

Handler pattern

The handler is an ordinary Go struct pointer assigned to Server.Handler. The server checks at runtime which ServerHandler* interfaces the struct implements and calls only those methods. None of the interfaces are required — implement only the callbacks relevant to your use case.

type myHandler struct {
    server *gortsplib.Server
    // ... your fields
}

// Implement only the interfaces you need:
func (h *myHandler) OnConnOpen(ctx *gortsplib.ServerHandlerOnConnOpenCtx)   { /* ... */ }
func (h *myHandler) OnDescribe(ctx *gortsplib.ServerHandlerOnDescribeCtx) (
    *base.Response, *gortsplib.ServerStream, error,
) { /* ... */ }
// ...

func main() {
    h := &myHandler{}
    h.server = &gortsplib.Server{
        Handler:      h,
        RTSPAddress:  ":8554",
    }
    panic(h.server.StartAndWait())
}

Basic server setup

The following example creates a server that accepts a single publisher and relays the stream to any number of readers.

server/main.go

// Package main contains an example.
package main

import (
	"log"
	"sync"

	"github.com/pion/rtp"

	"github.com/bluenviron/gortsplib/v5"
	"github.com/bluenviron/gortsplib/v5/pkg/base"
	"github.com/bluenviron/gortsplib/v5/pkg/description"
	"github.com/bluenviron/gortsplib/v5/pkg/format"
)

type serverHandler struct {
	server    *gortsplib.Server
	mutex     sync.RWMutex
	stream    *gortsplib.ServerStream
	publisher *gortsplib.ServerSession
}

func (sh *serverHandler) OnConnOpen(_ *gortsplib.ServerHandlerOnConnOpenCtx) {
	log.Printf("conn opened")
}

func (sh *serverHandler) OnConnClose(ctx *gortsplib.ServerHandlerOnConnCloseCtx) {
	log.Printf("conn closed (%v)", ctx.Error)
}

func (sh *serverHandler) OnSessionOpen(_ *gortsplib.ServerHandlerOnSessionOpenCtx) {
	log.Printf("session opened")
}

func (sh *serverHandler) OnSessionClose(ctx *gortsplib.ServerHandlerOnSessionCloseCtx) {
	log.Printf("session closed")

	sh.mutex.Lock()
	defer sh.mutex.Unlock()

	if sh.stream != nil && ctx.Session == sh.publisher {
		sh.stream.Close()
		sh.stream = nil
	}
}

func (sh *serverHandler) OnDescribe(
	_ *gortsplib.ServerHandlerOnDescribeCtx,
) (*base.Response, *gortsplib.ServerStream, error) {
	sh.mutex.RLock()
	defer sh.mutex.RUnlock()

	if sh.stream == nil {
		return &base.Response{StatusCode: base.StatusNotFound}, nil, nil
	}
	return &base.Response{StatusCode: base.StatusOK}, sh.stream, nil
}

func (sh *serverHandler) OnAnnounce(ctx *gortsplib.ServerHandlerOnAnnounceCtx) (*base.Response, error) {
	sh.mutex.Lock()
	defer sh.mutex.Unlock()

	if sh.stream != nil {
		sh.stream.Close()
		sh.publisher.Close()
	}

	sh.stream = &gortsplib.ServerStream{
		Server: sh.server,
		Desc:   ctx.Description,
	}
	err := sh.stream.Initialize()
	if err != nil {
		panic(err)
	}
	sh.publisher = ctx.Session

	return &base.Response{StatusCode: base.StatusOK}, nil
}

func (sh *serverHandler) OnSetup(ctx *gortsplib.ServerHandlerOnSetupCtx) (
	*base.Response, *gortsplib.ServerStream, error,
) {
	// SETUP is used by both readers and publishers.
	// In case of publishers, just return StatusOK.
	if ctx.Session.State() == gortsplib.ServerSessionStatePreRecord {
		return &base.Response{StatusCode: base.StatusOK}, nil, nil
	}

	sh.mutex.RLock()
	defer sh.mutex.RUnlock()

	if sh.stream == nil {
		return &base.Response{StatusCode: base.StatusNotFound}, nil, nil
	}

	return &base.Response{StatusCode: base.StatusOK}, sh.stream, nil
}

func (sh *serverHandler) OnPlay(_ *gortsplib.ServerHandlerOnPlayCtx) (*base.Response, error) {
	return &base.Response{StatusCode: base.StatusOK}, nil
}

func (sh *serverHandler) OnRecord(ctx *gortsplib.ServerHandlerOnRecordCtx) (*base.Response, error) {
	ctx.Session.OnPacketRTPAny(func(medi *description.Media, _ format.Format, pkt *rtp.Packet) {
		sh.stream.WritePacketRTP(medi, pkt) //nolint:errcheck
	})
	return &base.Response{StatusCode: base.StatusOK}, nil
}

func main() {
	h := &serverHandler{}
	h.server = &gortsplib.Server{
		Handler:           h,
		RTSPAddress:       ":8554",
		UDPRTPAddress:     ":8000",
		UDPRTCPAddress:    ":8001",
		MulticastIPRange:  "224.1.0.0/16",
		MulticastRTPPort:  8002,
		MulticastRTCPPort: 8003,
	}

	log.Printf("server is ready on %s", h.server.RTSPAddress)
	panic(h.server.StartAndWait())
}

Server lifecycle methods

Method	Description
Start()	Starts listeners and the internal run loop. Returns an error if configuration is invalid.
StartAndWait()	Calls Start() then blocks until the server shuts down.
Wait()	Blocks until the server shuts down. Returns the fatal error that caused the shutdown.
Close()	Signals the server to shut down and waits for all goroutines to exit.
NetListener()	Returns the underlying net.Listener for the TCP port.

Next steps

Handling requests

Implement handler callbacks to control how your server responds to DESCRIBE, ANNOUNCE, SETUP, PLAY, and RECORD.

Authentication

Validate publisher and reader credentials using VerifyCredentials.

Security

Enable TLS (RTSPS) and automatic SRTP/SRTCP encryption.