Efficient RTSP client for UDP/RTP audio with decoder pipeline. More...

#include <RTSPClient.h>

Inheritance diagram for RTSPClient< TcpClient, UdpSocket >:

Public Member Functions
	RTSPClient ()

	RTSPClient (AudioOutput &out)
	Construct with an AudioOutput as decoding sink.

	RTSPClient (AudioStream &out)
	Construct with an AudioStream as decoding sink.

	RTSPClient (Print &out)
	Construct with a generic Print sink.

void	addDecoder (const char *mimeType, AudioDecoder &decoder)
	Register a decoder to be auto-selected for the given MIME.

void	addNotifyAudioChange (AudioInfoSupport &bi) override
	Adds target to be notified about audio changes.

AudioInfo	audioInfo () override
	Audio info parsed from SDP for raw PCM encodings.

virtual AudioInfo	audioInfoOut ()

int	available ()
	Returns buffered RTP payload bytes available for copy().

bool	begin (IPAddress addr, uint16_t port, const char *path=nullptr)
	Start RTSP session and UDP RTP reception.

void	clearNotifyAudioChange () override
	Deletes all change notify subscriptions.

size_t	copy ()
	Copy the next buffered RTP payload into the decoder pipeline. Performs initial decoder selection based on SDP MIME.

void	end ()
	Stop streaming and close RTSP/UDP sockets.

bool	isNotifyActive ()

const char *	mime () const
	Best-effort MIME derived from SDP (e.g. audio/L16, audio/aac).

	operator bool ()

uint8_t	payloadType () const
	RTP payload type from SDP (0xFF if unknown).

bool	removeNotifyAudioChange (AudioInfoSupport &bi) override
	Removes a target in order not to be notified about audio changes.

bool	setActive (bool active)
	Pause or resume playback via RTSP PAUSE/PLAY.

void	setAudioInfo (AudioInfo info) override
	Defines the input AudioInfo.

void	setConnectRetries (uint8_t retries)
	Set number of TCP connect retries (default 2).

void	setConnectRetryDelayMs (uint32_t ms)
	Set delay between connect retries in ms (default 500ms).

void	setHeaderTimeoutMs (uint32_t ms)
	Set timeout (ms) for reading RTSP response headers. Increase if your server responds slowly. Default 3000ms.

void	setIdleDelay (uint32_t ms)
	Set idle backoff delay (ms) for zero-return cases. Used in available() and copy() to avoid busy loops.

void	setNotifyActive (bool flag)

void	setOutput (AudioOutput &out)
	Define decoding sink as AudioOutput.

void	setOutput (AudioStream &out)
	Define decoding sink as AudioStream.

void	setOutput (Print &out)
	Define decoding sink as Print.

void	setPayloadOffset (uint8_t bytes)
	Set additional RTP payload offset in bytes. Some payloads embed a small header before the actual audio data (e.g., RFC2250 4-byte header for MP3). This offset is added after the RTP header and any CSRC entries.

void	setResampleFactor (float factor)
	Set resampling factor to stabilize buffers and playback. 1.0 means no resampling. factor > 1.0 speeds up (upsamples), factor < 1.0 slows down (downsamples). Useful to compensate clock drift between sender and receiver to prevent buffer overflows/underflows. Internally mapped to step size as step = 1.0 / factor.

Protected Member Functions
void	buildTrackUrlFromBaseAndControl ()

void	buildUrls (const char *path)

size_t	computeRtpPayloadOffset (const uint8_t *data, size_t length)

bool	fail (const char *msg)

bool	isAbsoluteRtspUrl (const char *url)

void	maybeKeepalive ()

void	notifyAudioChange (AudioInfo info)

bool	openUdpPorts ()

void	parseContentBaseFromHeaders (const char *headers)

void	parseControlFromSdp (const char *sdp)

void	parseSdp (const char *sdp)

void	parseServerPortsFromHeaders (const char *headers)

void	parseSessionFromHeaders (const char *headers)

void	primeUdpPath ()

int	readExact (uint8_t *out, int len, uint32_t timeoutMs)

bool	readUntilDoubleCRLF (char *buf, size_t buflen, int &used, uint32_t timeoutMs=3000)

void	resetState ()

bool	sendSimpleRequest (const char method, const char url, const char extraHeaders, size_t extraLen, char outHeaders, size_t outHeadersLen, char *outBody, size_t outBodyLen, bool quiet=false)

void	serviceUdp ()

bool	sniffUdpFor (uint32_t ms)

bool	tcpCommit ()

size_t	tcpWrite (const uint8_t *data, size_t len)

Static Protected Member Functions
static int	parseContentLength (const char *headers)

Protected Attributes
bool	is_notify_active = true

IPAddress	m_addr {}

char	m_baseUrl [96] = {0}

char	m_bodyBuf [1024]

uint16_t	m_clientRtpPort = 0

uint8_t	m_connectRetries = 2

uint32_t	m_connectRetryDelayMs = 500

char	m_contentBase [160] = {0}

uint32_t	m_cseq = 1

DecoderL8	m_decoder_l8

DecoderNetworkFormat	m_decoder_net

bool	m_decoderReady = false

char	m_encoding [32] = {0}

char	m_hdrBuf [1024]

uint32_t	m_headerTimeoutMs = 4000

uint32_t	m_idleDelayMs = 10

AudioInfo	m_info {0, 0, 0}

bool	m_isPlaying = false

const uint32_t	m_keepaliveIntervalMs = 25000

uint32_t	m_lastKeepaliveMs = 0

MultiDecoder	m_multi_decoder

uint8_t	m_payloadOffset = 0

uint8_t	m_payloadType = 0xFF

SingleBuffer< uint8_t >	m_pktBuf {0}

uint16_t	m_port = 0

ResampleStream	m_resampler

float	m_resampleStep = 1.0f

char	m_sdpControl [128] = {0}

uint16_t	m_serverRtpPort = 0

char	m_sessionId [64] = {0}

bool	m_started = false

TcpClient	m_tcp

SingleBuffer< uint8_t >	m_tcpCmd {0}

char	m_trackUrl [128] = {0}

UdpSocket	m_udp

bool	m_udp_active = false

Vector< AudioInfoSupport * >	notify_vector

Detailed Description

template<typename TcpClient, typename UdpSocket>
class audio_tools::RTSPClient< TcpClient, UdpSocket >

Efficient RTSP client for UDP/RTP audio with decoder pipeline.

Establishes an RTSP session (OPTIONS, DESCRIBE, SETUP/UDP, PLAY), binds a local UDP RTP port and receives RTP audio packets. The payload of each RTP packet is forwarded to an internal MultiDecoder. For raw PCM over RTP (e.g. L16) a DecoderNetworkFormat is used to convert network byte order into host format before writing to the configured output. For compressed formats, register decoders with addDecoder().

Usage:

Construct and set an output via setOutput()
Call begin(address, port)
In your loop, call copy() to push RTP payloads to decoders
Optionally control streaming via setActive(true/false)
Optionally define resampling factor to prevent buffer over/underflows

Template parameters:

TcpClient: TCP client type (e.g: WiFiClient)
UdpSocket: UDP socket type (e.g: WiFiUDP)

Author: Phil Schatzmann

Constructor & Destructor Documentation

◆ RTSPClient() [1/4]

template<typename TcpClient , typename UdpSocket >

RTSPClient ( )

inline

◆ RTSPClient() [2/4]

template<typename TcpClient , typename UdpSocket >

RTSPClient ( AudioOutput & out )

inline

Construct with an AudioOutput as decoding sink.

◆ RTSPClient() [3/4]

template<typename TcpClient , typename UdpSocket >

RTSPClient ( AudioStream & out )

inline

Construct with an AudioStream as decoding sink.

◆ RTSPClient() [4/4]

template<typename TcpClient , typename UdpSocket >

RTSPClient ( Print & out )

inline

Construct with a generic Print sink.

Member Function Documentation

◆ addDecoder()

template<typename TcpClient , typename UdpSocket >

void addDecoder	(	const char *	mimeType,
		AudioDecoder &	decoder
	)

inline

Register a decoder to be auto-selected for the given MIME.

Parameters

mimeType	MIME to match
decoder	AudioDecoder instance handling that MIME

◆ addNotifyAudioChange()

template<typename TcpClient , typename UdpSocket >

void addNotifyAudioChange ( AudioInfoSupport & bi )

inlineoverridevirtual

Adds target to be notified about audio changes.

Reimplemented from AudioInfoSource.

◆ audioInfo()

template<typename TcpClient , typename UdpSocket >

AudioInfo audioInfo ( )

inlineoverridevirtual

Audio info parsed from SDP for raw PCM encodings.

Returns: AudioInfo or default-constructed if not PCM.

Implements AudioInfoSupport.

◆ audioInfoOut()

virtual AudioInfo audioInfoOut ( )

inlinevirtualinherited

provides the actual output AudioInfo: this is usually the same as audioInfo() unless we use a transforming stream

Reimplemented in PureDataStream, PWMAudioOutput, ChannelFormatConverterStreamT< T >, ChannelFormatConverterStream, NumberFormatConverterStreamT< TFrom, TTo >, NumberFormatConverterStream, FormatConverterStream, Pipeline, ResampleStream, and ResampleStreamT< TInterpolator >.

◆ available()

template<typename TcpClient , typename UdpSocket >

int available ( )

inline

Returns buffered RTP payload bytes available for copy().

◆ begin()

template<typename TcpClient , typename UdpSocket >

bool begin	(	IPAddress	addr,
		uint16_t	port,
		const char *	path = `nullptr`
	)

inline

Start RTSP session and UDP RTP reception.

Parameters

addr	RTSP server IP address
port	RTSP server port (typically 554)
path	Optional path appended to the RTSP URL (e.g. "stream1"). If provided, the base URL becomes rtsp://<ip>:<port>/<path>/

Returns: true on success

◆ buildTrackUrlFromBaseAndControl()

template<typename TcpClient , typename UdpSocket >

void buildTrackUrlFromBaseAndControl ( )

inlineprotected

◆ buildUrls()

template<typename TcpClient , typename UdpSocket >

void buildUrls ( const char * path )

inlineprotected

◆ clearNotifyAudioChange()

template<typename TcpClient , typename UdpSocket >

void clearNotifyAudioChange ( )

inlineoverridevirtual

Deletes all change notify subscriptions.

Reimplemented from AudioInfoSource.

◆ computeRtpPayloadOffset()

template<typename TcpClient , typename UdpSocket >

size_t computeRtpPayloadOffset	(	const uint8_t *	data,
		size_t	length
	)

inlineprotected

◆ copy()

template<typename TcpClient , typename UdpSocket >

size_t copy ( )

inline

Copy the next buffered RTP payload into the decoder pipeline. Performs initial decoder selection based on SDP MIME.

Returns: Bytes written to decoder, or 0 if none available.

◆ end()

template<typename TcpClient , typename UdpSocket >

void end ( )

inline

Stop streaming and close RTSP/UDP sockets.

◆ fail()

template<typename TcpClient , typename UdpSocket >

bool fail ( const char * msg )

inlineprotected

◆ isAbsoluteRtspUrl()

template<typename TcpClient , typename UdpSocket >

bool isAbsoluteRtspUrl ( const char * url )

inlineprotected

◆ isNotifyActive()

template<typename TcpClient , typename UdpSocket >

bool isNotifyActive ( )

inline

◆ maybeKeepalive()

template<typename TcpClient , typename UdpSocket >

void maybeKeepalive ( )

inlineprotected

◆ mime()

template<typename TcpClient , typename UdpSocket >

const char * mime ( ) const

inline

Best-effort MIME derived from SDP (e.g. audio/L16, audio/aac).

Returns: MIME string or nullptr if unknown.

◆ notifyAudioChange()

void notifyAudioChange ( AudioInfo info )

inlineprotectedinherited

◆ openUdpPorts()

template<typename TcpClient , typename UdpSocket >

bool openUdpPorts ( )

inlineprotected

◆ operator bool()

template<typename TcpClient , typename UdpSocket >

operator bool ( )

inline

returns true when streaming is active and a decoder is configured and we have data

◆ parseContentBaseFromHeaders()

template<typename TcpClient , typename UdpSocket >

void parseContentBaseFromHeaders ( const char * headers )

inlineprotected

◆ parseContentLength()

template<typename TcpClient , typename UdpSocket >

static int parseContentLength ( const char * headers )

inlinestaticprotected

◆ parseControlFromSdp()

template<typename TcpClient , typename UdpSocket >

void parseControlFromSdp ( const char * sdp )

inlineprotected

◆ parseSdp()

template<typename TcpClient , typename UdpSocket >

void parseSdp ( const char * sdp )

inlineprotected

◆ parseServerPortsFromHeaders()

template<typename TcpClient , typename UdpSocket >

void parseServerPortsFromHeaders ( const char * headers )

inlineprotected

◆ parseSessionFromHeaders()

template<typename TcpClient , typename UdpSocket >

void parseSessionFromHeaders ( const char * headers )

inlineprotected

◆ payloadType()

template<typename TcpClient , typename UdpSocket >

uint8_t payloadType ( ) const

inline

RTP payload type from SDP (0xFF if unknown).

◆ primeUdpPath()

template<typename TcpClient , typename UdpSocket >

void primeUdpPath ( )

inlineprotected

◆ readExact()

template<typename TcpClient , typename UdpSocket >

int readExact	(	uint8_t *	out,
		int	len,
		uint32_t	timeoutMs
	)

inlineprotected

◆ readUntilDoubleCRLF()

template<typename TcpClient , typename UdpSocket >

bool readUntilDoubleCRLF	(	char *	buf,
		size_t	buflen,
		int &	used,
		uint32_t	timeoutMs = `3000`
	)

inlineprotected

◆ removeNotifyAudioChange()

template<typename TcpClient , typename UdpSocket >

bool removeNotifyAudioChange ( AudioInfoSupport & bi )

inlineoverridevirtual

Removes a target in order not to be notified about audio changes.

Reimplemented from AudioInfoSource.

◆ resetState()

template<typename TcpClient , typename UdpSocket >

void resetState ( )

inlineprotected

◆ sendSimpleRequest()

template<typename TcpClient , typename UdpSocket >

bool sendSimpleRequest	(	const char *	method,
		const char *	url,
		const char *	extraHeaders,
		size_t	extraLen,
		char *	outHeaders,
		size_t	outHeadersLen,
		char *	outBody,
		size_t	outBodyLen,
		bool	quiet = `false`
	)

inlineprotected

◆ serviceUdp()

template<typename TcpClient , typename UdpSocket >

void serviceUdp ( )

inlineprotected

◆ setActive()

template<typename TcpClient , typename UdpSocket >

bool setActive ( bool active )

inline

Pause or resume playback via RTSP PAUSE/PLAY.

Parameters

active true to PLAY, false to PAUSE

Returns: true if command succeeded

◆ setAudioInfo()

template<typename TcpClient , typename UdpSocket >

void setAudioInfo ( AudioInfo info )

inlineoverridevirtual

Defines the input AudioInfo.

Implements AudioInfoSupport.

◆ setConnectRetries()

template<typename TcpClient , typename UdpSocket >

void setConnectRetries ( uint8_t retries )

inline

Set number of TCP connect retries (default 2).

◆ setConnectRetryDelayMs()

template<typename TcpClient , typename UdpSocket >

void setConnectRetryDelayMs ( uint32_t ms )

inline

Set delay between connect retries in ms (default 500ms).

◆ setHeaderTimeoutMs()

template<typename TcpClient , typename UdpSocket >

void setHeaderTimeoutMs ( uint32_t ms )

inline

Set timeout (ms) for reading RTSP response headers. Increase if your server responds slowly. Default 3000ms.

◆ setIdleDelay()

template<typename TcpClient , typename UdpSocket >

void setIdleDelay ( uint32_t ms )

inline

Set idle backoff delay (ms) for zero-return cases. Used in available() and copy() to avoid busy loops.

◆ setNotifyActive()

template<typename TcpClient , typename UdpSocket >

void setNotifyActive ( bool flag )

inline

◆ setOutput() [1/3]

template<typename TcpClient , typename UdpSocket >

void setOutput ( AudioOutput & out )

inline

Define decoding sink as AudioOutput.

◆ setOutput() [2/3]

template<typename TcpClient , typename UdpSocket >

void setOutput ( AudioStream & out )

inline

Define decoding sink as AudioStream.

◆ setOutput() [3/3]

template<typename TcpClient , typename UdpSocket >

void setOutput ( Print & out )

inline

Define decoding sink as Print.

◆ setPayloadOffset()

template<typename TcpClient , typename UdpSocket >

void setPayloadOffset ( uint8_t bytes )

inline

Set additional RTP payload offset in bytes. Some payloads embed a small header before the actual audio data (e.g., RFC2250 4-byte header for MP3). This offset is added after the RTP header and any CSRC entries.

◆ setResampleFactor()

template<typename TcpClient , typename UdpSocket >

void setResampleFactor ( float factor )

inline

Set resampling factor to stabilize buffers and playback. 1.0 means no resampling. factor > 1.0 speeds up (upsamples), factor < 1.0 slows down (downsamples). Useful to compensate clock drift between sender and receiver to prevent buffer overflows/underflows. Internally mapped to step size as step = 1.0 / factor.