arduino-audio-tools
Loading...
Searching...
No Matches
Classes | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
MultiStreamingDecoder Class Reference

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

#include <StreamingDecoder.h>

Inheritance diagram for MultiStreamingDecoder:
StreamingDecoder AudioInfoSource AudioInfoSupport

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.
 
MimeDetectormimeDetector ()
 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< DecoderInfodecoders {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
 
Streamp_data_source = nullptr
 effective data source for decoder
 
Streamp_input = nullptr
 Input stream for encoded audio data.
 
MimeSourcep_mime_source
 Optional MIME source for custom logic.
 
Printp_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:

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

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
decoderThe AudioDecoder to wrap and register
mimeThe MIME type string to associate with this decoder
bufferSizeBuffer 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
decoderThe 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
decoderThe StreamingDecoder to register
mimeThe MIME type string to associate with this decoder

◆ addNotifyAudioChange()

virtual void addNotifyAudioChange ( AudioInfoSupport bi)
inlinevirtualinherited

◆ 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

◆ 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
dataBuffer to store read data
lenMaximum 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:

  1. External MIME source - Uses a provided MimeSource for format information
  2. 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
mimeThe 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
inStreamThe 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
mimeSourceReference 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_streamThe 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_streamThe AudioStream for decoded audio data

Reimplemented from StreamingDecoder.

◆ setOutput() [3/3]

void setOutput ( Print out_stream)
inlineoverridevirtual

Defines the output Stream.

Parameters
out_streamThe 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: