Preflight spec reference

Preflight spec reference

Every field of the delivery spec that Preflight reads.

The spec is a JSON object, saved as a .json file (pass its path as spec) or given inline in the call. Every section and every field is optional. A check only runs when its section is in the spec. Unknown fields are rejected with a message naming them, so a typo never silently turns a check off.

The values come from your delivery document. The examples below are placeholders (<…>) showing the type and shape, not recommended values.

Units

Quantity	Unit
Sizes	pixels
Times	seconds
Frame rate	frames per second (29.97, not 30000/1001)
Safe-area margins	fraction of the frame per side (0.05 = 5 % in from each edge)
Luma / chroma	8-bit code values, 0–255 (a 10-bit file is scaled: 10-bit 941 is 235.25)
Loudness	LUFS, LU; true peak in dBTP (ITU-R BS.1770 / EBU R128)

Shape

{
  "name": "<name shown in the report>",
  "comp": "<delivered comp name or id>",
  "video": { "width": <px>, "height": <px>, "frameRate": <fps>, "duration": <s> },
  "safeAreas": { "title": <fraction>, "action": <fraction>,
                 "layersMustBeIn": [ { "layer": "<name or pattern*>", "area": "title" } ] },
  "text": { "minCapHeightPx": <px>, "maxCharsPerSecond": <n>, "minOnScreenSeconds": <s> },
  "project": { "noMissingFootage": true, "noMissingFonts": true },
  "legalRange": { "luma": { "min": <code>, "max": <code> } },
  "black": { "maxSeconds": <s> },
  "frozen": { "maxSeconds": <s> },
  "audio": { "integratedLUFS": <LUFS>, "maxTruePeakDBTP": <dBTP> },
  "flash": { "check": true }
}

Ask the AI to write it with you: "Here is the delivery document. Write a Preflight spec from it and show it to me before saving." It uses ae_preflight with action: "schema" to get the exact fields.

Top level

Field	Type	Meaning	Example
name	text	Shown in the report title	"<spec name>"
comp	text or integer	The delivered comp, by name or id, for the project checks. The call's comp overrides it. Default: the active comp.	"<comp name>"

video

Checked in the project (comp settings) and in the file. Fields marked file are only checked on a rendered file.

Field	Type	Meaning	Example
width	integer	Frame width in pixels	<px>
height	integer	Frame height in pixels	<px>
frameRate	number	Frames per second. In a file, 30000/1001 counts as 29.97, not 30	<fps>
pixelAspect	number	Pixel aspect ratio	<ratio>
duration	number, or {min, max}	Exact duration in seconds, or a range	<s> or {"min": <s>, "max": <s>}
durationToleranceFrames	integer ≥ 0	Allowed difference for an exact duration. Default 0	<frames>
codec	list of text	File. Allowed codec names as ffprobe reports them	["<codec>"]
container	list of text	File. Allowed containers / file extensions	["<ext>"]
bitDepth	integer or list	File. Bits per component	<bits> or [<bits>, <bits>]
chromaSubsampling	list of "4:2:0", "4:2:2", "4:4:4"	File. Allowed subsampling	["<subsampling>"]
alpha	true / false	File. Must (true) or must not (false) have an alpha channel	<true or false>
fieldOrder	"progressive", "tff", "bff"	File. Field order	"<order>"
colorPrimaries	text	File. Signalled primaries, as ffprobe reports them	"<primaries>"
colorTransfer	text	File. Signalled transfer characteristics	"<transfer>"
colorMatrix	text	File. Signalled matrix coefficients	"<matrix>"
colorRange	"limited" or "full"	File. Signalled range (limited = video / TV range)	"<range>"

A color tag that isn't in the file is a warning. Durations in the file are the picture's, not the container's; sound that runs longer or shorter than the picture by more than a frame is a warning.

safeAreas

Project only. Checked on every frame where the layer is visible (or every Nth frame).

Field	Type	Meaning	Example
title	number 0–0.5, or {x, y}	Title-safe margin per side	<fraction> or {"x": <fraction>, "y": <fraction>}
action	number 0–0.5, or {x, y}	Action-safe margin per side	<fraction>
textMustBeIn	"title", "action", "frame"	Area every visible text layer must stay in. Default "title"	"<area>"
layersMustBeIn	list of {layer, area}	Other layers (logos, bugs, supers) and their area. layer is an exact name or a pattern with *	[{"layer": "<name*>", "area": "<area>"}]
sampleEveryFrames	integer ≥ 1	Check every Nth frame. Default 1 (every frame)	<n>

An area named in textMustBeIn or layersMustBeIn needs its margin (title or action) in the spec; frame needs none. Without it, that check is listed as not run. Text layers are checked against title-safe only when the spec has a title margin (or a textMustBeIn you set).

text

Project only.

Field	Type	Meaning	Example
minCapHeightPx	number	Smallest rendered cap height in comp pixels (estimated as 0.7 × font size × scale)	<px>
maxCharsPerSecond	number	Reading speed: characters on screen ÷ seconds visible (spaces count, line breaks don't)	<n>
minOnScreenSeconds	number	Each text must stay visible at least this long	<s>
noOverflow	true / false	Paragraph (box) text must not overflow its box. Needs After Effects 24.6 or later	true
glyphs	true / false	Every character must exist in its font (no fallback glyphs). Needs After Effects 25.1 or later	true

project

Project only. Limited to the delivered comp and the precomps it pulls in.

Field	Type	Meaning	Example
noMissingFootage	true / false	No missing footage	true
noMissingFonts	true / false	No missing fonts	true
noMissingEffects	true / false	No missing effects (plug-ins)	true
noExpressionErrors	true / false	No expression errors	true
noDisabledLayersWithEffects	true / false	No disabled layers that still carry effects	true
bitsPerChannel	8, 16 or 32	Project bit depth	<8, 16 or 32>
workingSpace	text	Project working color space, as After Effects shows its name	"<working space name>"

legalRange

File only, Y'CbCr (YUV) files only. An RGB file makes this check "not run" (the verdict becomes INCOMPLETE).

Field	Type	Meaning	Example
luma	{min, max}	Allowed 8-bit luma code values	{"min": <code>, "max": <code>}
chroma	{min, max}	Allowed 8-bit chroma code values	{"min": <code>, "max": <code>}
maxOutOfRangePercent	number 0–100	Pixels per frame allowed outside the range. Default 0	<percent>

Every pixel of every frame is measured in the file's own bit depth, scaled to 8-bit. A frame fails when more than maxOutOfRangePercent of its pixels are outside. Results come as time ranges, with the worst frame and its code values. If you give only luma, only luma is checked (an open end defaults to 0 or 255). An empty "legalRange": {} checks the standard video range: luma 16–235, chroma 16–240. A file that signals full range is measured on its code values as they are, with a note.

black

File only. Uses ffmpeg blackdetect.

Field	Type	Meaning	Example
maxSeconds	number ≥ 0, required in this section	Longest allowed run of black frames	<s>
allowAtStart	number ≥ 0	Black allowed at the start, in seconds	<s>
allowAtEnd	number ≥ 0	Black allowed at the end, in seconds	<s>
threshold	number 0–1	Luma (as a fraction of the range) at or below which a pixel counts as black. Default 0.1	<fraction>

frozen

File only. Uses ffmpeg freezedetect. A black run isn't reported again as frozen.

Field	Type	Meaning	Example
maxSeconds	number ≥ 0, required in this section	Longest allowed run of identical frames	<s>
noise	number ≥ 0	Difference treated as identical. Default 0.001	<n>

audio

File only. Loudness is measured with ffmpeg ebur128 (ITU-R BS.1770 / EBU R128).

Field	Type	Meaning	Example
integratedLUFS	number	Integrated loudness target	<LUFS>
toleranceLU	number ≥ 0	Allowed deviation from the target. Default 1	<LU>
maxTruePeakDBTP	number	Highest allowed true peak	<dBTP>
maxShortTermLUFS	number	Highest allowed short-term (3 s) loudness	<LUFS>
loudnessRangeLU	{min, max}	Allowed loudness range (LRA)	{"min": <LU>, "max": <LU>}
sampleRate	integer	Sample rate in Hz	<Hz>
channels	integer	Number of channels	<n>
required	true / false	The file must (true) or must not (false) have audio	<true or false>

If the audio section asks for anything and the file has no audio stream, it fails (usually Audio Output was off in the output module).

flash

File only. A photosensitivity pre-check, not a certified PSE / Harding test.

Field	Type	Meaning	Example
check	true, required in this section	Turns the check on	true
maxFlashesPerSecond	number	More than this in any one second fails. Default 3	<n>
minAreaFraction	number 0–1	Smallest part of the screen that counts. Default 0.25	<fraction>
minLuminanceChange	number 0–1	Relative luminance change that counts as a transition. Default 0.1	<fraction>
redFlash	true / false	Also check saturated red transitions. Default true	<true or false>

How it measures: the picture as a 32 × 18 grid, relative luminance per cell. A transition is a change of at least minLuminanceChange where the darker state is below 0.8; a flash is a pair of opposing transitions over at least minAreaFraction of the screen. Saturated red (R / (R+G+B) ≥ 0.8) transitions with a change of (R−G−B) × 320 above 20 are counted too, unless redFlash is false. Definitions after ITU-R BT.1702 / WCAG 2.x.

Call options (not part of the spec)

These go in the ae_preflight call, not in the spec file.

Option	Meaning	Default
action	"check" runs the checks; "schema" returns the spec's JSON schema and how to write one	"check"
spec	Path to the spec file, or the spec object	—
target	"project", "file" or "both"	"project"
file	Path of the rendered file (for file and both)	—
comp	The delivered comp; overrides the spec's comp	spec, then active comp
maxFindings	Most findings listed (1–500)	60
allowFfmpegDownload	Only after you agreed: download FFmpeg once if none is found	false
timeBudgetSeconds	Time limit for the frame-by-frame project checks (5–1800)	120