Computed scopes
Scopes whose items PPROLint computes: gaps, outliers, pairs of clips, requirements.
Most rules run on the items of the sequence: its clips, tracks, effects or markers. Some checks need items that are not in the timeline as such: a gap between clips, a clip compared with the median of its track, an audio clip paired with the video clip it plays under, a requirement that is not met. PPROLint computes these items, and a rule names the computation as its scope: in the editor, the Analyzers group of the Scope list; in a rule file, "scope": "<id>".
What stays in the rule is what you decide: the thresholds, the condition, the message, the severity. The same computed scope can serve several rules.
How to use one
- Start from a built-in rule. Each computed scope below lists the built-in rules using it. Open one in the editor, or copy its file from its page, and change its thresholds and messages.
- Fields. Each item has the scope's own fields, under its prefix (
gap.durationFrames), and the fields of its base scope: a gap has thesequence.*fields, an outlier theclip.*,track.*andsequence.*fields of its clip. A field of typejsoncan only be copied into data. - Options. A computed scope reads options of the rule, such as the minimum number of clips to compare. The rule must declare each with the type given below; picking the scope in the editor adds them with placeholder defaults. A
jsonoption holds a structured value, described in the option's description. - Where reports point. The computed scope chooses each item's target and position: the gap's start, the outlier clip.
scale-outliers
Video clips compared with the median scale of their track or sequence.
| Property | Value |
|---|---|
| Fields | outlier.*, plus the fields of the clip scope (see Fields) |
| Used by | Scale outliers |
| Field | Type | Description |
|---|---|---|
outlier.value | number | The clip's value. |
outlier.median | number | Median of the population. |
outlier.deviationPercent | number | Deviation from the median, in percent of the median. Negative below. |
outlier.absDeviationPercent | number | Absolute deviation, in percent of the median. |
outlier.populationKey | string | "V1", "A2" for a track population, "sequence" otherwise. |
outlier.populationSize | number | Clips in the population. |
outlier.populationIsTrack | boolean | The population is one track (false: the whole sequence). |
Options it reads, which the rule must declare with these types:
| Option | Type | Description in the built-in rule |
|---|---|---|
scope | string | "track" compares clips with the other clips on the same track; "sequence" with every eligible clip of the sequence. |
minClips | number | Populations smaller than this are insufficient data and are not analysed. |
speed-outliers
Clips compared with the median speed of their track or sequence.
| Property | Value |
|---|---|
| Fields | outlier.*, plus the fields of the clip scope (see Fields) |
| Used by | Speed outliers |
| Field | Type | Description |
|---|---|---|
outlier.value | number | The clip's value. |
outlier.median | number | Median of the population. |
outlier.deviationPercent | number | Deviation from the median, in percent of the median. Negative below. |
outlier.absDeviationPercent | number | Absolute deviation, in percent of the median. |
outlier.populationKey | string | "V1", "A2" for a track population, "sequence" otherwise. |
outlier.populationSize | number | Clips in the population. |
outlier.populationIsTrack | boolean | The population is one track (false: the whole sequence). |
Options it reads, which the rule must declare with these types:
| Option | Type | Description in the built-in rule |
|---|---|---|
scope | string | "track" compares clips with the other clips on the same track; "sequence" with every eligible clip of the sequence. |
minClips | number | Populations smaller than this are insufficient data and are not analysed. |
audio-level-outliers
Audio clips compared with the median volume setting of their track or sequence.
| Property | Value |
|---|---|
| Fields | outlier.*, plus the fields of the clip scope (see Fields) |
| Used by | Audio level outliers |
| Field | Type | Description |
|---|---|---|
outlier.value | number | Volume setting in dB. |
outlier.median | number | Median volume of the population, in dB. |
outlier.deviation | number | Difference from the median in dB. Negative when quieter. |
outlier.absDeviation | number | Absolute difference from the median in dB. |
outlier.populationKey | string | "V1", "A2" for a track population, "sequence" otherwise. |
outlier.populationSize | number | Clips in the population. |
outlier.populationIsTrack | boolean | The population is one track (false: the whole sequence). |
Options it reads, which the rule must declare with these types:
| Option | Type | Description in the built-in rule |
|---|---|---|
scope | string | "track" compares clips with the other clips on the same track; "sequence" with every eligible clip of the sequence. |
minClips | number | Populations smaller than this are insufficient data and are not analysed. |
duration-outliers
Clips compared with the typical duration of their track or sequence.
| Property | Value |
|---|---|
| Fields | outlier.*, plus the fields of the clip scope (see Fields) |
| Used by | Duration outliers |
| Field | Type | Description |
|---|---|---|
outlier.z | number | Modified z-score of the log duration. Negative when shorter. |
outlier.absZ | number | Absolute modified z-score. |
outlier.durationTicks | number | Clip duration in ticks. |
outlier.durationSeconds | number | Clip duration in seconds. |
outlier.typicalTicks | number | Typical duration of the population (exp of the median log duration), in ticks. |
outlier.typicalSeconds | number | Typical duration in seconds. |
outlier.populationKey | string | "V1", "A2" for a track population, "sequence" otherwise. |
outlier.populationSize | number | Clips in the population. |
outlier.populationIsTrack | boolean | The population is one track (false: the whole sequence). |
Options it reads, which the rule must declare with these types:
| Option | Type | Description in the built-in rule |
|---|---|---|
scope | string | "track" compares clips with the other clips on the same track; "sequence" with every eligible clip of the sequence. |
minClips | number | Populations smaller than this are insufficient data and are not analysed. |
missing-effects
Clips lacking an effect that other clips of their track or sequence carry.
| Property | Value |
|---|---|
| Fields | missing.*, plus the fields of the clip scope (see Fields) |
| Used by | Inconsistent effects |
| Field | Type | Description |
|---|---|---|
missing.matchName | string | Match name of the effect the clip lacks. |
missing.displayName | string | Display name of that effect, from a clip that has it. |
missing.withEffect | number | Clips of the population that carry the effect. |
missing.prevalence | number | withEffect / populationSize. |
missing.populationKey | string | "V1", "A2" for a track population, "sequence" otherwise. |
missing.populationSize | number | Clips in the population. |
missing.populationIsTrack | boolean | The population is one track (false: the whole sequence). |
Options it reads, which the rule must declare with these types:
| Option | Type | Description in the built-in rule |
|---|---|---|
scope | string | "track" compares clips with the other clips on the same track; "sequence" with every eligible clip of the sequence. |
minClips | number | Populations smaller than this are insufficient data and are not analysed. |
video-gaps
Ranges of the work area where no video clip is visible.
| Property | Value |
|---|---|
| Fields | gap.*, plus the fields of the sequence scope (see Fields) |
| Used by | Video gaps |
| Field | Type | Description |
|---|---|---|
gap.start | number | Gap start (ticks). |
gap.end | number | Gap end (ticks). |
gap.startTimecode | string | Gap start as timecode. |
gap.endTimecode | string | Gap end as timecode. |
gap.durationTicks | number | Duration in ticks. |
gap.durationFrames | number | Duration in whole frames. |
gap.durationFramesRounded | number | Duration in frames, one decimal, for messages. |
gap.durationSeconds | number | Duration in seconds. |
gap.durationIsSeconds | boolean | At least one second long: word it in seconds rather than frames. |
gap.kind | string | "leading" (touches the work area start), "inner" or "trailing". |
gap.hasBefore | boolean | A clip ends the coverage before the gap. |
gap.beforeName | string | Name of the clip before the gap. |
gap.beforeTrack | string | Track of the clip before the gap: "V1", "A2". |
gap.hasAfter | boolean | A clip starts the coverage after the gap. |
gap.afterName | string | Name of the clip after the gap. |
gap.afterTrack | string | Track of the clip after the gap: "V1", "A2". |
Reads no options.
audio-gaps
Ranges of the work area where no audio clip is audible.
| Property | Value |
|---|---|
| Fields | gap.*, plus the fields of the sequence scope (see Fields) |
| Used by | Audio gaps |
| Field | Type | Description |
|---|---|---|
gap.start | number | Gap start (ticks). |
gap.end | number | Gap end (ticks). |
gap.startTimecode | string | Gap start as timecode. |
gap.endTimecode | string | Gap end as timecode. |
gap.durationTicks | number | Duration in ticks. |
gap.durationFrames | number | Duration in whole frames. |
gap.durationFramesRounded | number | Duration in frames, one decimal, for messages. |
gap.durationSeconds | number | Duration in seconds. |
gap.durationIsSeconds | boolean | At least one second long: word it in seconds rather than frames. |
gap.kind | string | "leading" (touches the work area start), "inner" or "trailing". |
gap.hasBefore | boolean | A clip ends the coverage before the gap. |
gap.beforeName | string | Name of the clip before the gap. |
gap.beforeTrack | string | Track of the clip before the gap: "V1", "A2". |
gap.hasAfter | boolean | A clip starts the coverage after the gap. |
gap.afterName | string | Name of the clip after the gap. |
gap.afterTrack | string | Track of the clip after the gap: "V1", "A2". |
Options it reads, which the rule must declare with these types:
| Option | Type | Description in the built-in rule |
|---|---|---|
silenceDb | number | Clips whose static volume is at or below this do not count as audio. |
av-sync-pairs
Audio clips paired with the overlapping video clip of the same source, with their drift.
| Property | Value |
|---|---|
| Fields | pair.*, plus the fields of the clip scope (see Fields) |
| Used by | Out-of-sync audio and video |
| Field | Type | Description |
|---|---|---|
pair.driftTicks | number | Audio offset from the video's source mapping, in ticks. Positive: the audio is late. |
pair.driftFrames | number | Drift in frames, signed. |
pair.absDriftFrames | number | Absolute drift in frames. |
pair.absDriftFramesRounded | number | Absolute drift in frames, one decimal, for messages. |
pair.videoName | string | Name of the video clip. |
pair.videoTrack | string | Track of the video clip: "V1", "A2". |
pair.projectItemId | string | Shared project item id. |
Options it reads, which the rule must declare with these types:
| Option | Type | Description in the built-in rule |
|---|---|---|
kinds | string[] | Source kinds compared. |
adjustment-layer-edges
Adjustment layer edges inside a clip below, with the offset to the clip's edge.
| Property | Value |
|---|---|
| Fields | edge.*, plus the fields of the clip scope (see Fields) |
| Used by | Partial adjustment layer coverage |
| Field | Type | Description |
|---|---|---|
edge.side | string | "start" or "end" of the adjustment layer. |
edge.time | number | Time of the edge (ticks). |
edge.timecode | string | Time of the edge as timecode. |
edge.offsetTicks | number | Distance to the clip's own edge on that side, in ticks. |
edge.offsetFrames | number | Offset in frames. |
edge.offsetFramesRounded | number | Offset in frames, one decimal, for messages. |
edge.clipName | string | Name of the clip below. |
edge.clipTrack | string | Track of the clip below: "V1", "A2". |
Reads no options.
repeated-footage-pairs
Clips reusing a source range already used by an earlier clip of the same source.
| Property | Value |
|---|---|
| Fields | reuse.*, plus the fields of the clip scope (see Fields) |
| Used by | Repeated footage |
| Field | Type | Description |
|---|---|---|
reuse.overlapTicks | number | Duration in ticks. |
reuse.overlapFrames | number | Duration in whole frames. |
reuse.overlapFramesRounded | number | Duration in frames, one decimal, for messages. |
reuse.overlapSeconds | number | Duration in seconds. |
reuse.overlapIsSeconds | boolean | At least one second long: word it in seconds rather than frames. |
reuse.earlierName | string | Name of the earlier clip. |
reuse.earlierTrack | string | Track of the earlier clip: "V1", "A2". |
reuse.earlierStart | number | Start of the earlier clip (ticks). |
reuse.earlierTimecode | string | Start of the earlier clip as timecode. |
reuse.projectItemId | string | Shared project item id. |
Reads no options.
required-effects
Clips missing an effect the configuration requires on their track.
| Property | Value |
|---|---|
| Fields | requirement.*, plus the fields of the clip scope (see Fields) |
| Used by | Required effects |
| Field | Type | Description |
|---|---|---|
requirement.matchName | string | Required match name. |
requirement.displayName | string | Display name of the effect, from a clip that has it, else the match name. |
requirement.explanation | string | The requirement's message with a leading space, or empty. |
requirement.tracks | json | The requirement's track references. |
requirement.trackType | string? | The requirement's track type. |
Options it reads, which the rule must declare with these types:
| Option | Type | Description in the built-in rule |
|---|---|---|
effects | json | Requirements: { "matchName", "tracks"?: ["V1"], "trackType"?: "video" | "audio", "message"? }. Empty: nothing is required. |
ignoreKinds | string[] | Source kinds exempt from requirements. |
restricted-effects
Clips using an effect the configuration forbids.
| Property | Value |
|---|---|
| Fields | restricted.*, plus the fields of the clip scope (see Fields) |
| Used by | Restricted effects |
| Field | Type | Description |
|---|---|---|
restricted.matchName | string | Match name of the restricted effect. |
restricted.displayName | string | Display name of the effect on the clip. |
restricted.explanation | string | The entry's message with a leading space, or empty. |
Options it reads, which the rule must declare with these types:
| Option | Type | Description in the built-in rule |
|---|---|---|
effects | json | Match names, or { "matchName", "message"? } to append an explanation. Empty: nothing is restricted. |
required-markers
Configured marker requirements the sequence does not meet.
| Property | Value |
|---|---|
| Fields | requirement.*, plus the fields of the sequence scope (see Fields) |
| Used by | Required markers |
| Field | Type | Description |
|---|---|---|
requirement.found | number | Matching markers found. |
requirement.minCount | number | Markers required. |
requirement.pluralCount | number | found, or 1 when none was found, so the requirement reads in the singular. |
requirement.hasType | boolean | The requirement names a marker type. |
requirement.type | string? | Required marker type. |
requirement.hasName | boolean | The requirement names a marker name. |
requirement.name | string? | Required name. |
requirement.hasPattern | boolean | The requirement has a name pattern. |
requirement.namePattern | string? | Required name pattern (regular expression source). |
requirement.hasColor | boolean | The requirement has a color index. |
requirement.colorIndex | number? | Required color index. |
requirement.explanation | string | The requirement's message with a leading space, or empty. |
requirement.requirement | json | The requirement as configured. |
Options it reads, which the rule must declare with these types:
| Option | Type | Description in the built-in rule |
|---|---|---|
markers | json | Requirements: { "type"?, "name"?, "namePattern"?, "colorIndex"?, "minCount"? (1), "message"? }; criteria combine with AND. Empty: nothing is required. |
required-tracks
Ways the track layout misses the configured requirements.
| Property | Value |
|---|---|
| Fields | violation.*, plus the fields of the sequence scope (see Fields) |
| Used by | Required tracks |
| Field | Type | Description |
|---|---|---|
violation.kind | string | "minVideo", "minAudio", "missingVideoName", "missingAudioName", "missingTrack", "wrongName" or "empty". |
violation.count | number? | Tracks found (count requirements). |
violation.min | number? | Tracks required (count requirements). |
violation.name | string? | Required name, or the name found for a wrong name. |
violation.expected | string? | Expected name (wrong name). |
violation.trackRef | string? | Track concerned: "V1", "A2". |
violation.trackName | string? | Name of the track concerned. |
violation.requirement | json | The requirement as configured. |
violation.found | json | What was found, when it is not the requirement itself. |
Options it reads, which the rule must declare with these types:
| Option | Type | Description in the built-in rule |
|---|---|---|
minVideoTracks | number | Minimum number of video tracks. 0: not checked. |
minAudioTracks | number | Minimum number of audio tracks. 0: not checked. |
videoTrackNames | string[] | Names that must exist among video tracks. |
audioTrackNames | string[] | Names that must exist among audio tracks. |
tracks | json | Per-position requirements: { "ref": "V1", "name"?, "nonEmpty"? }. |
sequence-settings
Sequence settings (frame rate, frame size) outside the allowed values.
| Property | Value |
|---|---|
| Fields | setting.*, plus the fields of the sequence scope (see Fields) |
| Used by | Sequence settings |
| Field | Type | Description |
|---|---|---|
setting.kind | string | "frameRate" or "frameSize". |
setting.frameRate | number | The sequence frame rate. |
setting.frameSizeText | string | The sequence frame size: "1920×1080". |
setting.frameSizesText | string | The allowed frame sizes, comma separated. |
setting.frameRates | json | Allowed frame rates. |
setting.frameSize | json | The sequence frame size. |
setting.frameSizes | json | Allowed frame sizes. |
Options it reads, which the rule must declare with these types:
| Option | Type | Description in the built-in rule |
|---|---|---|
frameRates | number[] | Allowed frame rates. 23.976, 29.97… stand for 24000/1001, 30000/1001… Empty: not checked. |
frameSizes | json | Allowed frame sizes: { "width", "height" }. Empty: not checked. |