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 ()

bool	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.

bool	resize (size_t 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
bool	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:

Writes data to the current stream index (starting at 0)
Increments to the next stream index after each write
Automatically calls flushMixer() after writing to the last stream
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>

bool 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

◆ flushMixer()

template<typename T = int16_t>

bool 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>

bool resize ( size_t 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

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ OutputMixer() [1/2]

◆ OutputMixer() [2/2]

Member Function Documentation

◆ allocate_buffers()

◆ available()

◆ availableForWrite() [1/2]

◆ availableForWrite() [2/2]

◆ availablePercent()

◆ availableSamples()

◆ begin()

◆ create_buffer()

◆ end()

◆ flush()

◆ flushMixer()

◆ free_buffers()

◆ getBuffer()

◆ mixSamples()

◆ next()

◆ resize()

◆ setAutoIndex()

◆ setCreateBufferCallback()

◆ setIndex()

◆ setOutput()

◆ setOutputCount()

◆ setWeight()

◆ size()

◆ update_total_weights()

◆ write() [1/3]

◆ write() [2/3]

◆ write() [3/3]

◆ writeSilence() [1/2]

◆ writeSilence() [2/2]

Member Data Documentation

◆ _timeout

◆ allocator

◆ buffers

◆ create_buffer_cb

◆ is_active

◆ is_auto_index

◆ output

◆ output_count

◆ p_final_output

◆ p_memory

◆ size_bytes

◆ stream_idx

◆ total_weights

◆ weights