Editor guidelines
How to write a good QC Item: what to call it, how to word the Definition, how to describe the Inputs and Outputs, and how to write the Examples. This page replaces the PDF "EBU.IO/QC Editor Guidelines" (version 11, December 2016).
How to use the Item editor itself is explained in Editing QC Items. The rules that apply to every Item without being repeated in it are in What is implicit for all QC Items.
If you have a doubt after reading this page, look at how stable, published Items do it, or ask in the EBU QC Group.
Before you start
- Think about what the new test is for.
- Decide what the Item does:
- a Check: it tests for something and gives a pass or fail result;
- a Report: it only reports something;
- both. Then structure it as a Check, with a set of optional Outputs that form the reporting part.
Usable as (Check, Report) is not typed in. It follows from the In Checks and In Reports settings of the Inputs and Outputs, see Usable as: Check and Report.
Naming
Item names
- Give the Item a meaningful Name and add all commonly known Aliases.
- The Name may contain spaces. Capitalise the words, for example Audio Channel Count.
- An Item that compares the same information in different Layers is a crosscheck. End its Name with "Crosscheck", for example Loudness Crosscheck.
- Some tests need two Items, one that looks for the presence of something and one that looks for its absence. End the Name of the first with "Expected" and of the second with "Not Expected", for example Video Test Pattern Expected and Video Test Pattern Not Expected. See Presence and absence.
Input and Output names
- Use a meaningful Name.
- Give every Input and Output a Description. It is mandatory in the data model, unlike the Description of the Item.
- When an Input provides a value that something is matched against, end the Name with "Expected", for example Display Aspect Ratio Expected.
- The Data model name is the Name without spaces, in PascalCase, for example
DisplayAspectRatioExpected. Vendors use it in their implementations. It must be unique among all Inputs (or all Outputs) of the Item, children included, and it must not start with "-" or "PRIVATE". See Rules for Inputs and Outputs.
Writing the Definition
- Keep the Definition concise and describe the key concepts. Do not go into implementation detail.
- Prefer these phrases:
- "Used in Checks, the system shall …"
- "Used in Reports, the system shall …"
- When an Item is both a Check and a Report, the Check normally has the option to report measured or calculated information too. Say so: "Optionally, the system shall report …".
- When a standard must be followed, say so: "xxxx shall be measured according to Standard YYY".
- Use Remarks for information that complements the Definition, not for text that belongs in it.
- The Definition starts with a capital letter and ends with a full stop (the Item checks warn when it does not).
References
Give each reference with its official title and a URL where it can be obtained. List references from recognised standards bodies first. A reference without a date means the latest version, see What is implicit for all QC Items.
Inputs and Outputs
What not to describe
Some things are always there, so they are not described as Inputs or Outputs. See Implicit inputs and outputs.
Type, Representation, Unit and Range
- Choose Type, Representation, Unit and Range from the official values in the lists. Editors can propose a new value, but it is not official until a Workflow Manager makes it so. See Parameters.
- In the 2026-04 data model Unit, Representation and Range are optional. A count has no unit: leave the Unit empty.
- The Range is free text and sets the values that users can choose. Users do not see the Range definition behind it.
- Use these notations for a Range with two boundaries a and b:
[a,b]: both a and b are included;(a,b]: b is included, a is not;[a,b): a is included, b is not.
Write infinity in lower case as one of the boundaries, for example [0,infinity).
* A Default value applies when an Input is not provided, for example -23 LUFS for a loudness target. A default value does not make an Input required or optional.
Required, optional and not applicable
Set In Checks and In Reports on every Input and Output to Required, Optional or Not applicable.
- Required parameters are the minimum a QC Item provides. They are always applied. Vendors must support all required Inputs and Outputs of the Items they claim to support.
- Optional parameters depend on whether the user wants to check for something, and on whether the vendor supports that function.
- Not applicable means the parameter plays no part in that use of the Item.
A required parameter can still have no real value in a particular result. Example: an Item has two required Outputs, Wrapper (raw or MXF) and Wrappertype (frame-based or clip-based). For a raw file there is no Wrappertype. The QC product then states "not applicable" or "not available" for it, and is exempt from producing a real value, even though the parameter is required in the Item.
Inputs
- Do not add Inputs for the content to analyse, for limiting the analysis to time intervals or areas, for tracks or for the wrapper location. See Implicit inputs and outputs.
- An Input that refers to a position in time or in the picture is rare. Use the positioning flags and the Parent field only when the Item really needs them.
Outputs
- In a Check, the Outputs that carry the result are required in checks. Other Outputs are normally optional: besides the pass or fail, a user can often ask for more reporting through them.
- Outputs that refer to a position in time or in the picture, or to a track or wrapper location, are described with the positioning flags. When several values belong to one fragment (for example an average, a maximum and a confidence level), give them a parent Output and add the values as its children, see Parent field.
Checks and CheckResult
- A Check reports whether it passed. The CheckResult is normally true when the test passed: thresholds are not exceeded, no defects are found, expected values match within tolerance.
- Explain what the CheckResult means in the CheckResult definition with a phrase such as "True when …, false otherwise". See CheckResult definition.
- To make the result fit the intention, some Checks need two Items, an Expected and a Not Expected one. See Presence and absence.
- A crosscheck tests whether the same information in different Layers (for example wrapper and bitstream) matches. It usually has no Inputs, or only a tolerance for matching.
Presence and absence
Some tests look for a pattern at a specific place in a programme, for example colour bars and tone at the start, then black and silence, then the programme, then black and silence at the end. For these:
- Add "Expected" to the Name and the data model name of the Item that checks for presence, for example Video Test Pattern Expected (
VideoTestPatternExpected). - Add "Not Expected" (
NotExpected) to the one that checks for absence. - The time windows to test are normally provided implicitly, by limiting the analysis to the scope the user sets (see Implicit inputs and outputs), not by Inputs in the Item. When there are several windows, and unless the Item says otherwise, the logic is AND: the Expected Item wants to find the pattern in every window, and the Not Expected Item does not want to find it in any window.
- When patterns on different tracks must be present in the same time interval (for example bars on video and tone on audio), create a separate, dedicated Check.
Examples
Give meaningful Examples. When the Item is both a Check and a Report, give at least one Example of each.
Use this template, and add Remarks when necessary:
Input: "inputname" = value
Output: "outputname" = value
When an Output has children, list each child below it with an arrow (two dashes and a greater-than sign):
Output: "parentoutput" from tc1 to tc2
--> "childoutput1" = value
--> "childoutput2" = value
Where to ask
Questions about editing, and proposals for new Types, Representations, Units or Ranges: the EBU QC Group, or e-mail tech@ebu.ch.