MP4 comments

Author: pschatzmann

src/AudioTools/AudioCodecs/MP4Parser.h

@@ -16,66 +16,86 @@ namespace audio_tools {
  * @brief MP4Parser is a class that parses MP4 files and extracts boxes (atoms).
  * It provides a callback mechanism to process each box as it is parsed. You can
  * define specific callbacks for individual box types or use a generic callback
- * for the undefined boxes: By default is just prints the box information to
+ * for the undefined boxes: By default it just prints the box information to
  * Serial.
  * If a container box contains data, it will be processed recursively and if it
  * contains data itself, it will be reported in a second callback call.
- * @Note This parser expects that the buffer size is largen then the biggest
+ * @note This parser expects that the buffer size is larger than the biggest
  * box!
  * @ingroup codecs
  * @author Phil Schatzmann
  */
-
 class MP4Parser {
  public:
-  /// An individual box in the MP4 file
+  /**
+   * @brief Represents an individual box in the MP4 file.
+   */
   struct Box {
-    friend class MP4Parser;     // Allow MP4Parser to access private members
-    friend class MP4ParserExt;  // Allow MP4Parser to access private members
-    size_t id = 0;
-    char type[5];         // 4-character box type
-    const uint8_t* data = nullptr;  // Pointer to box payload (not including header)
-    size_t data_size = 0;
-    size_t size = 0;      // Size of payload (not including header)
-    int level = 0;        // Nesting depth
-    uint64_t offset = 0;  // File offset where box starts
-    bool is_complete = false;
-    bool is_container = false;
-
-   private:
-    // SingleBuffer<uint8_t> data_buffer;  // Buffer to hold box data if needed
+    friend class MP4Parser;     ///< Allow MP4Parser to access private members
+    friend class MP4ParserExt;  ///< Allow MP4ParserExt to access private members
+    size_t id = 0;              ///< Unique box ID
+    char type[5];               ///< 4-character box type (null-terminated)
+    const uint8_t* data = nullptr;  ///< Pointer to box payload (not including header)
+    size_t data_size = 0;       ///< Size of payload (not including header)
+    size_t size = 0;            ///< Size of payload (not including header)
+    int level = 0;              ///< Nesting depth
+    uint64_t offset = 0;        ///< File offset where box starts
+    bool is_complete = false;   ///< True if the box data is complete
+    bool is_container = false;  ///< True if the box is a container
   };
 
   using BoxCallback = std::function<void(Box&, void* ref)>;
 
-  /// Type specific callbacks
+  /**
+   * @brief Structure for type-specific callbacks.
+   */
   struct CallbackEntry {
-    char type[5];    // 4-character box type
-    BoxCallback cb;  // Callback function
+    char type[5];    ///< 4-character box type
+    BoxCallback cb;  ///< Callback function
+    bool callGeneric = true; ///< If true, also call the generic callback after this one
   };
 
-  /// Defines an optional reference. By default it is the parser itself
+  /**
+   * @brief Defines an optional reference. By default it is the parser itself.
+   * @param ref Pointer to reference object.
+   */
   void setReference(void* ref) { this->ref = ref; }
 
-  /// Defines the generic callback for all boxes
+  /**
+   * @brief Defines the generic callback for all boxes.
+   * @param cb Callback function for all boxes.
+   */
   void setCallback(BoxCallback cb) { callback = cb; }
 
-  /// Defines a specific callback for a box type
-  void setCallback(const char* type, BoxCallback cb) {
+  /**
+   * @brief Defines a specific callback for a box type.
+   * @param type 4-character box type (e.g. "moov", "mdat").
+   * @param cb   Callback function for this box type.
+   * @param callGeneric If true, the generic callback will also be called after the type-specific callback.
+   */
+  void setCallback(const char* type, BoxCallback cb, bool callGeneric = true) {
     CallbackEntry entry;
     strncpy(entry.type, type, 4);
     entry.type[4] = '\0';  // Ensure null-termination
     entry.cb = cb;
+    entry.callGeneric = callGeneric;
     callbacks.push_back(entry);
   };
 
-  /// Defines a specific buffer size
+  /**
+   * @brief Defines a specific buffer size.
+   * @param size Buffer size in bytes.
+   * @return true if the buffer was resized successfully.
+   */
   bool resize(size_t size) {
     buffer.resize(size);
     return buffer.size() == size;
   }
 
-  /// Initializes the parser
+  /**
+   * @brief Initializes the parser.
+   * @return true on success.
+   */
   bool begin() {
     buffer.clear();
     if (buffer.size() == 0) buffer.resize(1024);
@@ -92,29 +112,52 @@ class MP4Parser {
     return true;
   }
 
-  /// Provide the data to the parser (in chunks if needed)
+  /**
+   * @brief Provide the data to the parser (in chunks if needed).
+   * @param data Pointer to input data.
+   * @param len Length of input data.
+   * @return Number of bytes written to the buffer.
+   */
   size_t write(const uint8_t* data, size_t len) {
     if (is_error) return len;  // If an error occurred, skip writing
     size_t result = buffer.writeArray(data, len);
     parse();
     return result;
   }
 
-  /// Provide the data to the parser (in chunks if needed)
+  /**
+   * @brief Provide the data to the parser (in chunks if needed).
+   * @param data Pointer to input data (char*).
+   * @param len Length of input data.
+   * @return Number of bytes written to the buffer.
+   */
   size_t write(const char* data, size_t len) {
     return write(reinterpret_cast<const uint8_t*>(data), len);
   }
 
+  /**
+   * @brief Returns the available space for writing.
+   * @return Number of bytes available for writing.
+   */
   int availableForWrite() { return buffer.availableForWrite(); }
 
-  /// Adds a box name that will be interpreted as container
+  /**
+   * @brief Adds a box name that will be interpreted as a container.
+   * @param name Name of the container box.
+   * @param start Offset of child boxes (default 0).
+   */
   void addContainer(const char* name, int start = 0) {
     ContainerInfo info;
     info.name = name;
     info.start = start;  // offset of child boxes
   }
 
-  /// trigger separate parsing (and callbacks) on the indicated string
+  /**
+   * @brief Trigger separate parsing (and callbacks) on the indicated string.
+   * @param str Pointer to the string data.
+   * @param len Length of the string data.
+   * @return Number of bytes parsed.
+   */
   int parseString(const uint8_t* str, int len) {
     char type[5];
     int idx = 0;
@@ -136,25 +179,36 @@ class MP4Parser {
   }
 
  protected:
-  BoxCallback callback = defaultCallback;
-  Vector<CallbackEntry> callbacks;
-  SingleBuffer<uint8_t> buffer;
-  Vector<size_t> levelStack;
-  size_t parseOffset = 0;
-  uint64_t fileOffset = 0;
-  void* ref = this;
-  Box box;
-  bool is_error = false;
+  BoxCallback callback = defaultCallback; ///< Generic callback for all boxes
+  Vector<CallbackEntry> callbacks;        ///< List of type-specific callbacks
+  SingleBuffer<uint8_t> buffer;           ///< Buffer for incoming data
+  Vector<size_t> levelStack;              ///< Stack for container box levels
+  size_t parseOffset = 0;                 ///< Current parse offset in buffer
+  uint64_t fileOffset = 0;                ///< Current file offset
+  void* ref = this;                       ///< Reference pointer for callbacks
+  Box box;                                ///< Current box being processed
+  bool is_error = false;                  ///< True if an error occurred
+
+  /**
+   * @brief Structure for container box information.
+   */
   struct ContainerInfo {
-    const char* name = nullptr;
-    int start = 0;
+    const char* name = nullptr; ///< Name of the container box
+    int start = 0;              ///< Offset of child boxes
   };
-  Vector<ContainerInfo> containers;
+  Vector<ContainerInfo> containers; ///< List of container box info
 
-  /// Returns the current file offset (absolute position in file)
+  /**
+   * @brief Returns the current file offset (absolute position in file).
+   * @return Current file offset.
+   */
   uint64_t currentFileOffset() { return fileOffset + parseOffset; }
 
-  // Default callback that prints box information to Serial
+  /**
+   * @brief Default callback that prints box information to Serial.
+   * @param box The box being processed.
+   * @param ref Optional reference pointer.
+   */
   static void defaultCallback(const Box& box, void* ref) {
     char space[box.level * 2 + 1];
     memset(space, ' ', box.level * 2);
@@ -172,13 +226,27 @@ class MP4Parser {
 #endif
   }
 
+  /**
+   * @brief Reads a 32-bit big-endian unsigned integer from a buffer.
+   * @param p Pointer to buffer.
+   * @return 32-bit unsigned integer.
+   */
   static uint32_t readU32(const uint8_t* p) {
     return (p[0] << 24) | (p[1] << 16) | (p[2] << 8) | p[3];
   }
 
+  /**
+   * @brief Reads a 64-bit big-endian unsigned integer from a buffer.
+   * @param p Pointer to buffer.
+   * @return 64-bit unsigned integer.
+   */
   static uint64_t readU64(const uint8_t* p) {
     return ((uint64_t)readU32(p) << 32) | readU32(p + 4);
   }
+
+  /**
+   * @brief Main parsing loop. Handles parsing of boxes in the buffer.
+   */
   virtual void parse() {
     while (true) {
       size_t bufferSize = buffer.available();
@@ -253,6 +321,9 @@ class MP4Parser {
     }
   }
 
+  /**
+   * @brief Pops levels from the stack if we've passed their bounds.
+   */
   void popLevels() {
     // Pop levels if we've passed their bounds (absolute file offset)
     while (!levelStack.empty() &&
@@ -261,18 +332,30 @@ class MP4Parser {
     }
   }
 
+  /**
+   * @brief Processes the callback for a box.
+   * Calls the type-specific callback if present, and the generic callback if allowed.
+   * @param box The box being processed.
+   */
   void processCallback(Box& box) {
     bool is_called = false;
+    bool call_generic = true;
     for (const auto& entry : callbacks) {
       if (strncmp(entry.type, box.type, 4) == 0) {
         entry.cb(box, ref);
         is_called = true;
+        if (!entry.callGeneric) call_generic = false;
       }
     }
-    /// call generic callback
-    if (!is_called) callback(box, ref);
+    /// call generic callback if allowed
+    if ((!is_called || call_generic) && callback) callback(box, ref);
   }
 
+  /**
+   * @brief Checks if a box type is a container box.
+   * @param type Box type string.
+   * @return true if container box, false otherwise.
+   */
   bool isContainerBox(const char* type) {
     // fill with default values if nothing has been defined
     if (containers.empty()) {
@@ -294,27 +377,47 @@ class MP4Parser {
     return false;
   }
 
+  /**
+   * @brief Gets the start offset for a subcontainer.
+   * @param type Box type string.
+   * @return Offset of the subcontainer.
+   */
   int getSubcontainerStart(const char* type) {
     for (auto& cont : containers) {
       if (StrView(type) == cont.name) return cont.start;
     }
     return 0;
   }
 
+  /**
+   * @brief Checks if a box type is a persisted box.
+   * @param type Box type string.
+   * @return true if persisted, false otherwise.
+   */
   bool isPersistedBox(const char* type) const {
     static const char* persisted[] = {"stsz"};
     for (const char* p : persisted)
       if (StrView(type) == p) return true;
     return false;
   }
 
+  /**
+   * @brief Checks if a type string is a valid 4-character box type.
+   * @param type Pointer to type string.
+   * @param offset Offset in the string.
+   * @return true if valid, false otherwise.
+   */
   bool isValidType(const char* type, int offset=0) const {
     // Check if the type is a valid 4-character string
     return (type != nullptr &&
             isalnum(type[offset]) && isalnum(type[offset+1]) &&
             isalnum(type[offset+2]) && isalnum(type[offset+3]));
   }
 
+  /**
+   * @brief Checks and adjusts the parse offset for valid box types.
+   * @return Adjusted parse offset.
+   */
   size_t checkParseOffset() {
     size_t current = parseOffset;
     const char* type = (char*)(buffer.data() + parseOffset + 4);