Server

Complete API reference for the Server struct.

Server is a RTSP server. It accepts connections from clients, manages sessions, and dispatches events to a user-supplied handler.

Struct fields

Network configuration

RTSPAddress · string · required

The TCP address the server listens on (e.g. ":8554"). Also used for TCP transport. This field is required.

UDPRTPAddress · string

Address for the UDP RTP listener (e.g. ":8000"). Must be set together with UDPRTCPAddress to enable UDP transport. The RTP port must be even.

UDPRTCPAddress · string

Address for the UDP RTCP listener (e.g. ":8001"). Must be set together with UDPRTPAddress. The RTCP port must equal UDPRTPPort + 1.

MulticastIPRange · string

CIDR range of multicast IPs to assign (e.g. "224.1.0.0/16"). Must be set together with MulticastRTPPort and MulticastRTCPPort to enable UDP-multicast transport.

MulticastRTPPort · int

Port for multicast RTP packets. Must be even.

MulticastRTCPPort · int

Port for multicast RTCP packets. Must equal MulticastRTPPort + 1.

Timeouts

ReadTimeout · time.Duration · default: "10s"

Timeout for read operations.

WriteTimeout · time.Duration · default: "10s"

Timeout for write operations.

IdleTimeout · time.Duration · default: "60s"

Read timeout for idle connections and sessions with no activity.

TLS

TLSConfig · *tls.Config

TLS configuration. When set, the server accepts RTSPS connections and enforces SRTP for UDP transport.

I/O tuning

UDPReadBufferSize · int · default: "OS default"

Size of the UDP read buffer. Increase to reduce packet loss on high-bandwidth streams.

WriteQueueSize · int · default: "256"

Size of the outbound packet queue per session. Must be a power of two.

MaxPacketSize · int · default: "1472"

Maximum size of outbound RTP/RTCP packets in bytes. Must be less than the IPv4/UDP MTU (1472 bytes).

DisableRTCPSenderReports · bool · default: "false"

Disable automatic generation and sending of RTCP sender reports to readers.

Authentication

AuthMethods · []auth.VerifyMethod · default: "[Basic, DigestMD5]"

Allowed authentication methods. Defaults to [auth.VerifyMethodBasic, auth.VerifyMethodDigestMD5]. DigestSHA256 is omitted by default because it prevents FFmpeg from authenticating.

Handler

Handler · ServerHandler

An object that implements one or more of the ServerHandler* interfaces to handle server events. See Handler interfaces below.

System functions

Listen · func(network, address string) (net.Listener, error) · default: "net.Listen"

Function used to create the TCP listener. Override for custom networking.

ListenPacket · func(network, address string) (net.PacketConn, error) · default: "net.ListenPacket"

Function used to create UDP listeners.

---

Methods

Lifecycle

Start

func (s *Server) Start() error

Starts the server. Validates configuration, opens all network listeners (TCP, UDP RTP/RTCP, multicast), and spawns the internal event loop goroutine.

error · error

Non-nil if configuration is invalid or listeners cannot be opened.

---

StartAndWait

func (s *Server) StartAndWait() error

Starts the server and blocks until a fatal error occurs or Close() is called. Equivalent to calling Start() then Wait().

error · error

The terminal error, or nil if closed cleanly.

---

Wait

func (s *Server) Wait() error

Blocks until all server resources have exited. Returns the error that caused the server to stop.

error · error

The terminal error, or nil if closed cleanly.

---

Close

func (s *Server) Close()

Closes all server resources (listeners, connections, sessions) and waits for them to exit.

---

NetListener

func (s *Server) NetListener() net.Listener

Returns the underlying net.Listener for the TCP RTSP socket. Useful for obtaining the dynamically assigned port when RTSPAddress uses port 0.

---

Handler interfaces

The Handler field accepts any value that implements one or more of the following interfaces. Implement only the interfaces relevant to your use case.

Connection events

ServerHandlerOnConnOpen

type ServerHandlerOnConnOpen interface {
    OnConnOpen(ctx *ServerHandlerOnConnOpenCtx)
}

Called when a new connection is opened.

Context struct ServerHandlerOnConnOpenCtx:

Field	Type	Description
Conn	*ServerConn	The newly opened connection

ServerHandlerOnConnClose

type ServerHandlerOnConnClose interface {
    OnConnClose(ctx *ServerHandlerOnConnCloseCtx)
}

Called when a connection is closed.

Context struct ServerHandlerOnConnCloseCtx:

Field	Type	Description
Conn	*ServerConn	The closed connection
Error	error	The error that caused the close, or nil

ServerHandlerOnRequest / ServerHandlerOnResponse

type ServerHandlerOnRequest interface {
    OnRequest(conn *ServerConn, req *base.Request)
}

type ServerHandlerOnResponse interface {
    OnResponse(conn *ServerConn, res *base.Response)
}

Called for every inbound request and outbound response on a connection. Useful for logging or debugging.

Session events

ServerHandlerOnSessionOpen

type ServerHandlerOnSessionOpen interface {
    OnSessionOpen(ctx *ServerHandlerOnSessionOpenCtx)
}

Called when a new RTSP session is created.

Context struct ServerHandlerOnSessionOpenCtx:

Field	Type	Description
Session	*ServerSession	The new session
Conn	*ServerConn	The connection that opened the session

ServerHandlerOnSessionClose

type ServerHandlerOnSessionClose interface {
    OnSessionClose(ctx *ServerHandlerOnSessionCloseCtx)
}

Called when a session is closed.

Context struct ServerHandlerOnSessionCloseCtx:

Field	Type	Description
Session	*ServerSession	The closed session
Error	error	The error that caused the close, or nil

RTSP method handlers

ServerHandlerOnDescribe

type ServerHandlerOnDescribe interface {
    OnDescribe(ctx *ServerHandlerOnDescribeCtx) (*base.Response, *ServerStream, error)
}

Called when a client sends a DESCRIBE request. Return the response and the ServerStream to use. The server serializes the stream description into the response body automatically.

Context struct ServerHandlerOnDescribeCtx:

Field	Type	Description
Conn	*ServerConn	The connection
Request	*base.Request	The raw request
Path	string	Request path
Query	string	Request query string

ServerHandlerOnAnnounce

type ServerHandlerOnAnnounce interface {
    OnAnnounce(ctx *ServerHandlerOnAnnounceCtx) (*base.Response, error)
}

Called when a publisher sends an ANNOUNCE request.

Context struct ServerHandlerOnAnnounceCtx:

Field	Type	Description
Session	*ServerSession	The session
Conn	*ServerConn	The connection
Request	*base.Request	The raw request
Path	string	Announced path
Query	string	Query string
Description	*description.Session	Parsed SDP from the request body

ServerHandlerOnSetup

type ServerHandlerOnSetup interface {
    OnSetup(ctx *ServerHandlerOnSetupCtx) (*base.Response, *ServerStream, error)
}

Called when a client sends a SETUP request. Return the ServerStream to associate the session with it as a reader. Return nil for the stream when handling publishers.

Context struct ServerHandlerOnSetupCtx:

Field	Type	Description
Session	*ServerSession	The session
Conn	*ServerConn	The connection
Request	*base.Request	The raw request
Path	string	Request path
Query	string	Query string
Transport	*SessionTransport	Negotiated transport details

ServerHandlerOnPlay

type ServerHandlerOnPlay interface {
    OnPlay(ctx *ServerHandlerOnPlayCtx) (*base.Response, error)
}

Called when a reader sends a PLAY request.

Context struct ServerHandlerOnPlayCtx:

Field	Type	Description
Session	*ServerSession	The session
Conn	*ServerConn	The connection
Request	*base.Request	The raw request
Path	string	Request path
Query	string	Query string

ServerHandlerOnRecord

type ServerHandlerOnRecord interface {
    OnRecord(ctx *ServerHandlerOnRecordCtx) (*base.Response, error)
}

Called when a publisher sends a RECORD request.

Context struct ServerHandlerOnRecordCtx:

Field	Type	Description
Session	*ServerSession	The session
Conn	*ServerConn	The connection
Request	*base.Request	The raw request
Path	string	Request path
Query	string	Query string

ServerHandlerOnPause

type ServerHandlerOnPause interface {
    OnPause(ctx *ServerHandlerOnPauseCtx) (*base.Response, error)
}

Called when a client sends a PAUSE request.

Context struct ServerHandlerOnPauseCtx:

Field	Type	Description
Session	*ServerSession	The session
Conn	*ServerConn	The connection
Request	*base.Request	The raw request
Path	string	Request path
Query	string	Query string

ServerHandlerOnGetParameter / ServerHandlerOnSetParameter

type ServerHandlerOnGetParameter interface {
    OnGetParameter(ctx *ServerHandlerOnGetParameterCtx) (*base.Response, error)
}

type ServerHandlerOnSetParameter interface {
    OnSetParameter(ctx *ServerHandlerOnSetParameterCtx) (*base.Response, error)
}

Called for GET_PARAMETER and SET_PARAMETER requests respectively. GET_PARAMETER is also used as a keepalive ping; the server responds with 200 OK automatically if this interface is not implemented.

Both context structs contain Session, Conn, Request, Path, and Query fields.

Error and diagnostic handlers

ServerHandlerOnPacketsLost

type ServerHandlerOnPacketsLost interface {
    OnPacketsLost(ctx *ServerHandlerOnPacketsLostCtx)
}

Called when the server detects lost inbound RTP packets (recording sessions).

Context struct ServerHandlerOnPacketsLostCtx:

Field	Type	Description
Session	*ServerSession	The session where loss was detected
Lost	uint64	Number of lost packets

ServerHandlerOnDecodeError

type ServerHandlerOnDecodeError interface {
    OnDecodeError(ctx *ServerHandlerOnDecodeErrorCtx)
}

Called when a non-fatal packet decode error occurs.

Context struct ServerHandlerOnDecodeErrorCtx:

Field	Type	Description
Session	*ServerSession	The session that encountered the error
Error	error	The decode error

ServerHandlerOnStreamWriteError

type ServerHandlerOnStreamWriteError interface {
    OnStreamWriteError(ctx *ServerHandlerOnStreamWriteErrorCtx)
}

Called when a ServerStream fails to write packets to a reader session. Defaults to logging the error if not implemented.

Context struct ServerHandlerOnStreamWriteErrorCtx:

Field	Type	Description
Session	*ServerSession	The reader session that failed
Error	error	The write error