analyze

Documentation

Overview

Package analyze fans decoded frames out to independent analyzers.

Index

• Variables
• func Run(ctx context.Context, src decode.Source, req decode.Request, ...) error
• func RunSegments(ctx context.Context, src decode.Source, reqs []decode.Request, workers int, ...) error
• func Splittable(analyzers []Analyzer) bool
• func Thumbnail(f *frame.Frame) []byte
• type Analyzer
• type Forker
• type Series
  • func (s *Series[T]) Add(first int, values []T)
  • func (s *Series[T]) Merge() []T

Variables

var ErrSegment = errors.New("segment does not match the plan")

ErrSegment is returned by RunSegments when a segment did not yield the frames planned: fewer than requested, or not the frame the previous segment ended with (a seek that did not land where expected). The segments are then unusable; a single sequential pass still is.

Functions

func Run

func Run(
	ctx context.Context,
	src decode.Source,
	req decode.Request,
	analyzers []Analyzer,
	progress func(frames int),
) error

Run decodes req once and feeds every frame to all analyzers concurrently. progress, when not nil, receives the number of frames decoded so far.

The first error (decoder or analyzer) cancels the run; every analyzer is still closed, after its queue has been drained.

func RunSegments

func RunSegments(
	ctx context.Context,
	src decode.Source,
	reqs []decode.Request,
	workers int,
	analyzers []Analyzer,
	progress func(frames int),
) error

RunSegments analyses a video decoded in segments, up to workers of them at once, each fed to forks of every analyzer (all must be Forkers, see Splittable). reqs are consecutive runs of frames in order, overlapping by one frame (see Forker); every request but the last must set MaxFrames. progress, when not nil, receives the number of distinct frames analysed so far; calls are serialised.

The first error (decoder, analyzer, ErrSegment) cancels the run; every fork and analyzer is still closed.

func Splittable

func Splittable(
	analyzers []Analyzer,
) bool

Splittable reports whether every analyzer is a Forker: only then can a video be analysed in concurrent segments (RunSegments).

func Thumbnail

func Thumbnail(
	f *frame.Frame,
) []byte

Thumbnail returns the samples analyzers working at low resolution should read: the frame's thumbnail, or its full luma when the pool builds no thumbnails (pooled 8-bit planes have no row padding, so Pix is the image). Without this fallback an empty thumbnail would read as a black, frozen and cut-free picture.

Types

type Analyzer

type Analyzer interface {
	Consume(f *frame.Frame) error
	Close() error
}

Analyzer consumes decoded frames. Consume is called from a single goroutine in presentation order; an analyzer that keeps a frame after Consume returns must Retain it. Close is called once after the last frame.

type Forker

type Forker interface {
	Analyzer
	Fork() Analyzer
}

Forker is implemented by analyzers whose work can be split into runs of consecutive frames analysed concurrently (RunSegments). Fork returns the analyzer of one run: it receives the frames of the run in order, from a single goroutine, while other forks analyse other runs, and it is closed after the last frame of its run. The Forker itself then receives no frame; it is closed after every fork, and its results must be those of a single sequential pass.

Consecutive runs overlap by one frame: the last frame of a run is the first frame of the next one. A fork measures what compares a frame with its predecessor (motion, cuts) from the second frame of its run on, as a sequential pass does from the second frame of the video, so every such measure is taken once, by the run holding both frames. Measures of the shared frame alone are taken by both runs, identically. Series merges per-frame values that way.

type Series

type Series[T any] struct {
	// contains filtered or unexported fields
}

Series gathers the per-frame values of an analyzer measured by runs of consecutive frames (its forks, or the single run of a sequential pass) and merges them in frame order. The zero value is ready to use and safe for concurrent use.

func (*Series[T]) Add

func (s *Series[T]) Add(
	first int,
	values []T,
)

Add records the values of the frames of a run, the first of them being frame first.

func (*Series[T]) Merge

func (s *Series[T]) Merge() []T

Merge returns the values of every frame in order, the first value being that of the earliest frame measured. Where runs overlap, the earlier run's values are kept: that run also had the frame's predecessor (see Forker). Runs are expected to leave no gap (RunSegments checks it).