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

#include <StreamingDecoder.h>

Inheritance diagram for MultiStreamingDecoder:

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

Public Member Functions
	MultiStreamingDecoder ()=default
	Default constructor.

	~MultiStreamingDecoder ()
	Destructor.

void	addDecoder (AudioDecoder &decoder, const char *mime, int bufferSize=DEFAULT_BUFFER_SIZE)
	Adds an AudioDecoder with explicit MIME type.

void	addDecoder (StreamingDecoder &decoder)
	Adds a decoder that will be selected by its MIME type.

void	addDecoder (StreamingDecoder &decoder, const char *mime)
	Adds a decoder with explicit MIME type.

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

AudioInfo	audioInfo () override
	Provides the audio information from the selected decoder.

virtual AudioInfo	audioInfoOut ()

bool	begin () override
	Starts the processing.

virtual void	clearNotifyAudioChange ()
	Deletes all change notify subscriptions.

virtual bool	copy () override
	Process a single read operation - to be called in the loop.

bool	copyAll ()
	Process all available data.

void	end () override
	Releases the reserved memory.

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

const char *	mime () override
	Provides the MIME type of the selected decoder.

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

virtual	operator bool () override
	Checks if the class is active.

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	setInput (Stream &inStream)
	Stream Interface: Decode directly by taking data from the stream.

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

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

void	setOutput (AudioOutput &out_stream) override
	Defines the output streams and register to be notified.

void	setOutput (AudioStream &out_stream) override
	Defines the output streams and register to be notified.

void	setOutput (Print &out_stream) override
	Defines the output Stream.

Protected Member Functions
void	notifyAudioChange (AudioInfo info)

size_t	readBytes (uint8_t *data, size_t len) override
	Reads bytes from the input stream.

bool	selectDecoder ()
	Automatically detects MIME type and selects appropriate decoder.

void	setAudioInfo (AudioInfo newInfo) override
	Defines the input AudioInfo.

const char *	toStr (const char *str)

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

Vector< StreamingDecoderAdapter * >	adapters
	Collection of internally created adapters.

BufferedStream	buffered_stream {0}
	Buffered stream for data preservation.

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

Vector< uint8_t >	detection_buffer {0}
	Buffer for format detection data.

AudioInfo	info

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

bool	is_notify_active = true

MimeDetector	mime_detector
	MIME type detection engine.

Vector< AudioInfoSupport * >	notify_vector

Stream *	p_data_source = nullptr
	effective data source for decoder

Stream *	p_input = nullptr
	Input stream for encoded audio data.

MimeSource *	p_mime_source
	Optional MIME source for custom logic.

Print *	p_print = nullptr
	Output stream for decoded PCM data.

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

Detailed Description

Manage multiple StreamingDecoders with automatic format detection.

This class automatically detects the audio format from incoming streaming 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, and the detected data is preserved for the selected decoder using a buffered stream approach.

Key features:

Automatic format detection using MimeDetector
Support for multiple decoder registration
Data preservation during format detection
Custom mime type detection logic support
Seamless integration with existing streaming architecture

Note: The first call to copy() will consume some data for format detection, but this data is preserved and made available to the selected decoder through a BufferedPrefixStream mechanism.

Author: Phil Schatzmann

Copyright: GPLv3

Constructor & Destructor Documentation

◆ ~MultiStreamingDecoder()

~MultiStreamingDecoder ( )

inline

Destructor.

Cleans up any internally created StreamingDecoderAdapter instances.

Member Function Documentation

◆ addDecoder() [1/3]

void addDecoder	(	AudioDecoder &	decoder,
		const char *	mime,
		int	bufferSize = `DEFAULT_BUFFER_SIZE`
	)

inline

Adds an AudioDecoder with explicit MIME type.

Wraps an AudioDecoder in a StreamingDecoderAdapter and registers it with the specified MIME type. This allows using traditional AudioDecoder instances with the MultiStreamingDecoder's automatic format detection.

Parameters

decoder	The AudioDecoder to wrap and register
mime	The MIME type string to associate with this decoder
bufferSize	Buffer size for the adapter (default: DEFAULT_BUFFER_SIZE)

Note: The created StreamingDecoderAdapter is stored internally and will be automatically managed by the MultiStreamingDecoder.

◆ addDecoder() [2/3]

void addDecoder ( StreamingDecoder & decoder )

inline

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

Registers a StreamingDecoder that will be automatically selected when the corresponding MIME type is detected in the input stream.

Parameters

decoder The StreamingDecoder to register

◆ addDecoder() [3/3]

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

inline

Adds a decoder with explicit MIME type.

Registers a StreamingDecoder with a specific MIME type, which may be different from what the decoder's mime() method returns.

Parameters

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

◆ addNotifyAudioChange()

virtual void addNotifyAudioChange ( AudioInfoSupport & bi )

inlinevirtualinherited

Adds target to be notified about audio changes.

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

◆ audioInfo()

AudioInfo audioInfo ( )

inlineoverridevirtual

Provides the audio information from the selected decoder.

Returns: AudioInfo from the currently active decoder, or empty AudioInfo if no decoder is selected

Implements StreamingDecoder.

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

bool begin ( )

inlineoverridevirtual

Starts the processing.

Initializes the MIME detector and prepares for format detection.

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

Implements StreamingDecoder.

◆ copy()

virtual bool copy ( )

inlineoverridevirtual

Process a single read operation - to be called in the loop.

On the first call, this method reads data for format detection, selects the appropriate decoder, and sets up a buffered stream. Subsequent calls delegate to the selected decoder's copy() method.

Returns: true if data was processed successfully, false if no data is available or format detection/decoding failed

Implements StreamingDecoder.

◆ copyAll()

bool copyAll ( )

inlineinherited

Process all available data.

Convenience method that calls copy() repeatedly until all available data has been processed.

Returns: true if any data was processed, false if no data was available

◆ end()

void end ( )

inlineoverridevirtual

Releases the reserved memory.

Stops the currently active decoder and resets the state for next use.

Implements StreamingDecoder.

◆ mime()

const char * mime ( )

inlineoverridevirtual

Provides the MIME type of the selected decoder.

Returns: MIME type string of the currently active decoder, or nullptr if no decoder is selected

Implements StreamingDecoder.

◆ 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 access to advanced features such as:

Adding custom MIME type detection logic
Setting custom detection callbacks
Configuring default MIME types
Accessing detection statistics

Note: This method should typically only be used for advanced configuration before calling begin(). Modifying the detector after format detection has occurred may lead to unexpected behavior.

Returns: Reference to the internal MimeDetector instance

See also: MimeDetector::setCheck() for adding custom detection logic; MimeDetector::setMimeCallback() for detection notifications

◆ operator bool()

virtual operator bool ( )

inlineoverridevirtual

Checks if the class is active.

Returns: true if a decoder is selected and active, or if format detection hasn't been performed yet

Implements StreamingDecoder.

◆ readBytes()

size_t readBytes	(	uint8_t *	data,
		size_t	len
	)

inlineoverrideprotectedvirtual

Reads bytes from the input stream.

Parameters

data	Buffer to store read data
len	Maximum number of bytes to read

Returns: Number of bytes actually read

Implements StreamingDecoder.

◆ selectDecoder() [1/2]

bool selectDecoder ( )

inlineprotected

Automatically detects MIME type and selects appropriate decoder.

This method performs automatic format detection and decoder selection when no decoder is currently active. It supports two modes of operation:

External MIME source - Uses a provided MimeSource for format information
Auto-detection - Analyzes stream content to determine the audio format

The method reads a small sample of data (80 bytes) from the input stream for format detection, then preserves this data in a buffered stream so it remains available to the selected decoder. This ensures no audio data is lost during the detection process.

Note: This method is automatically called by copy() on the first invocation. Subsequent calls will return immediately if a decoder is already selected.; The detection data is preserved using BufferedPrefixStream, allowing the selected decoder to process the complete stream including the bytes used for format identification.

Returns: true if a decoder was successfully selected and initialized, or if a decoder was already active; false if MIME detection failed or no matching decoder was found

See also: selectDecoder(const char* mime) for explicit Decoder selection; setMimeSource() for providing external MIME type information; MimeDetector for details on automatic format detection

◆ selectDecoder() [2/2]

bool selectDecoder ( const char * mime )

inline

Selects the actual decoder by MIME type.

Searches through registered decoders to find one that matches the detected MIME type, then initializes it for use.

Parameters

mime	The MIME type string to match

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 by the MimeDetector

◆ setAudioInfo()

void setAudioInfo ( AudioInfo info )

inlineoverrideprotectedvirtualinherited

Defines the input AudioInfo.

Implements AudioInfoSupport.

◆ setInput()

void setInput ( Stream & inStream )

inline

Stream Interface: Decode directly by taking data from the stream.

Parameters

inStream The input stream containing encoded audio data

◆ 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 already known from other sources such as:

HTTP Content-Type headers
File extensions
Metadata from containers or playlists
User-specified format preferences

When a MIME source is set, the automatic detection process (which requires reading and analyzing stream data) is bypassed, making the decoder initialization more efficient and faster.

Parameters

mimeSource Reference to a MimeSource object that provides the MIME type through its mime() method

Note: The MimeSource object must remain valid for the lifetime of this MultiStreamingDecoder instance, as only a reference is stored.; Setting a MIME source takes precedence over automatic detection. To revert to automatic detection, the MIME source would need to return nullptr from its mime() method.

See also: MimeSource interface for implementing custom MIME providers; selectDecoder() for how MIME type detection and selection works

Since: This feature allows integration with external metadata sources

◆ setOutput() [1/3]

void setOutput ( AudioOutput & out_stream )

inlineoverridevirtual

Defines the output streams and register to be notified.

Parameters

out_stream The AudioOutput for decoded audio data

Reimplemented from StreamingDecoder.

◆ setOutput() [2/3]

void setOutput ( AudioStream & out_stream )

inlineoverridevirtual

Defines the output streams and register to be notified.

Parameters

out_stream The AudioStream for decoded audio data

Reimplemented from StreamingDecoder.

◆ setOutput() [3/3]

void setOutput ( Print & out_stream )

inlineoverridevirtual

Defines the output Stream.

Parameters

out_stream The output stream for decoded audio data

Reimplemented from StreamingDecoder.

Member Data Documentation

◆ adapters

Vector<StreamingDecoderAdapter*> adapters

protected

Initial value:

{

0}

Collection of internally created adapters.

◆ p_mime_source

MimeSource* p_mime_source

protected

Initial value:

=

nullptr

Optional MIME source for custom logic.

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

src/AudioTools/AudioCodecs/StreamingDecoder.h

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~MultiStreamingDecoder()

Member Function Documentation

◆ addDecoder() [1/3]

◆ addDecoder() [2/3]

◆ addDecoder() [3/3]

◆ addNotifyAudioChange()

◆ audioInfo()

◆ audioInfoOut()

◆ begin()

◆ copy()

◆ copyAll()

◆ end()

◆ mime()

◆ mimeDetector()

◆ operator bool()

◆ readBytes()

◆ selectDecoder() [1/2]

◆ selectDecoder() [2/2]

◆ selectedMime()

◆ setAudioInfo()

◆ setInput()

◆ setMimeSource()

◆ setOutput() [1/3]

◆ setOutput() [2/3]

◆ setOutput() [3/3]

Member Data Documentation

◆ adapters

◆ p_mime_source