ServerSession

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:

Constant	Value	Meaning
`ServerSessionStateInitial`	`0`	Session created; no tracks set up yet
`ServerSessionStatePrePlay`	`1`	At least one track set up for reading; PLAY not yet sent
`ServerSessionStatePlay`	`2`	Actively reading — packets are being delivered to the client
`ServerSessionStatePreRecord`	`3`	ANNOUNCE received; at least one track set up for publishing; RECORD not yet sent
`ServerSessionStateRecord`	`4`	Actively recording — packets are being received from the client

ServerSession methods

State and properties

`State`

func (ss *ServerSession) State() ServerSessionState

Returns the current state of the session. Thread-safe.

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:

Field	Type	Description
`Protocol`	`Protocol`	Transport protocol: `ProtocolUDP`, `ProtocolUDPMulticast`, or `ProtocolTCP`
`Profile`	`headers.TransportProfile`	RTSP 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.

Lifecycle

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

Packet callbacks (inbound — recording sessions)

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

*description.Media

required

The media track to listen on.

format.Format

required

The codec format to receive packets for.

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

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

*description.Media

required

The media track to listen on.

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

OnPacketRTCPAnyFunc

required

Callback invoked with media context for each received RTCP packet.

Packet writing (outbound — per-session writes)

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

*description.Media

required

The media track to write to.

*rtp.Packet

required

The RTP packet to send.

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.

*description.Media

required

The media track to write to.

*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 (ss *ServerSession) WritePacketRTCP(medi *description.Media, pkt rtcp.Packet) error

Writes an RTCP packet directly to this session.

*description.Media

required

The media track to write to.

rtcp.Packet

required

The RTCP packet to send.

error

Non-nil on write failure.

Timestamps

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

*description.Media

required

The media track the packet belongs to.

*rtp.Packet

required

The inbound RTP packet.

int64

PTS in media clock units.

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.

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

Statistics

`Stats`

func (ss *ServerSession) Stats() *SessionStats

Returns a snapshot of session statistics.SessionStats fields:

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

ServerConn methods

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

Connection info

`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:

Field	Type	Description
`Tunnel`	`Tunnel`	Tunneling 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.

Authentication

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

*base.Request

required

The incoming RTSP request.

string

required

Expected username. Must not be empty.

string

required

Expected password.

bool

true if credentials are correct, false otherwise.

Statistics

`Stats`

func (sc *ServerConn) Stats() *ConnStats

Returns a snapshot of connection statistics.ConnStats fields:

Field	Type	Description
`InboundBytes`	`uint64`	Total bytes received on this connection
`OutboundBytes`	`uint64`	Total bytes sent on this connection

Lifecycle

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

Core Types

Packages

ServerSessionState

ServerSession methods

`State`

`Stream`

`Path`

`Query`

`AnnouncedDescription`

`Medias`

`Transport`

`Conns`

`SetUserData` / `UserData`

`Close`

`OnPacketRTP`

`OnPacketRTPAny`

`OnPacketRTCP`

`OnPacketRTCPAny`

`WritePacketRTP`

`WritePacketRTPWithNTP`

`WritePacketRTCP`

`PacketPTS`

`PacketNTP`

`Stats`

ServerConn methods

`NetConn`

`Transport`

`Session`

`SetUserData` / `UserData`

`VerifyCredentials`

`Stats`

`Close`

​ServerSessionState

​ServerSession methods

​State

​Stream

​Path

​Query

​AnnouncedDescription

​Medias

​Transport

​Conns

​SetUserData / UserData

​Close

​OnPacketRTP

​OnPacketRTPAny

​OnPacketRTCP

​OnPacketRTCPAny

​WritePacketRTP

​WritePacketRTPWithNTP

​WritePacketRTCP

​PacketPTS

​PacketNTP

​Stats

​ServerConn methods

​NetConn

​Transport

​Session

​SetUserData / UserData

​VerifyCredentials

​Stats

​Close

ServerSessionState

ServerSession methods

`State`

`Stream`

`Path`

`Query`

`AnnouncedDescription`

`Medias`

`Transport`

`Conns`

`SetUserData` / `UserData`

`Close`

`OnPacketRTP`

`OnPacketRTPAny`

`OnPacketRTCP`

`OnPacketRTCPAny`

`WritePacketRTP`

`WritePacketRTPWithNTP`

`WritePacketRTCP`

`PacketPTS`

`PacketNTP`

`Stats`

ServerConn methods

`NetConn`

`Transport`

`Session`

`SetUserData` / `UserData`

`VerifyCredentials`

`Stats`

`Close`