The Terminal
Volume Number: 20 (2004)
Issue Number: 12
Column Tag: Programming
QuickTime Toolkit
The Terminal: Developing Command-Line QuickTime Tools
by Tim Monroe
Introduction
When you think of QuickTime applications, you're likely to think of high-profile movie editing
and playback applications like Final Cut Pro or iMovie or QuickTime Player, which are dripping with
glitzy user interfaces and scads of controls for manipulating movie settings. Or maybe you'd think
of some more focused utility program like MakeRefMovie or one of the many applications developed in
this series of articles to illustrate particular aspects of the QuickTime APIs. Possibly the last
thing you'd think of is the lowly command-line tool, that is, a program that can be run in a
Terminal window on Mac OS X or using the DOS command line interface on Windows. After all, these
tools -- almost by definition -- have no graphical user interface; what can you do with QuickTime with
no user interface?
Quite a bit, as it turns out. Although command-line tools cannot directly display visual movie
data, they can very easily play sounds and they can be extremely useful for other sorts of
movie-related tasks. Indeed, command-line tools can be used for virtually any QuickTime task other
than video movie playback, including:
- creating movies from a set of images
- modifying existing movies by recompressing or transcoding the movie data
- adding visual effects to movies
- reporting information about installed components
- automating API testing and validation
Command-line tools offer several nice advantages over GUI-based applications. They are generally
easier to write, and they are almost always less demanding in terms of memory and other system
resources when they are running. They are also easy to execute at specific times (using scheduling
facilities like cron) and can easily handle batch processing tasks. If you need to modify a large
number of movie files (perhaps to export them under a new format or add copyright information to
each of them), you should certainly consider writing a command-line tool instead of a full-fledged
GUI-based application.
In this article, I want to take a look at some of the issues involved in writing command-line
tools for handling QuickTime-related tasks. In this article we'll get the ball rolling by writing a
tool called pics2mov that creates a QuickTime movie from a series of still images. We'll also see
how to write a tool, addFilter, that adds a visual effect (such as the film-noise filter) to an
existing movie. We've considered both of these tasks in earlier articles, so here we can focus on
the specific issues that arise when implementing them with command-line tools.
In an upcoming article, we'll take a look at a few additional topics related to calling QuickTime
APIs from command-line tools. We'll consider the Windows side of the coin, and we'll investigate a
clever way in which, contrary to my earlier claims, we can indeed display QuickTime video content
using command-line tools.
Command-Line Scripting
Before we launch into building our own QuickTime-savvy command-line tools from scratch, let's
first take a moment to consider the command-line capabilities of several scripting languages we have
investigated in past articles. In particular, let's take a quick second look at AppleScript and Tcl
to uncover some useful ways of executing scripts on the command line.
Using AppleScript
In a previous article ("Studio 54" in MacTech, June 2003), we saw how to use AppleScript scripts
to drive both our QTShell sample application and the QuickTime Player application. In that case, we
used the Script Editor application to create and test our scripts, from which we later created
double-clickable applets. It's also possible to compile and execute AppleScript scripts on the
command line. Mac OS X provides the osascript command for executing script files that contain text
or precompiled scripts written in AppleScript (or in any other language that conforms to the Open
Scripting Architecture). For instance, suppose that the file openQTShell contains these lines of
text:
tell application "QTShell" open the file "Kritik:cloud.mov" activate end tell
We can execute this script like so:
[Kant:~] monroe% osascript openQTShell
We can also specify lines of AppleScript directly on the command line, like this:
[Kant:~] monroe% osascript -e 'tell app "QTShell" to open \ "Kritik:cloud.mov"'
Multiple -e arguments are allowed, so we can build up multi-line scripts and execute them with a
single osascript command. See the osascript(1) manual page for more details.
Using Tcl
We took a look at building QuickTime applications using Tcl/Tk and the QuickTimeTcl extension in
two recent articles (in MacTech 2004, nos. 6 and 7). I noted in the first article that QuickTimeTcl
can be used as a pure scripting tool, with no Tk-based graphical user interface, but we postponed
looking at that way of using Tcl and QuickTimeTcl. Now we can tie up that loose end.
Listing 1 shows a Tcl script listComps.tcl, which prints a list of all installed components.
Listing 1: Finding installed components listComps.tcl #!/bin/sh # the next line
restarts using wish \ exec wish "$0" "$@"
package require QuickTimeTcl
wm withdraw .
set comps [::quicktimetcl::info components $argv] foreach comp $comps { set txt {} foreach {key
value} $comp { append txt " $value " }
puts stdout $txt }
exit
The key to this script is the QuickTimeTcl components command, which returns a list of all the
components that are available on the target machine. Each element in the list is of this form:
{-type type -subtype subType -manufacture manufacturer -name name}
As you can see, the listComps.tcl script iterates over the list returned by the components
command and extracts the associated values for these four keys into a string, which it prints to the
standard output file. Notice that we call the withdraw command so that the toplevel window "." is
not displayed by Wish.
Listing 1: Finding installed components
listComps.tcl
#!/bin/sh
# the next line restarts using wish \
exec wish "$0" "$@"
package require QuickTimeTcl
wm withdraw .
set comps [::quicktimetcl::info components $argv]
foreach comp $comps {
set txt {}
foreach {key value} $comp {
append txt " $value "
}
puts stdout $txt
}
exit
The key to this script is the QuickTimeTcl components command, which returns a list of all the components that are available on the target machine. Each element in the list is of this form:
{-type type -subtype subType -manufacture manufacturer -name name}
As you can see, the listComps.tcl script iterates over the list returned by the components command and extracts the associated values for these four keys into a string, which it prints to the standard output file. Notice that we call the withdraw command so that the toplevel window "." is not displayed by Wish.
Here's a sample run of listComps, looking for the installed graphics exporters:
[Kant:~] monroe% listComps.tcl grex
grex .SGI appl SGI
grex 8BPS appl Photoshop
grex BMPf appl BMP
grex JPEG appl JPEG
grex PICT appl PICT
grex PNGf appl PNG
grex PNTG appl MacPaint
grex TIFF appl TIFF
grex TPIC appl TGA
grex base appl Base
grex jp2 appl JP2
grex qtif appl QuickTime Image
Notice that the desired component type (in this case "grex") is passed to the components command as the value of the argv variable. This is a special variable maintained by Tcl for the purpose of passing command-line arguments to a script. If we do not specify a component type on the command line, then the components command will report information about all installed components. On current versions of Mac OS X, that's well over 700 components!
It would be nice to be able to specify multiple component types on the command line, like this:
[Kant:~] monroe% listComps.tcl grex grip
In this case, the argv variable will contain a list. However, the components command does not currently support multiple arguments, so it will ignore all but the first component type in that list. I'll leave it as an exercise for the reader to fix listComps so that it works as desired with multiple component types as command-line arguments.
Slide Show Movies
So, we can now see how to access the services of AppleScript and Tcl from the command line. Precisely how much QuickTime-related work we can accomplish using these services is of course a function of the richness of the AppleScript terminology supported by the available applications and of the capabilities of the commands provided by QuickTimeTcl. In neither case do we have access to anywhere near the entire QuickTime API set. So for arbitrary movie creation and manipulation by a command-line tool, we'll need to build a command-line tool from scratch.
Happily, this is a very easy thing to do. In this section, I'll illustrate that by building a command-line tool that creates a movie from a series of still images. I want to be able to type things like this, specifying an output movie file and some number of input image files:
[Kant:~] monroe% pics2mov file:///Volumes/Kritik/ABC.mov \
file:///Volumes/Kritik/A.jpg \
file:///Volumes/Kritik/B.jpg \
file:///Volumes/Kritik/C.jpg
For ease of implementation, I am requiring that all input and output files be specified by absolute URLs. In this case I'm using file URLs to pick out some local files, but URLs for remote images (for instance http URLs) would work just fine.
You may recall that we learned how to build slide show movies in an earlier article ("She's Gotta Have It" in MacTech, November 2002). There, we constructed a droplet application, called DropPix, that built a slide show movie from the images files dropped onto it. Because we wanted to see how to work directly with media sample references, the resulting code was fairly lengthy. In the current case, we can get by using just five interesting functions:
OpenMovieStorage, NewMovieFromDataRef, ScaleMovieSegment, InsertMovieSegment, and UpdateMovieInStorage. Then to create a self-contained movie, we'll call FlattenMovieDataToDataRef.
Creating a Project
We're getting ahead of ourselves, however. First we need to create a new Xcode project and add some frameworks to it to support QuickTime. Only then will we be in a position to start writing some code. Let's launch Xcode and select "New Project..." in File menu. Then choose a Core Foundation tool, as shown in Figure 1.
Figure 1: Creating a new project.
Let's call the new project "pics2mov", as in Figure 2.
Figure 2: Naming the new project
At this point, the new Xcode project window appears (Figure 3).
Figure 3: The pics2mov project window
Notice that the project contains only one source code file, main.c. The default implementation includes the header file CoreFoundation.h and just calls CFShow to print a message on the standard output. The default implementation also links against only one framework, CoreFoundaton.framework.
We will be using QuickTime and Carbon APIs in our tool, so we need to add to our project two additional frameworks, QuickTime.framework and Carbon.framework. Select "Add Frameworks..." in Project menu and navigate to /System/Library/Frameworks; add the two additional frameworks. In main.c, set the header file includes to look like this:
#include <CoreFoundation/CoreFoundation.h>
#include <Carbon/Carbon.h>
#include <QuickTime/QuickTime.h>
#include <stdio.h>
#include <unistd.h>
Handling Command-Line Options
We included unistd.h so that we can use the getopt system call, which provides a standard mechanism for handling command-line options. The pics2mov tool will support just one option, -d, for specifying the duration of each slide in the movie. If no such option is specified on the command line, we'll use the default duration of 5 seconds:
#define kImageDuration 5
If however a -d option does occur on the command line, then the code in Listing 2 will come into play.
Listing 2: Handling command-line options
main
gProgName = argv[0];
while ((myChar = getopt(argc, (char * const *)argv, "d:"))
!= -1) {
switch (myChar) {
case 'd':
myDuration = atoi(optarg);
if (myDuration <= 0) {
fprintf(stderr, "%s: illegal duration value.\n",
gProgName);
exit(2);
}
break;
default:
usage();
}
}
argc -= optind;
argv += optind;
The third parameter to the getopt function is a string that indicates which characters are to be considered as valid command-line options. If a character is followed by a colon (:), as above, then an argument is expected to follow the option character. In our case, we expect that the user will specify an integer that indicates the desired duration, in seconds, of each frame in the movie. For complete information on this method of handling options, see getopt(3).
Initializing QuickTime
Since we'll be using QuickTime APIs, we need to initialize QuickTime in the standard way:
EnterMovies();
QuickTime always wants a valid graphics port to be set. So even though we are constructing a command-line tool that will never actually draw any image or movie data anywhere, we still need to make sure that a graphics port exists and is set. We can do that with these two Carbon functions:
CGrafPtr myPort = CreateNewPort();
MacSetPort(myPort);
Creating the Output Movie File
In broadest outlines, our pics2mov tool will operate like this: create a new empty movie file and a new empty movie associated with that file. Then open each image file as a movie (using the NewMovieFromDataRef function) and scale that movie to the desired duration. Call InsertMovieSegment to insert the scaled movie into the final output movie. Once we've saved the resulting movie as a self-contained movie file, we're done.
Recall that the output movie file name is specified on the command line as an absolute URL. We can convert the C string specified on the command line into a CFStringRef like this:
myMovieStringRef = CFStringCreateWithCString(NULL, argv[0],
kCFStringEncodingMacRoman);
Then we can use QuickTime's data reference utilities to create a data reference from the CFStringRef:
myErr = QTNewDataReferenceFromURLCFString(myMovieStringRef,
0, &myDataRef, &myDataRefType);
Finally, we can create a new movie file at that location using the CreateMovieStorage function, passing in the new data reference and data reference type. Notice that CreateMovieStorage returns in its last parameter an identifier for a new empty movie.
myErr = CreateMovieStorage(myDataRef, myDataRefType,
FOUR_CHAR_CODE('TVOD'), smCurrentScript, myFlags,
&myHandler, &myMovie);
For more information about the movie storage functions (like CreateMovieStorage), see "Modern Times" in MacTech, 2004 no. 5.
Adding Images to the Movie
Now we are ready to start adding frames to the empty movie. As mentioned above, we want to open each image file as a movie, so that we can scale it and insert it into the output movie file. As in the previous subsection, we'll use CFStringCreateWithCString and QTNewDataReferenceFromURLCFString to get a data reference for an image file. Then we'll call OpenMovieStorage and NewMovieFromDataRef to open the image file as a movie:
myErr = OpenMovieStorage(myImageDataRef,
myImageDataRefType, kDataHCanRead, &myImageHandler);
myErr = NewMovieFromDataRef(&myImageMovie, newMovieActive,
NULL, myImageDataRef, myImageDataRefType);
Once we've got the image in the form of a movie, it's child's play to add the image to the output movie for the desired duration:
ScaleMovieSegment(myImageMovie, 0,
GetMovieDuration(myImageMovie),
myDuration * GetMovieTimeScale(myImageMovie));
myErr = InsertMovieSegment(myImageMovie, myMovie, 0,
GetMovieDuration(myImageMovie),
GetMovieDuration(myMovie));
Saving the Movie
We're almost done creating our slide show movie. All that remains is to call UpdateMovieInStorage to update the movie atom in the movie file:
myErr = UpdateMovieInStorage(myMovie, myHandler);
Then we can call FlattenMovieDataToDataRef to create a self-contained movie file:
FlattenMovieDataToDataRef(myMovie,
flattenAddMovieToDataFork |
flattenForceMovieResourceBeforeMovieData,
myDataRef, myDataRefType, FOUR_CHAR_CODE('TVOD'),
smCurrentScript, myFlags);
And we are done.
Putting It All Together
Listing 3 shows the complete source code for the pics2mov command-line tool.
Listing 3: Creating a movie file from a set of images
main.c
#include <CoreFoundation/CoreFoundation.h>
#include <Carbon/Carbon.h>
#include <QuickTime/QuickTime.h>
#include <stdio.h>
#include <unistd.h>
// duration (in seconds) of each image in movie; -d command-line option overrides this
#define kImageDuration 5
// global variables
const char * gProgName;
void usage (void);
void usage (void)
{
printf("%s: Create a movie from a sequence of images.\n",
gProgName);
printf("USAGE: %s [-d duration] movie image1...imageN\n",
gProgName);
exit(-1);
}
int main (int argc, const char * argv[])
{
CGrafPtr myPort = NULL;
CFStringRef myMovieStringRef;
Movie myMovie = NULL;
Handle myDataRef = NULL;
OSType myDataRefType;
DataHandler myHandler = NULL;
long myFlags = createMovieFileDeleteCurFile |
createMovieFileDontCreateResFile;
long myDuration = kImageDuration;
short myIndex;
char myChar;
OSErr myErr = noErr;
// process any command-line options
gProgName = argv[0];
while ((myChar = getopt(argc, (char * const *)argv,
"d:")) != -1) {
switch (myChar) {
case 'd':
myDuration = atoi(optarg);
if (myDuration <= 0) {
fprintf(stderr, "%s: illegal duration.\n",
gProgName);
exit(2);
}
break;
default:
usage();
}
}
argc -= optind;
argv += optind;
// make sure we got at least one movie filename and one image filename
if (argc < 2) {
usage();
}
// set up for QuickTime
EnterMovies();
// QuickTime always wants a valid graphics port to be set; let's make her happy
myPort = CreateNewPort();
MacSetPort(myPort);
// create a new empty movie to contain the source images;
// argv[0] is the destination file URL
myMovieStringRef = CFStringCreateWithCString(NULL,
argv[0], kCFStringEncodingMacRoman);
myErr = QTNewDataReferenceFromURLCFString(
myMovieStringRef, 0, &myDataRef, &myDataRefType);
if (myErr != noErr)
goto bail;
myErr = CreateMovieStorage(myDataRef, myDataRefType,
FOUR_CHAR_CODE('TVOD'), smCurrentScript,
myFlags, &myHandler, &myMovie);
if (myErr != noErr)
goto bail;
// add images to the movie;
// argv[1]... are the image files to concatenate into the destination movie
for (myIndex = 1; myIndex < argc; myIndex++) {
CFStringRef myImageStringRef;
Movie myImageMovie = NULL;
Handle myImageDataRef = NULL;
OSType myImageDataRefType;
DataHandler myImageHandler = NULL;
// open the image as a movie
myImageStringRef = CFStringCreateWithCString(NULL,
argv[myIndex], kCFStringEncodingMacRoman);
myErr = QTNewDataReferenceFromURLCFString(
myImageStringRef, 0, &myImageDataRef,
&myImageDataRefType);
if (myErr != noErr)
goto bailLoop;
myErr = OpenMovieStorage(myImageDataRef,
myImageDataRefType, kDataHCanRead, &myImageHandler);
if (myErr != noErr)
goto bailLoop;
myErr = NewMovieFromDataRef(&myImageMovie,
newMovieActive, NULL, myImageDataRef,
myImageDataRefType);
if (myErr != noErr)
goto bailLoop;
// scale the image movie to the desired duration
ScaleMovieSegment(myImageMovie, 0,
GetMovieDuration(myImageMovie),
myDuration * GetMovieTimeScale(myImageMovie));
// insert the scaled image movie at the end of the target movie
myErr = InsertMovieSegment(myImageMovie, myMovie, 0,
GetMovieDuration(myImageMovie),
GetMovieDuration(myMovie));
bailLoop:
if (myImageMovie != NULL)
DisposeMovie(myImageMovie);
if (myImageDataRef != NULL)
DisposeHandle(myImageDataRef);
CFRelease(myImageStringRef);
}
// save the movie
myErr = UpdateMovieInStorage(myMovie, myHandler);
CloseMovieStorage(myHandler);
// now flatten it
FlattenMovieDataToDataRef(myMovie,
flattenAddMovieToDataFork |
flattenForceMovieResourceBeforeMovieData,
myDataRef,
myDataRefType,
FOUR_CHAR_CODE('TVOD'),
smCurrentScript,
myFlags);
bail:
CFRelease(myMovieStringRef);
if (myMovie != NULL)
DisposeMovie(myMovie);
if (myDataRef != NULL)
DisposeHandle(myDataRef);
if (myPort != NULL)
DisposePort(myPort);
exit(myErr);
}
Notice that we need to release the various CFStringRef objects that we open, and that we need to dispose of the graphics port we opened at the beginning of our tool.
It's probably worth mentioning that we really don't even need to create an Xcode project in order to build command-line tools. We could just as easily have used our favorite text editor to enter the code in Listing 3 into a file called main.c; then we can build our tool like this:
[Kant:~] monroe% cc -o pics2mov -g main.c \
-framework Carbon -framework QuickTime \
-framework CoreFoundation
Movie Fiilters
Suppose now that we want to write a command-line tool addFilter that adds a visual effect -- perhaps the film-noise filter or the blur effect -- to an existing movie. In this case, we just need to open the target movie using the technique employed in the previous section and then call this function:
QTEffects_AddFilterToMovie(myMovie, myType);
The QTEffects_AddFilterToMovie function is a slightly more general version of the QTEffects_AddFilmNoiseToMovie function that we put together in an earlier article ("F/X" in MacTech, September 2001). So really our work is done once we determine how to specify the desired effect. As we'll see, we also need to tweak QTEffects_AddFilterToMovie so that it correctly handles scaled movie segments.
Handling Command-Line Options
In addFilter, we'll support a -e command-line option, which specifies the desired effect. So we could call our tool like this:
[Kant:~] monroe% addFilter -e fmns \
file:///Volumes/Kritik/ABC.mov
We'll use the getopt function to process the -e option, as before. This time, however, instead of calling atoi to convert the argument into a number, we want to convert the four-character string into a value of type OSType. We can do that like this:
case 'e':
myType = string2ostype(optarg);
break;
Listing 4 shows a quick-and-dirty implementation of string2ostype.
Listing 4: Converting a string into an OSType
string2ostype
#define kMaxOSTypeLength 5 // length of an OSType (plus terminating null)
OSType string2ostype (char *theString)
{
unsigned long myType = 0L;
if (strlen(theString) < kMaxOSTypeLength - 1)
return((OSType)myType);
myType += theString[3] << 0;
myType += theString[2] << 8;
myType += theString[1] << 16;
myType += theString[0] << 24;
return((OSType)myType);
}
This implementation of string2ostype is not a very good general-purpose method of converting strings into values of type OSType, since it assumes that all one-source effects have exactly four characters in their types (like 'fmns' and 'blur'). A better version is left as an exercise for the reader.
Scaling the Effect
I mentioned that QTEffects_AddFilterToMovie, which does all the heavy lifting in the addFilter tool, is based heavily on QTEffects_AddFilmNoiseToMovie. The newer function takes a parameter that specifies the effect type, and it also correctly handles movies that contain scaled segments.
The existing function, QTEffects_AddFilmNoiseToMovie, adds the effect description to the effects track like this:
myErr = AddMediaSample(myMedia, (Handle)myEffectDesc, 0,
GetHandleSize((Handle)myEffectDesc),
GetMediaDuration(GetTrackMedia(mySrcTrack)),
(SampleDescriptionHandle)mySampleDesc, 1, 0,
&mySampleTime);
The fifth parameter specifies the duration of the media sample to be added. As you can see, we use this code to determine that duration:
GetMediaDuration(GetTrackMedia(mySrcTrack))
It turns out that this way of determining the duration of the effects track will not work correctly on movies that contain scaled segments, like the movies that are created by our pics2mov tool. Instead, we need to take the duration of the movie and convert it to the media time scale, like this:
myMediaDuration = (GetMovieDuration(theMovie) *
GetMediaTimeScale(myMedia))
/ GetMovieTimeScale(theMovie);
Passing this value as the media duration in AddMediaSample results in a movie that operates as expected. (See this month's code for an Xcode project and the full source code for the addFilter tool.)
Conclusion
Building a command-line tool that accesses QuickTime APIs is really very straightforward. Everything works pretty much as you'd expect. The only non-obvious "gotcha" is the requirement that a valid graphics port be set whenever calling QuickTime APIs.
In this article, we've briefly investigated ways to call AppleScript or Tcl scripts on the command line, and we've seen how to build tools to create movies from still images and to apply video effects to existing movies. In the next article, we'll continue this investigation by constructing a Windows command-line tool and by seeing how a command-line tool can actually display QuickTime video content.
Tim Monroe is a member of the QuickTime engineering team at Apple. You can contact him at monroe@mactech.com. The views expressed here are not necessarily shared by his employer.
