README
¶
ebml-go
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 ¶
- Constants
- Variables
- func Marshal(val interface{}, w io.Writer, opts ...MarshalOption) error
- func MarshalBlock(b *Block, w io.Writer) error
- func Unmarshal(r io.Reader, val interface{}, opts ...UnmarshalOption) error
- type Block
- type DataType
- type Element
- type ElementType
- type Error
- type Lacer
- type LacingMode
- type MarshalOption
- type MarshalOptions
- type Unlacer
- type UnmarshalOption
- type UnmarshalOptions
Examples ¶
Constants ¶
const ( ElementTimecodeScale = ElementTimestampScale ElementTimecode = ElementTimestamp )
WebM aliases
const ( // DateEpochInUnixtime is the Unixtime of EBML date epoch. DateEpochInUnixtime = 978307200 // SizeUnknown is the longest unknown size value. SizeUnknown = 0xffffffffffffff )
Variables ¶
var ErrEmptyTag = errors.New("empty tag in tag string")
ErrEmptyTag means that a tag string has empty item.
var ErrFixedLaceUndivisible = errors.New("undivisible fixed lace")
ErrFixedLaceUndivisible means that a length of a fixed lacing data is undivisible.
var ErrIncompatibleType = errors.New("marshal/unmarshal to incompatible type")
ErrIncompatibleType means that an element is not convertible to a corresponding struct field.
var ErrIndefiniteType = errors.New("marshal/unmarshal to indefinite type")
ErrIndefiniteType means that a marshal/unmarshal destination type is not valid.
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.
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.
var ErrInvalidTag = errors.New("invalid tag in tag string")
ErrInvalidTag means that an invaild tag is specified.
var ErrInvalidType = errors.New("invalid type")
ErrInvalidType means that a value is not convertible to the element data.
var ErrNonStringMapKey = errors.New("non-string map key")
ErrNonStringMapKey is returned if input is map and key is not a string.
var ErrOutOfRange = errors.New("out of range")
ErrOutOfRange means that a value is out of range of the data type.
var ErrReadStopped = errors.New("read stopped")
ErrReadStopped is returned if unmarshaler finished to read element which has stop tag.
var ErrTooManyFrames = errors.New("too many frames")
ErrTooManyFrames means that a number of frames exceeds the limit.
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.
var ErrUnknownElement = errors.New("unknown element")
ErrUnknownElement means that a decoded element is not known.
var ErrUnknownElementName = errors.New("unknown element name")
ErrUnknownElementName means that a element name is not found in the ElementType list.
var ErrUnsupportedElement = errors.New("unsupported element")
ErrUnsupportedElement means that a element name is known but unsupported in this version of ebml-go.
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, 0x8f, 0x42, 0x82, 0x84, 0x77, 0x65, 0x62, 0x6d, 0x42, 0x87, 0x81, 0x02, 0x42, 0x85, 0x81, 0x02,
func MarshalBlock ¶
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.
type DataType ¶ added in v0.9.0
type DataType int
DataType represents EBML Element data type.
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 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 ¶ 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
Error records a failed parsing.
type Lacer ¶ added in v0.8.0
Lacer is the interface to read laced frames in Block.
func NewEBMLLacer ¶ added in v0.8.0
NewEBMLLacer creates Lacer for EBML laced data.
func NewFixedLacer ¶ added in v0.8.0
NewFixedLacer creates Lacer for Fixed laced data.
func NewNoLacer ¶ added in v0.8.0
NewNoLacer creates pass-through Lacer for not laced data.
func NewXiphLacer ¶ added in v0.8.0
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, 0x12, 0x42, 0x82, 0x40, 0x04, 0x77, 0x65, 0x62, 0x6d, 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
Unlacer is the interface to read laced frames in Block.
func NewEBMLUnlacer ¶ added in v0.8.0
NewEBMLUnlacer creates Unlacer for EBML laced data.
func NewFixedUnlacer ¶ added in v0.8.0
NewFixedUnlacer creates Unlacer for Fixed laced data.
func NewNoUnlacer ¶ added in v0.8.0
NewNoUnlacer creates pass-through Unlacer for not 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.
func WithIgnoreUnknown ¶ added in v0.14.0
func WithIgnoreUnknown(ignore bool) UnmarshalOption
WithIgnoreUnknown returns an UnmarshalOption which makes Unmarshal ignoring unknown element with static length.
type UnmarshalOptions ¶ added in v0.2.0
type UnmarshalOptions struct {
// contains filtered or unexported fields
}
UnmarshalOptions stores options for unmarshalling.
Source Files
¶
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. |