Using the Command Line

If you are accustomed to doing your work from Terminal shells, and you need or prefer to run Batch Monitor, Compressor, or the Apple Qmaster distributed processing system from the command line with minimal use of application interfaces, this appendix is for you.

Note: On any given Final Cut Studio system or network, the Compressor and Apple Qmaster versions (numbers) and the version of QuickTime must all match. For example, Compressor 3.0.5 will work only with the 3.0.5 version of Apple Qmaster, and no other version. In this example, the correct version of QuickTime is QuickTime 7.5.5 or later. Non-matching configurations are not supported.

Installing Apple Qmaster from the Command Line

Follow these steps to install Apple Qmaster software on each computer you want to use for distributed processing. (All computers must be on the same subnet.)

To install Apple Qmaster software from the command line
  1. Copy the standalone installer package (AppleQmasterNode.mpkg) to the remote system.

    Note: Do not alter the file hierarchy of the packages.

  2. Log in to the remote system.

  3. Enter the following command:

    sudo installer -pkg AppleQmasterNode.mpkg -target /

    Apple Qmaster processes start automatically after installation.

  4. Repeat these steps for each computer in your distributed processing network.

Tip: You can also install Apple Qmaster using Apple Remote Desktop. Just select a node, click Install Package, and select the standalone installer package (AppleQmasterNode.mpkg). The copy and installation process is done automatically.

Shell Commands for Configuring Service Nodes and Cluster Controllers

As an alternative to using the Apple Qmaster pane in System Preferences, you can use the command qmasterprefs, with command-line options for enabling and disabling service node and cluster-controlling services.

In the command-line descriptions below, angle brackets < > indicate a mandatory argument in a command, and brackets [ ] indicate an optional argument.

Synopsis

Below is a synopsis of the command for enabling and disabling Apple Qmaster services on a computer. The qmasterprefs command is located in /usr/sbin.

qmasterprefs [options] [-cluster <on | off> [options]] [-service <name> <on | off> [options]]

Command Options

This table provides information about each of the enabling and disabling service-node and cluster-controlling services on a computer.

Preference command option
Description
‑help
Displays information about supported options for qmasterprefs.
‑list
Lists the current qmasterprefs settings.
‑resetCluster [cancelJobs]
Restarts cluster processes. cancelJobs deletes batches in the queue.
‑allowBonjourDiscovery <on | off>
Enables or disables Bonjour advertisements.
‑startSharing [servicesOnly | servicesAndCluster | servicesAndQuickCluster]
Sets sharing state. (Similar to the Apple Qmaster pane in System Preferences.)
‑stopSharing
Stops Apple Qmaster services on local computer.
‑restart
Restarts all Apple Qmaster services.
‑reset
Resets Apple Qmaster services to default configuration.
‑launchContentAgent <on | off>
Automatically launches content agent at startup.
‑log [0-5] [truncate on | off]
Sets logging level. Default is 3. Off is 0. Sets whether logs are overwritten when services are restarted.
‑statusMenu <on | off>
Displays service node status indicator in menu bar.
‑cluster <on | off> [options]
Turns cluster-controlling services on or off. All [options] are:
[timeout min] [[quickcluster] servername name] [maxactivetargets val] [maxactivesegments val] [storagepath path] [privatestorage on|off] [publishedstorage on|off] [storagecleanupthreshold days] [unmanagedservices on|off] [unmanagedmulticapturethreshold sec] [networkinterface allinterfaces | <bsd name>] [log [0-5] | [truncate on|off]]
-service “name” [on|off] [options]
Turns service on or off. Valid names are Rendering or "Compressor Processing". All [options] are: [timeout min] [sharing on|off] [instances n] [autorestart on|off] [unmanaged on|off] [log [0-5] [truncate on|off]]

Note: For a complete list of shell command options, enter qmasterprefs -help.

Example of the qmasterprefs Command

In the following example, the computer is set to be a cluster controller, bound to the primary network interface (en0), with logging set to verbose, with the logs not overwritten. The Rendering service is on, with 4 managed services and logging set to verbose, with the logs not overwritten. The Compressor Processing service is configured with the same settings, with two instances.

qmasterprefs -sharingType servicesAndCluster -cluster on networkinterface en0 log 5 truncate off -service Rendering on sharing on instances 4 unmanaged off log 5 truncate off -service "Compressor Processing" on sharing on instances 2 unmanaged off log 5 truncate off
To reset controller and service configurations
  • Enter the following:

    qmasterprefs -reset
To reset all controller and service processes and cancel all batches in queue
  • Enter the following:

    qmasterprefs -resetCluster cancelJobs
To stop sharing
  • Enter the following:

    qmasterprefs -stopSharing
To start sharing
  • Enter the following:

    qmasterprefs -startSharing
To change the cluster storage path to an Xsan volume
  • Enter the following:

    qmasterprefs -cluster off storagepath /Volumes/XsanVol
To change the number of Compressor Processing services from 2 to 4
  • Enter the following:

    qmasterprefs -service "Compressor Processing" off sharing on instances 4
To turn off the Rendering service
  • Enter the following:

    qmasterprefs -service Rendering off
To turn on unmanaged services for Compressor Processing
  • Enter the following:

    qmasterprefs -service “Compressor Processing” on unmanaged on
To configure a service-only node
  • Enter the following:

    qmasterprefs -stopSharing -sharingType servicesOnly -startSharing
To create a QuickCluster
  • Enter the following:

    qmasterprefs -stopSharing -sharingType servicesAndQuickCluster -startSharing

Shell Commands for Submitting Compressor Jobs

You can run the Compressor application from the command line using the Compressor command, with a number of command-line options for submitting jobs.

In the command-line descriptions below, angle brackets < > indicate a mandatory argument in a command, and brackets [ ] indicate an optional argument.

Synopsis

Below is a synopsis of the command for submitting a job to a cluster. The Compressor command is located in /Applications/Compressor.app/Contents/MacOS/.

Compressor [‑clustername <name>][‑clusterid <username:password@ipaddress:portNumber>] [‑batchfilepath <path>] [‑batchname <batchname>] [‑priority <value>] [‑jobpath <path>] [‑settingpath <path>] [‑destinationpath <path>] [‑info <xml>] [‑timeout <seconds>] [‑help] [‑show]

In this example, ‑jobpath, ‑settingpath, and ‑destinationpath can be repeated as many times as the number of jobs you want to submit.

Note: Not all the options are necessary. For example, you can specify the cluster either by its ‑clustername or by its ‑clusterid. You do not need to specify both. If both are specified, only ‑clusterid is used.

Additionally, if you specify ‑batchfilepath, then ‑jobpath, ‑settingpath, and ‑destinationpath are not necessary because the previously saved batch file already contains information about the job, settings, and destination.

Example of ‑batchfilepath:

Compressor ‑clustername "This Computer" ‑batchfilepath "/Volumes/Hermione/SavedCompressorBatches/FreeChampagne.compressor"

Once the job is submitted successfully, this command displays the batch ID (identifier) and job ID (identifier) in the shell, and you can monitor the progress of a batch in Batch Monitor.

Command Options

This table provides information about each of the command options for submitting jobs.

Submission command option
Description
‑clustername <name>
Use to specify the name of the cluster to which you want to send the job. Using the cluster name, Compressor looks for the cluster on the network in order to use it.
‑password <value>
User password for the cluster specified by ID or name.
‑batchname <name>
Use to specify a name for the batch so that you can easily recognize it in Batch Monitor.
‑clusterid <user name:password@IP address:port number>
Optionally, you can use ‑clusterid to enter the cluster ID and port number instead of using ‑clustername. (When you enter the cluster ID and port, less time is required to find the cluster on the network.)
Or, if you used ‑clustername and the cluster requires a password, use ‑clusterid to specify the user name and password. (You need to include the IP address:port number as well whenever you use ‑clusterid.)
Use Compressor ‑show to see a cluster's IP address and port number.
‑priority <value>
Specifies the priority level for a job.
‑jobpath <url>
Specifies the location of the source file.
‑settingpath <url>
Specifies the location of the settings for the job.
‑destinationpath <url>
Specifies the destination file URL for the job.
‑info <xml>
Gives detailed information for a batch or a job.
‑timeout <seconds>
Use to specify the number of seconds before Compressor can quit when looking for a cluster. The default value is 0, which puts no limit on the timeout and allows Compressor to browse the network for as long as it needs to find the cluster.
‑show
Shows the ID information for the cluster specified with ‑clustername or ‑clusterid, or for all clusters if no cluster is specified.
‑help
Displays information regarding the required parameters for the Compressor command.

Example of Compressor Command XML

The code below is an example of XML code for submitting a Compressor command. Notice that because it needs to be entered as one command line, every character after ‑options that isn’t alphanumeric must be preceded with a backslash (\).

./Compressor ‑clusterid tcp://127.0.0.1:51737 ‑batchname myBatch ‑jobpath /Volumes/Source/ShortClips/NTSC24p.mov ‑settingpath /Users/stomper10/Library/Application\ Support/Compressor/PhotoJPEG.setting ‑destinationpath /Users/machinename/Movies/myDestinationFilename.mov.

This command has the following elements:

  • Cluster address is tcp://127.0.0.1:51737.

  • Batch name is myBatch.

  • Job path is /Volumes/Source/ShortClips/NTSC24p.mov.

  • Setting path is /Users/stomper10/Library/Application Support/Compressor/PhotoJPEG.setting.

  • Destination path is /Users/machinename/Movies.

Shell Commands for Submitting Apple Qmaster Jobs

You can use the Apple Qmaster command, Apple Qmaster, with a number of command-line options for submitting jobs.

In the command-line descriptions below, angle brackets < > indicate a mandatory argument in a command, and brackets [ ] indicate an optional argument.

Synopsis

Below is a synopsis of the command for submitting a job to a cluster. The Apple Qmaster command is located in /Applications/Apple Qmaster.app/Contents/MacOS/.

Apple Qmaster [‑clustername <name>] [‑clusterid <user name:password@IP address:port number>][‑command <command type> ‑options <XML command> [‑wd<working directory>] [‑timeout <seconds>] [‑show] [‑batchname <name>] [‑help]

Once the job is submitted successfully, this command displays the batch ID (identifier) and job ID (identifier) in the shell.

Command Options

This table provides information about each of the command options for submitting jobs.

Submission command option
Description
‑clustername <name>
Use to specify the name of the cluster to which you want to send the job. Using the cluster name, Apple Qmaster looks for the cluster on the network in order to use it.
‑batchname <name>
Use to specify a name for the batch so that you can easily recognize it in Batch Monitor.
‑clusterid <user name:password@IP address:port number>
Optionally, you can use ‑clusterid to enter the cluster ID and port number instead of using ‑clustername. (When you enter the cluster ID and port, less time is required to find the cluster on the network.)
Or, if you used ‑clustername and the cluster requires a password, use ‑clusterid to specify the user name and password. (You need to include the IP address:port number as well whenever you use ‑clusterid.)
Use Apple Qmaster ‑show to see a cluster’s IP address and port number.
‑command <command type>
Specifies the kind of command you are entering: Shell, Shake, Maya, or other command, depending on the application you want to use for distributed processing.
‑options <XML command>
Specifies the command with XML code. Enter the XML code after ‑options, with the necessary qualifiers for entering it in a shell. See Shell Commands for Submitting Apple Qmaster Jobs, next, for an example.
If no ‑option is entered, the values from the application’s preferences file, in ~/Library/Preferences/, are used (which are the values of the most recent job submitted).
‑wd <working directory>
Use to specify the working directory path (from which the command should be executed). The default working directory is /Applications/Shake.
‑timeout <seconds>
Use to specify the number of seconds before Apple Qmaster can quit when looking for a cluster. The default value is 0, which puts no limit on the timeout and allows Apple Qmaster to browse the network for as long as it needs to find the cluster.
‑show
Shows the ID information for the cluster specified with ‑clustername or ‑clusterid, or for all clusters if no cluster is specified.
‑help
Displays information about supported options for Apple Qmaster.

Example of Shake Command XML

The code below is an example of XML code for submitting a Shake command.

/Applications/Apple\ Qmaster.app/Contents/MacOS/Apple\ Qmaster ‑clustername elvis ‑command "Shake" ‑options "<command executable="/Applications/Shake/shake.app/Contents/MacOS/shake" script="/Volumes/Data/scripts/applestyle.shk" start="1" end="1000" stepsOf="1" minCount="10" otherOptions="" previewNode="" previewWidth="0" shutterOn="yes" motion="yes" proxyFlags="0" proxyScale="1.000000" proxyRatio="1000.000000" shutter="1.000000"></command>"

Note: Apple Qmaster stores the XML code for the last command you entered in ~Library/Preferences/com.apple.AppleQmaster.plist. You can copy the command in XML form there, and customize it to use for a new job submission.

Shell Commands for Monitoring Batches

You can use the Batch Monitor command, Batch Monitor, with a number of command-line options for monitoring jobs.

In the command-line descriptions below, angle brackets < > indicate a mandatory argument in a command, and brackets [ ] indicate an optional argument.

Synopsis

Below is a synopsis of the command for monitoring batches. The Batch Monitor command is located in /Applications/Utilities/Batch Monitor.app/Contents/MacOS/.

Batch Monitor [‑clustername <name>] [‑clusterid <user name:password@IP address:port number>] [‑jobid <identifier> ‑batchid <identifier>] [‑timeout <seconds>] [‑query <seconds>] [‑help]
To cancel a job or batch
  • Use the following command:

    Batch Monitor [‑clustername <name>] [‑clusterid <IP address> <port number> <user name> <password>] ‑kill ‑jobid <identifier> ‑batchid <identifier>

Command Options

This table provides information about each of the command options for monitoring batches.

Monitoring command option
Description
‑clustername <name>
Use to specify the name of the cluster to which the job was sent.
‑password <value>
User password for the cluster specified by ID or name.
‑clusterid <user name:password@IP address:port number>
Optionally, you can use ‑clusterid to enter the cluster ID and port number instead of using ‑clustername.
Or, if you used ‑clustername and the cluster requires a password, use ‑clusterid to specify the user name and password. (You need to include the IP address:port number as well whenever you use ‑clusterid.)
Use Apple Qmaster ‑show or Compressor ‑show to see a cluster’s IP address and port number.
‑jobid <identifier> ‑batchid <identifier>
Use to specify the job you want to monitor.
When you use the ‑jobid option, you must also specify the ‑batchid, in the form of the name that was given to the batch when it was submitted. (The ‑batchid and ‑jobid are displayed after a batch is submitted.)
If you do not use the ‑jobid option, all the jobs submitted to the specified cluster are listed.
‑timeout <seconds>
Use to specify the number of seconds before Batch Monitor can quit when looking for a cluster. The default value is 0, which puts no limit on the timeout and allows Batch Monitor to browse the network for as long as it needs to find the cluster.
‑query <seconds>
Use to specify how frequently, in seconds, the job status should be updated.
‑kill ‑jobid <identifier> ‑batchid <identifier>
Cancels the specified job or batch.
‑help
Displays information about supported options for Batch Monitor.

Using Scripts to Run Apple Qmaster, Compressor, and Batch Monitor

To simplify your use of the command line, you can add command-line-friendly scripts to /usr/bin. Each script sets an env variable for location and then executes the binary. Using the following scripts would be useful if you frequently use the command line for submissions or automated submissions. You do not need to specify the full path, and you can add frequently used env variables and options to speed up the submission process. To run Apple Qmaster, Compressor, or Batch Monitor, you can simply open up a terminal and type qmaster, compressor, or batchmonitor.

Apple Qmaster Script Example
#!/bin/csh ‑f # # set env var, QMASTER_LOCATION if not set # if ${? QMASTER_LOCATION} == 0 then pushd `dirname $0` >& /dev/null setenv QMASTER_LOCATION /Applications/Apple\ Qmaster popd >& /dev/null endif # # launch qmaster # exec ${QMASTER_LOCATION}/Apple\ Qmaster.app/Contents/MacOS/Apple\ Qmaster $argv:q
Compressor Script Example
#!/bin/csh ‑f # # set env var, COMPRESSOR_LOCATION if not set # if ${?COMPRESSOR_LOCATION} == 0 then pushd `dirname $0` >& /dev/null setenv COMPRESSOR_LOCATION /Applications/Compressor.app/Contents/MacOS popd >& /dev/null endif # # launch Compressor # exec ${COMPRESSOR_LOCATION}/Compressor $argv:q
Batch Monitor Script Example
#!/bin/csh ‑f # # set env var, BATCHMONITOR_LOCATION if not set # if ${?BATCHMONITOR_LOCATION} == 0 then pushd `dirname $0` >& /dev/null setenv BATCHMONITOR_LOCATION "/Applications/Utilities/Batch Monitor.app/Contents/MacOS" popd >& /dev/null endif # # launch Batch Monitor # exec "${BATCHMONITOR_LOCATION}/Batch Monitor" $argv:q