MultiStreamingDecoder: setMimeSource()

Author: pschatzmann

src/AudioTools/AudioCodecs/MultiDecoder.h

@@ -23,7 +23,7 @@ class MultiDecoder : public AudioDecoder {
   /// Default constructor
   MultiDecoder() = default;
   /// Provides a URLStream to look up the mime type from the http reply header
-  MultiDecoder(AbstractURLStream& url) { setMimeSource(url); }
+  MultiDecoder(MimeSource& mimeSource) { setMimeSource(mimeSource); }
 
   /// Enables the automatic mime type determination
   bool begin() override {
@@ -68,7 +68,7 @@ class MultiDecoder : public AudioDecoder {
 
   /// Defines url stream from which we determine the mime type from the reply
   /// header
-  void setMimeSource(AbstractURLStream& url) { p_url_stream = &url; }
+  void setMimeSource(MimeSource& mimeSource) { p_mime_source = &mimeSource; }
 
   /// selects the actual decoder by mime type - this is usually called
   /// automatically from the determined mime type
@@ -113,9 +113,9 @@ class MultiDecoder : public AudioDecoder {
   size_t write(const uint8_t* data, size_t len) override {
     if (is_first) {
       const char* mime = nullptr;
-      if (p_url_stream != nullptr) {
+      if (p_mime_source != nullptr) {
         // get content type from http header
-        mime = p_url_stream->getReplyHeader(CONTENT_TYPE);
+        mime = p_mime_source->mime();
         if (mime) LOGI("mime from http request: %s", mime);
       }
       if (mime == nullptr) {
@@ -168,7 +168,7 @@ class MultiDecoder : public AudioDecoder {
   Vector<DecoderInfo> decoders{0};
   MimeDetector mime_detector;
   CodecNOP nop;
-  AbstractURLStream* p_url_stream = nullptr;
+  MimeSource* p_mime_source = nullptr;
   bool is_first = true;
   const char* selected_mime = nullptr;
 };

src/AudioTools/AudioCodecs/StreamingDecoder.h

@@ -487,31 +487,9 @@ class MultiStreamingDecoder : public StreamingDecoder {
 
     // Automatically select decoder if not already selected
     if (is_first) {
-      if (actual_decoder.decoder == nullptr) {
-        // Read some data to determine the mime type
-        detection_buffer.resize(80);
-        size_t bytesRead =
-            readBytes(detection_buffer.data(), detection_buffer.size());
-        if (bytesRead == 0) return false;
-
-        // Make data available again
-        buffered_stream.setBuffer(detection_buffer.data(), bytesRead);
-
-        // Use the mime detector to determine format
-        mime_detector.write(detection_buffer.data(), bytesRead);
-        const char* mime = mime_detector.mime();
-
-        if (mime != nullptr) {
-          LOGI("mime from mime_detector: %s", mime);
-          // Select the decoder based on the determined mime type
-          if (!selectDecoder(mime)) {
-            LOGE("The decoder could not be found for %s", mime);
-            return false;
-          }
-        } else {
-          LOGE("Could not determine mime type");
-          return false;
-        }
+      // determine the mime and select the decoder
+      if (!selectDecoder()) {
+        return false;
       }
 
       // Set up buffered input stream that includes the detection data
@@ -532,7 +510,6 @@ class MultiStreamingDecoder : public StreamingDecoder {
     return actual_decoder.decoder->copy();
   }
 
-
   /**
    * @brief Selects the actual decoder by MIME type
    *
@@ -545,59 +522,73 @@ class MultiStreamingDecoder : public StreamingDecoder {
    */
   bool selectDecoder(const char* mime) {
     bool result = false;
+    
+    // Guard against null MIME type - cannot proceed without valid MIME
     if (mime == nullptr) return false;
 
-    // Do nothing if no change
+    // Optimization: Check if the requested MIME type is already active
+    // This avoids unnecessary decoder switching when the same format is detected
     if (StrView(mime).equals(actual_decoder.mime)) {
-      is_first = false;
-      return true;
+      is_first = false;  // Mark initialization as complete
+      return true;       // Already using the correct decoder
     }
 
-    // Close actual decoder if different
+    // Clean shutdown of currently active decoder before switching
+    // This ensures proper resource cleanup and state reset
     if (actual_decoder.decoder != nullptr) {
       actual_decoder.decoder->end();
     }
 
-    // Find the corresponding decoder
-    selected_mime = nullptr;
+    // Search through all registered decoders to find one that handles this MIME type
+    selected_mime = nullptr;  // Clear previous selection
     for (int j = 0; j < decoders.size(); j++) {
       DecoderInfo info = decoders[j];
+      
+      // Check if this decoder supports the detected MIME type
       if (StrView(info.mime).equals(mime)) {
         LOGI("Using StreamingDecoder for %s (%s)", info.mime, mime);
+        
+        // Switch to the matching decoder
         actual_decoder = info;
 
-        // Set up output for the selected decoder
+        // Configure the decoder's output stream to match our output
+        // This ensures decoded audio data flows to the correct destination
         if (p_print != nullptr) {
           actual_decoder.decoder->setOutput(*p_print);
         }
 
-        // Note: Input will be set up later with buffered stream
+        // Note: Input stream will be configured later with the buffered stream
+        // that preserves the data used for MIME detection
 
-        // Start the decoder
+        // Initialize the selected decoder and mark it as active
         if (actual_decoder.decoder->begin()) {
           actual_decoder.is_open = true;
           LOGI("StreamingDecoder %s started", actual_decoder.mime);
         } else {
+          // Decoder failed to start - this is a critical error
           LOGE("Failed to start StreamingDecoder %s", actual_decoder.mime);
           return false;
         }
 
+        // Successfully found and initialized a decoder
         result = true;
-        selected_mime = mime;
-        break;
+        selected_mime = mime;  // Store the MIME type that was selected
+        break;                 // Stop searching once we find a match
       }
     }
+    
+    // Mark initialization phase as complete regardless of success/failure
     is_first = false;
-    return result;
+    return result;  // true if decoder was found and started, false otherwise
   }
 
   /**
    * @brief Provides the MIME type of the selected decoder
-   *
    * @return MIME type string of the currently active decoder, or nullptr
    *         if no decoder is selected
    */
   const char* mime() override {
+    // fallback to actual decoder
     if (actual_decoder.decoder != nullptr) {
       return actual_decoder.decoder->mime();
     }
@@ -646,6 +637,38 @@ class MultiStreamingDecoder : public StreamingDecoder {
    */
   MimeDetector& mimeDetector() { return mime_detector; }
 
+  /**
+   * @brief 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.
+   *
+   * @param 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.
+   *
+   * @note 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 MimeSource interface for implementing custom MIME providers
+   * @see selectDecoder() for how MIME type detection and selection works
+   *
+   * @since This feature allows integration with external metadata sources
+   */
+  void setMimeSource(MimeSource& mimeSource) { p_mime_source = &mimeSource; }
+
  protected:
   /**
    * @brief Simple buffered stream that prefixes buffered data before reading
@@ -811,6 +834,91 @@ class MultiStreamingDecoder : public StreamingDecoder {
   Vector<uint8_t> detection_buffer{0};  ///< Buffer for format detection data
   bool is_first = true;                 ///< Flag for first copy() call
   const char* selected_mime = nullptr;  ///< MIME type that was selected
+  MimeSource* p_mime_source =
+      nullptr;  ///< Optional MIME source for custom logic
+
+  /**
+   * @brief 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.
+   *
+   * @note The detection data is preserved using BufferedPrefixStream, allowing
+   * the selected decoder to process the complete stream including the bytes
+   * used for format identification.
+   *
+   * @return 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 selectDecoder(const char* mime) for explicit decoder selection
+   * @see setMimeSource() for providing external MIME type information
+   * @see MimeDetector for details on automatic format detection
+   */
+  bool selectDecoder() {
+    // Only perform MIME detection and decoder selection if no decoder is active yet
+    // This prevents re-detection on subsequent calls during the same stream
+    if (actual_decoder.decoder == nullptr) {
+      const char* mime = nullptr;
+      
+      // Two methods for MIME type determination: external source or auto-detection
+      if (p_mime_source) {
+        // Option 1: Use externally provided MIME source (e.g., from HTTP headers)
+        // This is more efficient as it avoids reading and analyzing stream data
+        mime = p_mime_source->mime();
+      } else {
+        // Option 2: Auto-detect MIME type by analyzing stream content
+        // This requires reading a sample of data to identify the format
+        
+        // Allocate buffer for MIME detection sample (80 bytes is typically sufficient
+        // for most audio format headers to be identified)
+        detection_buffer.resize(80);
+        size_t bytesRead = readBytes(detection_buffer.data(), detection_buffer.size());
+        
+        // If no data is available, we cannot proceed with detection
+        if (bytesRead == 0) return false;
+
+        // Preserve the detection data for the selected decoder by setting up
+        // the buffered stream. This ensures the data used for detection
+        // is not lost and will be available to the decoder
+        buffered_stream.setBuffer(detection_buffer.data(), bytesRead);
+
+        // Feed the sample data to the MIME detector for format analysis
+        // The detector examines file headers, magic numbers, etc.
+        mime_detector.write(detection_buffer.data(), bytesRead);
+        mime = mime_detector.mime();
+      }
+      
+      // Process the detected/provided MIME type
+      if (mime != nullptr) {
+        LOGI("mime from mime_detector: %s", mime);
+        
+        // Delegate to the overloaded selectDecoder(mime) method to find
+        // and initialize the appropriate decoder for this MIME type
+        if (!selectDecoder(mime)) {
+          LOGE("The decoder could not be found for %s", mime);
+          return false;  // No registered decoder can handle this format
+        }
+      } else {
+        // MIME detection failed - format is unknown or unsupported
+        LOGE("Could not determine mime type");
+        return false;
+      }
+    }
+    
+    // Success: either decoder was already selected or selection completed successfully
+    return true;
+  }
 
   /**
    * @brief Reads bytes from the input stream

src/AudioTools/CoreAudio/AudioHttp/AbstractURLStream.h

@@ -14,7 +14,7 @@ namespace audio_tools {
  * @ingroup http
  * @copyright GPLv3
  */
-class AbstractURLStream : public AudioStream {
+class AbstractURLStream : public AudioStream, public MimeSource {
  public:
   // executes the URL request
   virtual bool begin(const char* urlStr, const char* acceptMime = nullptr,
@@ -29,6 +29,11 @@ class AbstractURLStream : public AudioStream {
   /// Provides reply header information
   virtual const char* getReplyHeader(const char* header) = 0;
 
+  /// Provides the MIME type for the current stream
+  const char* mime() override {
+    return getReplyHeader(CONTENT_TYPE);
+  }
+
   // only the ICYStream supports this
   virtual bool setMetadataCallback(void (*fn)(MetaDataType info,
                                               const char* str, int len)) {

src/AudioTools/CoreAudio/AudioMetaData/MimeDetector.h

@@ -6,6 +6,41 @@
 
 namespace audio_tools {
 
+/**
+ * @brief Abstract interface for classes that can provide MIME type information.
+ * 
+ * This class defines a simple interface for objects that can determine and provide
+ * MIME type strings. It serves as a base class for various MIME detection and 
+ * source identification implementations within the audio tools framework.
+ * 
+ * Classes implementing this interface should provide logic to determine the
+ * appropriate MIME type based on their specific context (e.g., file content,
+ * stream headers, file extensions, etc.).
+ * 
+ * @note This is a pure virtual interface class and cannot be instantiated directly.
+ * @ingroup codecs
+ * @ingroup decoder 
+ * @author Phil Schatzmann
+ * @copyright GPLv3
+ */
+class MimeSource {
+public:
+  /**
+   * @brief Get the MIME type string.
+   * 
+   * Pure virtual method that must be implemented by derived classes to return
+   * the appropriate MIME type string for the current context.
+   * 
+   * @return const char* Pointer to a null-terminated string containing the MIME type.
+   *                     The string should follow standard MIME type format (e.g., "audio/mpeg").
+   *                     Returns nullptr if MIME type cannot be determined.
+   * 
+   * @note The returned pointer should remain valid for the lifetime of the object
+   *       or until the next call to this method.
+   */
+  virtual const char* mime() = 0;
+};
+
 /**
  * @brief  Logic to detemine the mime type from the content.
  * By default the following mime types are supported (audio/aac, audio/mpeg,
@@ -20,7 +55,7 @@ namespace audio_tools {
  * @copyright GPLv3
  */
 
-class MimeDetector {
+class MimeDetector : public MimeSource {
  public:
   MimeDetector() {
     setCheck("audio/vnd.wave", checkWAV);