OutputMixer< T > Class Template Reference

Mixing of multiple audio input streams into a single output stream. More...

#include <AudioOutput.h>

Inheritance diagram for OutputMixer< T >:

Public Member Functions
	OutputMixer (Allocator &allocator=DefaultAllocatorRAM)
	Default constructor. You must call setOutput() and setOutputCount() before use.
	OutputMixer (Print &finalOutput, int outputStreamCount, Allocator &allocator=DefaultAllocatorRAM)
	Constructor with output stream, number of input streams, and allocator.
int	available (int idx)
	Provides the available bytes in the buffer.
int	availableForWrite () override
	Provides the bytes available to write for the current stream buffer.
int	availableForWrite (int idx)
	Provides the bytes available to write for the indicated stream index.
int	availablePercent (int idx)
	Provides the % fill level of the buffer for the indicated index.
int	availableSamples ()
	Returns the minimum number of samples available across all buffers.
bool	begin (int copy_buffer_size_bytes=DEFAULT_BUFFER_SIZE)
	Starts the processing.
void	end ()
	Remove all input streams.
virtual void	flush ()
void	flushMixer ()
	Force output to final destination.
BaseBuffer< T > *	getBuffer (int idx)
	Provides the write buffer for the indicated index.
void	next ()
	Moves to the next mixing index.
void	resize (int sizeBytes)
	Resizes the buffer to the indicated number of bytes.
void	setAutoIndex (bool flag)
	Automatically increment mixing index after each write.
void	setCreateBufferCallback (BaseBuffer< T > *(*cb)(int size))
	Define callback to allocate custum buffer types.
void	setIndex (int idx)
	Sets the Output Stream index.
void	setOutput (Print &finalOutput)
	Sets the final output destination for mixed audio.
void	setOutputCount (int count)
	Sets the number of input streams to mix.
void	setWeight (int channel, float weight)
int	size ()
	Number of stremams to which are mixed together.
size_t	write (const uint8_t *data, size_t len) override
size_t	write (int idx, const uint8_t *buffer_c, size_t bytes)
	Write the data for an individual stream idx which will be mixed together.
size_t	write (uint8_t) override
	Single byte write - not supported, returns 0.
size_t	writeSilence (int idx, size_t bytes)
	Writes silence to the specified stream buffer.
size_t	writeSilence (size_t bytes)
	Writes silence to the current stream buffer.

Protected Member Functions
void	allocate_buffers (int sizeBytes)
	Allocates ring buffers for all input streams.
void	free_buffers ()
	Releases memory for all ring buffers.
void	mixSamples (size_t samples)
	Mixes the samples from all input streams into the output buffer.
void	update_total_weights ()
	Recalculates the total weights for normalization.

Static Protected Member Functions
static BaseBuffer< T > *	create_buffer (int sizeBytes, Allocator &allocator)
	Creates a default ring buffer of the specified size.

Protected Attributes
int	_timeout = 10
Allocator &	allocator
Vector< BaseBuffer< T > * >	buffers {0, DefaultAllocatorRAM}
BaseBuffer< T > *(*	create_buffer_cb )(int size, Allocator &allocator) = create_buffer
bool	is_active = false
bool	is_auto_index = true
Vector< T >	output {0, allocator}
int	output_count = 0
Print *	p_final_output = nullptr
void *	p_memory = nullptr
int	size_bytes = 0
int	stream_idx = 0
float	total_weights = 0.0
Vector< float >	weights {0, DefaultAllocatorRAM}

Detailed Description

template<typename T = int16_t>
class audio_tools::OutputMixer< T >

Mixing of multiple audio input streams into a single output stream.

The OutputMixer allows you to combine multiple audio streams by summing their samples with configurable weights per channel. Each input stream is buffered independently using ring buffers, and the mixer outputs the combined result when all buffers have sufficient data available.

Features:

• Multiple input streams with individual weight control
• Automatic or manual stream indexing for simplified writing
• Configurable buffer sizes per stream
• Real-time mixing with sample-accurate synchronization
• Memory-efficient ring buffer implementation

Auto Index Functionality: By default, auto-indexing is enabled (setAutoIndex(true)). When using the basic write() method without specifying a stream index, the mixer automatically:

1. Writes data to the current stream index (starting at 0)
2. Increments to the next stream index after each write
3. Automatically calls flushMixer() after writing to the last stream
4. Resets the index back to 0 for the next cycle

This enables simple round-robin writing where you just call write() repeatedly and the mixer handles stream distribution and output flushing automatically.

Usage Examples:

Auto Index Mode (default):

OutputMixer<int16_t> mixer(Serial, 3);  // 3 input streams to Serial output
mixer.begin(1024);                      // 1KB buffer per stream
 
// Simple round-robin writing - auto-increments stream index
mixer.write(audio_data1, length);       // -> stream 0, index = 1
mixer.write(audio_data2, length);       // -> stream 1, index = 2
mixer.write(audio_data3, length);       // -> stream 2, auto-flush, index = 0
// Process repeats automatically

Manual Index Mode:

OutputMixer<int16_t> mixer(Serial, 3);
mixer.begin(1024);
mixer.setAutoIndex(false);              // Disable auto-indexing
mixer.setWeight(0, 0.8f);              // Stream 0 at 80% volume
mixer.setWeight(1, 1.0f);              // Stream 1 at 100% volume
mixer.setWeight(2, 0.5f);              // Stream 2 at 50% volume
 
// Write data to specific streams manually
mixer.write(0, audio_data1, length);   // Write to stream 0
mixer.write(1, audio_data2, length);   // Write to stream 1
mixer.write(2, audio_data3, length);   // Write to stream 2
mixer.flushMixer();                     // Manually trigger mix and output

Note

By default uses RingBuffer as the buffer type. Buffer type can be customized using setCreateBufferCallback().

All input streams must have the same sample format (bit depth, sample rate).

The mixer normalizes output by dividing by the total weight sum.

In auto-index mode, ensure you write to all streams in each cycle for proper mixing.

Author

Phil Schatzmann

Copyright

GPLv3

Template Parameters

T	Audio sample data type (e.g., int16_t, int32_t, float)

Constructor & Destructor Documentation

OutputMixer() [1/2]

template<typename T = int16_t>

OutputMixer ( Allocator &  allocator = DefaultAllocatorRAM )

inline

Default constructor. You must call setOutput() and setOutputCount() before use.

Parameters

allocator

Reference to the allocator to use for internal buffers (default: DefaultAllocatorRAM)

OutputMixer() [2/2]

template<typename T = int16_t>

OutputMixer ( Print &  finalOutput, int  outputStreamCount, Allocator &  allocator = DefaultAllocatorRAM  )

inline

Constructor with output stream, number of input streams, and allocator.

Parameters

finalOutput	Reference to the Print object for mixed audio output
outputStreamCount	Number of input streams to mix
allocator	Reference to the allocator to use for internal buffers (default: DefaultAllocatorRAM)

Member Function Documentation

allocate_buffers()

template<typename T = int16_t>

void allocate_buffers ( int  sizeBytes )

inlineprotected

Allocates ring buffers for all input streams.

available()

template<typename T = int16_t>

int available ( int  idx )

inline

Provides the available bytes in the buffer.

availableForWrite() [1/2]

template<typename T = int16_t>

int availableForWrite ( )

inlineoverridevirtual

Provides the bytes available to write for the current stream buffer.

Reimplemented from Print.

availableForWrite() [2/2]

template<typename T = int16_t>

int availableForWrite ( int  idx )

inline

Provides the bytes available to write for the indicated stream index.

availablePercent()

template<typename T = int16_t>

int availablePercent ( int  idx )

inline

Provides the % fill level of the buffer for the indicated index.

availableSamples()

template<typename T = int16_t>

int availableSamples ( )

inline

Returns the minimum number of samples available across all buffers.

begin()

template<typename T = int16_t>

bool begin ( int  copy_buffer_size_bytes = DEFAULT_BUFFER_SIZE )

inline

Starts the processing.

create_buffer()

template<typename T = int16_t>

static BaseBuffer< T > * create_buffer ( int  sizeBytes, Allocator &  allocator  )

inlinestaticprotected

Creates a default ring buffer of the specified size.

end()

template<typename T = int16_t>

void end ( )

inline

Remove all input streams.

flush()

virtual void flush ( )

inlinevirtualinherited

Reimplemented in PureDataStream, URLStreamBufferedT< T >, URLStreamBufferedT< ICYStream >, MultiOutput, AudioOutput, AudioStreamWrapper, ResampleStream, HDLCStream, URLStream, BufferedTaskStream, I2SStream, HexDumpOutput, MemoryStream, RingBufferStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, BufferedStream, BaseStream, NamePrinter, and VFSFile.

flushMixer()

template<typename T = int16_t>

void flushMixer ( )

inline

Force output to final destination.

free_buffers()

template<typename T = int16_t>

void free_buffers ( )

inlineprotected

Releases memory for all ring buffers.

getBuffer()

template<typename T = int16_t>

BaseBuffer< T > * getBuffer ( int  idx )

inline

Provides the write buffer for the indicated index.

mixSamples()

template<typename T = int16_t>

void mixSamples ( size_t  samples )

inlineprotected

Mixes the samples from all input streams into the output buffer.

next()

template<typename T = int16_t>

void next ( )

inline

Moves to the next mixing index.

resize()

template<typename T = int16_t>

void resize ( int  sizeBytes )

inline

Resizes the buffer to the indicated number of bytes.

setAutoIndex()

template<typename T = int16_t>

void setAutoIndex ( bool  flag )

inline

Automatically increment mixing index after each write.

setCreateBufferCallback()

template<typename T = int16_t>

void setCreateBufferCallback ( BaseBuffer< T > *(*)(int size)  cb )

inline

Define callback to allocate custum buffer types.

setIndex()

template<typename T = int16_t>

void setIndex ( int  idx )

inline

Sets the Output Stream index.

setOutput()

template<typename T = int16_t>

void setOutput ( Print &  finalOutput )

inline

Sets the final output destination for mixed audio.

setOutputCount()

template<typename T = int16_t>

void setOutputCount ( int  count )

inline

Sets the number of input streams to mix.

setWeight()

template<typename T = int16_t>

void setWeight ( int  channel, float  weight  )

inline

Defines a new weight for the indicated channel: If you set it to 0.0 it is muted. The initial value is 1.0

size()

template<typename T = int16_t>

int size ( )

inline

Number of stremams to which are mixed together.

update_total_weights()

template<typename T = int16_t>

void update_total_weights ( )

inlineprotected

Recalculates the total weights for normalization.

write() [1/3]

template<typename T = int16_t>

size_t write ( const uint8_t *  data, size_t  len  )

inlineoverridevirtual

Write the data from a simgle stream which will be mixed together (the stream idx is increased)

Reimplemented from Print.

write() [2/3]

template<typename T = int16_t>

size_t write ( int  idx, const uint8_t *  buffer_c, size_t  bytes  )

inline

Write the data for an individual stream idx which will be mixed together.

write() [3/3]

template<typename T = int16_t>

size_t write ( uint8_t  )

inlineoverride

Single byte write - not supported, returns 0.

writeSilence() [1/2]

template<typename T = int16_t>

size_t writeSilence ( int  idx, size_t  bytes  )

inline

Writes silence to the specified stream buffer.

writeSilence() [2/2]

template<typename T = int16_t>

size_t writeSilence ( size_t  bytes )

inline

Writes silence to the current stream buffer.

Member Data Documentation

_timeout

int _timeout = 10

protectedinherited

allocator

template<typename T = int16_t>

Allocator& allocator

protected

buffers

template<typename T = int16_t>

Vector<BaseBuffer<T> *> buffers {0, DefaultAllocatorRAM}

protected

create_buffer_cb

template<typename T = int16_t>

BaseBuffer< T > *(* create_buffer_cb) (int size, Allocator &allocator) = create_buffer

protected

is_active

template<typename T = int16_t>

bool is_active = false

protected

is_auto_index

template<typename T = int16_t>

bool is_auto_index = true

protected

output

template<typename T = int16_t>

Vector<T> output {0, allocator}

protected

output_count

template<typename T = int16_t>

int output_count = 0

protected

p_final_output

template<typename T = int16_t>

Print* p_final_output = nullptr

protected

p_memory

template<typename T = int16_t>

void* p_memory = nullptr

protected

size_bytes

template<typename T = int16_t>

int size_bytes = 0

protected

stream_idx

template<typename T = int16_t>

int stream_idx = 0

protected

total_weights

template<typename T = int16_t>

float total_weights = 0.0

protected

weights

template<typename T = int16_t>

Vector<float> weights {0, DefaultAllocatorRAM}

protected

---

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

• src/AudioTools/CoreAudio/AudioOutput.h