Build a quality-control check

This page works through one situation: footage arrives, and you have to decide whether to accept it, look at it, or send it back, without watching it. The accept-and-reject vocabulary belongs to that scenario rather than to the API. Three questions, in order. Later ones are only worth asking if earlier ones pass, because damaged footage cannot be rescued by being on-topic.

Question	Metric
Is the footage damaged?	Video characteristics
Is anything happening in it?	Hand activity
Is it the content you were expecting?	Content diversity

1. Is the footage damaged?

Read the measurements in this order:

unreadable. This is a percentage of planned clips with no usable deterministic video-characteristics reading, not a percentage of hours. Check those clips before interpreting the deterministic metrics; independent blur or stability observers may still cover them.
frozen and black. Footage that carries nothing, and usually fixable by trimming rather than rejecting.
clipped_highlights and crushed_shadows. Matters of degree.
blurry and unstable. Also matters of degree, and the two most worth sampling by eye before you set a bar.

Two things to know before acting on them:

null means the measurement was not taken. It is not a clean zero.
They can overlap. Read them one at a time; adding them into a damage total can count footage twice.

Trim before you reject

Request include=distribution and check the histogram before rejecting on black or frozen. 3% black spread thinly across every clip is a different problem from 3% concentrated in a few clips, and only the second can be handled by reviewing or excluding a small subset. The histogram shows concentration across clips but not position in time. Inspect the source or clip-level data to distinguish intentional head/tail black from a mid-recording fault.

Setting your bars

We do not publish recommended thresholds, because one that suits your cameras and lighting will not suit someone else’s. Deriving your own takes one batch:

Run the measurements against footage you already consider good.
Record what each one reads. That is your baseline, not zero.
Set each bar above its baseline, with enough margin for normal variation.

unreadable and frozen often sit near zero on healthy footage, so those bars can be tight. The other metrics can also be exactly zero; derive their normal levels from a trusted delivery rather than assuming either zero or a universal nonzero baseline. Err loose to begin with. A false rejection means re-shooting good footage, while a false acceptance means one noisy batch among many.

An example check

Return findings rather than a verdict, so the routing stays yours:

type Distribution = {
	percentiles: Array<{ percentile: number; affected_percent: number }>;
	histogram: {
		affected_percent_bin_width: number;
		bins: Array<{
			minimum_affected_percent: number;
			footage_percent: number;
			clip_count: number;
		}>;
	};
};
type Measured = { percent: number; distribution?: Distribution } | null;

const over = (measured: Measured, bar: number) =>
	measured !== null && measured.percent > bar;

// `bars` are your own, derived from footage you already trust.
const findings = [
	over(video.unreadable, bars.unreadable) && "incomplete",
	over(video.frozen, bars.frozen) && "frozen",
	over(video.black, bars.black) && "black",
	over(video.clipped_highlights, bars.clipping) && "exposure_loss",
	over(video.crushed_shadows, bars.clipping) && "exposure_loss",
	over(video.blurry, bars.blurry) && "soft",
	over(video.unstable, bars.unstable) && "shaky",
].filter(Boolean);

Whether a finding means “trim it” or “send it back” is a distribution question:

const affectedPercentAt = (distribution: Distribution, percentile: number) =>
	distribution.percentiles.find((point) => point.percentile === percentile)
		?.affected_percent;

const isConcentrated = (measured: Measured) => {
	if (measured?.distribution === undefined) return false;
	const median = affectedPercentAt(measured.distribution, 50) ?? 0;
	const tail = affectedPercentAt(measured.distribution, 95) ?? 0;
	return tail > Math.max(10, median * 4);
};

A concentrated tail says a small set of severe clips is worth finding in your clip-level data; the distribution does not identify them. Black spread evenly is a problem throughout the dataset.

2. Is anything happening in it?

Undamaged footage of nothing is still not worth much. active_manipulation_percent is the one to read. 100 hours reading 15% is about fifteen hours of work and eighty-five of walking and waiting. The visibility split tells you whether the camera is pointed at the work at all. Persistent no_hands_percent on work you expected to be manual is worth catching early, because it affects everything shot afterwards.

These fields describe a human camera-wearer’s hands. They do not apply to robot grippers, and they do not judge whether a task was done well.

3. Is it the content you were expecting?

Two checks worth automating: Presence. The objects and actions you expected appear at all, and in enough clips to be worth having. A named object with clip_count: 2 across a thousand-clip batch did not really get filmed. Concentration. 130 objects sounds broad, but if the top three appear in 80% of clips it is narrower than the count suggests. Content diversity describes composition. It does not detect duplicate footage, and it does not judge whether a demonstration succeeded.

Turn a percentage into a conversation

Percentages are easier to act on as footage:

8.5% crushed shadows across 71 assessed hours is 6 hours reaching the dark-end gate, with 80% of the assessed footage in clips below 10% affected and a p95 clip value of 31%.

That is specific enough for someone to act on, which “quality score 62” is not. Store the dataset, the response, the bars you applied and the outcome together, so a decision can be re-examined later against a bar you have since changed.

Getting started

Concepts

Workflows

Build a quality-control check

1. Is the footage damaged?

Trim before you reject

Setting your bars

An example check

2. Is anything happening in it?

3. Is it the content you were expecting?

Turn a percentage into a conversation

​1. Is the footage damaged?

​Trim before you reject

​Setting your bars

​An example check

​2. Is anything happening in it?

​3. Is it the content you were expecting?

​Turn a percentage into a conversation

1. Is the footage damaged?

Trim before you reject

Setting your bars

An example check

2. Is anything happening in it?

3. Is it the content you were expecting?

Turn a percentage into a conversation