ebml

package module
v0.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 20, 2020 License: Apache-2.0 Imports: 11 Imported by: 11

README

ebml-go

GoDoc Build Status codecov Go Report Card License

A pure Go implementation of bi-directional EBML encoder/decoder

EBML (Extensible Binary Meta Language) is a binary and byte-aligned format that was originally developed for the Matroska audio-visual container. See https://matroska.org/ for details.

This package implements EBML Marshaler and Unmarshaler for Go. Currently, commonly used elements of WebM subset is supported.

Usage

Check out the examples placed under ./examples directory.

API is documented using GoDoc. EBML can be Marshal-ed and Unmarshal-ed between tagged struct and binary stream through io.Reader and io.Writer.

References

License

This package is licensed under Apache License Version 2.0.

Documentation

Overview

Package ebml implements the encoder and decoder of Extensible Binary Meta Language (EBML).

The package supports Marshal and Unmarshal between tagged struct and EBML binary stream. WebM block data writer is provided as webm sub-package.

Index

Examples

Constants

View Source
const (
	ElementTimecodeScale = ElementTimestampScale
	ElementTimecode      = ElementTimestamp
)

WebM aliases

View Source
const (
	// DateEpochInUnixtime is the Unixtime of EBML date epoch.
	DateEpochInUnixtime = 978307200
	// SizeUnknown is the longest unknown size value.
	SizeUnknown = 0xffffffffffffff
)

Variables

View Source
var ErrEmptyTag = errors.New("empty tag in tag string")

ErrEmptyTag means that a tag string has empty item.

View Source
var ErrFixedLaceUndivisible = errors.New("undivisible fixed lace")

ErrFixedLaceUndivisible means that a length of a fixed lacing data is undivisible.

View Source
var ErrIncompatibleType = errors.New("marshal/unmarshal to incompatible type")

ErrIncompatibleType means that an element is not convertible to a corresponding struct field.

View Source
var ErrIndefiniteType = errors.New("marshal/unmarshal to indefinite type")

ErrIndefiniteType means that a marshal/unmarshal destination type is not valid.

View Source
var ErrInvalidFloatSize = errors.New("invalid float size")

ErrInvalidFloatSize means that a element size is invalid for float type. Float must be 4 or 8 bytes.

View Source
var ErrInvalidTag = errors.New("invalid tag in tag string")

ErrInvalidTag means that an invaild tag is specified.

View Source
var ErrInvalidType = errors.New("invalid type")

ErrInvalidType means that a value is not convertible to the element data.

View Source
var ErrNonStringMapKey = errors.New("non-string map key")

ErrNonStringMapKey is returned if input is map and key is not a string.

View Source
var ErrTooManyFrames = errors.New("too many frames")

ErrTooManyFrames means that a number of frames exceeds the limit.

View Source
var ErrUnevenFixedLace = errors.New("uneven size of frames in fixed lace")

ErrUnevenFixedLace means that an uneven number of frames are stored in a fixed lacing block.

View Source
var ErrUnknownElement = errors.New("unknown element")

ErrUnknownElement means that a decoded element is not known.

View Source
var ErrUnknownElementName = errors.New("unknown element name")

ErrUnknownElementName means that a element name is not found in the ElementType list.

View Source
var ErrUnsupportedElement = errors.New("unsupported element")

ErrUnsupportedElement means that a element name is known but unsupported in this version of ebml-go.

View Source
var ErrUnsupportedElementID = errors.New("unsupported Element ID")

ErrUnsupportedElementID means that a value is out of range of EBML encoding.

Functions

func Marshal

func Marshal(val interface{}, w io.Writer, opts ...MarshalOption) error

Marshal struct to EBML bytes.

Examples of struct field tags:

// Field appears as element "EBMLVersion".
Field uint64 `ebml:EBMLVersion`

// Field appears as element "EBMLVersion" and
// the field is omitted from the output if the value is empty.
Field uint64 `ebml:TheElement,omitempty`

// Field appears as element "EBMLVersion" and
// the field is omitted from the output if the value is empty.
EBMLVersion uint64 `ebml:,omitempty`

// Field appears as master element "Segment" and
// the size of the element contents is left unknown for streaming data.
Field struct{} `ebml:Segment,size=unknown`

// Field appears as master element "Segment" and
// the size of the element contents is left unknown for streaming data.
// This style may be deprecated in the future.
Field struct{} `ebml:Segment,inf`

// Field appears as element "EBMLVersion" and
// the size of the element data is reserved by 4 bytes.
Field uint64 `ebml:EBMLVersion,size=4`
Example
type EBMLHeader struct {
	DocType            string `ebml:"EBMLDocType"`
	DocTypeVersion     uint64 `ebml:"EBMLDocTypeVersion"`
	DocTypeReadVersion uint64 `ebml:"EBMLDocTypeReadVersion"`
}
type TestEBML struct {
	Header EBMLHeader `ebml:"EBML"`
}
s := TestEBML{
	Header: EBMLHeader{
		DocType:            "webm",
		DocTypeVersion:     2,
		DocTypeReadVersion: 2,
	},
}

var b bytes.Buffer
if err := Marshal(&s, &b); err != nil {
	panic(err)
}
for _, b := range b.Bytes() {
	fmt.Printf("0x%02x, ", int(b))
}
Output:
0x1a, 0x45, 0xdf, 0xa3, 0x90, 0x42, 0x82, 0x85, 0x77, 0x65, 0x62, 0x6d, 0x00, 0x42, 0x87, 0x81, 0x02, 0x42, 0x85, 0x81, 0x02,

func MarshalBlock

func MarshalBlock(b *Block, w io.Writer) error

MarshalBlock marshals EBML Block structure.

func Unmarshal

func Unmarshal(r io.Reader, val interface{}, opts ...UnmarshalOption) error

Unmarshal EBML stream.

Example
TestBinary := []byte{
	0x1a, 0x45, 0xdf, 0xa3, // EBML
	0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, // 0x10
	0x42, 0x82, 0x85, 0x77, 0x65, 0x62, 0x6d, 0x00,
	0x42, 0x87, 0x81, 0x02, 0x42, 0x85, 0x81, 0x02,
}
type TestEBML struct {
	Header struct {
		DocType            string `ebml:"EBMLDocType"`
		DocTypeVersion     uint64 `ebml:"EBMLDocTypeVersion"`
		DocTypeReadVersion uint64 `ebml:"EBMLDocTypeReadVersion"`
	} `ebml:"EBML"`
}

r := bytes.NewReader(TestBinary)

var ret TestEBML
if err := Unmarshal(r, &ret); err != nil {
	fmt.Printf("error: %v\n", err)
}
fmt.Println(ret)
Output:
{{webm 2 2}}

Types

type Block

type Block struct {
	TrackNumber uint64
	Timecode    int16
	Keyframe    bool
	Invisible   bool
	Lacing      LacingMode
	Discardable bool
	Data        [][]byte
}

Block represents EBML Block/SimpleBlock element.

func UnmarshalBlock

func UnmarshalBlock(r io.Reader, n int64) (*Block, error)

UnmarshalBlock unmarshals EBML Block structure.

type DataType added in v0.9.0

type DataType int

DataType represents EBML Element data type.

const (
	DataTypeMaster DataType = iota
	DataTypeInt
	DataTypeUInt
	DataTypeDate
	DataTypeFloat
	DataTypeBinary
	DataTypeString
	DataTypeBlock
)

EBML Element data types.

func (DataType) String added in v0.9.0

func (t DataType) String() string

type Element added in v0.2.0

type Element struct {
	Value    interface{}
	Name     string
	Type     ElementType
	Position uint64
	Size     uint64
	Parent   *Element
}

Element represents an EBML element.

type ElementType

type ElementType int

ElementType represents EBML Element type.

const (
	ElementInvalid ElementType = iota

	ElementEBML
	ElementEBMLVersion
	ElementEBMLReadVersion
	ElementEBMLMaxIDLength
	ElementEBMLMaxSizeLength
	ElementEBMLDocType
	ElementEBMLDocTypeVersion
	ElementEBMLDocTypeReadVersion

	ElementVoid
	ElementSegment

	ElementSeekHead
	ElementSeek
	ElementSeekID
	ElementSeekPosition

	ElementInfo
	ElementSegmentUID
	ElementSegmentFilename
	ElementTimestampScale
	ElementDuration
	ElementDateUTC
	ElementTitle
	ElementMuxingApp
	ElementWritingApp

	ElementCluster
	ElementTimestamp
	ElementPosition
	ElementPrevSize
	ElementSimpleBlock
	ElementBlockGroup
	ElementBlock
	ElementBlockAdditions
	ElementBlockMore
	ElementBlockAddID
	ElementBlockAdditional
	ElementBlockDuration
	ElementReferenceBlock
	ElementDiscardPadding

	ElementTracks
	ElementTrackEntry
	ElementTrackNumber
	ElementTrackUID
	ElementTrackType
	ElementFlagEnabled
	ElementFlagForced
	ElementFlagLacing
	ElementDefaultDuration
	ElementName
	ElementLanguage
	ElementCodecID
	ElementCodecPrivate
	ElementCodecName
	ElementCodecDelay
	ElementSeekPreRoll
	ElementVideo
	ElementFlagInterlaced
	ElementStereoMode
	ElementAlphaMode
	ElementPixelWidth
	ElementPixelHeight
	ElementPixelCropBottom
	ElementPixelCropTop
	ElementPixelCropLeft
	ElementPixelCropRight
	ElementDisplayWidth
	ElementDisplayHeight
	ElementDisplayUnit
	ElementAspectRatioType
	ElementAudio
	ElementSamplingFrequency
	ElementOutputSamplingFrequency
	ElementChannels
	ElementBitDepth
	ElementContentEncodings
	ElementContentEncoding
	ElementContentEncodingOrder
	ElementContentEncodingScope
	ElementContentEncodingType
	ElementContentEncryption
	ElementContentEncAlgo
	ElementContentEncKeyID
	ElementContentEncAESSettings
	ElementAESSettingsCipherMode

	ElementCues
	ElementCuePoint
	ElementCueTime
	ElementCueTrackPositions
	ElementCueTrack
	ElementCueClusterPosition
	ElementCueBlockNumber

	ElementTags
	ElementTag
	ElementSimpleTag
	ElementTagName
	ElementTagString
	ElementTagBinary
)

EBML Element types.

func ElementTypeFromString

func ElementTypeFromString(s string) (ElementType, error)

ElementTypeFromString converts string to ElementType.

func (ElementType) Bytes added in v0.5.0

func (i ElementType) Bytes() []byte

Bytes returns []byte representation of the element ID.

func (ElementType) DataType added in v0.9.0

func (i ElementType) DataType() DataType

DataType returns DataType of the element.

func (ElementType) String

func (i ElementType) String() string

type Error added in v0.10.0

type Error struct {
	Err     error
	Failure string
}

Error records a failed parsing.

func (*Error) Error added in v0.10.0

func (e *Error) Error() string

func (*Error) Is added in v0.10.0

func (e *Error) Is(target error) bool

Is reports whether chained error contains target. This is for Go1.13 error unwrapping.

func (*Error) Unwrap added in v0.10.0

func (e *Error) Unwrap() error

Unwrap returns the reason of the failure. This is for Go1.13 error unwrapping.

type Lacer added in v0.8.0

type Lacer interface {
	Write([][]byte) error
}

Lacer is the interface to read laced frames in Block.

func NewEBMLLacer added in v0.8.0

func NewEBMLLacer(w io.Writer) Lacer

NewEBMLLacer creates Lacer for EBML laced data.

func NewFixedLacer added in v0.8.0

func NewFixedLacer(w io.Writer) Lacer

NewFixedLacer creates Lacer for Fixed laced data.

func NewNoLacer added in v0.8.0

func NewNoLacer(w io.Writer) Lacer

NewNoLacer creates pass-through Lacer for not laced data.

func NewXiphLacer added in v0.8.0

func NewXiphLacer(w io.Writer) Lacer

NewXiphLacer creates Lacer for Xiph laced data.

type LacingMode

type LacingMode uint8

LacingMode is type of laced data.

const (
	LacingNo    LacingMode = 0
	LacingXiph  LacingMode = 1
	LacingFixed LacingMode = 2
	LacingEBML  LacingMode = 3
)

Type of laced data.

type MarshalOption added in v0.4.0

type MarshalOption func(*MarshalOptions) error

MarshalOption configures a MarshalOptions struct.

func WithDataSizeLen added in v0.4.0

func WithDataSizeLen(l int) MarshalOption

WithDataSizeLen returns an MarshalOption which sets number of reserved bytes of element data size.

Example
type EBMLHeader struct {
	DocType            string `ebml:"EBMLDocType"`
	DocTypeVersion     uint64 `ebml:"EBMLDocTypeVersion"`
	DocTypeReadVersion uint64 `ebml:"EBMLDocTypeReadVersion"`
}
type TestEBML struct {
	Header EBMLHeader `ebml:"EBML"`
}
s := TestEBML{
	Header: EBMLHeader{
		DocType:            "webm",
		DocTypeVersion:     2,
		DocTypeReadVersion: 2,
	},
}

var b bytes.Buffer
if err := Marshal(&s, &b, WithDataSizeLen(2)); err != nil {
	panic(err)
}
for _, b := range b.Bytes() {
	fmt.Printf("0x%02x, ", int(b))
}
Output:
0x1a, 0x45, 0xdf, 0xa3, 0x40, 0x13, 0x42, 0x82, 0x40, 0x05, 0x77, 0x65, 0x62, 0x6d, 0x00, 0x42, 0x87, 0x40, 0x01, 0x02, 0x42, 0x85, 0x40, 0x01, 0x02,

func WithElementWriteHooks added in v0.7.0

func WithElementWriteHooks(hooks ...func(*Element)) MarshalOption

WithElementWriteHooks returns an MarshalOption which registers element hooks.

type MarshalOptions added in v0.4.0

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

MarshalOptions stores options for marshalling.

type Unlacer added in v0.8.0

type Unlacer interface {
	Read() ([]byte, error)
}

Unlacer is the interface to read laced frames in Block.

func NewEBMLUnlacer added in v0.8.0

func NewEBMLUnlacer(r io.Reader, n int64) (Unlacer, error)

NewEBMLUnlacer creates Unlacer for EBML laced data.

func NewFixedUnlacer added in v0.8.0

func NewFixedUnlacer(r io.Reader, n int64) (Unlacer, error)

NewFixedUnlacer creates Unlacer for Fixed laced data.

func NewNoUnlacer added in v0.8.0

func NewNoUnlacer(r io.Reader, n int64) (Unlacer, error)

NewNoUnlacer creates pass-through Unlacer for not laced data.

func NewXiphUnlacer added in v0.8.0

func NewXiphUnlacer(r io.Reader, n int64) (Unlacer, error)

NewXiphUnlacer creates Unlacer for Xiph laced data.

type UnmarshalOption added in v0.2.0

type UnmarshalOption func(*UnmarshalOptions) error

UnmarshalOption configures a UnmarshalOptions struct.

func WithElementReadHooks added in v0.2.0

func WithElementReadHooks(hooks ...func(*Element)) UnmarshalOption

WithElementReadHooks returns an UnmarshalOption which registers element hooks.

type UnmarshalOptions added in v0.2.0

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

UnmarshalOptions stores options for unmarshalling.

Directories

Path Synopsis
examples
rtp-to-webm command
webm-roundtrip command
internal
errs
Package errs is for compatibility with Go1.13 error wrapping.
Package errs is for compatibility with Go1.13 error wrapping.
Package mkv provides the Matroska multimedia writer.
Package mkv provides the Matroska multimedia writer.
Package mkvcore provides the core functionality of Matroska/WebM multimedia writer.
Package mkvcore provides the core functionality of Matroska/WebM multimedia writer.
Package webm provides the WebM multimedia writer.
Package webm provides the WebM multimedia writer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL