ebml

package module
v0.20.7 Latest Latest
Warning

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

Go to latest
Published: Sep 7, 2023 License: Apache-2.0 Imports: 11 Imported by: 0

README

ebml-go

GoDoc ci 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 ErrInvalidElementSize = errors.New("invalid element size")

ErrInvalidElementSize means that an element has inconsistent size. e.g. element size is larger than its parent element size.

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 ErrOutOfRange = errors.New("out of range")

ErrOutOfRange means that a value is out of range of the data type.

View Source
var ErrReadStopped = errors.New("read stopped")

ErrReadStopped is returned if unmarshaler finished to read element which has stop tag.

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, // EBMLDocType = webm
	0x42, 0x87, 0x81, 0x02, // DocTypeVersion = 2
	0x42, 0x85, 0x81, 0x02, // DocTypeReadVersion = 2
}
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}}
Example (Partial)
TestBinary := []byte{
	0x1a, 0x45, 0xdf, 0xa3, 0x84, // EBML
	0x42, 0x87, 0x81, 0x02, // DocTypeVersion = 2
	0x18, 0x53, 0x80, 0x67, 0xFF, // Segment
	0x16, 0x54, 0xae, 0x6b, 0x85, // Tracks
	0xae, 0x83, // TrackEntry[0]
	0xd7, 0x81, 0x01, // TrackNumber=1
	0x1F, 0x43, 0xB6, 0x75, 0xFF, // Cluster
	0xE7, 0x81, 0x00, // Timecode
	0xA3, 0x86, 0x81, 0x00, 0x00, 0x88, 0xAA, 0xCC, // SimpleBlock
}

type TestHeader struct {
	Header  map[string]interface{} `ebml:"EBML"`
	Segment struct {
		Tracks map[string]interface{} `ebml:"Tracks,stop"` // Stop unmarshalling after reading this element
	}
}
type TestClusters struct {
	Cluster []struct {
		Timecode    uint64
		SimpleBlock []Block
	}
}

r := bytes.NewReader(TestBinary)

var header TestHeader
if err := Unmarshal(r, &header); !errs.Is(err, ErrReadStopped) {
	panic("Unmarshal failed")
}
fmt.Printf("First unmarshal: %v\n", header)

var clusters TestClusters
if err := Unmarshal(r, &clusters); err != nil {
	panic("Unmarshal failed")
}
fmt.Printf("Second unmarshal: %v\n", clusters)
Output:

First unmarshal: {map[EBMLDocTypeVersion:2] {map[TrackEntry:map[TrackNumber:1]]}}
Second unmarshal: {[{0 [{1 0 true true 0 false [[170 204]]}]}]}

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

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

func (t DataType) String() string

type Element

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

	ElementCRC32
	ElementVoid
	ElementSegment

	ElementSeekHead
	ElementSeek
	ElementSeekID
	ElementSeekPosition

	ElementInfo
	ElementSegmentUID
	ElementSegmentFilename
	ElementPrevUID
	ElementPrevFilename
	ElementNextUID
	ElementNextFilename
	ElementSegmentFamily
	ElementChapterTranslate
	ElementChapterTranslateEditionUID
	ElementChapterTranslateCodec
	ElementChapterTranslateID
	ElementTimestampScale
	ElementDuration
	ElementDateUTC
	ElementTitle
	ElementMuxingApp
	ElementWritingApp

	ElementCluster
	ElementTimestamp
	ElementSilentTracks
	ElementSilentTrackNumber
	ElementPosition
	ElementPrevSize
	ElementSimpleBlock
	ElementBlockGroup
	ElementBlock
	ElementBlockAdditions
	ElementBlockMore
	ElementBlockAddID
	ElementBlockAdditional
	ElementBlockDuration
	ElementReferencePriority
	ElementReferenceBlock
	ElementCodecState
	ElementDiscardPadding
	ElementSlices
	// Deprecated: Dropped in v2
	ElementTimeSlice
	// Deprecated: Dropped in v2
	ElementLaceNumber

	ElementTracks
	ElementTrackEntry
	ElementTrackNumber
	ElementTrackUID
	ElementTrackType
	ElementFlagEnabled
	ElementFlagDefault
	ElementFlagForced
	ElementFlagHearingImpaired
	ElementFlagVisualImpaired
	ElementFlagTextDescriptions
	ElementFlagOriginal
	ElementFlagCommentary
	ElementFlagLacing
	ElementMinCache
	ElementMaxCache
	ElementDefaultDuration
	ElementDefaultDecodedFieldDuration
	// Deprecated: Dropped in v4
	ElementTrackTimestampScale
	ElementMaxBlockAdditionID
	ElementBlockAdditionMapping
	ElementBlockAddIDValue
	ElementBlockAddIDName
	ElementBlockAddIDType
	ElementBlockAddIDExtraData
	ElementName
	ElementLanguage
	ElementLanguageIETF
	ElementCodecID
	ElementCodecPrivate
	ElementCodecName
	// Deprecated: Dropped in v4
	ElementAttachmentLink
	ElementCodecDecodeAll
	ElementTrackOverlay
	ElementCodecDelay
	ElementSeekPreRoll
	ElementTrackTranslate
	ElementTrackTranslateEditionUID
	ElementTrackTranslateCodec
	ElementTrackTranslateTrackID
	ElementVideo
	ElementFlagInterlaced
	ElementFieldOrder
	ElementStereoMode
	ElementAlphaMode
	ElementPixelWidth
	ElementPixelHeight
	ElementPixelCropBottom
	ElementPixelCropTop
	ElementPixelCropLeft
	ElementPixelCropRight
	ElementDisplayWidth
	ElementDisplayHeight
	ElementDisplayUnit
	ElementAspectRatioType
	ElementColourSpace
	ElementColour
	ElementMatrixCoefficients
	ElementBitsPerChannel
	ElementChromaSubsamplingHorz
	ElementChromaSubsamplingVert
	ElementCbSubsamplingHorz
	ElementCbSubsamplingVert
	ElementChromaSitingHorz
	ElementChromaSitingVert
	ElementRange
	ElementTransferCharacteristics
	ElementPrimaries
	ElementMaxCLL
	ElementMaxFALL
	ElementMasteringMetadata
	ElementPrimaryRChromaticityX
	ElementPrimaryRChromaticityY
	ElementPrimaryGChromaticityX
	ElementPrimaryGChromaticityY
	ElementPrimaryBChromaticityX
	ElementPrimaryBChromaticityY
	ElementWhitePointChromaticityX
	ElementWhitePointChromaticityY
	ElementLuminanceMax
	ElementLuminanceMin
	ElementProjection
	ElementProjectionType
	ElementProjectionPrivate
	ElementProjectionPoseYaw
	ElementProjectionPosePitch
	ElementProjectionPoseRoll
	ElementAudio
	ElementSamplingFrequency
	ElementOutputSamplingFrequency
	ElementChannels
	ElementBitDepth
	ElementTrackOperation
	ElementTrackCombinePlanes
	ElementTrackPlane
	ElementTrackPlaneUID
	ElementTrackPlaneType
	ElementTrackJoinBlocks
	ElementTrackJoinUID
	ElementContentEncodings
	ElementContentEncoding
	ElementContentEncodingOrder
	ElementContentEncodingScope
	ElementContentEncodingType
	ElementContentCompression
	ElementContentCompAlgo
	ElementContentCompSettings
	ElementContentEncryption
	ElementContentEncAlgo
	ElementContentEncKeyID
	ElementContentEncAESSettings
	ElementAESSettingsCipherMode
	ElementContentSignature
	ElementContentSigKeyID
	ElementContentSigAlgo
	ElementContentSigHashAlgo

	ElementCues
	ElementCuePoint
	ElementCueTime
	ElementCueTrackPositions
	ElementCueTrack
	ElementCueClusterPosition
	ElementCueRelativePosition
	ElementCueDuration
	ElementCueBlockNumber
	ElementCueCodecState
	ElementCueReference
	ElementCueRefTime

	ElementAttachments
	ElementAttachedFile
	ElementFileDescription
	ElementFileName
	ElementFileMimeType
	ElementFileData
	ElementFileUID

	ElementChapters
	ElementEditionEntry
	ElementEditionUID
	ElementEditionFlagHidden
	ElementEditionFlagDefault
	ElementEditionFlagOrdered
	ElementChapterAtom
	ElementChapterUID
	ElementChapterStringUID
	ElementChapterTimeStart
	ElementChapterTimeEnd
	ElementChapterFlagHidden
	ElementChapterFlagEnabled
	ElementChapterSegmentUID
	ElementChapterSegmentEditionUID
	ElementChapterPhysicalEquiv
	ElementChapterTrack
	ElementChapterTrackUID
	ElementChapterDisplay
	ElementChapString
	ElementChapLanguage
	ElementChapLanguageIETF
	ElementChapCountry
	ElementChapProcess
	ElementChapProcessCodecID
	ElementChapProcessPrivate
	ElementChapProcessCommand
	ElementChapProcessTime
	ElementChapProcessData

	ElementTags
	ElementTag
	ElementTargets
	ElementTargetTypeValue
	ElementTargetType
	ElementTagTrackUID
	ElementTagEditionUID
	ElementTagChapterUID
	ElementTagAttachmentUID
	ElementSimpleTag
	ElementTagName
	ElementTagLanguage
	ElementTagLanguageIETF
	ElementTagDefault
	ElementTagString
	ElementTagBinary
)

EBML Element types.

func ElementTypeFromString

func ElementTypeFromString(s string) (ElementType, error)

ElementTypeFromString converts string to ElementType.

func (ElementType) Bytes

func (i ElementType) Bytes() []byte

Bytes returns []byte representation of the element ID.

func (ElementType) DataType

func (i ElementType) DataType() DataType

DataType returns DataType of the element.

func (ElementType) String

func (i ElementType) String() string

type Error

type Error struct {
	Err     error
	Failure string
}

Error records a failed parsing.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Is

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

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

func (*Error) Unwrap

func (e *Error) Unwrap() error

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

type Lacer

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

Lacer is the interface to read laced frames in Block.

func NewEBMLLacer

func NewEBMLLacer(w io.Writer) Lacer

NewEBMLLacer creates Lacer for EBML laced data.

func NewFixedLacer

func NewFixedLacer(w io.Writer) Lacer

NewFixedLacer creates Lacer for Fixed laced data.

func NewNoLacer

func NewNoLacer(w io.Writer) Lacer

NewNoLacer creates pass-through Lacer for not laced data.

func NewXiphLacer

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

type MarshalOption func(*MarshalOptions) error

MarshalOption configures a MarshalOptions struct.

func WithDataSizeLen

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

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

WithElementWriteHooks returns an MarshalOption which registers element hooks.

type MarshalOptions

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

MarshalOptions stores options for marshalling.

type Unlacer

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

Unlacer is the interface to read laced frames in Block.

func NewEBMLUnlacer

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

NewEBMLUnlacer creates Unlacer for EBML laced data.

func NewFixedUnlacer

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

NewFixedUnlacer creates Unlacer for Fixed laced data.

func NewNoUnlacer

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

NewNoUnlacer creates pass-through Unlacer for not laced data.

func NewXiphUnlacer

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

NewXiphUnlacer creates Unlacer for Xiph laced data.

type UnmarshalOption

type UnmarshalOption func(*UnmarshalOptions) error

UnmarshalOption configures a UnmarshalOptions struct.

func WithElementReadHooks

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

WithElementReadHooks returns an UnmarshalOption which registers element hooks.

func WithIgnoreUnknown

func WithIgnoreUnknown(ignore bool) UnmarshalOption

WithIgnoreUnknown returns an UnmarshalOption which makes Unmarshal ignoring unknown element with static length.

type UnmarshalOptions

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

UnmarshalOptions stores options for unmarshalling.

Directories

Path Synopsis
examples
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