Documentation
¶
Overview ¶
Package decode turns the coded video samples avkit's container package demuxes into pictures.
The first codec is H.264 (ITU-T H.264 | ISO/IEC 14496-10), through github.com/oops1/go.264, the second HEVC (ITU-T H.265), through github.com/gen2brain/h265: pure Go decoders that are checked here, picture for picture, against ffmpeg. See the README for the profiles that claim holds for and the conformance bitstreams it was measured on.
Input is what a container hands over: an AVCDecoderConfigurationRecord or an HEVCDecoderConfigurationRecord (ISO/IEC 14496-15) or the parameter sets of a container.TrackConfig, then one length-prefixed access unit per sample. Output is every picture in display order as planar YUV, with its chroma format, bit depth and presentation time.
Index ¶
Constants ¶
const ( // DefaultMaxFrameMBs is 36864 macroblocks, a 4096x2304 picture: level 5.1 // of H.264 Annex A. DefaultMaxFrameMBs = 36864 // DefaultMaxSampleBytes is 64 MiB, far above any single access unit a // level 6.2 stream can carry at its maximum bit rate and frame rate. DefaultMaxSampleBytes = 64 << 20 )
Default limits. A stream is untrusted input: the picture size in its sequence parameter set sizes every buffer the decoder allocates, so it is bounded before the first of them is.
const ( // DefaultMaxPosterSamples is 600 samples, ten seconds of 60 frames per // second video decoded for a single picture. DefaultMaxPosterSamples = 600 // DefaultMaxTrackSamples is 1<<20 samples, about 4.8 hours at 60 frames per // second. DefaultMaxTrackSamples = 1 << 20 )
Default PosterConfig bounds.
Variables ¶
var ( // ErrConfig means the codec configuration (an avcC record or a track's // parameter sets) is malformed. ErrConfig = errors.New("decode: invalid codec configuration") // ErrSample means a sample is not a well formed run of length-prefixed // NAL units. ErrSample = errors.New("decode: invalid sample") // ErrOverLimit means the stream asks for more than Config allows: a // picture larger than MaxFrameMBs, or a sample larger than MaxSampleBytes. // It is raised before anything sized by the stream is allocated. ErrOverLimit = errors.New("decode: stream exceeds the configured limits") // ErrUnsupported means the stream uses a coding tool this decoder does // not implement (see the README): for H.264 interlaced coding, a chroma // format other than 4:2:0, a bit depth above 8, lossless transform bypass; // for HEVC a chroma format other than 4:2:0, a bit depth other than 8 or // 10, and, because the HEVC decoder reports both the same way, a picture // larger than Config.MaxFrameMBs. ErrUnsupported = errors.New("decode: unsupported coding tool") // ErrClosed means the decoder was used after Close. ErrClosed = errors.New("decode: use of a closed decoder") )
Errors a decoder can refuse with. Each is matched with errors.Is.
var ( // ErrPosterLimit means the picture asked for is further from the keyframe it // is decoded from than PosterConfig.MaxSamples allows, or the track lists // more samples than PosterConfig.MaxTrackSamples. It is raised before the // decoder is built, so a stream with a distant keyframe costs nothing. ErrPosterLimit = errors.New("decode: poster frame exceeds the configured work limit") // ErrTime means the time asked for is negative or not a number. ErrTime = errors.New("decode: invalid poster time") // ErrNoVideo means the file has no video track. ErrNoVideo = errors.New("decode: no video track") )
Errors PosterFrame refuses with, besides the ones above.
var ErrBitstream = errors.New("decode: malformed bitstream")
ErrBitstream means the HEVC bitstream itself is malformed: a parameter set, slice header or slice data the decoder cannot read. A bitstream the decoder can read but does not implement is ErrUnsupported instead.
Functions ¶
Types ¶
type AVCConfig ¶
type AVCConfig struct {
// Profile, Compatibility and Level are AVCProfileIndication,
// profile_compatibility and AVCLevelIndication, the first three bytes of
// the SPS after the NAL header.
Profile, Compatibility, Level uint8
// LengthSize is the size in bytes of each NAL unit's length prefix:
// lengthSizeMinusOne + 1: 1, 2 or 4 (3 is reserved).
LengthSize int
// SPS and PPS are the parameter sets, as NAL units without a prefix.
SPS, PPS [][]byte
}
AVCConfig is an AVCDecoderConfigurationRecord, the content of the avcC box (ISO/IEC 14496-15). The standard's text is paywalled and was not opened; the layout is that of mp4ff v0.62.0, avc/avcdecoderconfigurationrecord.go, which was.
func ParseAVCC ¶
ParseAVCC parses an AVCDecoderConfigurationRecord. It reads the record only as far as the decoder needs: the extension fields a High profile record appends (chroma format, bit depths, SPS extensions) are bounds-checked but not kept, since the sequence parameter set itself is authoritative.
type Config ¶
type Config struct {
// MaxFrameMBs is the largest picture accepted, in 16x16 macroblocks.
MaxFrameMBs int
// MaxSampleBytes is the largest sample (access unit) accepted.
MaxSampleBytes int
// EnforceLevel also refuses a stream that exceeds its own declared
// level's limits (Annex A), where MaxFrameMBs alone would admit it.
EnforceLevel bool
}
Config bounds what a stream may make the decoder allocate. A zero field takes its default.
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder decodes one H.264 or HEVC elementary stream. It is not safe for concurrent use.
func New ¶
New returns a decoder for length-prefixed samples with lengthSize-byte lengths (1, 2 or 4 as avcC allows; MP4 and Matroska use 4). The parameter sets must then arrive in-band, or through Config via NewAVCC or NewTrack.
func NewHEVC ¶ added in v0.3.0
NewHEVC returns an HEVC (H.265) decoder for length-prefixed samples with lengthSize-byte lengths (1, 2 or 4). The parameter sets must then arrive in-band, or through NewHVCC or NewTrack. For HEVC, Config.MaxFrameMBs counts 256 luma samples (a 16x16 block, as for H.264) and Config.EnforceLevel has no effect.
func NewHVCC ¶ added in v0.3.0
NewHVCC returns an HEVC decoder configured by an hvcC record, as MP4 stores it. Samples are length-prefixed with the record's length size.
func NewTrack ¶
func NewTrack(tc container.TrackConfig, cfg Config) (*Decoder, error)
NewTrack returns a decoder for an avkit container track: an HEVC decoder for a track whose sample entry is hvc1 or hev1, an H.264 decoder otherwise. Samples are length-prefixed with four-byte lengths, which is what container.Reader hands over for MP4 and Matroska. The track's parameter sets are decoded first.
func (*Decoder) DecodeAnnexB ¶
DecodeAnnexB decodes part of a raw Annex B byte stream (start code delimited, as in a .264 file). The pictures' PTS is their index in display order. The chunk need not end on a NAL unit boundary.
func (*Decoder) DecodeSample ¶
DecodeSample decodes one access unit in length-prefixed form, which is container.Sample.Data, and returns the pictures that became ready, in display order. pts is the sample's presentation time; it is attached to the pictures in increasing order as they come out, so it need not belong to the picture the sample itself contains. A picture can come out several samples late.
type Frame ¶
type Frame struct {
// Y, Cb and Cr are the planes. A sample is one byte when BitDepth is 8
// and a little-endian 16-bit word above that. A Chroma400 frame has no
// Cb or Cr.
Y, Cb, Cr []byte
// YStride and CStride are the plane row lengths in bytes.
YStride, CStride int
// Width and Height are the luma size in samples.
Width, Height int
// Chroma is the chroma sampling.
Chroma Chroma
// BitDepth is the luma bit depth.
BitDepth int
// PTS is the presentation time in the track timescale: the decode time
// of the sample plus its composition offset. For a raw Annex B stream it
// is the picture's index in display order.
PTS int64
// Corrupt reports that the HEVC decoder lost a slice of the picture, failed
// partway through it, or predicted it from a reference the stream never
// delivered. The picture is still returned, as far as it was decoded. It is
// never set for H.264.
Corrupt bool
}
Frame is one decoded picture, cropped to the stream's display window.
The field names and meaning match go-videodsp/yuv.Picture for 8-bit 4:2:0 so that converting is a field-by-field copy. A Frame owns its planes.
func DecodeTrack ¶
DecodeTrack decodes every sample of one video track of a demuxed file and returns the pictures in display order with their presentation times in the track's timescale. It is the whole-file form of NewTrack and DecodeSample.
func PosterFrame ¶ added in v0.2.0
PosterFrame decodes the one picture a track displays at t seconds: the one with the greatest presentation time at or before t, where a sample's presentation time is its decode time plus its composition offset, as for DecodeTrack, whose picture and PTS it returns byte for byte.
A t past the end of the track gives the last picture, and a t before the first presentation time gives the first. A negative or NaN t is ErrTime. Decoding starts at the last sample marked Sync at or before the picture's sample (the first sample when none is) and stops as soon as the picture is out, so the work is bounded by cfg.MaxSamples, not by the length of the track (ErrPosterLimit). Only H.264 and HEVC are decoded; another codec is ErrUnsupported.
The track's samples are listed by container.Reader.Samples, which a reader on a file that stays on disk (container.NewFileReader) fetches whole: the limit on their number is checked once they are listed.
type HVCConfig ¶ added in v0.3.0
type HVCConfig struct {
// ProfileSpace, Tier, Profile and Level are general_profile_space,
// general_tier_flag, general_profile_idc and general_level_idc, as the
// sequence parameter set states them.
ProfileSpace uint8
Tier bool
Profile uint8
Level uint8
// ChromaFormat is chroma_format_idc; BitDepthLuma and BitDepthChroma are the
// sample bit depths (the record stores them minus eight).
ChromaFormat uint8
BitDepthLuma, BitDepthChroma uint8
// LengthSize is the size in bytes of each NAL unit's length prefix:
// lengthSizeMinusOne + 1: 1, 2 or 4 (3 is reserved).
LengthSize int
// VPS, SPS and PPS are the parameter sets of the record's arrays, as NAL
// units without a prefix. Arrays of any other NAL unit type (SEI) are
// skipped.
VPS, SPS, PPS [][]byte
}
HVCConfig is an HEVCDecoderConfigurationRecord, the content of the hvcC box (ISO/IEC 14496-15, clause 8.3.3). The standard's text is paywalled and was not opened; the layout is that of mp4ff v0.62.0, hevc/hevcdecoderconfigurationrecord.go (DecodeHEVCDecConfRec and the DecConfRec type), which was.
type PosterConfig ¶ added in v0.2.0
type PosterConfig struct {
Config
// MaxSamples is the most samples decoded for the picture: the run from the
// keyframe it starts at, up to the sample that outputs it, which can come
// several samples after the sample holding it when the stream reorders.
MaxSamples int
// MaxTrackSamples is the longest sample list accepted.
MaxTrackSamples int
}
PosterConfig bounds the work PosterFrame does for one picture, on top of the decoder's own Config. A zero field takes its default.