QuartzCrystalCLI is the command-line interface to the QuartzCrystal renderer. It's used behind the scenes from the GUI, and can also be used manually.

It's located in the /Contents/Resources folder of the Application Bundle (where it's needed by the GUI), but can also be copied elsewhere (e.g., /usr/local/bin) for easier access.

When run without any command-line options, it looks like this:

QuartzCrystal 2.0 (20110529 X86)        http://kineme.net/
Copyright (C) 2011 Kosada Incorporated.
usage: ./QuartzCrystalCLI [options] [Composition File]
Where Options are as follows:
   * --version          prints the current version/build number
   * --help             prints this message
   * -o [file]          output file name
   * -w [width]         output width, in pixels.  Default is 640
   * -h [height]        output height, in pixels.  Default is 480
   * -c [codec]         output codec (use '-c help' to list available codecs).  Default is 'avc1'
   * -f [framerate]     output framerate, in frames per second.  Default is 30
   * -q [quality]       codec quality -- 0-5, lowest to highest.  Default is 3
   * -a [antialias]     amount of anti-aliasing -- 1-8 are sane values.  Default is 1 (none)
   * -m [motionblur]    amount of motion blur -- 1-1024 are sane values.  Default is 1 (none)
   * -d [duration]      length of movie in seconds.  Default is 10
   * -s [start time]    initial frame time.  Default is 0
   * -l [time scale]    time multiplier.  Default is 1
   * -p [key=value]     parameter control.
   * -e [file]          a QCRecording event file to render.  If specified, and no duration is specified,
                        renders entire QCRecording event file.
   * -v                 increases verbosity.  Default is 0 (no output).


Render a composition to a movie file

Say you have a composition on your Desktop called "spherespin.qtz". Open Terminal, and cd into the QuartzCrystal.app/Contents/Resources folder, then type:

./QuartzCrystalCLI ~/Desktop/spherespin.qtz

This command creates a 10-second movie in the current folder, called "QuartzCrystalRender.mov", 640x480, at 30 FPS.

Render a composition to a movie file, setting a published input port value

./QuartzCrystalCLI -p Period=42 ~/Desktop/spherespin.qtz

This command sets the published input port "Period" to have value "42", then renders the movie with defaults as above.

If the value contains spaces, put it in double quotes, like this:

./QuartzCrystalCLI -p Text="Hello World" ~/Desktop/textscroll.qtz

Render multiple compositions to multiple movie files

Let's make a script to run QuartzCrystalCLI multiple times.

Open TextEdit and create a new document. Go to the Format menu and click Make Plain Text. Then paste the following:

QuartzCrystalParameters="-p Period=42"
for InputComposition in "$@"; do
    OutputMovie=$(dirname "$InputComposition")/$(basename "$InputComposition" .qtz).mov
    $QuartzCrystalCLI $QuartzCrystalParameters -v -o "$OutputMovie" "$InputComposition"

In the above script, change QuartzCrystalCLI to the path where you've installed QuartzCrystal.app. Change QuartzCrystalParameters to the rendering parameters you'd like to use. Save it as QuartzCrystalBatch.sh. In Terminal, make the script executable:

chmod +x QuartzCrystalBatch.sh

Then, invoke the script in Terminal, adding the composition files you'd like to render:

./QuartzCrystalBatch.sh /Users/smokris/Desktop/spherespin.qtz /Users/smokris/Desktop/boidfish.qtz /Users/smokris/Desktop/pauli-dyson-lenard.qtz

You can drag and drop compositions into the Terminal window, and it'll fill in the full path to the composition file.

The script will render each composition to a movie file in the same folder as the composition.