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

# Server

> Complete API reference for the Server struct.

`Server` is a RTSP server. It accepts connections from clients, manages sessions, and dispatches events to a user-supplied handler.

## Struct fields

### Network configuration

<ParamField path="RTSPAddress" type="string" required>
  The TCP address the server listens on (e.g. `":8554"`). Also used for TCP transport. This field is required.
</ParamField>

<ParamField path="UDPRTPAddress" type="string">
  Address for the UDP RTP listener (e.g. `":8000"`). Must be set together with `UDPRTCPAddress` to enable UDP transport. The RTP port must be even.
</ParamField>

<ParamField path="UDPRTCPAddress" type="string">
  Address for the UDP RTCP listener (e.g. `":8001"`). Must be set together with `UDPRTPAddress`. The RTCP port must equal `UDPRTPPort + 1`.
</ParamField>

<ParamField path="MulticastIPRange" type="string">
  CIDR range of multicast IPs to assign (e.g. `"224.1.0.0/16"`). Must be set together with `MulticastRTPPort` and `MulticastRTCPPort` to enable UDP-multicast transport.
</ParamField>

<ParamField path="MulticastRTPPort" type="int">
  Port for multicast RTP packets. Must be even.
</ParamField>

<ParamField path="MulticastRTCPPort" type="int">
  Port for multicast RTCP packets. Must equal `MulticastRTPPort + 1`.
</ParamField>

### Timeouts

<ParamField path="ReadTimeout" type="time.Duration" default="10s">
  Timeout for read operations.
</ParamField>

<ParamField path="WriteTimeout" type="time.Duration" default="10s">
  Timeout for write operations.
</ParamField>

<ParamField path="IdleTimeout" type="time.Duration" default="60s">
  Read timeout for idle connections and sessions with no activity.
</ParamField>

### TLS

<ParamField path="TLSConfig" type="*tls.Config">
  TLS configuration. When set, the server accepts RTSPS connections and enforces SRTP for UDP transport.
</ParamField>

### I/O tuning

<ParamField path="UDPReadBufferSize" type="int" default="OS default">
  Size of the UDP read buffer. Increase to reduce packet loss on high-bandwidth streams.
</ParamField>

<ParamField path="WriteQueueSize" type="int" default="256">
  Size of the outbound packet queue per session. Must be a power of two.
</ParamField>

<ParamField path="MaxPacketSize" type="int" default="1472">
  Maximum size of outbound RTP/RTCP packets in bytes. Must be less than the IPv4/UDP MTU (1472 bytes).
</ParamField>

<ParamField path="DisableRTCPSenderReports" type="bool" default="false">
  Disable automatic generation and sending of RTCP sender reports to readers.
</ParamField>

### Authentication

<ParamField path="AuthMethods" type="[]auth.VerifyMethod" default="[Basic, DigestMD5]">
  Allowed authentication methods. Defaults to `[auth.VerifyMethodBasic, auth.VerifyMethodDigestMD5]`. DigestSHA256 is omitted by default because it prevents FFmpeg from authenticating.
</ParamField>

### Handler

<ParamField path="Handler" type="ServerHandler">
  An object that implements one or more of the `ServerHandler*` interfaces to handle server events. See [Handler interfaces](#handler-interfaces) below.
</ParamField>

### System functions

<ParamField path="Listen" type="func(network, address string) (net.Listener, error)" default="net.Listen">
  Function used to create the TCP listener. Override for custom networking.
</ParamField>

<ParamField path="ListenPacket" type="func(network, address string) (net.PacketConn, error)" default="net.ListenPacket">
  Function used to create UDP listeners.
</ParamField>

***

## Methods

<AccordionGroup>
  <Accordion title="Lifecycle">
    ### `Start`

    ```go theme={null}
    func (s *Server) Start() error
    ```

    Starts the server. Validates configuration, opens all network listeners (TCP, UDP RTP/RTCP, multicast), and spawns the internal event loop goroutine.

    <ResponseField name="error" type="error">
      Non-nil if configuration is invalid or listeners cannot be opened.
    </ResponseField>

    ***

    ### `StartAndWait`

    ```go theme={null}
    func (s *Server) StartAndWait() error
    ```

    Starts the server and blocks until a fatal error occurs or `Close()` is called. Equivalent to calling `Start()` then `Wait()`.

    <ResponseField name="error" type="error">
      The terminal error, or `nil` if closed cleanly.
    </ResponseField>

    ***

    ### `Wait`

    ```go theme={null}
    func (s *Server) Wait() error
    ```

    Blocks until all server resources have exited. Returns the error that caused the server to stop.

    <ResponseField name="error" type="error">
      The terminal error, or `nil` if closed cleanly.
    </ResponseField>

    ***

    ### `Close`

    ```go theme={null}
    func (s *Server) Close()
    ```

    Closes all server resources (listeners, connections, sessions) and waits for them to exit.

    ***

    ### `NetListener`

    ```go theme={null}
    func (s *Server) NetListener() net.Listener
    ```

    Returns the underlying `net.Listener` for the TCP RTSP socket. Useful for obtaining the dynamically assigned port when `RTSPAddress` uses port `0`.
  </Accordion>
</AccordionGroup>

***

## Handler interfaces

The `Handler` field accepts any value that implements one or more of the following interfaces. Implement only the interfaces relevant to your use case.

### Connection events

<AccordionGroup>
  <Accordion title="ServerHandlerOnConnOpen">
    ```go theme={null}
    type ServerHandlerOnConnOpen interface {
        OnConnOpen(ctx *ServerHandlerOnConnOpenCtx)
    }
    ```

    Called when a new connection is opened.

    **Context struct `ServerHandlerOnConnOpenCtx`:**

    | Field | Type | Description |
    | - | - | - |
    | `Conn` | `*ServerConn` | The newly opened connection |
  </Accordion>

  <Accordion title="ServerHandlerOnConnClose">
    ```go theme={null}
    type ServerHandlerOnConnClose interface {
        OnConnClose(ctx *ServerHandlerOnConnCloseCtx)
    }
    ```

    Called when a connection is closed.

    **Context struct `ServerHandlerOnConnCloseCtx`:**

    | Field | Type | Description |
    | - | - | - |
    | `Conn` | `*ServerConn` | The closed connection |
    | `Error` | `error` | The error that caused the close, or `nil` |
  </Accordion>

  <Accordion title="ServerHandlerOnRequest / ServerHandlerOnResponse">
    ```go theme={null}
    type ServerHandlerOnRequest interface {
        OnRequest(conn *ServerConn, req *base.Request)
    }

    type ServerHandlerOnResponse interface {
        OnResponse(conn *ServerConn, res *base.Response)
    }
    ```

    Called for every inbound request and outbound response on a connection. Useful for logging or debugging.
  </Accordion>
</AccordionGroup>

### Session events

<AccordionGroup>
  <Accordion title="ServerHandlerOnSessionOpen">
    ```go theme={null}
    type ServerHandlerOnSessionOpen interface {
        OnSessionOpen(ctx *ServerHandlerOnSessionOpenCtx)
    }
    ```

    Called when a new RTSP session is created.

    **Context struct `ServerHandlerOnSessionOpenCtx`:**

    | Field | Type | Description |
    | - | - | - |
    | `Session` | `*ServerSession` | The new session |
    | `Conn` | `*ServerConn` | The connection that opened the session |
  </Accordion>

  <Accordion title="ServerHandlerOnSessionClose">
    ```go theme={null}
    type ServerHandlerOnSessionClose interface {
        OnSessionClose(ctx *ServerHandlerOnSessionCloseCtx)
    }
    ```

    Called when a session is closed.

    **Context struct `ServerHandlerOnSessionCloseCtx`:**

    | Field | Type | Description |
    | - | - | - |
    | `Session` | `*ServerSession` | The closed session |
    | `Error` | `error` | The error that caused the close, or `nil` |
  </Accordion>
</AccordionGroup>

### RTSP method handlers

<AccordionGroup>
  <Accordion title="ServerHandlerOnDescribe">
    ```go theme={null}
    type ServerHandlerOnDescribe interface {
        OnDescribe(ctx *ServerHandlerOnDescribeCtx) (*base.Response, *ServerStream, error)
    }
    ```

    Called when a client sends a DESCRIBE request. Return the response and the `ServerStream` to use. The server serializes the stream description into the response body automatically.

    **Context struct `ServerHandlerOnDescribeCtx`:**

    | Field | Type | Description |
    | - | - | - |
    | `Conn` | `*ServerConn` | The connection |
    | `Request` | `*base.Request` | The raw request |
    | `Path` | `string` | Request path |
    | `Query` | `string` | Request query string |
  </Accordion>

  <Accordion title="ServerHandlerOnAnnounce">
    ```go theme={null}
    type ServerHandlerOnAnnounce interface {
        OnAnnounce(ctx *ServerHandlerOnAnnounceCtx) (*base.Response, error)
    }
    ```

    Called when a publisher sends an ANNOUNCE request.

    **Context struct `ServerHandlerOnAnnounceCtx`:**

    | Field | Type | Description |
    | - | - | - |
    | `Session` | `*ServerSession` | The session |
    | `Conn` | `*ServerConn` | The connection |
    | `Request` | `*base.Request` | The raw request |
    | `Path` | `string` | Announced path |
    | `Query` | `string` | Query string |
    | `Description` | `*description.Session` | Parsed SDP from the request body |
  </Accordion>

  <Accordion title="ServerHandlerOnSetup">
    ```go theme={null}
    type ServerHandlerOnSetup interface {
        OnSetup(ctx *ServerHandlerOnSetupCtx) (*base.Response, *ServerStream, error)
    }
    ```

    Called when a client sends a SETUP request. Return the `ServerStream` to associate the session with it as a reader. Return `nil` for the stream when handling publishers.

    **Context struct `ServerHandlerOnSetupCtx`:**

    | Field | Type | Description |
    | - | - | - |
    | `Session` | `*ServerSession` | The session |
    | `Conn` | `*ServerConn` | The connection |
    | `Request` | `*base.Request` | The raw request |
    | `Path` | `string` | Request path |
    | `Query` | `string` | Query string |
    | `Transport` | `*SessionTransport` | Negotiated transport details |
  </Accordion>

  <Accordion title="ServerHandlerOnPlay">
    ```go theme={null}
    type ServerHandlerOnPlay interface {
        OnPlay(ctx *ServerHandlerOnPlayCtx) (*base.Response, error)
    }
    ```

    Called when a reader sends a PLAY request.

    **Context struct `ServerHandlerOnPlayCtx`:**

    | Field | Type | Description |
    | - | - | - |
    | `Session` | `*ServerSession` | The session |
    | `Conn` | `*ServerConn` | The connection |
    | `Request` | `*base.Request` | The raw request |
    | `Path` | `string` | Request path |
    | `Query` | `string` | Query string |
  </Accordion>

  <Accordion title="ServerHandlerOnRecord">
    ```go theme={null}
    type ServerHandlerOnRecord interface {
        OnRecord(ctx *ServerHandlerOnRecordCtx) (*base.Response, error)
    }
    ```

    Called when a publisher sends a RECORD request.

    **Context struct `ServerHandlerOnRecordCtx`:**

    | Field | Type | Description |
    | - | - | - |
    | `Session` | `*ServerSession` | The session |
    | `Conn` | `*ServerConn` | The connection |
    | `Request` | `*base.Request` | The raw request |
    | `Path` | `string` | Request path |
    | `Query` | `string` | Query string |
  </Accordion>

  <Accordion title="ServerHandlerOnPause">
    ```go theme={null}
    type ServerHandlerOnPause interface {
        OnPause(ctx *ServerHandlerOnPauseCtx) (*base.Response, error)
    }
    ```

    Called when a client sends a PAUSE request.

    **Context struct `ServerHandlerOnPauseCtx`:**

    | Field | Type | Description |
    | - | - | - |
    | `Session` | `*ServerSession` | The session |
    | `Conn` | `*ServerConn` | The connection |
    | `Request` | `*base.Request` | The raw request |
    | `Path` | `string` | Request path |
    | `Query` | `string` | Query string |
  </Accordion>

  <Accordion title="ServerHandlerOnGetParameter / ServerHandlerOnSetParameter">
    ```go theme={null}
    type ServerHandlerOnGetParameter interface {
        OnGetParameter(ctx *ServerHandlerOnGetParameterCtx) (*base.Response, error)
    }

    type ServerHandlerOnSetParameter interface {
        OnSetParameter(ctx *ServerHandlerOnSetParameterCtx) (*base.Response, error)
    }
    ```

    Called for GET\_PARAMETER and SET\_PARAMETER requests respectively. GET\_PARAMETER is also used as a keepalive ping; the server responds with 200 OK automatically if this interface is not implemented.

    Both context structs contain `Session`, `Conn`, `Request`, `Path`, and `Query` fields.
  </Accordion>
</AccordionGroup>

### Error and diagnostic handlers

<AccordionGroup>
  <Accordion title="ServerHandlerOnPacketsLost">
    ```go theme={null}
    type ServerHandlerOnPacketsLost interface {
        OnPacketsLost(ctx *ServerHandlerOnPacketsLostCtx)
    }
    ```

    Called when the server detects lost inbound RTP packets (recording sessions).

    **Context struct `ServerHandlerOnPacketsLostCtx`:**

    | Field | Type | Description |
    | - | - | - |
    | `Session` | `*ServerSession` | The session where loss was detected |
    | `Lost` | `uint64` | Number of lost packets |
  </Accordion>

  <Accordion title="ServerHandlerOnDecodeError">
    ```go theme={null}
    type ServerHandlerOnDecodeError interface {
        OnDecodeError(ctx *ServerHandlerOnDecodeErrorCtx)
    }
    ```

    Called when a non-fatal packet decode error occurs.

    **Context struct `ServerHandlerOnDecodeErrorCtx`:**

    | Field | Type | Description |
    | - | - | - |
    | `Session` | `*ServerSession` | The session that encountered the error |
    | `Error` | `error` | The decode error |
  </Accordion>

  <Accordion title="ServerHandlerOnStreamWriteError">
    ```go theme={null}
    type ServerHandlerOnStreamWriteError interface {
        OnStreamWriteError(ctx *ServerHandlerOnStreamWriteErrorCtx)
    }
    ```

    Called when a `ServerStream` fails to write packets to a reader session. Defaults to logging the error if not implemented.

    **Context struct `ServerHandlerOnStreamWriteErrorCtx`:**

    | Field | Type | Description |
    | - | - | - |
    | `Session` | `*ServerSession` | The reader session that failed |
    | `Error` | `error` | The write error |
  </Accordion>
</AccordionGroup>


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