RTSP¶

RTSP server classes for live stream serving. The main class is Limef::rtsp::RTSPServerThread.

namespace rtsp¶

Typedefs

using SDPLookupCallback = std::function<std::string(const std::string &url_tail)>¶

Callback type for SDP lookup.

The session doesn’t own the SDP data - it requests it via callback. Returns empty string if stream not found.

using UDPPortCallback = std::function<std::pair<int, int>(const std::string &url_tail)>¶

Callback type for getting server UDP ports.

Called during SETUP when client requests UDP transport. Returns pair of (rtp_port, rtcp_port), or (0,0) on failure.

Enums

enum class SessionState¶

RTSP session state machine states.

Values:

enumerator INIT¶: TCP connection accepted.

enumerator DESCRIBED¶: Client received the SDP.

enumerator SETUP_PARTIAL¶: Some tracks set up.

enumerator READY¶: All requested tracks set up.

enumerator PLAYING¶: Streaming active.

enumerator PAUSED¶: Streaming paused.

Functions

inline Request parseRequest(const std::string &raw)¶

Parse raw RTSP request text into Request struct.

Parameters:: raw – The raw request string from client
Returns:: Parsed Request

inline std::string extractUrlTail(const std::string &url)¶

Extract URL tail (path after host) from RTSP URL.

Parameters:: url – Full RTSP URL like rtsp://host:port/path/to/stream
Returns:: Tail like /path/to/stream

inline int extractTrackId(const std::string &url)¶

Extract track ID from URL if present.

Parameters:: url – URL like rtsp://host/stream/trackID=0
Returns:: Track ID or -1 if not found

struct ClientTrack¶

#include <rtsp.h>

Client track transport configuration.

Public Members

bool use_tcp = true¶: TCP interleaved vs UDP.

int rtp_channel = 0¶: For TCP interleaved.

int server_rtp_port = 0¶: Server’s RTP port (set by RTSPServerThread)

int server_rtcp_port = 0¶: Server’s RTCP port (set by RTSPServerThread)

struct Request¶

#include <rtsp.h>

Parsed RTSP request from client.

Public Members

std::string method¶: OPTIONS, DESCRIBE, SETUP, PLAY, etc.

std::string url¶: rtsp://host/path or rtsp://host/path/trackID=0

int cseq = 0¶: CSeq header (must echo back)

std::string session_id¶: Session header (empty until after SETUP)

std::string transport¶: Transport header (SETUP only)

std::map<std::string, std::string> headers¶: All headers.

struct RTPStream¶

#include <rtspserverthread.h>

Per-stream state.

Public Members

int slot¶: Slot number.

std::string url_tail¶: URL path like “/live/camera1”.

std::string sdp¶: Cached SDP (empty until SDPFrame arrives)

std::vector<int> session_fds¶: Socket fds of subscribed clients.

bool paused = {false}¶: When true, RTP forwarding is silently suppressed.

int udp_rtp_fd = -1¶: UDP socket for sending RTP.

int udp_rtcp_fd = -1¶: UDP socket for sending RTCP.

int udp_rtp_port = 0¶: Server’s RTP port.

int udp_rtcp_port = 0¶: Server’s RTCP port.

struct RTSPServerContext¶

#include <rtspserverthread.h>

Network settings for RTSPServerThread.

Public Members

int port = 554¶: TCP port to listen on.

std::string bind_address = {}¶: IPv4 address to bind to (e.g. “100.84.182.90”), or empty (default) to bind to 0.0.0.0 (any interface). Applies to the TCP listen socket and the per-stream UDP RTP/RTCP sockets (UDP transport mode).

class RTSPServerSignal : public Limef::signal::Signal ¶: #include <rtspserverthread.h>

Signal for RTSPServerThread control operations.

class RTSPServerThread : public Limef::thread::PollThread<Limef::frame::RTPFrame>¶

#include <rtspserverthread.h>

RTSP server thread.

Poll-based thread that:

Listens for RTSP client connections on a TCP port
Receives frames (SDPFrame, RTPFrame) from upstream
Routes RTP packets to subscribed clients

Data flow:

MediaFileThread → RTPMuxerFrameFilter → RTSPServerThread
                  (CodecFrame→SDP)       (caches SDP per slot)
                  (PacketFrame→RTP)      (routes to playing sessions)
                                              │
                              ┌───────────────┼───────────────┐
                              ▼               ▼               ▼
                         RTSPSession    RTSPSession    RTSPSession
                         (client 1)     (client 2)     (client 3)

Usage:

RTSPServerThread server("rtsp", FrameFifoContext(false, 30, 100), RTSPServerContext{8554});

// Connect callbacks
server.streamRequired.connect([&](int slot) {
    mediafile.playStream();
});
server.streamNotRequired.connect([&](int slot) {
    mediafile.stopStream();
});

server.start();
server.expose(1, "/live/camera1");  // Register stream

// ... frames flow in from upstream via server.getInput()

server.stop();

Public Functions

RTSPServerThread(std::string name, const Limef::FrameFifoContext &ctx, const RTSPServerContext &net = RTSPServerContext())¶

Construct RTSP server thread.

Parameters:

name – Thread name

ctx – FrameFifo context (default: NON-leaky, 30 frames stack, 100-frame fifo).

        IMPORTANT: the fifo MUST be non-leaky (leaky=false).
        RTP is a sequence-numbered protocol: every dropped packet creates
        a sequence-number gap that the client cannot recover from — ffplay
        and other clients will log "RTP: missed N packets" and produce
        corrupt video.  Backpressure (leaky=false) is far preferable to
        silent packet loss.

        Stack size of 50 is recommended: RTPFrames are small (~1400 bytes
        each, ~70 KB total) but an I-frame burst can produce 20-30 packets in
        rapid succession — 50 slots gives enough breathing room for I-frame bursts.

net – Network settings — port and (optionally) a bind address restricting which interface the server listens/sends on (e.g. a Tailscale IP).

void expose(int slot, const std::string &url_tail)¶

Expose a stream for clients to access.

Parameters:

slot – Slot number (must match SDPFrame/RTPFrame slot)
url_tail – URL path like “/live/camera1”

void unexpose(int slot)¶

Remove stream exposure.

Parameters:: slot – Slot number to unexpose

void pauseStream(int slot)¶

Pause RTP forwarding for a slot without tearing down client sessions.

Silently drops all incoming RTP packets for the slot. Connected clients will see a frozen stream and eventually time out and reconnect. On resume, all sessions for the slot are put back into keyframe-wait state so decoders get a clean start.

Parameters:: slot – Slot number to pause

void resumeStream(int slot)¶

Resume RTP forwarding for a previously paused slot.

Parameters:: slot – Slot number to resume

Public Members

Limef::comm::Caller<int> streamRequired¶: Emitted when first client subscribes to a slot.

Limef::comm::Caller<int> streamNotRequired¶: Emitted when last client unsubscribes from a slot.

class RTSPSession¶

#include <rtspsession.h>

Encapsulates one RTSP client connection and its state.

This class handles RTSP protocol state machine for a single client. It parses requests and generates responses, but does NOT handle socket I/O directly - that’s the responsibility of RTSPServerThread.

Example usage:

RTSPSession session("192.168.1.100");
session.setSDPLookup([&](const std::string& tail) {
    return sdp_cache_[tail];
});

// When data arrives on socket:
std::string response = session.handleRequest(raw_request);
// Send response back to client

Public Functions

explicit RTSPSession(const std::string &client_ip)¶

Construct a new session.

Parameters:: client_ip – Client’s IP address (for logging/UDP)

std::string handleRequest(const std::string &raw)¶

Process incoming RTSP request, returns response to send.

Parameters:: raw – Raw request text from client
Returns:: Response string to send back

inline void setSDPLookup(SDPLookupCallback callback)¶: Set callback for SDP lookup (used in DESCRIBE)

inline void setUDPPortCallback(UDPPortCallback callback)¶: Set callback for getting server UDP ports (used in SETUP with UDP)

inline const std::vector<ClientTrack> &getTracks() const noexcept¶: Get configured tracks for RTP delivery.

inline const std::string &getStreamTail() const noexcept¶: Get the URL tail this session is subscribed to.