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.

Let's call the new project "pics2mov", as in Figure 2.

At this point, the new Xcode project window appears (Figure 3).

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.