MP4Parser.h

Go to the documentation of this file.

#pragma once
 
#include <cstdint>
#include <cstring>
#include <functional>
#include <string>
 
#include "AudioTools/CoreAudio/Buffers.h"
 
namespace audio_tools {
 
class MP4Parser {
 public:
  struct Box {
    friend class MP4Parser;     
    friend class MP4ParserExt;  
    size_t id = 0;              
    size_t seq = 0;             
    char type[5];               
    const uint8_t* data =
        nullptr;           
    size_t data_size = 0;  
    size_t size =
        0;  
    int level = 0;              
    uint64_t file_offset = 0;   
    int available = 0;         
    bool is_complete = false;   
    bool is_incremental = false;  
    bool is_container = false;  
  };
 
  using BoxCallback = std::function<void(Box&, void* ref)>;
 
  struct CallbackEntry {
    char type[5];    
    BoxCallback cb;  
    bool callGeneric =
        true;  
  };
 
  void setReference(void* ref) { this->ref = ref; }
 
  void setCallback(BoxCallback cb) { callback = cb; }
 
  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);
  };
 
  bool resize(size_t size) {
    buffer.resize(size);
    return buffer.size() == size;
  }
 
  bool begin(uint64_t startFileOffset = 0) {
    buffer.clear();
    if (buffer.size() == 0) buffer.resize(2 * 1024);
    parseOffset = 0;
    fileOffset = startFileOffset;
    levelStack.clear();
    box.is_complete = true;  // Start with no open box
    box.data = nullptr;
    box.size = 0;
    box.level = 0;
    box.file_offset = startFileOffset;
    box.id = 0;
    box.is_incremental = false;
    box.is_complete = true;
    // reset incremental-box state too, in case begin() is called again
    // mid-parse (see startFileOffset above)
    box_in_progress = false;
    box_bytes_received = 0;
    box_bytes_expected = 0;
    box_seq = 0;
    incremental_offset = 0;
    moov_found = false;
    return true;
  }
 
  size_t write(const uint8_t* data, size_t len) {
    if (is_error) return len;  // If an error occurred, skip writing
    // The accumulation buffer (default 2KB, see begin()) is usually much
    // smaller than a single caller-side write (e.g. a 16-64KB StreamCopy
    // chunk): a single writeArray() silently truncates at buffer.size(),
    // dropping the remainder with no error, which desyncs the parser from
    // the real byte stream (misread box headers, huge bogus sizes, etc.).
    // Feed it in buffer-sized slices, parsing (and thereby freeing space)
    // between each one, until every byte has been accepted.
    size_t total_written = 0;
    while (total_written < len) {
      size_t avail = buffer.availableForWrite();
      if (avail == 0) {
        parse();
        avail = buffer.availableForWrite();
        if (avail == 0) break;  // parser made no progress: avoid a hang
      }
      size_t chunk = std::min(avail, len - total_written);
      size_t written = buffer.writeArray(data + total_written, chunk);
      if (written == 0) break;  // safety net, should not happen
      total_written += written;
      parse();
    }
    return total_written;
  }
 
  size_t write(const char* data, size_t len) {
    return write(reinterpret_cast<const uint8_t*>(data), len);
  }
 
  int availableForWrite() { return buffer.availableForWrite(); }
 
  void setRequireMoovBeforeMdat(bool flag) { require_moov_before_mdat = flag; }
 
  void addContainer(const char* name, int start = 0) {
    ContainerInfo info;
    info.name = name;
    info.start = start;  // offset of child boxes
  }
 
  int parseString(const uint8_t* str, int len, int fileOffset = 0,
                  int level = 0) {
    char type[5];
    int idx = 0;
    Box box;
    while (true) {
      if (!isValidType((const char*)str + idx + 4)) {
        return idx;
      }
      size_t box_size = readU32(str + idx) - 8;
      box.data = str + 8 + idx;
      box.size = box_size;
      box.level = level;
      box.data_size = box.size;
      box.file_offset = fileOffset + idx;
      box.is_complete = true;
      box.is_incremental = false;
      strncpy(box.type, (char*)(str + idx + 4), 4);
      box.type[4] = '\0';
      idx += box.size;
      processCallback(box);
      if (idx >= len) break;  // No more data to parse
    }
    return idx;
  }
 
  bool findBox(const char* name, const uint8_t* data, size_t len, Box& result) {
    for (int j = 0; j < len - 4; j++) {
      if (!isValidType((const char*)data + j + 4)) {
        continue;  // Skip invalid types
      }
      size_t box_size = readU32(data + j) - 8;
      if (box_size < 8) continue;  // Invalid box size
      Box box;
      box.data = data + j + 8;
      box.size = box_size;
      box.data_size = box.size;
      strncpy(box.type, (char*)(data + j + 4), 4);
      box.type[4] = '\0';
      if (StrView(box.type) == name) {
        result = box;
        return true;  // Found the box
      }
    }
    return false;
  }
 
  static void defaultCallback(const Box& box, void* ref) {
    char space[box.level * 2 + 1];
    char str_buffer[200];
    memset(space, ' ', box.level * 2);
    space[box.level * 2] = '\0';  // Null-terminate the string
    snprintf(str_buffer, sizeof(str_buffer),
             "%s- #%u %u) %s, Offset: %u, Size: %u, Data Size: %u, Available: %u", space,
             (unsigned)box.id, (unsigned) box.seq, box.type, (unsigned)box.file_offset,
             (unsigned)box.size, (unsigned) box.data_size, (unsigned) box.available);
#ifdef ARDUINO
    Serial.println(str_buffer);
#else
    printf("%s\n", str_buffer);
#endif
  }
 
 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;                   
  bool moov_found = false;  
  bool require_moov_before_mdat = true;  
 
  struct ContainerInfo {
    const char* name = nullptr;  
    int start = 0;               
  };
  Vector<ContainerInfo> containers;  
protected:
  bool box_in_progress =
      false;  
  size_t box_bytes_received = 0;  
  size_t box_bytes_expected = 0;  
  char box_type[5] = {0};         
  int box_level = 0;              
  int box_seq = 0;
  size_t incremental_offset = 0;
 
  void parse()  {
    while (true) {
      size_t bufferSize = buffer.available();
      if (!box_in_progress) {
        if (!tryStartNewBox(bufferSize)) break;
      } else {
        if (!continueIncrementalBox()) break;
      }
      popLevels();
    }
    finalizeParse();
  }
 
  bool tryStartNewBox(size_t bufferSize) {
    if (parseOffset + 8 > bufferSize) return false;
    char type[5];
    box_seq = 0;
 
    // get basic box information
    parseOffset = checkParseOffset();
    const uint8_t* p = buffer.data() + parseOffset;
    uint32_t size32 = readU32(p);
    strncpy(type, (char*)(p + 4), 4);
    type[4] = '\0';
 
    uint64_t boxSize = size32;
    size_t headerSize = 8;
    // A 32-bit size of 0 or 1 are reserved ISO/IEC 14496-12 special cases
    // that a plain 32-bit compare against headerSize can't handle.
    bool unbounded = false;
    if (size32 == 1) {
      // 64-bit "largesize" follows the type field
      if (parseOffset + 16 > bufferSize) return false;  // wait for largesize
      boxSize = readU64(p + 8);
      headerSize = 16;
    } else if (size32 == 0) {
      // box extends to the end of the file/stream (e.g. a streamed mdat
      // written by an encoder that never seeks back to patch in the size)
      unbounded = true;
    }
 
    if (!unbounded && boxSize < headerSize) return false;
 
    int level = static_cast<int>(levelStack.size());
 
    // mdat holds the audio payload and must be preceded by moov, otherwise
    // sample/format info needed to decode it is missing.
    if (level == 0 && strcmp(type, "mdat") == 0 && !moov_found) {
      if (require_moov_before_mdat) {
        LOGE(
            "mdat box found before moov box: moov must precede mdat (e.g. "
            "use 'ffmpeg -movflags +faststart') or this file will not play "
            "correctly");
      } else {
        LOGW(
            "mdat box found before moov box: moov should precede mdat (e.g. "
            "use 'ffmpeg -movflags +faststart') - continuing anyway since "
            "the requirement was opted out of");
      }
    }
 
    bool is_container = isContainerBox(type);
 
    if (is_container) {
      if (unbounded) {
        LOGE("Unsupported: container box '%s' with size 0 (extends to EOF)",
             type);
        return false;
      }
      handleContainerBox(type, boxSize, headerSize, level);
      return true;
    }
 
    size_t payload_size =
        unbounded ? SIZE_MAX : static_cast<size_t>(boxSize - headerSize);
    if (!unbounded && parseOffset + boxSize <= bufferSize) {
      // start with full buffer!
      handleCompleteBox(type, p, headerSize, payload_size, level);
      parseOffset += boxSize;
    } else {
      startIncrementalBox(type, p, headerSize, payload_size, level, bufferSize);
      return false;  // Wait for more data
    }
    return true;
  }
 
  void handleContainerBox(const char* type, uint64_t boxSize,
                          size_t headerSize, int level) {
    strcpy(box.type, type);
    ++box.id;
    box.data = nullptr;
    box.size = static_cast<size_t>(boxSize - headerSize);
    box.data_size = 0;
    box.available = 0;
    box.level = level;
    box.file_offset = fileOffset + parseOffset;
    box.is_incremental = false;
    box.is_complete = true;
    box.is_container = true;
    box.seq = 0;
 
    if (strcmp(type, "moov") == 0) moov_found = true;
 
    processCallback(box);
 
    uint64_t absBoxOffset = fileOffset + parseOffset;
    levelStack.push_back(absBoxOffset + boxSize);
    parseOffset += headerSize;
  }
 
  void handleCompleteBox(const char* type, const uint8_t* p, size_t headerSize,
                         size_t payload_size, int level) {
    strcpy(box.type, type);
    ++box.id; 
    box.data = p + headerSize;
    box.size = payload_size;
    box.data_size = payload_size;
    box.level = level;
    box.file_offset = fileOffset + parseOffset;
    box.is_complete = true;
    box.is_container = false;
    box.available = payload_size;
    box.is_incremental = false;
    box.seq = 0;
 
    processCallback(box);
  }
 
  void startIncrementalBox(const char* type, const uint8_t* p,
                           size_t headerSize, size_t payload_size, int level,
                           size_t bufferSize) {
    box_in_progress = true;
    box_bytes_received = 0;
    box_bytes_expected = payload_size;
    strncpy(box_type, type, 5);
    box_level = level;
    box_seq = 0;
 
    size_t available_payload = bufferSize - parseOffset - headerSize;
    incremental_offset = fileOffset + parseOffset;
    if (available_payload > 0) {
      box_bytes_received += available_payload;
      strcpy(box.type, box_type);
      ++box.id;
      box.data = p + headerSize;
      box.size = box_bytes_expected;
      box.data_size = box_bytes_expected;
      box.available = available_payload;
      box.level = box_level;
      box.file_offset = incremental_offset;
      box.seq = 0;
      box.is_incremental = true;
      box.is_complete = false;
      box.is_container = false;
      processCallback(box);
    }
    // fileOffset += (bufferSize - buffer.available());
    if (payload_size == SIZE_MAX) {
      // unbounded box (extends to EOF): its end is unknown, so only
      // advance past the header that was just consumed
      fileOffset += (parseOffset + headerSize);
    } else {
      fileOffset += (parseOffset + payload_size + headerSize);
    }
    incremental_offset += available_payload;
    buffer.clear();
    parseOffset = 0;
  }
 
  bool continueIncrementalBox() {
    size_t to_read = std::min((size_t)box_bytes_expected - box_bytes_received,
                              (size_t)buffer.available());
    if (to_read == 0) return true;
    strcpy(box.type, box_type);
    ++box.id;
    box.data = buffer.data();
    box.size = box_bytes_expected;
    box.data_size = box_bytes_expected;
    box.available = to_read;
    box.level = box_level;
    box.file_offset = incremental_offset;
    box.is_complete = (box_bytes_received + to_read == box_bytes_expected);
    box.is_container = false;
    box.is_incremental = true;
    box.seq = ++box_seq;
    processCallback(box);
    box_bytes_received += to_read;
    // fileOffset += to_read;
    buffer.clearArray(to_read);
    incremental_offset += to_read;
 
    if (box_bytes_received >= box_bytes_expected) {
      box_in_progress = false;
    }
    return false;
  }
 
  void finalizeParse() {
    if (parseOffset > 0) {
      fileOffset += parseOffset;
      buffer.clearArray(parseOffset);
      parseOffset = 0;
    }
  }
 
  uint64_t currentFileOffset() { return fileOffset + parseOffset; }
 
  static uint32_t readU32(const uint8_t* p) {
    return (p[0] << 24) | (p[1] << 16) | (p[2] << 8) | p[3];
  }
 
  static uint64_t readU64(const uint8_t* p) {
    return ((uint64_t)readU32(p) << 32) | readU32(p + 4);
  }
 
 
  void popLevels() {
    // Pop levels if we've passed their bounds (absolute file offset)
    while (!levelStack.empty() &&
           (fileOffset + parseOffset) >= levelStack.back()) {
      levelStack.pop_back();
    }
  }
 
  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;
      }
    }
    if ((!is_called || call_generic) && callback) callback(box, ref);
  }
 
  bool isContainerBox(const char* type) {
    // fill with default values if nothing has been defined
    if (containers.empty()) {
      // pure containers
      static const char* containers_str[] = {
          "moov", "trak", "mdia", "minf", "stbl", "edts", "dinf", "udta",
          "ilst", "moof", "traf", "mfra", "tref", "iprp", "sinf", "schi"};
      for (const char* c : containers_str) {
        ContainerInfo info;
        info.name = c;
        info.start = 0;
        containers.push_back(info);
      }
      // container with data
      ContainerInfo info;
      info.name = "meta";
      info.start = 4;  // 4 bytes: version (1 byte) + flags (3 bytes)
      containers.push_back(info);
    }
    // find the container by name
    for (auto& cont : containers) {
      if (StrView(type) == cont.name) return true;
    }
    return false;
  }
 
  int getContainerDataLength(const char* type) {
    for (auto& cont : containers) {
      if (StrView(type) == cont.name) return cont.start;
    }
    return 0;
  }
 
  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]));
  }
 
  size_t checkParseOffset() {
    size_t current = parseOffset;
    const char* type = (char*)(buffer.data() + parseOffset + 4);
    for (int j = 0; j < buffer.available() - parseOffset - 4; j += 4) {
      if (isValidType(type, j)) {
        if (j != 0) {
          // report the data under the last valid box
          box.size = 0;
          box.data_size = j;
          box.level = static_cast<int>(levelStack.size()) + 1;
          box.data = buffer.data() + parseOffset;
          processCallback(box);
        }
 
        return j + parseOffset;
      }
    }
    return parseOffset;
  }
};
 
}  // namespace audio_tools