Manage multiple AudioDecoders with automatic format detection. More...

#include <MultiDecoder.h>

Inheritance diagram for MultiDecoder:

Classes
struct	DecoderInfo
	Information about a registered decoder. More...

Public Member Functions
	MultiDecoder ()=default
	Default constructor.

	MultiDecoder (MimeSource &mimeSource)
	Constructor with external MIME source.

void	addDecoder (AudioDecoder &decoder, const char *mime)
	Adds a decoder that will be selected by its MIME type.

void	addDecoder (AudioDecoder &decoder, const char mime, bool(check)(uint8_t *data, size_t len))
	Adds a decoder with custom MIME detection logic.

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

AudioInfo	audioInfo () override
	provides the actual input AudioInfo

virtual AudioInfo	audioInfoOut ()

bool	begin () override
	Starts the processing and enables automatic MIME type determination.

virtual bool	begin (AudioInfo info) override

virtual void	clearNotifyAudioChange ()
	Deletes all change notify subscriptions.

void	end () override
	Releases resources and closes the active decoder.

Print *	getOutput ()

bool	isNotifyActive ()
	Checks if the automatic AudioInfo update is active.

virtual bool	isResultPCM ()
	Returns true to indicate that the decoding result is PCM data.

MimeDetector &	mimeDetector ()
	Provides access to the internal MIME detector.

virtual	operator bool () override
	Checks if the decoder is active and ready.

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

bool	selectDecoder (const char *mime)
	Selects the actual decoder by MIME type.

const char *	selectedMime ()
	Returns the MIME type that was detected and selected.

void	setAudioInfo (AudioInfo from) override
	for most decoders this is not needed

bool	setCodecConfig (const uint8_t *data, size_t len) override
	Sets codec-specific configuration data.

void	setMimeSource (MimeSource &mimeSource)
	Sets an external MIME source for format detection.

void	setNotifyActive (bool flag)
	Deactivate/Reactivate automatic AudioInfo updates: (default is active)

virtual void	setOutput (AudioOutput &out_stream)
	Defines where the decoded result is written to.

virtual void	setOutput (AudioStream &out_stream)
	Defines where the decoded result is written to.

void	setOutput (Print &out_stream) override
	Sets the output stream for decoded audio data.

size_t	write (const uint8_t *data, size_t len) override
	Writes encoded audio data to be decoded.

Public Attributes
int	id
	custom id to be used by application

Protected Member Functions
void	notifyAudioChange (AudioInfo info)

void	writeBlocking (Print out, uint8_t data, size_t len)

Protected Attributes
struct audio_tools::MultiDecoder::DecoderInfo	actual_decoder
	Currently active decoder information.

Vector< DecoderInfo >	decoders {0}
	Collection of registered decoders.

AudioInfo	info

bool	is_first = true
	Flag for first write() call.

bool	is_notify_active = true

MimeDetector	mime_detector
	MIME type detection engine.

CodecNOP	nop
	No-operation codec for unsupported formats.

Vector< AudioInfoSupport * >	notify_vector

MimeSource *	p_mime_source = nullptr
	Optional external MIME source.

Print *	p_print = nullptr

const char *	selected_mime = nullptr
	MIME type that was selected.

Detailed Description

Manage multiple AudioDecoders with automatic format detection.

This class automatically detects the audio format from incoming data and selects the appropriate decoder from a collection of registered decoders. The format detection is performed using the MimeDetector on the first chunk of data written to the decoder.

Key features:

Automatic format detection using MimeDetector
Support for multiple decoder registration
Custom MIME type detection logic support
External MIME source integration (e.g., HTTP headers)
Lazy decoder initialization for memory efficiency
Seamless integration with existing AudioDecoder architecture

The actual decoder is only opened when it has been selected, which allows for memory-efficient operation when dealing with multiple possible formats. The relevant decoder is determined dynamically at the first write() call based on the determined MIME type.

Note: This class uses a write-based interface, unlike StreamingDecoder which uses a pull-based approach. For streaming scenarios with direct access to input/output streams, consider using MultiStreamingDecoder.

Author: Phil Schatzmann

Copyright: GPLv3

Constructor & Destructor Documentation

◆ MultiDecoder()

MultiDecoder ( MimeSource & mimeSource )

inline

Constructor with external MIME source.

Creates a MultiDecoder that uses an external source for MIME type determination, such as HTTP Content-Type headers. This can be more efficient than automatic detection as it avoids analyzing data content.

Parameters

mimeSource Reference to a MimeSource that provides MIME type information

Member Function Documentation

◆ addDecoder() [1/2]

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

inline

Adds a decoder that will be selected by its MIME type.

Registers an AudioDecoder that will be automatically selected when the corresponding MIME type is detected in the input data.

Parameters

decoder	The AudioDecoder to register
mime	The MIME type string to associate with this decoder

◆ addDecoder() [2/2]

void addDecoder	(	AudioDecoder &	decoder,
		const char *	mime,
		bool()(uint8_t data, size_t len)	check
	)

inline

Adds a decoder with custom MIME detection logic.

Registers an AudioDecoder with a specific MIME type and provides custom logic for detecting that MIME type from raw data. This allows for specialized format detection beyond the standard MimeDetector capabilities.

Parameters

decoder	The AudioDecoder to register
mime	The MIME type string to associate with this decoder
check	Custom function that analyzes data to detect this MIME type. Should return true if the data matches this format.

◆ addNotifyAudioChange()

virtual void addNotifyAudioChange ( AudioInfoSupport & bi )

inlinevirtualinherited

Adds target to be notified about audio changes.

Reimplemented in CodecNOP, EncodedAudioOutput, EncodedAudioStream, AACDecoderFDK, DecoderBasic, MP3DecoderHelix, MP3DecoderMAD, OggContainerDecoder, Pipeline, and Pipeline::ModifyingStreamAdapter.

◆ audioInfo()

AudioInfo audioInfo ( )

inlineoverridevirtualinherited

provides the actual input AudioInfo

Implements AudioInfoSupport.

Reimplemented in CodecNOP, GGWaveDecoder, DecoderBasic, DSFDecoder, MP3DecoderHelix, MP3DecoderMAD, OpusAudioDecoder, WAVDecoder, WavIMADecoder, and OggContainerDecoder.

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

◆ begin() [1/2]

bool begin ( )

inlineoverridevirtual

Starts the processing and enables automatic MIME type determination.

Initializes the MIME detector and prepares the MultiDecoder for format detection. This method must be called before any write() operations.

Returns: true if initialization was successful, false if no output is defined

Reimplemented from AudioDecoder.

◆ begin() [2/2]

virtual bool begin ( AudioInfo info )

inlineoverridevirtualinherited

Reimplemented from AudioWriter.

◆ end()

void end ( )

inlineoverridevirtual

Releases resources and closes the active decoder.

Stops the currently active decoder and resets the MultiDecoder state for potential reuse. After calling end(), begin() must be called again before the decoder can process new data.

Reimplemented from AudioDecoder.

◆ isResultPCM()

virtual bool isResultPCM ( )

inlinevirtualinherited

Returns true to indicate that the decoding result is PCM data.

Reimplemented in CopyDecoder, DecoderNetworkFormat, GGWaveDecoder, and ContainerM4A.

◆ mimeDetector()

MimeDetector & mimeDetector ( )

inline

Provides access to the internal MIME detector.

Returns a reference to the MimeDetector instance used for automatic format detection. This allows direct access to configure custom MIME detection logic or to query detection results.

Returns: Reference to the internal MimeDetector instance

◆ operator bool()

virtual operator bool ( )

inlineoverridevirtual

Checks if the decoder is active and ready.

Returns: true if a decoder is selected and active, or if format detection hasn't been performed yet; false if no suitable decoder was found

Implements AudioWriter.

◆ selectDecoder()

bool selectDecoder ( const char * mime )

inline

Selects the actual decoder by MIME type.

Searches through registered decoders to find one that matches the specified MIME type, then initializes it for use. This method is usually called automatically from the determined MIME type during the first write() operation.

Parameters

mime	The MIME type string to match against registered decoders

Returns: true if a matching decoder was found and initialized, false otherwise

◆ selectedMime()

const char * selectedMime ( )

inline

Returns the MIME type that was detected and selected.

Returns: The MIME type string that was detected and used to select the current decoder, or nullptr if no decoder has been selected

◆ setAudioInfo()

void setAudioInfo ( AudioInfo from )

inlineoverridevirtualinherited

for most decoders this is not needed

Implements AudioWriter.

Reimplemented in GGWaveDecoder, DecoderALAC, CodecChain, DSFDecoder, DecoderL8, OpusAudioDecoder, CodecNOP, and G7xxDecoder.

◆ setCodecConfig()

bool setCodecConfig	(	const uint8_t *	data,
		size_t	len
	)

inlineoverridevirtual

Sets codec-specific configuration data.

Forwards codec configuration data to the currently selected decoder. This method can only be called after a decoder has been selected.

Parameters

data	Buffer containing codec configuration data
len	Length of the configuration data

Returns: true if the configuration was successfully applied, false otherwise

Reimplemented from AudioDecoder.

◆ setMimeSource()

void setMimeSource ( MimeSource & mimeSource )

inline

Sets an external MIME source for format detection.

Provides an alternative to automatic MIME detection by allowing an external source to provide the MIME type information. This is particularly useful when the MIME type is available from HTTP headers or other metadata sources.

When a MIME source is set, it takes precedence over automatic detection, making the decoder selection process more efficient.

Parameters

mimeSource Reference to a MimeSource that provides MIME type information

Note: The MimeSource object must remain valid for the lifetime of this MultiDecoder instance, as only a reference is stored.

◆ setOutput() [1/3]

virtual void setOutput ( AudioOutput & out_stream )

inlinevirtualinherited

Defines where the decoded result is written to.

Reimplemented in ADTSDecoder, CodecChain, MTSDecoder, MTSDecoderTSDemux, and MetaDataFilterDecoder.

◆ setOutput() [2/3]

virtual void setOutput ( AudioStream & out_stream )

inlinevirtualinherited

Defines where the decoded result is written to.

Reimplemented in ADTSDecoder, CodecChain, MTSDecoder, MTSDecoderTSDemux, and MetaDataFilterDecoder.

◆ setOutput() [3/3]

void setOutput ( Print & out_stream )

inlineoverridevirtual

Sets the output stream for decoded audio data.

Defines where the decoded PCM audio data will be written to. This output will be automatically configured for the selected decoder.

Parameters

out_stream The Print stream to write decoded audio data to

Reimplemented from AudioDecoder.

◆ write()

size_t write	(	const uint8_t *	data,
		size_t	len
	)

inlineoverridevirtual

Writes encoded audio data to be decoded.

On the first call, this method performs MIME type detection to select the appropriate decoder. Subsequent calls delegate to the selected decoder's write() method to process the audio data.

The MIME detection process uses either an external MIME source (if set) or analyzes the provided data to determine the audio format.

Parameters

data	Buffer containing encoded audio data
len	Number of bytes to write

Returns: Number of bytes actually written to the selected decoder

Implements AudioWriter.

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

src/AudioTools/AudioCodecs/MultiDecoder.h

Classes

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ MultiDecoder()

Member Function Documentation

◆ addDecoder() [1/2]

◆ addDecoder() [2/2]

◆ addNotifyAudioChange()

◆ audioInfo()

◆ audioInfoOut()

◆ begin() [1/2]

◆ begin() [2/2]

◆ end()

◆ isResultPCM()

◆ mimeDetector()

◆ operator bool()

◆ selectDecoder()

◆ selectedMime()

◆ setAudioInfo()

◆ setCodecConfig()

◆ setMimeSource()

◆ setOutput() [1/3]

◆ setOutput() [2/3]

◆ setOutput() [3/3]

◆ write()