Skip to content

Reading a QCTools Document

dlandes edited this page Dec 7, 2014 · 29 revisions

The QCTools Document is designed to be a self-descriptive metadata document that stores analytical metadata about video and audio frames and may be quickly rendered in QCTools version 0.5 or later. The QCTools Document is an XML expression of FFprobe's XML expression as defined by the ffprobe schema at http://www.ffmpeg.org/schema/ffprobe.xsd. For more information about FFprobe's XML expression please visit: http://www.ffmpeg.org/schema/ffprobe.xsd; for additional information about FFprobe's XML expression: http://ffmpeg.org/ffprobe.html#xml.

In addition to frame metadata, the QCTools Document stores metadata values output from four evaluative filters: signalstats, cropdetect, psnr, and ebur128.

  • signal stats
    The signalstats filter is a project of the QCTools project. Signalstats outputs information about the range of values used in luminance and chrominance video planes as well as details of hue and saturation and pixel labeling tests such as vertical line repetition, temporal outliers, and broadcast range adherence. More info: http://ffmpeg.org/ffmpeg-filters.html#signalstats.

  • crop detect
    The cropdetect filter detects how a given frame may be cropped to remove black (or nearly black) borders from the edges of the video. It can detect if video has been letterboxed or pillarboxed or other bordering rows or columns of black pixels. More info: http://ffmpeg.org/ffmpeg-filters.html#cropdetect.

  • psnr
    Within the QCTools Document the psnr filter is used specifically to visually compare field 1 and field 2. The filter accepts field 1 and field 2 as two separate inputs and provides quantification of the visual difference between those two images for each plane (Y, U, and V) as well as for the overall image. This data is presented in both Peak Signal to Noise Ratio (PSNR) and Mean Square Error (MSE). More info: ffmpeg.org/ffmpeg-filters.html#psnr.

  • ebur128
    The ebur128 filter is a volume detection filter that measures perceived loudness according to the EBU standard. More info: http://ffmpeg.org/ffmpeg-filters.html#ebur128.

###Library Versions QCTools incorporates a set of open-source libraries, developed under the ffmpeg project, that were built to process audiovisual data. This section of the data format calls out the specific libraries referenced by QCTools. They include:

  • libavutil
  • libavcodec
  • libavformat
  • libavdevice
  • libavfilter
  • libswscale
  • libswresample
  • libpostproc

###Frames and Tags# The document is further divided into Frames and Tags per media type.

A frame describes a particular point in the video or audio and has a set of attributes that describe and identify that point (or frame)--including media type, duration, size, position, etc. A tag contains a key--in this case a reference to the filter name-- and the value for that filter.

Media Type: Audio

The Audio frame element contains descriptive information that identifies a particular frame. The tag attributes include values for the following filters (based on EBU R 128):

  • lavfi.r128.M: or 'Momentary loudness' reflects sudden changes in volume over brief intervals of time (up to 400ms)
  • lavri.r128.S: 'Short term loudness', measured in intervals of up to 3s in duration
  • lavfi.r128.I: 'Integrated loudness', or overall loudness occurring over the entire duration of the audiovisual asset, or from 'start to stop'
  • lavfi.r128.LRA: 'Loudness Range' quantifies the variation across loudness; measured in units of LU (1 LU is equal to 1 dB)
  • lavfi.r128.LRA.low
  • lavfi.r128LRA.high

###Creating a QCTools Document# The QCTools Document can be created in either of the following ways:

  • Via QCTools (version 0.5 or later)

Open a video file for evaluation and then select "Export > To qctools.xml.gz".

  • Via FFmpeg (version 2.3 or later)

For a file with video and audio named EXAMPLE.mov ffprobe -f lavfi -i "movie=EXAMPLE.mov:s=v+a[in0][in1],[in0]signalstats=stat=tout+vrep+brng,cropdetect=reset=1,split[a][b];[a]field=top[a1];[b]field=bottom[b1],[a1][b1]psnr[out0];[in1]ebur128=metadata=1[out1]" -show_frames -show_versions -of xml=x=1:q=1 -noprivate | gzip > EXAMPLE.mov.qctools.xml.gz For a file with video and no audio named EXAMPLE.mov ffprobe -f lavfi -i "movie=EXAMPLE.mov,signalstats=stat=tout+vrep+brng,cropdetect=reset=1,split[a][b];[a]field=top[a1];[b]field=bottom[b1],[a1][b1]psnr" -show_frames -show_versions -of xml=x=1:q=1 -noprivate | gzip > EXAMPLE.mov.qctools.xml.gz

###About gzip Compression # Because of the large volume of data contained in a QCTools document, it is necessary to compress the XML file to ensure it is a manageable size. QCTools uses a compression software called gzip to do this (en.wikipedia.org/wiki/Gzip) which accounts for the .gz file extension.

###Additional Resources# For further information about FFmpeg, EBU audio specifications, etc., please see: FFmpeg / ffmpeg.org
FFmpeg Documentation / [http://ffmpeg.org/documentation.html](http://ffmpeg.org/documentation.html] (http://ffmpeg.org/documentation.html](http://ffmpeg.org/documentation.html) EBU 3341, Loudness Metering: 'EBU Mode' metering to supplement loudness normalizqation in accordance with EBU R 128 / https://tech.ebu.ch/docs/tech/tech3341.pdf
EBU R 128, Loudness Normalisation and permitted maximum level of audio signals / https://tech.ebu.ch/docs/r/r128-2014.pdf
GZIP / www.gzip.org

Clone this wiki locally