video

README

mpeg/video

Package video implements the basic structures for simple MPEG-2 video decoding as defined in ISO/IEC 13818-1.

Documentation

Overview

Package video implements the basic structures for simple MPEG-2 video decoding as defined in ISO/IEC 13818-1.

This package is experimental and is not intended for use in production environments.

Presently, this library supports decoding a subset of the entire MPEG-2 decoding specification: namely frame based pictures, subsampled by 4:2:0 can be decoded. However, this package is an active work in progress and slowly inching toward broader support the spec.

Index

• Constants
• Variables
• type ChromaFormat
  • func (cf ChromaFormat) String() string
• type ExtensionID
  • func (expected ExtensionID) Assert(br bitreader.BitReader) error
  • func (expected ExtensionID) Check(br bitreader.BitReader) (bool, error)
  • func (id ExtensionID) IsReserved() bool
• type GroupOfPicturesHeader
  • func ReadGOPHeader(br bitreader.BitReader) (*GroupOfPicturesHeader, error)
  • func (gop *GroupOfPicturesHeader) TimeCode() TimeCode
• type Macroblock
• type MacroblockType
• type PictureCodingExtension
• type PictureCodingType
  • func (pct PictureCodingType) String() string
• type PictureHeader
  • func (ph PictureHeader) String() string
• type PictureStructure
• type PictureTemporalScalableExtension
• type ScalableMode
• type SequenceDisplayExtension
• type SequenceExtension
• type SequenceHeader
  • func ReadSequenceHeader(br bitreader.BitReader) (*SequenceHeader, error)
• type SequenceScalableExtension
• type Slice
• type StartCode
  • func (expected StartCode) Assert(br bitreader.BitReader) error
  • func (expected StartCode) Check(br bitreader.BitReader) (bool, error)
  • func (code StartCode) IsSlice() bool
• type TimeCode
  • func (tc TimeCode) String() string
• type UserData
• type VideoSequence
  • func NewVideoSequence(r io.Reader) *VideoSequence
  • func (br *VideoSequence) AlignTo(startCode StartCode) error
  • func (vs *VideoSequence) Next() (*image.YCbCr, error)
  • func (vs *VideoSequence) Size() (width int, height int)

Constants

const (
	PictureCodingType_IntraCoded PictureCodingType
	PictureCodingType_PredictiveCoded
	PictureCodingType_BidirectionallyPredictiveCoded

	PictureCodingType_DCIntraCoded // Shall not be used (Used in ISO/IEC11172-2)

	IFrame = PictureCodingType_IntraCoded
	PFrame = PictureCodingType_PredictiveCoded
	BFrame = PictureCodingType_BidirectionallyPredictiveCoded
)

Variables

var EOS = errors.New("end of sequence")

var ErrInvalidReservedBits = errors.New("invalid reserved bits")

var ErrMissingMarkerBit = errors.New("missing marker bit")

var ErrUnexpectedDecodedValueType = errors.New("unexpected decoded value type")

var ErrUnexpectedExtensionID = errors.New("unexpected sequence extension id")

ErrUnexpectedExtensionID indicates that a Extension ID was read from the bitstream that was unexpected.

var ErrUnexpectedNonZeroByte = errors.New("unexpected non-zero byte")

var ErrUnexpectedStartCode = errors.New("unexpected start code")

ErrUnexpectedStartCode indicates that a start code was read from the bitstream that was unexpected.

var ErrUnsupportedVideoStream_ISO_IEC_11172_2 = errors.New("unsupported video stream ISO/IEC 11172-2")

Types

type ChromaFormat

type ChromaFormat uint32

ChromaFormat is chroma subsample ratio used in the video bitstream. It defines the number and location of the blocks encoded in a macroblock.

A macroblock in a 4:2:0 image contains 6 blocks: 4 Y, and 1 Cb, and 1 Cr, arranged in the following order:

┌───┬───┐
│ 0 │ 1 │  ┌───┐  ┌───┐
├───┼───┤  │ 4 │  │ 5 │
│ 2 │ 3 │  └───┘  └───┘
└───┴───┘
    Y        Cb     Cr

A macroblock in a 4:2:2 image contains 8 blocks: 4 Y, and 2 Cb, and 2 Cr, arranged in the following order:

┌───┬───┐  ┌───┐  ┌───┐
│ 0 │ 1 │  │ 4 │  │ 5 │
├───┼───┤  ├───┤  ├───┤
│ 2 │ 3 │  │ 6 │  │ 7 │
└───┴───┘  └───┘  └───┘
    Y        Cb     Cr

A macroblock in a 4:4:4 image contains 12 blocks: 4 Y, and 4 Cb, and 4 Cr, arranged in the following order:

┌───┬───┐ ┌───┬───┐ ┌───┬───┐
│ 0 │ 1 │ │ 4 │ 8 │ │ 5 │ 9 │
├───┼───┤ ├───┼───┤ ├───┼───┤
│ 2 │ 3 │ │ 6 │10 │ │ 7 │11 │
└───┴───┘ └───┴───┘ └───┴───┘
    Y        Cb        Cr

Note: At present, this library only supports decoding video with subsample ratio of 4:2:0.

const (
	ChromaFormat420 ChromaFormat
	ChromaFormat422
	ChromaFormat444
)

func (ChromaFormat) String

func (cf ChromaFormat) String() string

type ExtensionID

type ExtensionID uint32

ExtensionID is a 4 bit code, that immediately follows an ExtensionStartCode, used identify the following data.

const (
	SequenceExtensionID ExtensionID
	SequenceDisplayExtensionID
	QuantMatrixExtensionID
	CopyrightExtensionID
	SequenceScalableExtensionID

	PictureDisplayExtensionID
	PictureCodingExtensionID
	PictureSpatialScalableExtensionID
	PictureTemporalScalableExtensionID
)

func (ExtensionID) Assert

func (expected ExtensionID) Assert(br bitreader.BitReader) error

Assert() returns an ErrUnexpectedExtensionID if the following bits in the bitstream do not match the expected extension id. If the expected code is present, the the bits are consumed from the bitstream.

func (ExtensionID) Check

func (expected ExtensionID) Check(br bitreader.BitReader) (bool, error)

Check() returns true if the following bits in the bitstream match the expected extension id. Check() does not consume any bits from the bitstream and will only return an error if there is a underlying error attempting to peek into the bitstream.

func (ExtensionID) IsReserved

func (id ExtensionID) IsReserved() bool

IsReserved() returns true if the extension id is described as "reserved".

type GroupOfPicturesHeader

type GroupOfPicturesHeader struct {
	ClosedGOP  bool // 1 uimsbf
	BrokenLink bool // 1 uimsbf
	// contains filtered or unexported fields
}

func ReadGOPHeader

func ReadGOPHeader(br bitreader.BitReader) (*GroupOfPicturesHeader, error)

ReadGOPHeader parses a group_of_pictures header from the given bitstream.

func (*GroupOfPicturesHeader) TimeCode

func (gop *GroupOfPicturesHeader) TimeCode() TimeCode

Returns a parsed TimeCode from the raw GOP header data.

type Macroblock

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

type MacroblockType

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

type PictureCodingExtension

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

type PictureCodingType

type PictureCodingType uint32

PictureCodingType defines the encoding used for a frame within a video bitstream.

Intra coded pictures are encoded independently of any other pictures. They are similar to other self-contained image formats like JPEG.

Predictive coded pictures are pictures coded using a motion compensated sample from a previous decoded reference frame to be reconstructed. If a macroblock is encoded with motion vectors, then to decode the block a motion prediction is formed by projecting a portion of a "past" reference frame "forward" into the current frame. Using the motion vector to sample image data from a previously decoded reference frame, the samples are then added to the encoded samples in the bitstream to reconstruct the final block.

x──────────────────────┐   x───┬──────────────────┐
│╲               ┌ ─ ─ ┼ ─ ▶   │                  │
│ MV                   │   ├───┘                  │
│  ╲───┐         │     │   │                      │
│  │   │─ ─ ─ ─ ─      │   │                      │
│  └───┘               │   │                      │
│                      │   │                      │
│                      │   │                      │
│                      │   │                      │
└──────────────────────┘   └──────────────────────┘
    Reference Frame                P-Frame

Bi-directionally coded picture is a picture coded using motion compensated sample from either a past frame and/or a future frame. B-Frames can contain "forward" and/or "backward" projections.

x──────────────────────┐   x───┬──────────────────┐   x──────────────────────┐
│╲               ┌ ─ ─ ┼ ─ ▶   ◀ ─ ─ ─ ─ ─ ─ ─    │   │╲─MV──┌───┐           │
│ MV                   │   ├───┘              └ ─ ┼ ─ ┼ ─ ─ ─│   │           │
│  ╲───┐         │     │   │                      │   │      └───┘           │
│  │   │─ ─ ─ ─ ─      │   │                      │   │                      │
│  └───┘               │   │                      │   │                      │
│                      │   │                      │   │                      │
│                      │   │                      │   │                      │
│                      │   │                      │   │                      │
└──────────────────────┘   └──────────────────────┘   └──────────────────────┘
  Past Reference Frame             B-Frame             Future Reference Frame

func (PictureCodingType) String

func (pct PictureCodingType) String() string

type PictureHeader

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

func (PictureHeader) String

func (ph PictureHeader) String() string

type PictureStructure

type PictureStructure uint32

const (
	PictureStructure_TopField PictureStructure
	PictureStructure_BottomField
	PictureStructure_FramePicture
)

type PictureTemporalScalableExtension

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

type ScalableMode

type ScalableMode uint32

const (
	DataPartitioning ScalableMode = iota
	SpatialScalability
	SNRScalability
	TemporalScalability
)

type SequenceDisplayExtension

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

type SequenceExtension

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

type SequenceHeader

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

func ReadSequenceHeader

func ReadSequenceHeader(br bitreader.BitReader) (*SequenceHeader, error)

ReadSequenceHeader reads a sequence header from the bit stream.

type SequenceScalableExtension

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

type Slice

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

type StartCode

type StartCode uint32

StartCode is a 32 bit code that acts as a marker in a coded bitstream. They usually signal the structure of following bits and/or how the bits should be interpreted.

Start codes always begin with the 24 bit integer 0x000001 followed by a specific identifier.

const (
	StartCodePrefix = 0x000001

	PictureStartCode StartCode = (StartCodePrefix << 8) | 0x00

	// slice_start_code 01 through AF
	MinSliceStartCode StartCode = (StartCodePrefix << 8) | 0x01
	MaxSliceStartCode StartCode = (StartCodePrefix << 8) | 0xAF

	UserDataStartCode       StartCode = (StartCodePrefix << 8) | 0xB2
	SequenceHeaderStartCode StartCode = (StartCodePrefix << 8) | 0xB3
	ExtensionStartCode      StartCode = (StartCodePrefix << 8) | 0xB5
	SequenceEndStartCode    StartCode = (StartCodePrefix << 8) | 0xB7
	GroupStartCode          StartCode = (StartCodePrefix << 8) | 0xB8
)

func (StartCode) Assert

func (expected StartCode) Assert(br bitreader.BitReader) error

Assert() returns an ErrUnexpectedStartCode if the next bits in the bitstream do not match the expected code. If the expected code is present, the the bits are consumed from the bitstream.

func (StartCode) Check

func (expected StartCode) Check(br bitreader.BitReader) (bool, error)

Check() will return true if the next bits in the bitstream match the expected code. Check() does not consume any bits from the bitstream and will only return an error if there is a underlying error attempting to peek into the bitstream.

func (StartCode) IsSlice

func (code StartCode) IsSlice() bool

IsSlice() returns true if the StartCode falls within the acceptable range of codes designated as slice start codes.

type TimeCode

type TimeCode struct {
	DropFrame bool  // 1-bit
	Hours     int32 // 5-bit
	Minutes   int32 // 6-bit
	Seconds   int32 // 6-bit
	Pictures  int32 // 6-bit
}

TimeCode represents the associated time code with the first picture following the Group of Pictures header with a TemporalReference = 0. DropFrame will only be true if the desired framerate is 29.97Hz.

TimeCode appears in the bitstream as a 25-bit integer that has the following layout:

┌──┬──────────────────┬──────────────────────┬──┬──────────────────────┬──────────────────────┐
│DF│Hours             │Minutes               │MB│Seconds               │Pictures              │
└──┴──────────────────┴──────────────────────┴──┴──────────────────────┴──────────────────────┘
├───────────────────────────────────────────25 bits───────────────────────────────────────────┤

func (TimeCode) String

func (tc TimeCode) String() string

String formats the time code as a string in SMPTE format: "HH:MM:SS:FF". If the timecode is in drop frame, then the separator between seconds and frames is replaced with a ";" character.

type UserData

type UserData []byte

type VideoSequence

type VideoSequence struct {
	bitreader.BitReader
	// contains filtered or unexported fields
}

func NewVideoSequence

func NewVideoSequence(r io.Reader) *VideoSequence

func (*VideoSequence) AlignTo

func (br *VideoSequence) AlignTo(startCode StartCode) error

AlignTo will trash all bits until the stream is aligned with the desired start code or error is produced.

func (*VideoSequence) Next

func (vs *VideoSequence) Next() (*image.YCbCr, error)

Next() will return the next frame of video decoded from the video stream.

func (*VideoSequence) Size

func (vs *VideoSequence) Size() (width int, height int)