InputStream Adaptive

The Reader interface acts as the data source for the parser. You can subclass Reader to implement your own data source.

Provided Implementations

If you do not want to implement a custom one, use these built-in blocking readers:

• FileReader: Reads from a FILE*.
• IstreamReader: Reads from a std::istream.
• BufferReader: Reads from a std::vector<std::uint8_t>.

Handling Partial Reads and EOF

• Partial Reads: If Reader::Skip() or Reader::Read() return Status::kOkPartial, the parser will attempt to call them again.
• Blocking/Waiting: If no data is available, return Status::kWouldBlock. The parser will stop and can be resumed later when more data is available.
• End of File: When no more data is available, return Status::kEndOfFile.
  • If the file ended at a valid location, the parser returns Status::kOkCompleted.
  • If the file ended prematurely, the parser returns Status::kEndOfFile.
• Post-EOF calls: Implementations should be able to handle being called multiple times after Status::kEndOfFile has been returned (e.g., by nested parsers terminating) and should consistently return Status::kEndOfFile in those cases.

To react to WebM parsing events (like when an element begins), you must create a class that inherits from video_webm_parser::Callback and overrides its virtual methods.

In the OnElementBegin override, you receive video_webm_parser::ElementMetadata containing the element's id, position, header_size, and size. You must also set the video_webm_parser::Action* action pointer to determine the next step (e.g., video_webm_parser::Action::kRead) and return a video_webm_parser::Status.

#include <iomanip>
#include <iostream>
#include <webm/callback.h>
#include <webm/file_reader.h>
#include <webm/status.h>
#include <webm/webm_parser.h>

class MyCallback : public video_webm_parser::Callback {
 public:
  video_webm_parser::Status OnElementBegin(const video_webm_parser::ElementMetadata& metadata,
                                           video_webm_parser::Action* action) override {
    // Access metadata fields:
    // metadata.id
    // metadata.position
    // metadata.header_size
    // metadata.size

    // Set the action to continue reading
    *action = video_webm_parser::Action::kRead;
    return video_webm_parser::Status(video_webm_parser::Status::kOkCompleted);
  }
};

int main() {
  MyCallback callback;
  video_webm_parser::FileReader reader(std::freopen(nullptr, "rb", stdin));
  video_webm_parser::WebmParser parser;
  video_webm_parser::Status status = parser.Feed(&callback, &reader);
  
  if (status.completed_ok()) {
    std::cout << "Parsing successfully completed\n";
  } else {
    std::cout << "Parsing failed with status code: " << status.code << '\n';
  }
}

The Callback class is notified as the parser builds objects representing WebM elements. You should subclass Callback and override the methods corresponding to the elements you wish to process.

Core Callback Methods

• OnElementBegin(): Called for every element encountered. Useful for mapping the file structure or skipping elements.
• OnUnknownElement(): Called when an element is unrecognized or improperly nested. The default behavior is to skip the element.
• OnVoid(): Called to handle Void elements.

Element Nesting and Lifecycle

Most methods follow a *Begin() and *End() pattern. The parser guarantees that these are called in the proper nesting order defined by the WebM DOM. For example, OnTrackEntry() will only be called between OnSegmentBegin() and OnSegmentEnd().

Controlling Parser Flow

• Continue Parsing: Return Status::kOkCompleted from a callback method.
• Stop Parsing: Return any other status code (except Status::kEndOfFile). The parser will stop and return that status to the caller.
• Resuming: If you return a non-error status (like Status::kWouldBlock or a custom status > 0), the parser may be resumed, and it will call the same callback method again.

/* Example of the nesting order for specific elements */
// Callback::OnEbml()
// Callback::OnSegmentBegin()
//    Callback::OnSeek()
//    Callback::OnInfo()
//    Callback::OnClusterBegin()
//       Callback::OnSimpleBlockBegin()
//          Callback::OnFrame()
//       Callback::OnSimpleBlockEnd()
//       ...
//    Callback::OnClusterEnd()
//    Callback::OnTrackEntry()
//    ...
// Callback::OnSegmentEnd()

To parse a WebM file, construct a WebmParser instance and call WebmParser::Feed(), passing in your Reader and Callback implementations.

Standard Parsing

WebmParser parser;
// parser.Feed(callback, reader) returns Status::kOkCompleted on success
Status status = parser.Feed(myCallback, myReader);

Seeking to the middle of a file

If you want to start parsing from an arbitrary point, you must call WebmParser::DidSeek() before calling Feed().

Important: You must seek to the beginning of a WebM element. Seeking to a location that is not the start of an element (like the middle of a frame) will cause parsing to fail.

Calling DidSeek() resets the parser state and clears internal errors, allowing the same WebmParser instance to be reused for a different file or a different seek location.

WebmParser parser;

// To start from the middle of a file:
parser.DidSeek(); 

// Then feed the data starting from that element:
Status status = parser.Feed(myCallback, myReader);