Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bluenviron/gortsplib/llms.txt

Use this file to discover all available pages before exploring further.

ServerSession represents a server-side RTSP session. A session is created automatically by the server when a client sends a SETUP or ANNOUNCE request. It tracks the session state, the negotiated transport, setupped media tracks, and optional user data. ServerConn represents a single TCP connection to a client. One connection can be associated with at most one session, but a session (when using UDP transport) can be associated with multiple connections.

​
ServerSessionState

The state of a session progresses through the following values:
ConstantValueMeaning
ServerSessionStateInitial0Session created; no tracks set up yet
ServerSessionStatePrePlay1At least one track set up for reading; PLAY not yet sent
ServerSessionStatePlay2Actively reading — packets are being delivered to the client
ServerSessionStatePreRecord3ANNOUNCE received; at least one track set up for publishing; RECORD not yet sent
ServerSessionStateRecord4Actively recording — packets are being received from the client

​
ServerSession methods

​
State

func (ss *ServerSession) State() ServerSessionState
Returns the current state of the session. Thread-safe.
​
ServerSessionState
ServerSessionState
One of the ServerSessionState* constants.

​
Stream

func (ss *ServerSession) Stream() *ServerStream
Returns the ServerStream associated with this session (set during SETUP for reading sessions). Returns nil for publishing sessions or before SETUP.

​
Path

func (ss *ServerSession) Path() string
Returns the RTSP path extracted from the SETUP or ANNOUNCE request URL.

​
Query

func (ss *ServerSession) Query() string
Returns the query string extracted from the SETUP or ANNOUNCE request URL.

​
AnnouncedDescription

func (ss *ServerSession) AnnouncedDescription() *description.Session
Returns the session description provided by a publishing client in the ANNOUNCE request. Returns nil for reading sessions.

​
Medias

func (ss *ServerSession) Medias() []*description.Media
Returns the list of media tracks that have been set up via SETUP, in the order they were set up.

​
Transport

func (ss *ServerSession) Transport() *SessionTransport
Returns the negotiated transport details. Non-nil only after SETUP has been called at least once.SessionTransport fields:
FieldTypeDescription
ProtocolProtocolTransport protocol: ProtocolUDP, ProtocolUDPMulticast, or ProtocolTCP
Profileheaders.TransportProfileRTSP transport profile (TransportProfileAVP or TransportProfileSAVP)

​
Conns

func (ss *ServerSession) Conns() []*ServerConn
Returns all ServerConn instances currently associated with the session.

​
SetUserData / UserData

func (ss *ServerSession) SetUserData(v any)
func (ss *ServerSession) UserData() any
Attach and retrieve arbitrary application data associated with the session. Not thread-safe — should be called only from handler callbacks.

​
Close

func (ss *ServerSession) Close()
Closes the session. Causes all associated connections to be closed and OnSessionClose to be called. Safe to call from any goroutine.

​
OnPacketRTP

func (ss *ServerSession) OnPacketRTP(
    medi *description.Media,
    forma format.Format,
    cb OnPacketRTPFunc,
)
Registers a callback for inbound RTP packets on a specific media format. Must be called after SETUP. OnPacketRTPFunc has signature func(*rtp.Packet).
​
medi
*description.Media
required
The media track to listen on.
​
forma
format.Format
required
The codec format to receive packets for.
​
cb
OnPacketRTPFunc
required
Callback invoked for each received RTP packet.

​
OnPacketRTPAny

func (ss *ServerSession) OnPacketRTPAny(cb OnPacketRTPAnyFunc)
Registers a callback for inbound RTP packets on all set-up media tracks and formats. OnPacketRTPAnyFunc has signature func(*description.Media, format.Format, *rtp.Packet).
​
cb
OnPacketRTPAnyFunc
required
Callback invoked with media and format context for each received RTP packet.

​
OnPacketRTCP

func (ss *ServerSession) OnPacketRTCP(medi *description.Media, cb OnPacketRTCPFunc)
Registers a callback for inbound RTCP packets on a specific media track. OnPacketRTCPFunc has signature func(rtcp.Packet).
​
medi
*description.Media
required
The media track to listen on.
​
cb
OnPacketRTCPFunc
required
Callback invoked for each received RTCP packet.

​
OnPacketRTCPAny

func (ss *ServerSession) OnPacketRTCPAny(cb OnPacketRTCPAnyFunc)
Registers a callback for inbound RTCP packets on all set-up media tracks. OnPacketRTCPAnyFunc has signature func(*description.Media, rtcp.Packet).
​
cb
OnPacketRTCPAnyFunc
required
Callback invoked with media context for each received RTCP packet.

​
WritePacketRTP

func (ss *ServerSession) WritePacketRTP(medi *description.Media, pkt *rtp.Packet) error
Writes an RTP packet directly to this session. Use ServerStream.WritePacketRTP instead when you want to fan out to all readers.
​
medi
*description.Media
required
The media track to write to.
​
pkt
*rtp.Packet
required
The RTP packet to send.
​
error
error
Non-nil on write failure.

​
WritePacketRTPWithNTP

func (ss *ServerSession) WritePacketRTPWithNTP(
    medi *description.Media,
    pkt *rtp.Packet,
    ntp time.Time,
) error
Like WritePacketRTP but accepts an explicit NTP timestamp for RTCP sender reports.
​
medi
*description.Media
required
The media track to write to.
​
pkt
*rtp.Packet
required
The RTP packet to send.
​
ntp
time.Time
required
Absolute NTP timestamp of the packet.
​
error
error
Non-nil on write failure.

​
WritePacketRTCP

func (ss *ServerSession) WritePacketRTCP(medi *description.Media, pkt rtcp.Packet) error
Writes an RTCP packet directly to this session.
​
medi
*description.Media
required
The media track to write to.
​
pkt
rtcp.Packet
required
The RTCP packet to send.
​
error
error
Non-nil on write failure.

​
PacketPTS

func (ss *ServerSession) PacketPTS(medi *description.Media, pkt *rtp.Packet) (int64, bool)
Returns the presentation timestamp (PTS) of an inbound RTP packet for recording sessions. Decodes the RTP timestamp and synchronizes it with other tracks.
​
medi
*description.Media
required
The media track the packet belongs to.
​
pkt
*rtp.Packet
required
The inbound RTP packet.
​
int64
int64
PTS in media clock units.
​
bool
bool
true if the PTS could be determined.

​
PacketNTP

func (ss *ServerSession) 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 sent by the publisher.
​
medi
*description.Media
required
The media track the packet belongs to.
​
pkt
*rtp.Packet
required
The inbound RTP packet.
​
time.Time
time.Time
The absolute NTP timestamp.
​
bool
bool
true if the NTP could be derived from RTCP sender reports.

​
Stats

func (ss *ServerSession) Stats() *SessionStats
Returns a snapshot of session statistics.SessionStats fields:
FieldTypeDescription
InboundBytesuint64Total inbound bytes
InboundRTPPacketsuint64RTP packets correctly received and processed
InboundRTPPacketsLostuint64Lost inbound RTP packets
InboundRTPPacketsInErroruint64Inbound RTP packets that could not be processed
InboundRTPPacketsJitterfloat64Mean jitter of inbound RTP packets
InboundRTCPPacketsuint64RTCP packets received and processed
InboundRTCPPacketsInErroruint64Inbound RTCP packets that could not be processed
OutboundBytesuint64Total outbound bytes
OutboundRTPPacketsuint64RTP packets sent
OutboundRTPPacketsReportedLostuint64RTP packets reported lost by the remote
OutboundRTCPPacketsuint64RTCP packets sent
Mediasmap[*description.Media]SessionStatsMediaPer-media breakdown

​
ServerConn methods

ServerConn is a server-side TCP connection. It is passed to handler callbacks and provides the following public API.

​
NetConn

func (sc *ServerConn) NetConn() net.Conn
Returns the underlying net.Conn. The remote address (RemoteAddr()) gives the client’s IP and port.

​
Transport

func (sc *ServerConn) Transport() *ConnTransport
Returns connection transport details. The ConnTransport struct has a single field:
FieldTypeDescription
TunnelTunnelTunneling method: TunnelNone, TunnelHTTP, or TunnelWebSocket

​
Session

func (sc *ServerConn) Session() *ServerSession
Returns the ServerSession currently associated with this connection, or nil if no session has been established yet.

​
SetUserData / UserData

func (sc *ServerConn) SetUserData(v any)
func (sc *ServerConn) UserData() any
Attach and retrieve arbitrary application data associated with the connection.

​
VerifyCredentials

func (sc *ServerConn) VerifyCredentials(
    req *base.Request,
    expectedUser string,
    expectedPass string,
) bool
Verifies the credentials provided in the Authorization header of req against expectedUser and expectedPass. Supports the authentication methods configured in Server.AuthMethods (Basic and/or Digest).Call this inside handler callbacks (e.g. OnDescribe, OnAnnounce) to enforce access control. Returns false and the server will automatically send a 401 Unauthorized with a WWW-Authenticate challenge on the first attempt. Returns false and closes the connection if wrong credentials are provided after a challenge.
​
req
*base.Request
required
The incoming RTSP request.
​
expectedUser
string
required
Expected username. Must not be empty.
​
expectedPass
string
required
Expected password.
​
bool
bool
true if credentials are correct, false otherwise.

​
Stats

func (sc *ServerConn) Stats() *ConnStats
Returns a snapshot of connection statistics.ConnStats fields:
FieldTypeDescription
InboundBytesuint64Total bytes received on this connection
OutboundBytesuint64Total bytes sent on this connection

​
Close

func (sc *ServerConn) Close()
Closes the connection. If a session is associated, it is notified and may be closed if no other connections remain.

Build docs developers (and LLMs) love

Get started for freeTalk to us