RTSPAudioStreamerUsingTask - Task-driven RTP Audio Streaming Engine. More...

#include <RTSPAudioStreamer.h>

Inheritance diagram for RTSPAudioStreamerUsingTask< Platform >:

Public Member Functions
	RTSPAudioStreamerUsingTask (bool throttled=true)
	Default constructor for RTSPAudioStreamerUsingTask.

	RTSPAudioStreamerUsingTask (IAudioSource &source, bool throttled=true)
	Constructor with audio source and throttling control.

virtual	~RTSPAudioStreamerUsingTask ()
	Destructor.

bool	checkTimerPeriodChange ()
	Check if timer period has changed and update if necessary.

uint32_t	currentRtpTimestamp () const
	Get current RTP timestamp value that will be used in the next packet.

uint16_t	currentSeq () const
	Get current RTP sequence number that will be used in the next packet.

uint32_t	currentSsrc () const
	Get current SSRC used in RTP header.

IAudioSource *	getAudioSource ()
	Get the configured audio source.

u_short	getRtcpServerPort ()
	Get the RTCP server port number.

u_short	getRtpServerPort ()
	Get the RTP server port number.

uint32_t	getTimerPeriodMs () const
	Get the timer period in milliseconds.

uint32_t	getTimerPeriodUs () const
	Get the timer period in microseconds.

bool	initAudioSource ()
	Initialize audio source configuration.

void	initTcpInterleavedTransport (typename Platform::TcpClientType *tcpSock, int rtpChannel, int rtcpChannel)
	Initialize TCP interleaved transport for RTP over RTSP.

bool	initUdpTransport (IPAddress aClientIP, uint16_t aClientPort)
	Initialize UDP transport for RTP streaming.

bool	isTaskRunning () const
	Check if streaming task is currently running.

void	releaseUdpTransport (void)
	Release UDP transport resources.

int	sendRtpPacketDirect ()
	Send a single RTP packet with audio data.

virtual void	setAudioSource (IAudioSource *source)
	Configure the audio source for streaming.

void	setFixedDelayMs (uint32_t delayUs)
	Set a fixed inter-packet delay in non-throttled mode.

void	setTaskParameters (uint32_t stackSize, uint8_t priority, int core=-1)
	Set task parameters for streaming task.

void	setThrottled (bool isThrottled)
	Enable or disable throttled timing mode.

void	setThrottleInterval (uint32_t interval)
	Set the throttle interval (number of sends before precise correction)

void	start () override
	Start task-driven RTP streaming.

void	stop () override
	Stop task-driven RTP streaming.

Static Public Member Functions
static void	timerCallback (void *audioStreamerObj)
	Static timer callback function for periodic RTP streaming.

Protected Member Functions
void	applyThrottling (unsigned long iterationStartUs)
	Apply streaming throttling policy.

void	buildRtpHeader ()

uint32_t	computeTimestampIncrement (int bytesSent)
	Compute RTP timestamp increment based on samples sent.

void	sendOut (uint16_t totalLen)

void	streamingTaskLoop ()
	Main streaming task loop iteration.

Protected Attributes
const int	HEADER_SIZE = 12

IAudioSource *	m_audioSource = nullptr

IPAddress	m_ClientIP

uint16_t	m_ClientPort

uint16_t	m_fixed_delay_ms = 1
	Fixed delay in milliseconds (if used)

int	m_fragmentSize = 0

unsigned long	m_last_throttle_us
	Start timestamp of current throttle window (micros)

int	m_lastSamplesSent = 0

int	m_payloadType = 96

uint32_t	m_prevMsec

uint16_t	m_RtcpServerPort

Platform::UdpSocketType *	m_RtcpSocket

uint16_t	m_RtpServerPort

Platform::UdpSocketType *	m_RtpSocket

Platform::TcpClientType *	m_RtspTcpSocket

uint32_t	m_send_counter
	Counts sends within the current throttle window.

int	m_SendIdx

u_short	m_SequenceNumber

uint32_t	m_Ssrc = 0x13F97E67

audio_tools::Task	m_streamingTask
	AudioTools task for streaming loop.

int	m_taskCore = -1
	CPU core affinity (-1 = any core)

uint8_t	m_taskPriority = 5
	Task priority (5 = medium priority)

volatile bool	m_taskRunning
	Flag indicating if task is active.

uint32_t	m_taskStackSize = 8192
	Task stack size in bytes (8KB default)

int	m_TcpRtcpChannel

int	m_TcpRtpChannel

uint32_t	m_throttle_interval
	Number of sends before precise correction.

bool	m_throttled = true
	Enable precise microsecond timing.

int	m_timer_period_us = 20000

volatile bool	m_timer_restart_needed

uint32_t	m_Timestamp

int	m_udpRefCount

bool	m_useTcpInterleaved

audio_tools::Vector< uint8_t >	mMp3Carry

int	mMp3CarryLen = 0

audio_tools::Vector< uint8_t >	mRtpBuf

const int	STREAMING_BUFFER_SIZE = 1024 * 3

Detailed Description

template<typename Platform>
class audio_tools::RTSPAudioStreamerUsingTask< Platform >

RTSPAudioStreamerUsingTask - Task-driven RTP Audio Streaming Engine.

The RTSPAudioStreamerUsingTask class extends RTSPAudioStreamerBase with AudioTools Task-driven streaming functionality. Instead of using hardware timers, this class creates a dedicated task that continuously calls the timer callback at the appropriate intervals. This approach provides:

All base class functionality (audio source, UDP transport, RTP packets)
Task-based periodic streaming using AudioTools Task class
More predictable scheduling compared to hardware timers
Better resource control and priority management
Reduced timer resource usage
Optional throttling for timing control

The throttling feature is particularly important when working with audio sources that can provide data faster than the defined sampling rate, such as file readers, buffer sources, or fast generators. Without throttling, these sources would flood the network with packets faster than real-time playback.

Technical Details

Inherits all base class functionality
Uses AudioTools Task class for periodic packet transmission
Configurable task priority, stack size, and CPU core affinity
Optional throttling with microsecond precision timing
Clean task lifecycle management with proper cleanup

Note: Useful when hardware timers are limited or need different scheduling; Requires FreeRTOS support (ESP32, etc.); Throttled mode provides more accurate timing but uses more CPU

Author: Thomas Pfitzinger

Version: 0.2.0

Constructor & Destructor Documentation

◆ RTSPAudioStreamerUsingTask() [1/2]

template<typename Platform >

RTSPAudioStreamerUsingTask ( bool throttled = true )

inline

Default constructor for RTSPAudioStreamerUsingTask.

Creates a new RTSPAudioStreamerUsingTask instance with task functionality. Initializes the base class and sets default task parameters.

Parameters

throttled Enable precise timing control with microsecond delays. Set to true when your audio source provides data faster than the defined sampling rate (e.g., reading from files, buffers, or fast generators). Set to false when the source naturally produces data at the correct rate (e.g., ADC, microphone input, or rate-limited streams). Default: false for better performance.

Note: Audio source must be set using setAudioSource() before streaming

See also: setAudioSource(), setTaskParameters()

◆ RTSPAudioStreamerUsingTask() [2/2]

template<typename Platform >

RTSPAudioStreamerUsingTask	(	IAudioSource &	source,
		bool	throttled = `true`
	)

inline

Constructor with audio source and throttling control.

Creates a new RTSPAudioStreamerUsingTask instance with task functionality and immediately configures it with the specified audio source.

Parameters

source	Reference to an object implementing the IAudioSource interface. The source provides audio data and format information.
throttled	Enable precise timing control with microsecond delays. Set to true when your audio source provides data faster than the defined sampling rate (e.g., reading from files, buffers, or fast generators). Set to false when the source naturally produces data at the correct rate (e.g., ADC, microphone input, or rate-limited streams). Default: false for better performance.

Note: The audio source object must remain valid for the lifetime of the streamer

See also: IAudioSource, setTaskParameters()

◆ ~RTSPAudioStreamerUsingTask()

template<typename Platform >

virtual ~RTSPAudioStreamerUsingTask ( )

inlinevirtual

Destructor.

Ensures the streaming task is properly stopped and cleaned up.

Member Function Documentation

◆ applyThrottling()

template<typename Platform >

void applyThrottling ( unsigned long iterationStartUs )

inlineprotected

Apply streaming throttling policy.

Implements the two-stage throttling:

Always delay by m_fixed_delay_ms after each send
Every m_throttle_interval sends, precisely correct drift to match m_timer_period_us pacing

Resets the throttle window if the source format changes.

Parameters

iterationStartUs Start timestamp of this loop iteration (micros)

◆ checkTimerPeriodChange()

template<typename Platform >

bool checkTimerPeriodChange ( )

inlineinherited

Check if timer period has changed and update if necessary.

Checks the audio source format for timer period changes and updates the cached value if different. This enables dynamic timer period adjustments during playback when the audio format changes.

Returns: true if timer period changed, false if unchanged or no audio source

Note: Call this periodically to detect format changes during streaming

See also: updateTimerPeriod()

◆ computeTimestampIncrement()

template<typename Platform >

uint32_t computeTimestampIncrement ( int bytesSent )

inlineprotectedinherited

Compute RTP timestamp increment based on samples sent.

Calculates the appropriate RTP timestamp increment based on the number of audio samples sent in the last packet. This ensures proper timing and synchronization in the RTP stream.

Parameters

bytesSent Number of bytes sent in the last RTP packet

Returns: Calculated timestamp increment value

Note: Uses exact samples sent if available, otherwise falls back to audio source format or a crude estimate

◆ currentRtpTimestamp()

template<typename Platform >

uint32_t currentRtpTimestamp ( ) const

inlineinherited

Get current RTP timestamp value that will be used in the next packet.

Returns: Current RTP timestamp

◆ currentSeq()

template<typename Platform >

uint16_t currentSeq ( ) const

inlineinherited

Get current RTP sequence number that will be used in the next packet.

Returns: Current RTP sequence number

◆ getAudioSource()

template<typename Platform >

IAudioSource * getAudioSource ( )

inlineinherited

Get the configured audio source.

Returns: Pointer to the current audio source, nullptr if not set

See also: setAudioSource()

◆ getRtcpServerPort()

template<typename Platform >

u_short getRtcpServerPort ( )

inlineinherited

Get the RTCP server port number.

Returns: Port number used for RTCP communication, 0 if not initialized

See also: initUdpTransport()

◆ getRtpServerPort()

template<typename Platform >

u_short getRtpServerPort ( )

inlineinherited

Get the RTP server port number.

Returns: Port number used for RTP packet transmission, 0 if not initialized

See also: initUdpTransport()

◆ getTimerPeriodMs()

template<typename Platform >

uint32_t getTimerPeriodMs ( ) const

inlineinherited

Get the timer period in milliseconds.

Returns: Timer period in milliseconds for convenience

See also: getTimerPeriodUs()

◆ getTimerPeriodUs()

template<typename Platform >

uint32_t getTimerPeriodUs ( ) const

inlineinherited

Get the timer period in microseconds.

Returns: Timer period configured from audio source format

See also: initAudioSource()

◆ initAudioSource()

template<typename Platform >

bool initAudioSource ( )

inlineinherited

Initialize audio source configuration.

Extracts and caches configuration parameters from the audio source including fragment size (bytes per packet) and timer period (microseconds between packets). This method must be called before streaming can begin.

Returns: true if initialization succeeded, false if audio source or format is invalid

Note: Fragment size determines how much audio data is sent per RTP packet; Timer period controls the streaming rate and must match the audio sample rate

◆ initTcpInterleavedTransport()

template<typename Platform >

void initTcpInterleavedTransport	(	typename Platform::TcpClientType *	tcpSock,
		int	rtpChannel,
		int	rtcpChannel
	)

inlineinherited

Initialize TCP interleaved transport for RTP over RTSP.

Configures the streamer to send RTP packets using RTSP TCP interleaving. RTP and RTCP packets are framed with '$', channel byte, and 2-byte length per RFC 2326 section 10.12 and sent over the RTSP control socket.

Parameters

tcpSock	Pointer to the RTSP TCP client socket
rtpChannel	Interleaved channel number for RTP packets (e.g., 0)
rtcpChannel	Interleaved channel number for RTCP packets (e.g., 1)

◆ initUdpTransport()

template<typename Platform >

bool initUdpTransport	(	IPAddress	aClientIP,
		uint16_t	aClientPort
	)

inlineinherited

Initialize UDP transport for RTP streaming.

Sets up UDP sockets for RTP and RTCP communication with a specific client. Automatically allocates consecutive port pairs starting from 6970. Supports multiple clients through reference counting - subsequent calls with different clients will reuse existing sockets.

Parameters

aClientIP	IP address of the RTP client that will receive the stream
aClientPort	Port number on the client for receiving RTP packets

Returns: true if transport initialization succeeded, false on socket creation failure

Note: Port allocation: RTP uses even ports (6970, 6972, ...), RTCP uses odd ports (6971, 6973, ...); Call releaseUdpTransport() when streaming to this client is complete

See also: releaseUdpTransport(), getRtpServerPort(), getRtcpServerPort()

◆ isTaskRunning()

template<typename Platform >

bool isTaskRunning ( ) const

inline

Check if streaming task is currently running.

Returns: true if task is active and streaming, false otherwise

◆ releaseUdpTransport()

template<typename Platform >

void releaseUdpTransport ( void )

inlineinherited

Release UDP transport resources.

Decrements the reference count for UDP socket usage and closes sockets when no more clients are using them. This implements proper resource management for multiple concurrent streaming sessions.

Note: Only closes sockets when reference count reaches zero; Always call this method when streaming to a client is complete

See also: initUdpTransport()

◆ sendRtpPacketDirect()

template<typename Platform >

int sendRtpPacketDirect ( )

inlineinherited

Send a single RTP packet with audio data.

Constructs and sends one RTP packet containing audio data from the configured source. This method handles the complete RTP packet creation process including:

RTP header construction with sequence numbers and timestamps
Audio data retrieval from the source
Network byte order conversion
UDP transmission to the configured client

Returns: Number of bytes sent in the packet payload, or negative value on error

Return values

-1	RTP buffer not allocated or audio source not configured

Note: This method is typically called periodically by the timer-driven streaming; Automatically increments sequence numbers and updates timestamps

See also: start(), timerCallback()

◆ setAudioSource()

template<typename Platform >

virtual void setAudioSource ( IAudioSource * source )

inlinevirtualinherited

Configure the audio source for streaming.

Sets or changes the audio source that provides data for the RTP stream. This method automatically initializes the audio source configuration including fragment size and timer period based on the source's format specifications.

Parameters

source Pointer to an IAudioSource implementation. Must not be nullptr.

Note: Calling this method will reinitialize audio source parameters

See also: IAudioSource, initAudioSource()

◆ setFixedDelayMs()

template<typename Platform >

void setFixedDelayMs ( uint32_t delayUs )

inline

Set a fixed inter-packet delay in non-throttled mode.

Disables microsecond-level throttling and applies a constant delay between iterations of the streaming task using delay(). This is useful when the audio source is naturally rate-limited and a small cooperative sleep is sufficient to avoid busy looping.

Parameters

delayUs Fixed delay in milliseconds applied via delay().

Note: Calling this method sets throttled mode to false.

See also: setThrottled(bool)

◆ setTaskParameters()

template<typename Platform >

void setTaskParameters	(	uint32_t	stackSize,
		uint8_t	priority,
		int	core = `-1`
	)

inline

Set task parameters for streaming task.

Configure the AudioTools Task parameters before starting streaming. These parameters control the task's resource usage and scheduling behavior. Must be called before start() to take effect.

Parameters

stackSize	Stack size in bytes for the streaming task (default: 8192) Increase if experiencing stack overflow issues
priority	Task priority (0-configMAX_PRIORITIES-1, default: 5) Higher values = higher priority. Use with caution.
core	CPU core to pin task to (default: -1 for any core) ESP32 only: 0 or 1 for specific core, -1 for automatic

Note: Higher priority tasks can starve lower priority tasks; Core pinning can improve performance but reduces scheduling flexibility

Warning: Cannot change parameters while streaming is active

◆ setThrottled()

template<typename Platform >

void setThrottled ( bool isThrottled )

inline

Enable or disable throttled timing mode.

Throttled mode provides more precise timing by using microsecond-level delays, but consumes more CPU resources. This is essential when your audio source can provide data faster than the defined sampling rate.

When to enable throttling (isThrottled = true):

Audio source reads from files, buffers, or memory
Fast audio generators that can produce data instantly
Sources that don't naturally limit their data rate
When precise timing is critical for synchronization

When to disable throttling (isThrottled = false):

Real-time sources like ADC or microphone input
Sources that naturally produce data at the correct rate
Battery-powered devices where CPU efficiency is important
Rate-limited streams or network sources

Parameters

isThrottled true to enable precise timing with delays, false for efficient timing

Note: Can be changed while streaming is active; Throttled mode uses more CPU but prevents audio data overrun; Non-throttled mode is more efficient but requires rate-limited sources

◆ setThrottleInterval()

template<typename Platform >

void setThrottleInterval ( uint32_t interval )

inline

Set the throttle interval (number of sends before precise correction)

After each packet send, the streamer delays by a fixed millisecond value. After interval sends, it applies a precise microsecond correction based on the expected elapsed time (interval * timerPeriodUs) versus the actual elapsed time, then resets the interval window.

Parameters

interval Number of sends per throttle window (e.g., 1000 or 10000)

◆ start()

template<typename Platform >

void start ( )

inlineoverridevirtual

Start task-driven RTP streaming.

Begins the RTP streaming process by:

Calling base class start() to initialize audio source and buffer
Creating an AudioTools Task for periodic streaming
Beginning task-driven packet transmission

Note: UDP transport must be initialized before calling this method; Audio source must be configured before calling this method

Warning: Will log errors if audio source is not properly configured

See also: stop(), initUdpTransport(), setAudioSource()

Reimplemented from RTSPAudioStreamerBase< Platform >.

◆ stop()

template<typename Platform >

void stop ( )

inlineoverridevirtual

Stop task-driven RTP streaming.

Stops the RTP streaming process by:

Signaling the streaming task to stop
Ending the AudioTools Task
Calling base class stop() to stop the audio source

Note: Does not release UDP transport or buffers - use releaseUdpTransport() separately; Can be restarted by calling start() again

See also: start(), releaseUdpTransport()

Reimplemented from RTSPAudioStreamerBase< Platform >.

◆ streamingTaskLoop()

template<typename Platform >

void streamingTaskLoop ( )

inlineprotected

Main streaming task loop iteration.

This method contains a single iteration of the streaming loop that is called continuously by the AudioTools Task. Each iteration:

Records start time for performance monitoring
Checks for timer period changes and adjusts if needed
Calls the timer callback to send one RTP packet
Optionally applies throttling delay for precise timing

The task runs in its own context using the AudioTools Task class and handles timing based on the throttling mode setting. Dynamic timer period changes are handled seamlessly within the task loop.

Note: This method is called repeatedly by the task framework; Performance is monitored when throttling is enabled

See also: timerCallback(), checkTimerPeriodChange()

◆ timerCallback()

template<typename Platform >

static void timerCallback ( void * audioStreamerObj )

inlinestaticinherited

Static timer callback function for periodic RTP streaming.

This static method is called periodically by timers to send RTP packets. It handles timing measurements and calls sendRtpPacketDirect() to transmit audio data. Performance monitoring ensures the streaming keeps up with real-time requirements.

This method can be used by any derived class that implements timer-driven streaming functionality.

Parameters

audioStreamerObj Void pointer to the RTSPAudioStreamerBase instance (passed as callback parameter)

Note: This is a static method suitable for use as a timer callback; Logs warnings if packet transmission takes too long

See also: sendRtpPacketDirect()

Member Data Documentation

◆ m_last_throttle_us

template<typename Platform >

unsigned long m_last_throttle_us

protected

Initial value:

=

0

Start timestamp of current throttle window (micros)

◆ m_send_counter

template<typename Platform >

uint32_t m_send_counter

protected

Initial value:

=

0

Counts sends within the current throttle window.

◆ m_throttle_interval

template<typename Platform >

uint32_t m_throttle_interval

protected

Initial value:

=

1000

Number of sends before precise correction.

◆ m_timer_restart_needed

template<typename Platform >

volatile bool m_timer_restart_needed

protectedinherited

Initial value:

=

false

The documentation for this class was generated from the following file:

src/AudioTools/Communication/RTSP/RTSPAudioStreamer.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Technical Details

Constructor & Destructor Documentation

◆ RTSPAudioStreamerUsingTask() [1/2]

◆ RTSPAudioStreamerUsingTask() [2/2]

◆ ~RTSPAudioStreamerUsingTask()

Member Function Documentation

◆ applyThrottling()

◆ checkTimerPeriodChange()

◆ computeTimestampIncrement()

◆ currentRtpTimestamp()

◆ currentSeq()

◆ getAudioSource()

◆ getRtcpServerPort()

◆ getRtpServerPort()

◆ getTimerPeriodMs()

◆ getTimerPeriodUs()

◆ initAudioSource()

◆ initTcpInterleavedTransport()

◆ initUdpTransport()

◆ isTaskRunning()

◆ releaseUdpTransport()

◆ sendRtpPacketDirect()

◆ setAudioSource()

◆ setFixedDelayMs()

◆ setTaskParameters()

◆ setThrottled()

◆ setThrottleInterval()

◆ start()

◆ stop()

◆ streamingTaskLoop()

◆ timerCallback()

Member Data Documentation

◆ m_last_throttle_us

◆ m_send_counter

◆ m_throttle_interval

◆ m_timer_restart_needed