ebml

README

EBML

An EBML parser written in Go.

• Introduction
• Production readiness
• Documents
• Similar libraries

Introduction

Extensible Binary Meta Language (EBML) is a generalized file format for any kind of data, aiming to be a binary equivalent to XML. It provides a basic framework for storing data in XML-like tags. It was originally developed for the Matroska audio/video container format.

Source: https://en.wikipedia.org/wiki/Extensible_Binary_Meta_Language

This library is based on the July 2020 version of RFC 8794 (with additions from github.com/ietf-wg-cellar/ebml-specification). This document did not reach "Internet Standard" status yet. RFC 8794 is in a "Proposed Standard" status.

The goal of this project is to create an implementation based on the document and during the implementation provide feedback.

Production readiness

This project is still in alpha phase. In this stage the public API can change between days.

Beta version will be considered when the feature set covers the documents the implementation is based on, and the public API is reached a mature state.

Stable version will be considered only if enough positive feedback is gathered to lock the public API and all document the implementation is based on became "Internet Standard".

Documents

Official sites

• libEBML
• EBML Specification
• Matroska
• Matroska Element Specification
• WebM
• WebM Container Guidelines

Huge thanks to the Matroska.org for their work.

IETF Documents

• RFC 8794: Extensible Binary Meta Language

Huge thanks to the IETF CELLAR Working Group for their work.

Inspiration

Inspiration for the implementation comes from the following places:

• https://pkg.go.dev/database/sql#Drivers
• https://pkg.go.dev/database/sql#Register
• https://pkg.go.dev/encoding/json#Decoder
• https://pkg.go.dev/golang.org/x/image/vp8#Decoder

Similar libraries

Last updated: 2025-04-09

URL	Status
https://github.com/at-wat/ebml-go	In active development
https://github.com/ebml-go/ebml + https://github.com/ebml-go/webm	Last updated on 17 Nov 2022
https://github.com/ehmry/go-ebml	Deleted
https://github.com/jacereda/ebml	Last updated on 10 Jan 2016
https://github.com/mediocregopher/ebmlstream	Last updated on 15 Dec 2014
https://github.com/pankrator/ebml-parser	Last updated on 24 Jun 2020
https://github.com/pixelbender/go-matroska	Last updated on 29 Oct 2018
https://github.com/pubblic/ebml	Last updated on 12 Dec 2018
https://github.com/quadrifoglio/go-mkv	Last updated on 20 Jun 2018
https://github.com/rrerolle/ebml-go	Last updated on 1 Dec 2012
https://github.com/remko/go-mkvparse	Last updated on 9 Aug 2023
https://github.com/tpjg/ebml-go	Last updated on 1 Dec 2012

Documentation

Overview

Package ebml implements a simple EBML parser.

The EBML specification is RFC 8794.

Index

• Variables
• func DocTypes() []string
• func Register(docType string, s schema.Schema)
• type Callbacker
• type DecodeSeeker
  • func (s DecodeSeeker) Seek(offset int64, whence int) (ret int64, err error)
• type DecodeTypeError
  • func (e *DecodeTypeError) Error() string
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) AsSeeker() (io.Seeker, bool)
  • func (d *Decoder) Decode(el Element, v interface{}) error
  • func (d *Decoder) DecodeBody(v interface{}) error
  • func (d *Decoder) DecodeHeader() (*EBML, error)
  • func (d *Decoder) EndOfKnownDataSize(parent Element, offset int64) bool
  • func (d *Decoder) EndOfUnknownDataSize(parent Element, el Element) bool
  • func (d *Decoder) NextOf(parent Element, offset int64) (el Element, n int, err error)
  • func (d *Decoder) SetCallback(c Callbacker)
  • func (d *Decoder) Skip(el Element) error
  • func (d *Decoder) SkipByte() error
• type Def
  • func Definition(docType string) (*Def, error)
  • func NewDef(s schema.Schema) (*Def, error)
  • func (d *Def) All() iter.Seq[schema.Element]
  • func (d *Def) Fields(path string) iter.Seq[schema.Element]
  • func (d *Def) Get(id schema.ElementID) (schema.Element, bool)
• type DocTypeExtension
• type EBML
• type Element
• type InvalidDecodeError
  • func (e *InvalidDecodeError) Error() string
• type UnknownDocTypeError
  • func (e UnknownDocTypeError) Error() string

Variables

var (
	IDEBML                    schema.ElementID = 0x1a45dfa3
	IDEBMLVersion             schema.ElementID = 0x4286
	IDEBMLReadVersion         schema.ElementID = 0x42f7
	IDEBMLMaxIDLength         schema.ElementID = 0x42f2
	IDEBMLMaxSizeLength       schema.ElementID = 0x42f3
	IDDocType                 schema.ElementID = 0x4282
	IDDocTypeVersion          schema.ElementID = 0x4287
	IDDocTypeReadVersion      schema.ElementID = 0x4285
	IDDocTypeExtension        schema.ElementID = 0x4281
	IDDocTypeExtensionName    schema.ElementID = 0x4283
	IDDocTypeExtensionVersion schema.ElementID = 0x4284
	IDVoid                    schema.ElementID = 0xec
	IDCRC32                   schema.ElementID = 0xbf
)

var (
	HeaderDef *Def

	DefaultMaxIDLength   uint = 4
	DefaultMaxSizeLength uint = 8
)

var (
	TypeInteger  = "integer"
	TypeUinteger = "uinteger"
	TypeFloat    = "float"
	TypeString   = "string"
	TypeDate     = "date"
	TypeUTF8     = "utf-8"
	TypeMaster   = "master"
	TypeBinary   = "binary"
)

var DefaultAllocationWindow = int64(1<<24) - 1

var ErrElementOverflow = errors.New("ebml: element overflow")

ErrElementOverflow signals that an element signals a length greater than the parent DataSize.

var ErrInvalidVINTLength = ebmltext.ErrInvalidVINTWidth

var RootEl = Element{DataSize: -1, Schema: schema.Element{Name: "root", Type: TypeMaster}}

var UnknownSchema = schema.Element{
	Name:          "Unknown element",
	Documentation: []schema.Documentation{{Content: "The purpose of this object is to signal an error."}},
}

Functions

func DocTypes

func DocTypes() []string

DocTypes returns a sorted list of the names of the registered document types.

func Register

func Register(docType string, s schema.Schema)

Register makes a schema.Schema available by the provided doc type. If Register is called twice with the same name or if driver is nil, it panics.

Types

type Callbacker

type Callbacker interface {
	// Found is called whenever a new element is found in the target io.Reader.
	Found(el Element, offset int64, headerSize int) Callbacker
	// Decoded is called whenever an element is decoded from the target io.Reader.
	Decoded(el Element, offset int64, headerSize int, val any) Callbacker
}

type DecodeSeeker

type DecodeSeeker struct {
	// contains filtered or unexported fields
}

func (DecodeSeeker) Seek

func (s DecodeSeeker) Seek(offset int64, whence int) (ret int64, err error)

type DecodeTypeError

type DecodeTypeError struct {
	EBMLType string       // description of EBML type - "integer", "binary", "master"
	Type     reflect.Type // type of Go value it could not be assigned to
	Offset   int64        // error occurred after reading Offset bytes
	Path     string       // the full path from root node to the field
}

An DecodeTypeError describes an EBML value that was not appropriate for a value of a specific Go type.

func (*DecodeTypeError) Error

func (e *DecodeTypeError) Error() string

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

A Decoder represents an EBML parser reading a particular input stream.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder reads and parses an EBML Document from r.

func (*Decoder) AsSeeker

func (d *Decoder) AsSeeker() (io.Seeker, bool)

func (*Decoder) Decode

func (d *Decoder) Decode(el Element, v interface{}) error

func (*Decoder) DecodeBody

func (d *Decoder) DecodeBody(v interface{}) error

DecodeBody decodes the EBML Body and stores the result in the value pointed to by v. If v is nil or not a pointer, DecodeBody returns an InvalidDecodeError.

func (*Decoder) DecodeHeader

func (d *Decoder) DecodeHeader() (*EBML, error)

DecodeHeader decodes the document header.

func (*Decoder) EndOfKnownDataSize

func (d *Decoder) EndOfKnownDataSize(parent Element, offset int64) bool

EndOfKnownDataSize tries to guess the end of an element which has a know data size.

A parent with unknown data size won't raise an error but not handled as the end of the parent.

func (*Decoder) EndOfUnknownDataSize

func (d *Decoder) EndOfUnknownDataSize(parent Element, el Element) bool

EndOfUnknownDataSize tries to guess the end of an element which has an unknown data size.

A parent with known data size won't raise an error but not handled as the end of the parent.

func (*Decoder) NextOf

func (d *Decoder) NextOf(parent Element, offset int64) (el Element, n int, err error)

NextOf reads the following element id and data size related to the given parent Element.

When NextOf encounters io.EOF or end-of-element condition, it returns io.EOF.

When NextOf encounters ErrElementOverflow fo known data size, you can skip the parent object, or you can read until the parent ends.

See Next about ErrInvalidVINTLength.

func (*Decoder) SetCallback

func (d *Decoder) SetCallback(c Callbacker)

SetCallback adds a Callbacker which is triggered when NextOf reads element id and data size, and when a value is successfully decoded.

func (*Decoder) Skip

func (d *Decoder) Skip(el Element) error

func (*Decoder) SkipByte

func (d *Decoder) SkipByte() error

type Def

type Def struct {
	Root schema.Element
	// contains filtered or unexported fields
}

func Definition

func Definition(docType string) (*Def, error)

func NewDef

func NewDef(s schema.Schema) (*Def, error)

func (*Def) All

func (d *Def) All() iter.Seq[schema.Element]

func (*Def) Fields

func (d *Def) Fields(path string) iter.Seq[schema.Element]

func (*Def) Get

func (d *Def) Get(id schema.ElementID) (schema.Element, bool)

type DocTypeExtension

type DocTypeExtension struct {
	DocTypeExtensionName    string
	DocTypeExtensionVersion uint
}

type EBML

type EBML struct {
	EBMLVersion        uint
	EBMLReadVersion    uint
	EBMLMaxIDLength    uint
	EBMLMaxSizeLength  uint
	DocType            string
	DocTypeVersion     uint
	DocTypeReadVersion uint
	DocTypeExtension   []DocTypeExtension
}

type Element

type Element struct {
	ID schema.ElementID

	// DataSize expresses the length of Element Data. Unknown data length is
	// represented with `-1`.
	//
	// With 8 octets it can have 2^56-2 possible values. That fits into int64.
	DataSize int64

	Schema schema.Element
}

type InvalidDecodeError

type InvalidDecodeError struct {
	Type reflect.Type
}

An InvalidDecodeError describes an invalid argument passed to Unmarshal. (The argument to Unmarshal must be a non-nil pointer.)

func (*InvalidDecodeError) Error

func (e *InvalidDecodeError) Error() string

type UnknownDocTypeError

type UnknownDocTypeError struct {
	DocType string
}

func (UnknownDocTypeError) Error

func (e UnknownDocTypeError) Error() string