How rules work
The model behind every rule — snapshot, scope, items, checks, diagnostics.
From a sequence to diagnostics
When PPROLint checks a sequence, it first reads a snapshot of it from Premiere: its settings, its video and audio tracks, their clips with their effects, and the sequence markers. Rules only ever see this snapshot. They never read or change your project directly.
Each rule then runs on its own:
- Its scope turns the snapshot into items: every clip, every track, every marker, the sequence itself…
- For each item, its checks are tried in order. A check is a condition and a message.
- When a condition holds, the item gets a diagnostic: the rule's severity, the message with its placeholders filled in, the item it points at and a position in the timeline.
sequence ──snapshot──▶ items of the scope ──conditions──▶ diagnosticsA rule is deterministic: the same sequence, the same rule file and the same settings always give the same diagnostics.
Scope and items
The scope decides what a check is evaluated against, and so which fields it can read:
| Scope | One item per | Fields |
|---|---|---|
sequence | sequence (once) | sequence.* |
track | video track, then audio track | track.*, sequence.* |
clip | clip of every track, video first | clip.*, track.*, sequence.* |
effect | user-applied effect of every clip | effect.*, clip.*, track.*, sequence.* |
marker | sequence marker | marker.*, sequence.* |
Every scope also reads the rule's options as options.<name>. See Scopes for what each diagnostic points at.
Some built-in rules use a computed scope, such as video-gaps or scale-outliers: PPROLint computes the items for them (a gap between clips, a clip compared with its neighbours) and the rule file keeps the thresholds and messages. You can copy such a built-in rule and change its options, severity and wording; Computed scopes lists them all with their fields.
Fields are typed and checked
A field is a named, typed value of the current item: clip.scale is a number, clip.name a string, clip.disabled a boolean. Every field path, operator and placeholder is checked when the rule loads. A typo, or a field the scope does not have, makes the file fail to load with a precise message; it never becomes a rule that silently reports nothing.
Times are integer ticks, 254,016,000,000 per second, unless the field's name says frames, seconds or timecode: clip.duration is in ticks, clip.durationFrames in frames, clip.startTimecode a HH:MM:SS:FF string.
Unknown values
Some values can be missing from a timeline: an audio clip has no scale, a clip without source media has no media path, an in point may not be set. Such a value is unknown. The fields reference marks these fields with a ? type.
Unknown is never replaced by a default. A comparison on an unknown value is false, so a rule does not report what it cannot measure. See Unknown values for the one trap this sets with not.
One rule, one id
The id of a rule (no-offline-media) is how the panel, the settings and every diagnostic refer to it. It never changes once a rule is in use; its display name may. Two rules cannot share an id, except on purpose: a custom rule file with the id of a built-in rule replaces it. See Custom rules.
What a rule file does not do
On purpose, the format has:
- No code. A rule file combines fields and operators PPROLint knows. It cannot compute anything new, read files or reach the network.
- No arithmetic or string functions in conditions. Values a rule needs are fields of their own, such as
clip.durationFramesnext toclip.duration. - No changes to your project. Rules report; you decide what to fix.
- One sequence at a time. There are no checks across sequences.