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.
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.