Parse::Matroska::Element - a mid-level representation of an EBML element


version 0.001001


    use Parse::Matroska::Reader;
    my $reader = Parse::Matroska::Reader->new($path);
    my $elem = $reader->read_element;

    print "ID: $elem->{elid}\n";
    print "Name: $elem->{name}\n";
    print "Length: $elem->{content_len}\n";
    print "Type: $elem->{type}\n";
    print "Child count: ", scalar(@{$elem->all_children}), "\n";
    if ($elem->{type} eq 'sub') {
        while (my $chld = $elem->next_child) {
            print "Child Name: $chld->{name}\n";
    } else {
        print "Value: ", $elem->get_value, "\n";


Represents a single Matroska element as decoded by Parse::Matroska::Reader. This is essentially a hash augmented with functions for delay-loading of binary values and children elements.



The EBML Element ID, suitable for passing to "elem_by_hexid" in Parse::Matroska::Definitions.


The EBML Element's name.


The EBML Element's type. Can be uint, sint, float, ebml_id, str or binary. See "value" for details.

Equivalent to elem_by_hexid($elem->{value})->{valtype}.


The EBML Element's value. Should be obtained through "get_value".

Is an unicode string if the "type" is str, that is, the string has already been decoded by "decode" in Encode.

Is undef if the "type" is binary and the contents were delay-loaded and not yet read. "get_value" will do the delayed load if needed.

Is an arrayref if the "type" is sub, containing the children nodes that were already loaded.

Is a hashref if the "type" is ebml_id, containing the referred element's information as defined in Parse::Matroska::Definitions. Calling elem_by_hexid($elem->{value}->{elid}) will return the same object as $elem->{value}.


The entire length of this EBML Element, including the header's.


The length of the size marker. Used when calculating "full_len" from "content_len"


The length of the contents of this EBML Element, which excludes the header.


A weakened reference to the associated Parse::Matroska::Reader.



Creates a new Element initialized with the hash given as argument.


Called by "new" on initialization.


Called by the user to ignore the contents of this EBML node. Needed when ignoring the children of a node.


Returns the value contained by this EBML element.

If the element has children, returns an arrayref to the children elements that were already encountered.

If the element's type is binary and the value was delay-loaded, does the reading now.

If $keep_bin is true, the delay-loaded data is kept as the "value", otherwise, further calls to get_value will reread the data from the "reader".


Builtin iterator; reads and returns the next child element. Always returns undef if the type isn't sub.

Returns undef at the end of the iterator and resets itself to point to the first element; so calling "next_child($read_bin)" after the iterator returned undef will return the first child.

The optional $read_bin parameter has the children elements not delay-load their value if their type is binary.

If all children elements have already been read, return each element in-order as would be given by "all_children($recurse,$read_bin)".


Calls "populate_children($recurse,$read_bin)" on self and returns an arrayref with the children nodes.

Both $recurse and $read_bin are optional and default to false.


Searches in the already read children elements for all elements with the EBML name $name. Returns the found element if only one was found, or an arrayref containing all found elements. If no elements are found, an empty arrayref is returned.


Populates the internal array of children elements, that is, requests that the associated Matroska::Parser::Reader reads all children elements.

If $recurse is provided and is true, the method will call itself in the children elements with the same parameters it received; this will build a full EBML tree.

If $read_bin is provided and is true, disables delay-loading of the contents of binary-type nodes, reading the contents to memory.

If both $recurse and $read_bin are true, entire EBML trees can be loaded without requiring seeks, thus behaving correctly on unseekable streams. If $read_bin is false, the entire EBML tree is still loaded, but calling "get_value" on binary-type nodes will produce an error on unseekable streams.


The API of this module is not yet considered stable.


Kovensky <>


This software is Copyright (c) 2012 by Diogo Franco.

This is free software, licensed under:

  The (two-clause) FreeBSD License