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

availableForWrite()

template<typename T = int16_t>

int availableForWrite ( )

inlineoverridevirtual

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

Reimplemented from Print.

flush()

virtual void flush ( )

inlinevirtualinherited

Reimplemented in ResampleStream, HDLCStream, BufferedTaskStream, BufferedStream, and NamePrinter.

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

write()

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.

---

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

• src/AudioTools/CoreAudio/AudioOutput.h