qctools

QCTools (Quality Control Tools for Video Preservation) is a free and open source software tool that helps users analyze and understand their digitized video files through use of audiovisual analytics and filtering. QCTools is funded by the National Endowment for the Humanities and the Knight Foundation, and is developed by the Bay Area Video Coalition.

View the Project on GitHub bavc/qctools

Playback Filter Descriptions

The QCTools preview window is intended as an analytical playback environment that allows the user to review video through multiple filters simultaneously. Often inconsistencies within the graph layout may be better understood by examining those frames in the playback window. The playback window includes two viewing windows which may be set to different combinations of filters. This allows a user to playback a video by multiple forms of analysis simultaneously just as viewing a waveform and a vectorscope side-by-side or seeing the video with highlighted pixels that are outside of broadcast range while seeing the waveform display.


Table of Contents

Arrangement

Adjustments
Adjust Signal

Bit Plane
Bit Plane 10 slices
Bit Plane Noise
Broadcast Illegal Focus
Broadcast Range Pixels
Chroma Shift
CIE Scope
Color Matrix
Corners
Datascope
EIA608 VITC Viewer
Extract Planes Equalized
Field Difference
Filmstrip
Histogram
Histogram Temporal X Limiter
Line Over Time
Line Select
Normal
Oscilloscope
Pixel Offset Subtraction
Pixel Scope
Sample Range
Saturation Highlight
Temporal Difference
Temporal Outlier Pixels
Value Highlight
Value Highlight (Range)
Vectorscope
Vectorscope High/Low
Vectorscope Target
Vertical Line Repetitions
Vertical Repetition Pixels
Waveform
Waveform Target
Zoom

Arrangement

The size of the player may be set to “Fit to screen”, “100%”, or “Free Scale”.

The QCTools player can show from one to six different visualizations, so their arrangement may be selected from the following options:

Adjustments

Adjust Signal

If “Adjust Signal” is enabled, then the signal of the input video will be adjusted before the filters are applied or the presentation is made. For instance, if viewing the waveform filter and adjusting the ‘Black’ or ‘Contrast’ settings under ‘Adjust Signal’ then you’ll see the waveform be subsequently adjusted. Adjustments can be helpful is you suspect a video was digitization with unoptimal settings and the brightness and color could here be adjusted, similar to the settings of a proc amp, to show the impact of the change. It is recommend to use the waveform and vectorscope filters as the ‘Adjust Signal’ settings are calibrated in order to see the impact of the adjustments.

This filter allows the Y values to be increased or decreased via the Black slider. Also the Contrast allows a multiplier to be applied to all Y values.

This filter enables the hue and saturation levels to be adjusted. Hue adjustments may be expressed in degrees where 0 is no change and 180 would invert the color. For saturation a value of 1 needs the saturation unchanged, 0 removes all color, and the saturation may be increased up to a maximum of 10. The chroma values (Cb and Cr) may also be shifted by increasing or decreasing their values (similar to Red Shift/Blue Shift on a time-base corrector).

Filters

Normal

This view simply shows the video as QCTools interprets it, no special effects or filtering are added. In this view, however, you also have the option of enabling a ‘Field’ display which splits the two video fields for the selected frame and displays them as discrete images. Thus all odd-numbered video lines appear are resorted to appear on the top of the image and the even-numbered lines appear on the bottom. Since many analog video issues occur differently between the two interlaced fields, splitting the fields into two distinct images can make it easier to see if a given issue is from problems with the analog video playback device (such as a head clog where the two fields would react very differently) and tape damage (where the two fields would react similarly).

The Metadata option will overlay some metadata onto the image, including the presentation timestamp, frame size, and metadata from filters that perform crop detection and interlacement pattern detection.

The Action/Title Safe option will overlay boxes to show the Action Safe and Title Safe areas as defined by SMPTE ST 2046-1 (2009). The Safe Action Area is a box that includes 93% of the width and height and is drawn in yellow. The Safe Title Area is a box that includes 90% of the width and height and is drawn in green. Thanks much to @bbgdzxng1 for supporting this feature.

Bit Plane

This filter selects the bit position of each plane for display. Selecting ‘None’ for a plane will replace all values with a neutral middle gray. Selecting ‘All’ will send the display plane as is. Selecting ‘Bit N’ (where N is the number of a bit position) will display only that specific bit position of each pixel of the plane. For example, the Y plane a pixel will display as black if that bit is ‘0’ or white if that bit is ‘1’, for U a pixel will be yellow-green if ‘0’ purple if ‘1’, for V a pixel will be green for ‘0’ and red for ‘1’ (RGB pixel formats are supported as well). Generally lossy video codecs will show blocky structured patterns at higher numbered bit positions. See the bit plane article in Wikipedia for more information about the application of bit plane filtering.

Bit Plane

(Video sample and permission to use provided by seattle.gov)

Bit Plane 10 slices

This filter is similar to Bit Plane, but it shows a section of each of the first 10 bit planes at once in the selected plane. The slices are presented in most-significant to least-significant order as left to right (or top to bottom if ‘Rows’ is selected). Each of the 10 bit planes is marked by a green border. If the Slice option is enabled, the video will be sliced into 10 parts with a different bit position (from 1 to 10) presented in each slice, if slice is unchecked then the video is repeated as a full frame ten times with a different bit position presented in each iteration (this will display as a very wide image, so it’s recommended to uncheck ‘Fit to Grid’ with this option). The Show 2 will present each bit plane with the subsequent bit plane. Note that if the input video is uses less than 10 bits per sample, then part of the image will be blank.

Bit Plane 10 Slices

Bit Plane Noise

This filter is similar to Bit Plane, but instead of showing if the selected bit position of a selected plane is set to 0 or 1, it attempts to predict if that bit represents signal or noise. This filters uses a method for calculating this by comparing each pixel’s selected bit (X,Y) to selected bit of three adjacent pixels (X-1,Y), (X,Y-1) and (X-1,Y-1). If the bit is the same as at least two of the three adjacent bits, it may not be noise. A noisy bit-plane will have 49% to 51% pixels that are noise.

Bit Plane Noise

Bit Plane Noise Graph

This filter displays the YUV plot of a selected plane (y, u, or v). Note that because this filter requires more than one frame to display the filter will need to be in playback mode to reveal an image. The 10 least significant bits will be plotted on a scale of 0 to 1, where 1 (the top of the graph) indicates a random level of noise and 0 depicts less random data. When the video uses less than 10 bits, the higher numbered bits will be 0.

Broadcast Illegal Focus

For video that uses the YUV colorspace and decode in a broadcast range. On an 8-bit scale, values from 0-16 will all decode to black on a computer monitor, while values from 235-255 will decode as white. This filter allows the users to select to feature pixel data that is outside of broadcast range. Select “above whites” to set pixels with luma values from 236-255 to a range of grays (while all other pixels are set to black). Select “below black” to set pixels with luma values from 0-15 to a range of grays (while all other pixels are set to black). If a video frame only contains pixels that have luma values within broadcast range, then this filter will play black only black pixels. This filter portrays broadcast range compliance in somewhat the opposite way as the “Broadcast Range Pixels” filter since it focuses on values that may be crushed to black or white because they fall outside of broadcast range. Note that some videos may intentionally be encoded in ‘full range’ where this filter is less relevant.

Broadcast Illegal Focus

Broadcast Range Pixels

This is the same presentation as ‘Normal’ except that pixels that are outside of broadcast range are highlighted. Again here, you have the option of selecting ‘Field’ to display field 1 (top) and field 2 (bottom) separately.

Broadcast Range Pixels

CIE Scope

This filter plots the range of visible colors as defined by the Committee Internationale de l’Eclairage/International Commission on Lighting (CIE) chromaticity diagram. See Georgia State University’s Hyperphysics page for more information on this color space.

CIE Scope

Chroma Shift

This filter allows the Cb and Cr planes to be offset horizontally or veritcally to check if the color data is properly timed to the luminence data. See FFmpeg’s documentation on chroma shift.

Color Matrix

Allows for playback in various color spaces, including BT.601, BT.709, SMPTE240M and FCC. The filter includes a Reveal slider so that the original image and a version interpreted through the selected color matrix may be shown side-by-side for review.

Color Matrix

Corners

This view presents a quadrant view of a zoom in on the four corners of the image. The W and H options can be adjusted to change the width and height of the corner to crop and display. The resulting pixels are then enlarged and shown within a grid. This view can be used to determine a precise cropping for an image or to inspect the details of the frame’s edges.

When the ‘field’ mode is selected the four quadrants are split to show the top field on the top of each part of the quadrant and the bottom field on the bottom of each part of the quadrant.

Datascope

Datascope

EIA608 VITC Viewer

This filter interprets potential VITC and EIA608 (often referred to as line 21) data to display the values stored as timecode and/or captions. By default the top 30 lines of video are assessed for this data but the scan_max option can adjust the number of top lines to assess from 1 to 100. EIA608 data will be shown in hexadecimal form along with the number of the line (counting from 1 as the top line). There is a ‘zoom’ option which will crop and scale the selected lines so that they can be viewed in more detail. If VITC or EIA608 data is not found then hyphens will be shown instead.

Several options from FFmpeg’s readeia608 filter are accessible:

EIA608 VITC Viewer

For more information, see the documentation on FFmpeg’s readvitc and readeia608 filters. A sample IMX file with both VITC and EIA608 data is available at the Internet Archive.

Extract Planes Equalized

This filter extracts a specified video plane (such as Y, U, or V) which represents the luma or part of the chroma data from the video so that it may be reviewed on its own. The filter also may apply histogram equalization to redistributes the pixel intensities to equalize their distribution across the intensity range (this feature can help exaggerate or clarify the details of the plane image). This filter is useful for detecting lossy compression in video signals or establishing provenance.

This image shows the Normal display on the left and Extract Planes on the right. The Extract Planes filters reveals the macroblock pattern of lossy MPEG2 compression in the square patterns throughout the image.

Extract Planes Equalized

Field Difference

This presentation visualizes the difference between video field 1 and field 2. A middle gray image would mean that field 1 and field 2 were identical, whereas deviation to white or black indicates a difference.

Field Difference

Filmstrip

Displays a user-defined “tiled” mosaic of successive frames. Maximum 12x12 grid. Note that because this filter requires more than one frame to display the filter will need to be in playback mode to reveal an image. By default, this player will scale down the frame size before tiling them together, but the “Full Size” option will avoid scaling but impact performance.

Frame Tiles

Histogram

The histogram shows the frequency of occurrence of values per channel. Typically the histogram will show one graph per channel (one for each Y, U, and V or one for each red, green, and blue). Video with a lot of contrast and a well distributed range of luminance values will result in a histogram with an even spread. You may also select ‘Field’ option which will depict fields 1 and 2 separately (field 1 on top, field 2 on bottom).

Histogram

Histogram (Temporal)

The histogram shows the frequency of occurrence of values per channel over time. See the ffmpeg documentation on thistogram for more information.

Limiter

Constrain playback to a specified sample range of the frame. Setting min and max values will clip all values below min to min and all values above max to max. For instance with an 8 bit video, the samples above broadcast range could be examined by setting min to 235 (the upper limit of broadcast range) and 255 (the highest possible 8-bit value). The strength value will apply a global color histogram equalization to stress the difference between the sample values. See the FFmpeg limiter filter for more information.

Line over Time

This filter shows only 1 or 2 lines of video accumulate over time, like a slit-scan video. It can be used to focus on a single line of video (such as captioning in line 21) but showing multiple frames of an isolated line at once. The image is generated with FFmpeg’s tile filter.

Line Select

Allows a user to select one line of video signal to display as a waveform. Includes ‘Vertical’ and ‘Background’ modes. When ‘Vertical’ is enable the user may select to plot a waveform of a single column rather than the default plot of a single row. The ‘Background’ option shows the frame image under the waveform with the highlighted row or column highlighted in yellow.

Line Select

Oscilloscope

Provides a 2D Video Oscilloscope. Useful to measure spatial impulse, step responses, chroma delays, etc. See FFmpeg’s oscilloscope documentation for more information.

Pixel Offset Subtraction

Displays the difference betweeen a frame and the same frame offset vertically or horizontally by a specified amount. Vertical and horizontal offsets may be specified independently for luma and chroma. When all offsets are set the zero, the image should be gray (i.e. no difference).

Pixel Offset Subtraction

Pixel Scope

Displays an image using FFmpeg’s (pixscope)[https://ffmpeg.org/ffmpeg-filters.html#pixscope] filter. Note that if the image is less than 640x480, it will be scaled up to that size before displaying it in the scope.

Sample Range

This filter operates similarly to Color Matrix but shows the original image alongside a version interpreted through a selected sample range. Here you can see how the video would look it interpreted as either full range or broadcast range.

Sample Range

Saturation Highlight

Highlights saturation with a user-defined range of minimum value to maximum value. Includes field mode.

Saturation Highlight

Temporal Difference

Displays an image obtained from the temporal difference between successive frames. Note that because this filter requires more than one frame to display the filter will need to be in playback mode to reveal an image.

Temporal Difference

Temporal Outlier Pixels

This is the same presentation as ‘Normal’ except that pixels that are labelled as temporal outliers are highlighted. Temporal outliers are pixels that significantly differ from their neighbors and often correspond to tape damage or playback error. Select ‘Field’ to see the fields displayed separately.

Temporal Outlier Pixels

Value Highlight

This filter selects a video plane and highlights a specific value. The original image of the plane will be presented in grayscale and value will be highlighted as the selected color.

Value Highlight (Range)

This filter selects a video plane and highlights values with a specified range of minimum value to maximum value. The original image of the plane will be presented in grayscale and values within the range will be highlighted as the selected color; for instance to highlight Y values below NTSC broadcast range, set plane to Y, min to 0 and max to 16 (16 for 8 bit video or 64 for 10 bit video) and the resulting image will highlight Y values below broadcast range.

Value Highlight

Vectorscope

A vectorscope display. This display plots chroma values (U/V color placement) in two dimensional graph (which is called a vectorscope). It can be used to read of the hue and saturation of the current frame. The whiter a pixel in the vectorscope, the more pixels of the input frame correspond to that pixel (that is the more pixels have this chroma value). On an 8-bit scale, the V component is displayed on the vertical (Y) axis, with the bottom edge being V = 0 and the top being V = 255. The U component is displayed on the horizontal (Y) axis, with the left representing U = 0 and the right representing U = 255. Six blocks are highlighted to depict standardized color points for red (90, 16), green (54, 222), blue (240, 146), cyan (166, 240), magenta (202, 44), and yellow (16, 110). All valid chroma values fall within a circular shape from the center to the outer edge of the plot.You may also select ‘Field’ option which will depict fields 1 and 2 separately (field 1 on top, field 2 on bottom).

Vectorscope Split Screen

The vectorscope player provides the following options:

Vectorscope

Vectorscope High/Low #{vectorscope-highlow}

This player is similar to Vectorscope but it shows two vectorscopes side by side showing the lower range of colors on the left and higher range of colors on the right. The threshold slider can adjust the divider between low and high in allocating plotted colors between the two vectorscopes. This technique can be helpful to isolate colors which occur in a shadow or a highlight. See FFmpeg’s vectorscope documentation for information, particularly the lthreshold and hthreshold options which are used here to generate the two vectorscope images.

Vectorscope Target

The Vectorscope Target is similar to the Vectorscope filter but a box is drawn over the image by setting an x and y coordinate and size of the box. The vectorscope image drawn will depict the vectorscope plotting of only the samples within the box. The original image may be shown as a background to the vectorscope by enabling the ‘Background’ checkbox.

Vectorscope Target

Vertical Line Repetitions

This filter highlights repetitive lines of video data.

Vertical Line Repetitions

Waveform

The waveform plots the brightness of the image, each column of the waveform corresponds to a column of pixels in the source video. The pixels of each column are then plotted in an 8-bit scale (0-255) which is equivalent to 0 to 110 IRE. The range from 0-16 (0 to 7.5 IRE) is highlighted in blue and indicates a black value that is below traditional NTSC broadcast range. The range from 235-255 (100 to 110 IRE) is highlighted in red and indicates a white value that is above broadcast range. For most analog media the intended pixel luminosity values should exist between 7.5 and 100 IRE. You may also select ‘Field’ option which will depict fields 1 and 2 separately (field 1 on top, field 2 on bottom).

Traditionally a waveform plots the values of each column of video pixels. The QCTools waveform also provides a ‘Vertical’ option which plots the video as rows of pixels. The waveform will still show the value range of the whole frame whether ‘Vertical’ is enabled or not, but with ‘Vertical’ enabled it is often easier to detect video issues that affect rows of pixel data such as dropouts. The waveform player is based on the waveform filter from FFmpeg.

Waveform

The waveform player provides the following options:

Waveform Target

The Waveform Target is similar to the Waveform filter but a box is drawn over the image by setting an x and y coordinate and size of the box. The waveform image drawn will depict the waveform plotting of only the samples within the box. The original image may be shown as a background to the vectorscope by enabling the ‘Background’ checkbox.

Waveform Target

Zoom

Allows a user to zoom to a particular portion of the image using X and Y coordinates. Includes “Strength” and “Intensity” modes.

Zoom