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

> Complete API reference for the ServerSession type.

`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`
>
> ```go theme={null}
> func (ss *ServerSession) State() ServerSessionState
> ```
>
> Returns the current state of the session. Thread-safe.
>
> **ServerSessionState** `ServerSessionState`
>
> One of the `ServerSessionState*` constants.
>
> ***
>
> ### `Stream`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> func (ss *ServerSession) Path() string
> ```
>
> Returns the RTSP path extracted from the SETUP or ANNOUNCE request URL.
>
> ***
>
> ### `Query`
>
> ```go theme={null}
> func (ss *ServerSession) Query() string
> ```
>
> Returns the query string extracted from the SETUP or ANNOUNCE request URL.
>
> ***
>
> ### `AnnouncedDescription`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> func (ss *ServerSession) Conns() []*ServerConn
> ```
>
> Returns all `ServerConn` instances currently associated with the session.
>
> ***
>
> ### `SetUserData` / `UserData`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> 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.

> **Packet writing (outbound — per-session writes)**
>
> ### `WritePacketRTP`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> 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.

> **Timestamps**
>
> ### `PacketPTS`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> 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.

> **Statistics**
>
> ### `Stats`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> func (sc *ServerConn) NetConn() net.Conn
> ```
>
> Returns the underlying `net.Conn`. The remote address (`RemoteAddr()`) gives the client's IP and port.
>
> ***
>
> ### `Transport`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> func (sc *ServerConn) Session() *ServerSession
> ```
>
> Returns the `ServerSession` currently associated with this connection, or `nil` if no session has been established yet.
>
> ***
>
> ### `SetUserData` / `UserData`
>
> ```go theme={null}
> func (sc *ServerConn) SetUserData(v any)
> func (sc *ServerConn) UserData() any
> ```
>
> Attach and retrieve arbitrary application data associated with the connection.

> **Authentication**
>
> ### `VerifyCredentials`
>
> ```go theme={null}
> 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.

> **Statistics**
>
> ### `Stats`
>
> ```go theme={null}
> 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`
>
> ```go theme={null}
> func (sc *ServerConn) Close()
> ```
>
> Closes the connection. If a session is associated, it is notified and may be closed if no other connections remain.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.