gortsplib

gortsplib is an RTSP client and server library for the Go programming language. It is designed for high-performance media streaming and is used by projects like MediaMTX.

Client Capabilities

• Security: Supports RTSPS, SRTP, and SRTCP.
• Tunneling: Supports RTSP-over-HTTP and RTSP-over-WebSocket.
• Stream Management: Query available media, read streams ("play") using UDP, UDP-multicast, or TCP, and write streams ("record") using UDP or TCP. It features automatic transport protocol switching.
• Control: Supports pausing, seeking, and writing to ONVIF back channels without disconnecting.
• Metadata: Provides access to PTS (presentation timestamp) and NTP (absolute timestamp) for inbound packets.

Server Capabilities

• Security: Supports RTSPS, SRTP, and SRTCP.
• Tunneling: Supports RTSP-over-HTTP and RTSP-over-WebSocket.
• Client Handling: Validates credentials and handles requests from clients.
• Media Handling: Can read streams from clients ("record") and serve streams to clients ("play"). It can compute SSRC and RTP-Info and read ONVIF back channels.

Utilities

• Parses RTSP elements.
• Encodes/decodes RTP packets into/from codec-specific frames.

To customize the behavior of a gortsplib server, you can implement one or more of the ServerHandler interfaces. The library uses a modular interface approach where you only need to implement the specific lifecycle or request methods you are interested in.

Commonly used interfaces include:

• ServerHandlerOnConnOpen / ServerHandlerOnConnClose: Handle connection-level events.
• ServerHandlerOnSessionOpen / ServerHandlerOnSessionClose: Handle RTSP session lifecycle.
• ServerHandlerOnDescribe: Handle DESCRIBE requests (must return a *base.Response and *ServerStream).
• ServerHandlerOnSetup: Handle SETUP requests (must return a *base.Response and *ServerStream).
• ServerHandlerOnPlay / ServerHandlerOnPause / ServerHandlerOnRecord: Handle media control requests.
• ServerHandlerOnPacketsLost: Handle notifications when the server detects lost packets.
• ServerHandlerOnDecodeError: Handle non-fatal decoding errors.

Each method receives a specific context struct (e.g., ServerHandlerOnDescribeCtx) containing the relevant metadata like the Conn, Session, Request, Path, and Query.

type myHandler struct{}

// Handle DESCRIBE requests
func (h *myHandler) OnDescribe(ctx *gortsplib.ServerHandlerOnDescribeCtx) (*base.Response, *gortsplib.ServerStream, error) {
	// Return your response and the stream for the client
	return &base.Response{StatusCode: base.StatusOK}, nil, nil
}

// Handle PLAY requests
func (h *myHandler) OnPlay(ctx *gortsplib.ServerHandlerOnPlayCtx) (*base.Response, error) {
	// Logic for starting playback
	return &base.Response{StatusCode: base.StatusOK}, nil
}

The serverSessionFormat manages the lifecycle of RTP packets for a specific media format during a RTSP session. It handles two primary directions:

Inbound RTP (Receiving)

When packets are received via readPacketRTP:

1. SSRC Validation: The first packet received sets the expected remoteSSRC. Subsequent packets are checked against this SSRC. If encryption (SRTP) is enabled, a mismatch triggers a decode error.
2. Decoding: The payload is decoded using the session's media decoder.
3. Receiver Processing: Packets are passed to an rtpreceiver.Receiver to track sequence numbers, jitter, and packet loss.
4. Loss Notification: If packet loss is detected, the server triggers the OnPacketsLost handler if the session handler implements ServerHandlerOnPacketsLost.
5. Callback: Validated packets are passed to the onPacketRTP callback.

Outbound RTP (Sending)

When packets are sent via writePacketRTP:

1. SSRC Assignment: The packet's SSRC is set to the localSSRC.
2. Encryption: If SRTP is configured (srtpOutCtx is present), the packet is encrypted.
3. Sender Processing: The packet is passed to an rtpsender.Sender to manage sequence numbers and timing.
4. Queueing: The payload is pushed to the session's writer queue. If the queue is full, it returns liberrors.ErrServerWriteQueueFull.
5. Transport: Depending on the session protocol, packets are written via UDP (writePacketRTPInQueueUDP) or interleaved TCP (writePacketRTPInQueueTCP).

The Server struct is the main entrypoint for an RTSP server. You must provide at least the RTSPAddress. You can optionally configure UDP transport (RTP/RTCP), multicast support, TLS, and authentication methods.

Key Configuration Options

• RTSPAddress: The address to accept TCP connections (e.g., ":8554").
• UDPRTPAddress & UDPRTCPAddress: Required together to enable UDP transport. The RTP port must be even, and the RTCP port must be the consecutive odd port (e.g., RTP: ":8000", RTCP: ":8001").
• MulticastIPRange, MulticastRTPPort, & MulticastRTCPPort: Required together to enable UDP-multicast. The RTP port must be even and RTCP must be consecutive.
• TLSConfig: Provide a *tls.Config to enable RTSPS (TLS).
• AuthMethods: A slice of auth.VerifyMethod. Defaults to auth.VerifyMethodBasic and auth.VerifyMethodDigestMD5 if not specified.
• Handler: An optional ServerHandler to react to server events.

Lifecycle Methods

• Start(): Initializes listeners and starts the server loop in a background goroutine.
• StartAndWait(): Starts the server and blocks until a fatal error occurs or the server is closed.
• Close(): Gracefully shuts down the server and waits for all resources to exit.
• Wait(): Blocks until the server has finished shutting down (either via Close() or a fatal error).

server := &gortsplib.Server{
	RTSPAddress:    ":8554",
	UDPRTPAddress:  ":8000",
	UDPRTCPAddress: ":8001",
}

// Start and block until error
err := server.StartAndWait()
if err != nil {
	panic(err)
}