QCSchool: Introducing qcli

Published On: April 18, 2017 |
Screen Shot 2017-04-22 at 12

With the release of QCTools 0.8.0 comes an exciting new satellite feature: qcli (pronounciation is currently under debate). We asked developer Ashley Blewer to walk us through the basics. For more about QCTools, check out our preservation tools page. You can also check out her qcli Recipes document developed for the 2017 QCTools Tester Workshop. 

QCTools reports can now be generated via the command line. This feature will allow for quick and easy generation of QCTools reports for larger-scale digitization projects through simple scripting, using bash or a programming language like Python. This task can be run in the background and loaded into any QCTools GUI on any computer, which has the potential to help speed up workflow progress.

qcli can be downloaded here, or via Homebrew (brew install amiaopensource/amiaos/qcli).

We will go through how the tool works together.

Run this command

qcli -h

It will trigger the full instructions page and running the command with no flags at all will trigger the simple help page.

Creating files from videos

Find a video file! If you don’t have one lying around, but you do have ffmpeg installed, you can make one on the command line by typing:

ffmpeg -f lavfi -i mandelbrot -c:v libx264 -pix_fmt yuv420p -t 10 test.mkv

It will make a video file in your current directory.

Now that you have a video file, you can pass it into qcli. The most basic way to do this is by typing:

qcli -i test.mkv

qcli will generate a file in the same place as the video file with the same name, but with an additional .qctools.xml.gz suffix.

If you want the exported file to have a specific file name or live in a different directory, you can specify this with the -o command.

qcli -i filename.mkv -o filename.xml.gz

Note that if you use the -o command, you should declare that the file ends in .qctools.xml.gz so it retains the correct formatting and can be compatible with other QCTools systems like the QCTools GUI and the forthcoming SignalServer.

If you’ve already exported a qctools report, or if a qctools.xml.gz exists with the same name in the same folder, the program will exit and not overwrite your file, unless you use the -y flag to force the creation of a new file.


qcli uses the QCTools configuration settings set in the GUI by default. So if you use QCTools regularly and have specified which filters to use, it will keep that same configuration. If you want something else, you can apply specific filters via the command line. For this, the -f flag is used and filters are added by name, with multiple filters being added with a + sign. For example,

qcli -i test.mkv -f signalstats+cropdetect


qcli is also ready to integrate into SignalServer (a web server for processing QCTools for large digitization projects, currently in beta/pre-release). This also relies on the QCTools GUI’s connection to a local SignalServer web server. Because this is still in prerelease, we won’t go into the details associated with SignalServer flags, but they can be seen in the qcli help page.

Let us know what you think of the new tool! Please add any issues to our Issue Tracker here on Github and tweet @BAVCPreserve to let us know how you plan to integrate this into your workflows!