Client

Client is a RTSP client that can read streams from servers (playing) or publish streams to servers (recording). It manages connections, transport negotiation, authentication, and packet I/O.

Struct fields

Target

string

URL scheme. Must be "rtsp" or "rtsps" (TLS).

string

Remote host and port (e.g. "192.168.1.10:554").

RTSP parameters

time.Duration

default:"10s"

Timeout for read operations.

time.Duration

default:"10s"

Timeout for write operations.

*tls.Config

default:"nil"

TLS configuration used when connecting to RTSPS servers.

Tunnel

default:"TunnelNone"

Tunneling method. One of TunnelNone, TunnelHTTP, or TunnelWebSocket.

*Protocol

default:"nil"

Transport protocol (ProtocolUDP, ProtocolUDPMulticast, or ProtocolTCP). When nil the client first tries UDP, then falls back to TCP automatically.

bool

default:"false"

Enable communication with servers that do not provide UDP server ports or that use different server ports than announced. This can be a security risk.

time.Duration

default:"3s"

When reading with UDP, if no packet is received within this timeout the client switches to TCP.

int

default:"OS default"

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

int

default:"256"

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

int

default:"1472"

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

string

default:"\"gortsplib\""

Value sent in the User-Agent RTSP header.

bool

default:"false"

Disable automatic generation and sending of RTCP sender reports.

bool

default:"false"

Explicitly request back channels from the server (ONVIF extension).

[2]uint16

default:"[10000, 65535]"

Range of local source ports used for outbound UDP packets.

System functions

func(ctx context.Context, network, address string) (net.Conn, error)

default:"(&net.Dialer{}).DialContext"

Function used to open TCP connections. Override for custom networking.

func(network, address string) (net.PacketConn, error)

default:"net.ListenPacket"

Function used to open UDP listeners.

func(network, address string) (*net.IPAddr, error)

default:"net.ResolveIPAddr"

Function used to resolve IP addresses from hostnames.

Callbacks

ClientOnRequestFunc

Called each time the client sends a request to the server. Prototype: func(*base.Request).

ClientOnResponseFunc

Called each time the client receives a response from the server. Prototype: func(*base.Response).

ClientOnRequestFunc

Called each time the client receives a request from the server (e.g. server-initiated OPTIONS). Prototype: func(*base.Request).

ClientOnResponseFunc

Called each time the client sends a response to the server. Prototype: func(*base.Response).

ClientOnTransportSwitchFunc

Called when the transport protocol is switched (e.g. UDP to TCP fallback). Prototype: func(err error). Defaults to logging the error.

ClientOnPacketsLostFunc

Called when the client detects lost RTP packets. Prototype: func(lost uint64). Defaults to logging the count.

ClientOnDecodeErrorFunc

Called when a non-fatal decode error occurs. Prototype: func(err error). Defaults to logging the error.

Methods

Lifecycle

`Start`

func (c *Client) Start() error

Initializes the connection to the server using the Scheme and Host fields. Must be called before any RTSP method calls. Starts the internal event loop in a goroutine.

error

Non-nil if initialization fails (e.g. invalid WriteQueueSize, invalid MaxPacketSize).

`StartRecording`

func (c *Client) StartRecording(address string, desc *description.Session) error

Convenience method that parses address as a URL, calls Start(), Announce(), SetupAll(), and Record() in sequence. The client is closed automatically on any error.

string

required

Full RTSP URL string of the server to publish to.

*description.Session

required

Session description (SDP) of the media to be published.

error

Non-nil if any step in the connection/publish sequence fails.

`Close`

func (c *Client) Close()

Closes all client resources (connections, UDP listeners, goroutines) and waits for them to exit. Sends a TEARDOWN request before closing. Safe to call from any goroutine.

`Wait`

func (c *Client) Wait() error

Blocks until all client resources have exited. This occurs either when Close() is called or when a fatal error occurs (e.g. network timeout).

error

The close error, or nil if closed cleanly via Close().

Stream negotiation

`Describe`

func (c *Client) Describe(u *base.URL) (*description.Session, *base.Response, error)

Sends a DESCRIBE request to the server and returns the parsed session description. Handles redirects automatically.

*base.URL

required

The RTSP URL to describe.

*description.Session

Parsed session description containing media tracks and their formats.

*base.Response

The raw RTSP response.

error

Non-nil on failure.

`Announce`

func (c *Client) Announce(u *base.URL, desc *description.Session) (*base.Response, error)

Sends an ANNOUNCE request to the server with the given session description. Call before Setup() and Record() when publishing.

*base.URL

required

The RTSP URL to announce to.

*description.Session

required

Session description of the media to publish.

*base.Response

The raw RTSP response.

error

Non-nil on failure.

`SetupAll`

func (c *Client) SetupAll(baseURL *base.URL, medias []*description.Media) error

Calls Setup() for every media in medias. Uses port 0 for both RTP and RTCP (auto-assigned). Stops and returns on the first error.

*base.URL

required

The base URL returned from Describe() (available as desc.BaseURL).

[]*description.Media

required

Slice of media descriptions to set up.

error

Non-nil if any SETUP request fails.

`Setup`

func (c *Client) Setup(
    baseURL *base.URL,
    media *description.Media,
    rtpPort int,
    rtcpPort int,
) (*base.Response, error)

Sends a SETUP request for a single media track. rtpPort and rtcpPort are only used with UDP transport; pass 0 for both to let the OS choose ports.

*base.URL

required

The base URL of the stream (from Describe()).

*description.Media

required

The specific media track to set up.

int

Local UDP port for RTP. 0 means auto-assign. Must be even.

int

Local UDP port for RTCP. 0 means auto-assign. Must equal rtpPort + 1.

*base.Response

The raw RTSP response.

error

Non-nil on failure.

`Options`

func (c *Client) Options(u *base.URL) (*base.Response, error)

Sends an OPTIONS request. Normally called automatically; can be used to probe server capabilities.

*base.URL

required

The URL to send the OPTIONS request to.

*base.Response

The raw RTSP response containing a Public header with supported methods.

error

Non-nil on failure.

Stream control

`Play`

func (c *Client) Play(ra *headers.Range) (*base.Response, error)

Sends a PLAY request. Must be called after Setup(). Starts receiving packets.

*headers.Range

Playback range. Pass nil to start from the beginning (NPT 0).

*base.Response

The raw RTSP response.

error

Non-nil on failure.

`Record`

func (c *Client) Record() (*base.Response, error)

Sends a RECORD request. Must be called after Announce() and Setup(). Starts sending packets.

*base.Response

The raw RTSP response.

error

Non-nil on failure.

`Pause`

func (c *Client) Pause() (*base.Response, error)

Sends a PAUSE request. Can only be called after Play() or Record(). Suspends the stream without tearing it down.

*base.Response

The raw RTSP response.

error

Non-nil on failure.

Packet I/O

`WritePacketRTP`

func (c *Client) WritePacketRTP(medi *description.Media, pkt *rtp.Packet) error

Sends an RTP packet to the server. Uses the current wall clock as the NTP timestamp. Only valid in the recording state after Record().

*description.Media

required

The media track to send on.

*rtp.Packet

required

The RTP packet to send.

error

Non-nil on write failure.

`WritePacketRTPWithNTP`

func (c *Client) WritePacketRTPWithNTP(medi *description.Media, pkt *rtp.Packet, ntp time.Time) error

Like WritePacketRTP but accepts an explicit NTP timestamp. This NTP value is used in periodic RTCP sender reports.

*description.Media

required

The media track to send on.

*rtp.Packet

required

The RTP packet to send.

time.Time

required

Absolute NTP timestamp of the packet.

error

Non-nil on write failure.

`WritePacketRTCP`

func (c *Client) WritePacketRTCP(medi *description.Media, pkt rtcp.Packet) error

Sends an RTCP packet to the server.

*description.Media

required

The media track to send on.

rtcp.Packet

required

The RTCP packet to send.

error

Non-nil on write failure.

`OnPacketRTP`

func (c *Client) OnPacketRTP(medi *description.Media, forma format.Format, cb OnPacketRTPFunc)

Registers a callback for incoming RTP packets on a specific media format. OnPacketRTPFunc has signature func(*rtp.Packet). Must be called after Setup() and before Play().

*description.Media

required

The media track to listen on.

format.Format

required

The specific codec format to receive packets for.

OnPacketRTPFunc

required

Callback invoked for each received RTP packet: func(*rtp.Packet).

`OnPacketRTPAny`

func (c *Client) OnPacketRTPAny(cb OnPacketRTPAnyFunc)

Registers a callback for incoming RTP packets on all set-up media tracks and formats. OnPacketRTPAnyFunc has signature func(*description.Media, format.Format, *rtp.Packet).

OnPacketRTPAnyFunc

required

Callback invoked for each received RTP packet with media and format context.

`OnPacketRTCP`

func (c *Client) OnPacketRTCP(medi *description.Media, cb OnPacketRTCPFunc)

Registers a callback for incoming RTCP packets on a specific media track. OnPacketRTCPFunc has signature func(rtcp.Packet).

*description.Media

required

The media track to listen on.

OnPacketRTCPFunc

required

Callback invoked for each received RTCP packet.

`OnPacketRTCPAny`

func (c *Client) OnPacketRTCPAny(cb OnPacketRTCPAnyFunc)

Registers a callback for incoming RTCP packets on all set-up media tracks. OnPacketRTCPAnyFunc has signature func(*description.Media, rtcp.Packet).

OnPacketRTCPAnyFunc

required

Callback invoked for each received RTCP packet with media context.

Timestamps

`PacketPTS`

func (c *Client) PacketPTS(medi *description.Media, pkt *rtp.Packet) (int64, bool)

Returns the presentation timestamp (PTS) of an inbound RTP packet. The PTS is computed by decoding the RTP timestamp and synchronizing it with other tracks via rtptime.GlobalDecoder.

*description.Media

required

The media track the packet belongs to.

*rtp.Packet

required

The inbound RTP packet.

int64

The PTS in media clock units.

bool

true if the PTS could be computed, false if not enough information is available yet.

`PacketNTP`

func (c *Client) PacketNTP(medi *description.Media, pkt *rtp.Packet) (time.Time, bool)

Returns the absolute NTP timestamp of an inbound RTP packet, derived from RTCP sender reports.

*description.Media

required

The media track the packet belongs to.

*rtp.Packet

required

The inbound RTP packet.

time.Time

The absolute NTP timestamp.

bool

true if the NTP could be derived from RTCP sender reports, false otherwise.

Introspection

`Transport`

func (c *Client) Transport() *ClientTransport

Returns details about the active transport. The returned ClientTransport contains:

Conn ConnTransport — connection transport, with Tunnel field (TunnelNone, TunnelHTTP, TunnelWebSocket).
Session *SessionTransport — session transport (non-nil after Setup()), with Protocol (ProtocolUDP, ProtocolUDPMulticast, ProtocolTCP) and Profile fields.

`Stats`

func (c *Client) Stats() *ClientStats

Returns a snapshot of client statistics. The returned *ClientStats struct contains:

Field	Type	Description
`Conn.InboundBytes`	`uint64`	Total bytes received on the TCP connection
`Conn.OutboundBytes`	`uint64`	Total bytes sent on the TCP connection
`Session.InboundBytes`	`uint64`	Total inbound media bytes
`Session.InboundRTPPackets`	`uint64`	RTP packets received and processed
`Session.InboundRTPPacketsLost`	`uint64`	Lost inbound RTP packets
`Session.InboundRTPPacketsInError`	`uint64`	Inbound RTP packets that could not be processed
`Session.InboundRTPPacketsJitter`	`float64`	Mean jitter of inbound RTP packets
`Session.InboundRTCPPackets`	`uint64`	RTCP packets received and processed
`Session.OutboundBytes`	`uint64`	Total outbound media bytes
`Session.OutboundRTPPackets`	`uint64`	RTP packets sent
`Session.OutboundRTPPacketsReportedLost`	`uint64`	RTP packets reported lost by the remote
`Session.OutboundRTCPPackets`	`uint64`	RTCP packets sent
`Session.Medias`	`map[*description.Media]SessionStatsMedia`	Per-media statistics

Callback type aliases

Type	Signature	Used by
`ClientOnRequestFunc`	`func(*base.Request)`	`OnRequest`, `OnServerRequest`
`ClientOnResponseFunc`	`func(*base.Response)`	`OnResponse`, `OnServerResponse`
`ClientOnTransportSwitchFunc`	`func(err error)`	`OnTransportSwitch`
`ClientOnPacketsLostFunc`	`func(lost uint64)`	`OnPacketsLost`
`ClientOnDecodeErrorFunc`	`func(err error)`	`OnDecodeError`
`OnPacketRTPFunc`	`func(*rtp.Packet)`	`OnPacketRTP`
`OnPacketRTPAnyFunc`	`func(description.Media, format.Format, rtp.Packet)`	`OnPacketRTPAny`
`OnPacketRTCPFunc`	`func(rtcp.Packet)`	`OnPacketRTCP`
`OnPacketRTCPAnyFunc`	`func(*description.Media, rtcp.Packet)`	`OnPacketRTCPAny`

Core Types

Packages

Struct fields

Target

RTSP parameters

System functions

Callbacks

Methods

`Start`

`StartRecording`

`Close`

`Wait`

`Describe`

`Announce`

`SetupAll`

`Setup`

`Options`

`Play`

`Record`

`Pause`

`WritePacketRTP`

`WritePacketRTPWithNTP`

`WritePacketRTCP`

`OnPacketRTP`

`OnPacketRTPAny`

`OnPacketRTCP`

`OnPacketRTCPAny`

`PacketPTS`

`PacketNTP`

`Transport`

`Stats`

Callback type aliases

​Struct fields

​Target

​RTSP parameters

​System functions

​Callbacks

​Methods

​Start

​StartRecording

​Close

​Wait

​Describe

​Announce

​SetupAll

​Setup

​Options

​Play

​Record

​Pause

​WritePacketRTP

​WritePacketRTPWithNTP

​WritePacketRTCP

​OnPacketRTP

​OnPacketRTPAny

​OnPacketRTCP

​OnPacketRTCPAny

​PacketPTS

​PacketNTP

​Transport

​Stats

​Callback type aliases

Struct fields

Target

RTSP parameters

System functions

Callbacks

Methods

`Start`

`StartRecording`

`Close`

`Wait`

`Describe`

`Announce`

`SetupAll`

`Setup`

`Options`

`Play`

`Record`

`Pause`

`WritePacketRTP`

`WritePacketRTPWithNTP`

`WritePacketRTCP`

`OnPacketRTP`

`OnPacketRTPAny`

`OnPacketRTCP`

`OnPacketRTCPAny`

`PacketPTS`

`PacketNTP`

`Transport`

`Stats`

Callback type aliases