Client overview

The Client struct — connecting to RTSP servers to play or record streams.

The Client struct is the main entry point for connecting to RTSP servers. It operates in two primary modes:

• Play mode — read RTP/RTCP media streams from a server.
• Record mode — publish RTP media streams to a server.

Both modes share the same struct. You configure fields before calling Start() or one of its shorthand helpers, then register packet callbacks and enter the active state.

Client fields

All fields are optional unless noted. Zero values produce the documented defaults.

Connection target

Field	Type	Description
Scheme	string	URL scheme: "rtsp" or "rtsps". Set automatically by StartRecording.
Host	string	Host and port of the server (e.g. "localhost:8554"). Set automatically by StartRecording.

RTSP parameters

Field	Type	Default	Description
ReadTimeout	time.Duration	10s	Timeout for read operations.
WriteTimeout	time.Duration	10s	Timeout for write operations.
TLSConfig	*tls.Config	nil	TLS configuration for RTSPS connections.
Tunnel	Tunnel	TunnelNone	Tunneling method: TunnelNone, TunnelHTTP, or TunnelWebSocket.
Protocol	*Protocol	nil (auto)	Transport protocol. nil means automatic: try UDP first, fall back to TCP.
AnyPortEnable	bool	false	Accept server UDP ports that differ from the announced ones.
InitialUDPReadTimeout	time.Duration	3s	How long to wait for the first UDP packet before switching to TCP.
UDPReadBufferSize	int	OS default	UDP receive buffer size. Increase to reduce packet loss on high-bitrate streams.
WriteQueueSize	int	256	Outbound packet queue depth. Must be a power of two.
MaxPacketSize	int	1472	Maximum RTP/RTCP packet size (must be ≤ IPv4/UDP MTU of 1472 bytes).
UserAgent	string	"gortsplib"	Value sent in the User-Agent header.
DisableRTCPSenderReports	bool	false	Suppress automatic RTCP sender report generation.
RequestBackChannels	bool	false	Explicitly request ONVIF back channels from the server.
UDPSourcePortRange	[2]uint16	[10000, 65535]	Source port range for outbound UDP packets.

Callbacks

Field	Signature	Description
OnRequest	func(*base.Request)	Called when sending a request to the server.
OnResponse	func(*base.Response)	Called when receiving a response from the server.
OnTransportSwitch	func(err error)	Called when the library switches transport (e.g. UDP → TCP).
OnPacketsLost	func(lost uint64)	Called when the client detects lost RTP packets.
OnDecodeError	func(err error)	Called on non-fatal decode errors.

Key methods

Method	Description
Start() error	Connect to the server. Must be called before Describe, SetupAll, or Announce.
Close()	Close all resources and wait for cleanup to finish.
Wait() error	Block until a fatal error occurs or Close() is called. Returns the error.
Describe(u) (*description.Session, ...)	Send DESCRIBE and retrieve the session description.
SetupAll(baseURL, medias) error	Send SETUP for every media in the list.
Play(range) error	Enter play state and start receiving packets.
Pause() error	Pause playback or recording without disconnecting.
Record() error	Re-enter record state after a pause.
StartRecording(url, desc) error	Shorthand: Start + Announce + SetupAll + Record in one call.
WritePacketRTP(media, pkt) error	Send an RTP packet (record mode).
OnPacketRTPAny(func)	Register a callback for all incoming RTP packets (play mode).
OnPacketRTCPAny(func)	Register a callback for all incoming RTCP packets (play mode).
PacketPTS(media, pkt)	Return the presentation timestamp of an RTP packet.
PacketNTP(media, pkt)	Return the absolute NTP timestamp of an RTP packet, if available.

What’s next

Playing streams

Read RTP media from an RTSP server with callbacks and pause/resume.

Recording streams

Publish RTP media to an RTSP server using StartRecording.

Transport options

Choose between UDP, TCP, and UDP-multicast transports.

Security

RTSPS, SRTP, credentials, and self-signed certificates.