bitstream

Documentation

Overview

Package bitstream analyses compressed packets without decoding them: bitrate over time, peaks and GOP structure.

Index

• func ParsePacketLine(line []byte) (media.Packet, error)
• func SplitAtKeyframes(keyframe []bool, count, minGap int) []int
• type BitratePoint
• type FFprobeReader
  • func NewFFprobeReader(bin string) *FFprobeReader
  • func (r *FFprobeReader) ReadPackets(ctx context.Context, path string, fn func(media.Packet) error) error
• type GOPStats
• type Options
• type PacketReader
• type Report
  • func Analyze(packets []media.Packet, opts Options) Report
• type SizeStats

Functions

func ParsePacketLine

func ParsePacketLine(
	line []byte,
) (media.Packet, error)

ParsePacketLine parses one ffprobe compact line such as "pts_time=0.1|dts_time=0.0|duration_time=0.033|size=1234|flags=K__". Missing timestamps ("N/A") fall back to the other timestamp.

func SplitAtKeyframes

func SplitAtKeyframes(
	keyframe []bool,
	count, minGap int,
) []int

SplitAtKeyframes returns the first frames of up to count runs of consecutive frames of about equal length, split at keyframes (keyframe[i] tells whether frame i, in presentation order, is one): the first bound is 0, every other one a keyframe, at least minGap frames after the previous bound and before the end. Work spread over concurrent processes (decodes, renders) starts each run at a keyframe, where a decoder can start. A video without keyframes to split at is one run.

Types

type BitratePoint

type BitratePoint struct {
	Start   media.Duration `json:"start"`
	Bitrate int64          `json:"bitrate"`
}

BitratePoint is the bitrate of one bucket of the series.

type FFprobeReader

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

FFprobeReader implements PacketReader with ffprobe. It only demuxes: no frame is decoded, which keeps it close to disk read speed.

func NewFFprobeReader

func NewFFprobeReader(
	bin string,
) *FFprobeReader

NewFFprobeReader returns a PacketReader backed by the given ffprobe binary.

func (*FFprobeReader) ReadPackets

func (r *FFprobeReader) ReadPackets(
	ctx context.Context,
	path string,
	fn func(media.Packet) error,
) error

ReadPackets implements PacketReader.

type GOPStats

type GOPStats struct {
	KeyframeCount int            `json:"keyframeCount"`
	MinInterval   media.Duration `json:"minInterval"`
	MaxInterval   media.Duration `json:"maxInterval"`
	MeanInterval  media.Duration `json:"meanInterval"`
	// Fixed reports whether every interval is within one and a half mean
	// frame durations of the mean interval.
	Fixed bool `json:"fixed"`
}

GOPStats summarises the distance between consecutive keyframes.

type Options

type Options struct {
	// Interval is the bucket size of the bitrate series (default 1s).
	Interval time.Duration
	// PeakWindow is the sliding window used for the peak bitrate (default 1s).
	PeakWindow time.Duration
}

Options tunes the bitstream analysis. The zero value is valid.

type PacketReader

type PacketReader interface {
	ReadPackets(
		ctx context.Context,
		path string,
		fn func(media.Packet) error,
	) error
}

PacketReader streams the compressed packets of the primary video stream.

type Report

type Report struct {
	PacketCount int            `json:"packetCount"`
	Duration    media.Duration `json:"duration"`
	// Start is the presentation time of the first frame on the container's
	// timeline: ffmpeg shifts it by the container's start time, which
	// timelines built on PTS (relative to the first frame) need to match
	// what ffmpeg filters see.
	Start          media.Duration   `json:"start"`
	TotalBytes     int64            `json:"totalBytes"`
	AverageBitrate int64            `json:"averageBitrate"`
	PeakBitrate    int64            `json:"peakBitrate"`
	PeakAt         media.Duration   `json:"peakAt"`
	PeakWindow     media.Duration   `json:"peakWindow"`
	PeakToAverage  float64          `json:"peakToAverage"`
	FrameSize      SizeStats        `json:"frameSize"`
	GOP            GOPStats         `json:"gop"`
	Interval       media.Duration   `json:"interval"`
	Bitrate        []BitratePoint   `json:"bitrate"`
	Keyframes      []media.Duration `json:"keyframes"`
	// Per-frame columns in presentation order. PTS is relative to the first
	// frame; decoded-frame analyzers use it to timestamp frames.
	PTS        []media.Duration `json:"-"`
	FrameSizes []int            `json:"-"`
	KeyFlags   []bool           `json:"-"`
}

Report is the result of a bitstream analysis.

func Analyze

func Analyze(
	packets []media.Packet,
	opts Options,
) Report

Analyze computes a Report from packets given in any order.

type SizeStats

type SizeStats struct {
	Min  int     `json:"min"`
	Max  int     `json:"max"`
	Mean float64 `json:"mean"`
	P50  int     `json:"p50"`
	P95  int     `json:"p95"`
}

SizeStats summarises packet sizes in bytes.