TweetFollow Us on Twitter

Terminal Velocity

Volume Number: 21 (2005)
Issue Number: 2
Column Tag: Programming

QuickTime Toolkit

by Tim Monroe

Terminal Velocity

Developing Command-Line QuickTime Tools, Part II

In the previous article ("The Terminal" in MacTech December 2004), we looked at using command-line tools to accomplish various QuickTime-related tasks, such as building movies from a series of still images or applying visual effects to an existing movie. We focused on building tools on Mac OS X, either using Xcode or just directly compiling and linking with cc on the command line. In this article, I want to continue that investigation by stepping through the process of building a command-line tool on Windows. The fundamental ideas are the same as on the Macintosh, but when moving to a different platform, it's always useful to see a step-by-step walkthrough. Then, toward the middle of this article, we'll return to Mac OS X to look at a clever way to actually draw video data on the screen using a command-line tool.

DOS Command-Line Tools

For our Windows command-line tool, let's build a C-language version of the Tcl listComps script we considered in the previous article. Figure 1 shows the C version of listComps at work in a DOS console window. We are asking it to list all available graphics exporters (that is, components of type 'grex').

Figure 1: Output of listComps on Windows

Creating a Project

Launch the Visual C++ development environment. Select "New..." in the File menu to get a list of available project types. In the Projects pane, select "Win32 Console Application". Set the project name and select a more convenient location for the project files (Figure 2)

Figure 2: The new project dialog box

Because there are several flavors of console applications, we'll be prompted to select one, as in Figure 3. Choose "A "Hello, World!" application".

Figure 3: The console application wizard

At this point, the project window appears; the Workspace pane shows the files associated with the new project (Figure 4).

Figure 4: The listComps Workspace pane

Setting Project Paths

Our Windows command-line tool will not actually call any QuickTime-specific APIs, since it can do all its work using the Component Manager functions FindNextComponent and GetComponentInfo. Nevertheless, we need to link against the library qtmlclient.lib, because the QuickTime Media Layer (QTML) supplies the Component Manager implementation on Windows. So let's select the Settings menu item in the Project menu and choose the Link tab. In the "Object/library modules" text box, add qtmlclient.lib, as shown in Figure 5.

Figure 5: The Link tab

We also need to specify the path to the directory that contains the file qtmlclient.lib, since it's probably not in the default library paths. In the Category pop-up menu, select Input and add a full or relative path to that directory. As you can see in Figure 6, I've specified a relative path from the directory containing the listComps project file to the directory that contains the QTML libraries on my machine.

Figure 6: The Input pane of the Link tab

Handling Command-Line Options

As you know, we want to be able to specify one or more component types on the command line, to limit the displayed components to the specified type or types. In our Mac OS X tools, we used the system call getopt to process options specified on the command line. The getopt function is not part of the standard Windows APIs, but there are implementations available that work well on Windows. Indeed, some of the Microsoft Developer Network (MSDN) sample code includes the files getopt.c and getopt.h, which we can copy directly into our project. We can then call the getopt function as shown in Listing 1.

Listing 1: Handling command-line options

while ((myChar = getopt(argc, argv, "e:")) != -1) {
   switch (myChar) {
      case 'e':
         string2ostype(optarg, &myType);

argc -= optind;
argv += optind;

You may recall that in the previous article we provided a quick and dirty version of the string2ostype function. Let's take a moment to look at a better version. The principal flaw with the original version was that it assumed that all strings specified on the command line would be exactly four characters in length. While most publicly defined values of type OSType are indeed exactly four characters in length, not all are. Listing 2 provides a better implementation that handles strings of any length that is less than or equal to 4.

Listing 2: Converting a string into an OSType

void string2ostype (const char *inString, OSType *outType)
   OSType      type = 0;
   short       i;	

   for (i = 0; i < 4; i++) {
      type <<= 8;
      if (*inString) {
         type += (unsigned char)(*inString);

   *outType = type;

Note that it's perfectly legal for the string passed in to contain spaces, so our code can handle strings like "eat " (the component subtype of movie importers). The only restriction is that strings containing spaces need to be quoted on the command line, like this:

listComps -e "eat "

The listComps tool also needs to implement an ostype2string function, so that it can display the type, subtype, and manufacturer of any found component in a readable form. Listing 3 shows a version of ostype2string.

Listing 3: Converting an OSType into a string

static void ostype2string (OSType inType, char *outString)
   unsigned char   theChars[4];
   unsigned char *theString = (unsigned char *)outString;
   unsigned char *theCharPtr = theChars;
   int                       i;

   // extract four characters in big-endian order
   theChars[0] = 0xff & (inType >> 24);
   theChars[1] = 0xff & (inType >> 16);
   theChars[2] = 0xff & (inType >> 8);
   theChars[3] = 0xff & (inType);

   for (i = 0; i < 4; i++) {
      if((*theCharPtr >= ' ') && (*theCharPtr <= 126)) {
         *theString++ = *theCharPtr;
      } else {
         *theString++ = ' ';


   *theString = 0;

You'll notice that any unprintable characters (that is, characters with ASCII values less than 32 or greater than 126) are replaced by a space character. For our present purposes, that's quite acceptable. For other purposes, however, it might be better to encode unprintable characters in some way so that their values are easily discernible. This refinement is left as an exercise for the reader.

Finding Components

Looping through all installed components to find those with a specific component type is really easy. All we need to do is use the functions FindNextComponent and GetComponentInfo, as shown in Listing 4. Notice that we call InitializeQTML with a set of flags appropriate for command-line tools, and that we later call TerminateQTML.

Listing 4: Listing installed components

int main (int argc, char* argv[])
   char            myType[5];
   char            mySubType[5];
   char            myManu[5];
   char            myChar;
   OSType          myType = 0L;

   ComponentDescription findCD = {0, 0, 0, 0, 0};
   ComponentDescription infoCD = {0, 0, 0, 0, 0};
   Component comp = NULL;

   // process command-line options
   while ((myChar = getopt(argc, argv, "e:")) != -1) {
      switch (myChar) {
         case 'e':
            string2ostype(optarg, &myType);
   argc -= optind;
   argv += optind;

   InitializeQTML(kInitializeQTMLNoSoundFlag | 

   findCD.componentType = myType;
   findCD.componentFlagsMask = cmpIsMissing;

   while (comp = FindNextComponent(comp, &findCD)) {
      GetComponentInfo(comp, &infoCD, NULL, NULL, NULL);

      ostype2string(infoCD.componentType, myType);
      ostype2string(infoCD.componentSubType, mySubType);
      ostype2string(infoCD.componentManufacturer, myManu);

      printf("  %s\t%s\t%s\n", myType, mySubType, myManu);

   return 0;

This implementation does not support more than one -e option on the command line; removing that restriction is also left as an exercise for the reader.


In the previous article, I mentioned that command-line tools are well-suited to handle tasks that do not require visual movie data to be displayed to the user. Command-line tools can play audio just fine, and (as we've seen) they can create and modify QuickTime movies in virtually any way imaginable. They just can't display any video data on the screen.

Or can they? Consider our standard penguin movie, the last frame of which is shown once again in Figure 7. If we are very clever, we can write a command-line tool that displays the movie in a Terminal window, as in Figure 8. As you can see, the image is composed of ASCII characters. All we need to do is draw an image like this, erase the Terminal window, draw another image, and so forth. So, if we can do this erasing and drawing fast enough, and if we are willing to live with images composed entirely of ASCII characters (or whatever else can be displayed in a Terminal window), we can indeed play QuickTime video using a command-line tool.

Figure 7: A movie playing in an application window

Figure 8: A movie playing in a Terminal window

How is this done? It's actually surprisingly simple. I'll step through the details in a moment, but in overview the process is this: open a QuickTime movie and set it to draw to an offscreen graphics world. Play the movie by calling MCIdle until the movie is done. Each time a frame is drawn into the offscreen graphics world, inspect each pixel that lies on an intersection of two lines in a w x h grid, where w and h are the width and height of the Terminal window. Convert the RGB value of that pixel to a relative lightness value (called the luminance of the pixel) and map that luminance value to one of these 23 characters: " .,:!-+=;iot76x0s&8%#@$". Draw the character at the appropriate location on the Terminal window. Voila: Terminal-based movie playback.

Opening and Running the Movie

The first part of this process is easy. We already know how to open a QuickTime movie file and load the movie from the file. Then we need to create an offscreen graphics world and set the movie to draw into it, as shown in Listing 5.

Listing 5: Setting up to draw

Rect            myBounds;
GWorldPtr       myGW = NULL;

GetMovieBox(myMovie, &myBounds);
QTNewGWorld(&myGW, k32ARGBPixelFormat, &myBounds, NULL, 
                            NULL, 0);
if (myGW != NULL) {
   SetGWorld(myGW, NULL);
   myMC = NewMovieController(myMovie, &myBounds,
                             mcTopLeftMovie | mcNotVisible);
   SetMovieGWorld(myMovie, myGW, NULL);
   SetMovieActive(myMovie, true);

Notice that we create a new movie controller with the controller bar hidden.

Once this is all accomplished, we can start the movie playing, like this:

MCDoAction(myMC, mcActionPrerollAndPlay, (void *)fixed1);

And we can run the movie by continually calling MCIdle:

do {
} while (1);

Remember, though, that we want to do some work each time a frame is drawn into the offscreen graphics world, so we'll also install a movie drawing-completion procedure:

                    DrawCompleteProc, (long)myGW); 

This drawing-completion procedure DrawCompleteProc will be responsible for looking at the appropriate pixels in the offscreen graphics world, converting them into characters, and drawing the characters into the Terminal window. (For more information about movie drawing-completion procedures, see "Loaded" in MacTech, September 2002.)

Converting Pixels to Luminance Values

The pixels in the offscreen graphics world contain RGB data. What we want to do is convert an RGB value into a luminance value, which is a measure of the lightness of the RGB value. Figure 9 shows the luminance color space. (Exciting, huh?)

Figure 9: The luminance color space

The standard formula for converting an RGB value into a luminance value is this:

Y = (0.30 x R) + (0.59 x G) + (0.11 x B)
In our command-line tool, we'll approximate this value, for a given pixel color, with this code:
   R = (color & 0x00FF0000) >> 16;
   G = (color & 0x0000FF00) >> 8;
   B = (color & 0x000000FF) >> 0;
   Y = (R + (R << 2) + G + (G << 3) + (B + B)) >> 4;

The luminance values generated in this way will range from 0 to 255, where 0 is black and 255 is white.

Converting Luminance Values to Characters

In order to be able to draw in a Terminal window, we need to convert these luminance values into ASCII characters. The list of characters given earlier is ranked roughly in order of lightness, with characters to the left being lighter than those to the right:

 " .,:!-+=;iot76x0s&8%#@$". 

The code in Listing 6 loads an array with these characters.

Listing 6: Loading a conversion array

char convert[256];
char *table = "   .,:!-+=;iot76x0s&8%#@$";

for (i = 0; i < 256; ++i) {
   convert[i] = table[i * strlen(table) / 256];

For instance, luminance values in the range 195 to 204 are mapped to the ampersand "&". (Notice that the first three characters in the table string are the space character, so that any luminance value less than or equal to 30 is mapped to the space character.)

Drawing Characters

All that remains is to see how to traverse the offscreen graphics world to grab pixels and draw the associated character into the Terminal window. A couple of for loops will do the trick, as shown in Listing 7.

Listing 7: Drawing characters

static pascal OSErr DrawCompleteProc 
                        (Movie theMovie, long theRefCon)
#define WIDTH   ((float)(80))
#define HEIGHT   ((float)(24))

   int                y, x;
   GWorldPtr          myGW = (GWorldPtr)theRefCon;
   Rect               myBounds;
   Ptr                baseAddr;
   long               rowBytes;

   // get the information we need from the GWorld
   GetPixBounds(GetGWorldPixMap(myGW), &myBounds);
   baseAddr = GetPixBaseAddr(GetGWorldPixMap(myGW));
   rowBytes = GetPixRowBytes(GetGWorldPixMap(myGW));

   // go to home position
   printf("%c[0;0H", ESC);

   // for each row
   for (y = 0; y < HEIGHT; ++y) {
      long   *p;

      // for each column
      p = (long*)(baseAddr + rowBytes * 
               (long)(y * ((myBounds.bottom - / 
      for (x = 0; x < WIDTH; ++x) {
         UInt32      color;
         long        Y, R, G, B;

         color = *(long *)((long)p + 4 * 
               (long)(x * (myBounds.right - myBounds.left) / 
         R = (color & 0x00FF0000) >> 16;
         G = (color & 0x0000FF00) >> 8;
         B = (color & 0x000000FF) >> 0;

         // convert to luminace
         Y = (R + (R << 2) + G + (G << 3) + (B + B)) >> 4;
         // draw it
         putchar(convert[255 - Y]);

      // next line

   return noErr;

Notice that the cursor is moved to the home position on the Terminal window (that is, the location at the top-left of the window) at the beginning of the callback procedure with this line of code:

printf("%c[0;0H", ESC);

By default, the Terminal application emulates a terminal of type xterm-color, which supports a superset of the standard vt100 escape codes. To move the cursor to the home position, therefore, we can send the sequence of characters Esc-[-0-;-0-H, where "Escape" is the ASCII value of the Escape key:

#define ESC   27

Similarly, when our tool first starts up, we want to erase the screen; we can do that like this:

printf("%c[0J", ESC);


So, we've seen how to build a command-line tool for Windows and how to "draw" movies inside a Terminal window on Mac OS X. We might naturally wonder whether we can combine these two accomplishments to do the same sort of movie drawing in the DOS console window. Indeed this is possible, but moving this code from Mac OS X to Windows is not without complications. The main problem here is that the DOS console window does not support the vt100 escape codes that we rely upon to move the cursor around the window and to clear the window. Happily, Window provides a set of functions that so-called character-mode applications can use to control the cursor position and other characteristics of a console window. Once we move to those functions, it's straightforward to generate movie frames like the one shown in Figure 10.

Adjusting Header Files and Function Calls

First things first, however. We need to do a little work to make our code suitably cross-platform. The existing Mac OS X code includes only two header files:

#include <stdio.h>
#include <QuickTime/QuickTime.h>
We need to adjust that so that the appropriate files are included on each platform, like this: 
#include <stdio.h>
#include <QuickTime/QuickTime.h>
#include <windows.h>
#include <QTML.h>
#include <Movies.h>
#include <Quickdraw.h>
#include <QDOffscreen.h>
#include <string.h>
#include <FixMath.h>

Figure 10: A movie playing in a DOS console window

If we try to compile and link our tool at this point, we'll discover that the GetPixBounds, GetPixBaseAddr, and GetPixRowBytes functions are not currently available on Windows. We can work around that limitation by directly accessing the fields of a PixMap structure, as shown in Listing 8.

Listing 8: Getting the offscreen graphics world information

GetPixBounds(GetGWorldPixMap(offWorld), &bounds);
baseAddr = GetPixBaseAddr(GetGWorldPixMap(offWorld));
rowBytes = GetPixRowBytes(GetGWorldPixMap(offWorld));
bounds = (**GetGWorldPixMap(offWorld)).bounds;
baseAddr = (**GetGWorldPixMap(offWorld)).baseAddr;
rowBytes = (**GetGWorldPixMap(offWorld)).rowBytes & 0x3fff;

Note the addition of the value 0x3fff to the value of the rowBytes field. It turns out that the two high-order bits of that field are used for other purposes, so we need to mask them off if we read it directly.

Finally, of course, we need to make sure to call InitializeQTML before we call EnterMovies and then call TerminateQTML once we are done drawing movie frames.

Controlling the Cursor

As I mentioned earlier, the DOS console window does not support the vt100 escape sequences that we use to clear the window and position the cursor when running in a Terminal window on Mac OS X. Fortunately, we can make use of a set of console functions supported by Windows for managing input and output in character-mode applications -- that is, an application that reads from the standard input and writes to the standard output or to the standard error. For present purposes, we need to be concerned only with writing characters to the standard output, which we can access using a HANDLE value:


We can, for instance, move the cursor to a specified position by calling the SetConsoleCursorPosition function like this:

SetConsoleCursorPosition(hStdOut, coord);

The coord parameter is a value of type COORD that specifies the desired location of the cursor.

Listing 9 defines a function that we can call from either Windows code or Mac OS X code to move the cursor to a screen location.

Listing 9: Setting the position of the cursor

void MoveCursor (int x, int y)
#ifdef TARGET_OS_WIN32
   COORD coord;

   coord.X = x;
   coord.Y = y;
   SetConsoleCursorPosition(hStdOut, coord);
   fprintf(stdout, "%c[%i;%iH", ESC, y, x);

And Listing 10 defines a function that we can call to clear the console screen. On Windows, it simply fills the entire console screen with space characters.

Listing 10: Clearing the screen

void ClearScreen (void)
#ifdef TARGET_OS_WIN32
   COORD coord = {0, 0};
   DWORD count;

   GetConsoleScreenBufferInfo(hStdOut, &csbi);
   FillConsoleOutputCharacter(hStdOut, ' ', 
                      csbi.dwSize.X * csbi.dwSize.Y, coord, &count);

   SetConsoleCursorPosition(hStdOut, coord);
   fprintf(stdout, "%c[2J", ESC);

Once we revise the existing code to use MoveCursor and ClearScreen, we're done.


Command-line tools are powerful, easy to write, and can provide several advantages over GUI-based applications, even when working with multimedia technologies like QuickTime. In this article and the previous one, we've learned how to build QuickTime command-line tools on both Mac OS X and on Windows. We've also taken a look at a very clever way to display the visual output of a movie inside a Terminal window or a DOS console window.


The ASCIIMoviePlayer command-line tool for drawing movies using ASCII characters was written by Tom Dowdy and is available at An enhanced version of this project (which, among other things, adds support for color characters) can be found at The Windows adaptation is my own contribution to this crazy but intriguing tool.

Another useful collection of command-line tools for QuickTime processing is qt_tools by David Van Brink; the tools and their complete source code are available at

Tim Monroe is a member of the QuickTime engineering team at Apple. You can contact him at The views expressed here are not necessarily shared by his employer.


Community Search:
MacTech Search:

Software Updates via MacUpdate

Gopogo guide - How to bounce like the be...
Nitrome just launched a new game and, as to be expected, it's a lot of addictive fun. It's called Gopogo, and it challenges you to hoparound a bunch of platforms, avoiding enemies and picking up shiny stuff. It's not easy though - just like the... | Read more »
Sago Mini Superhero (Education)
Sago Mini Superhero 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: KAPOW! Jack the rabbit bursts into the sky as the Sago Mini Superhero! Fly with Jack as he lifts impossible weights,... | Read more »
Star Wars: Galaxy of Heroes guide - How...
Star Wars: Galaxy of Heroes is all about collecting heroes, powering them up, and using them together to defeat your foes. It's pretty straightforward stuff for the most part, but increasing your characters' stats can be a bit confusing because it... | Read more »
The best cooking apps (just in time for...
It’s that time of year again, where you’ll be gathering around the dinner table with your family and a huge feast in front of you. [Read more] | Read more »
Square Rave guide - How to grab those te...
Square Rave is an awesome little music-oriented puzzle game that smacks of games like Lumines, but with its own unique sense of gameplay. To help wrap your head around the game, keep the following tips and tricks in mind. [Read more] | Read more »
Snowboard Party 2 (Games)
Snowboard Party 2 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Crowned the best snowboarding game available on the market, Snowboard Party is back to fulfill all your adrenaline needs in... | Read more »
One Button Travel (Games)
One Button Travel 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: “To cut a long story short, If you like interactive fiction, just go buy this one.” - “Oozes the polish that... | Read more »
Light Apprentice Volume 1 (Games)
Light Apprentice Volume 1 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Light Apprentice Volume 1 includes Chapters 1 to 4, all gathered in a new exclusive game. When life in the world of... | Read more »
The best games like Animal Crossing on m...
Animal Crossing amiibo Festival is out right now for the Wii U, reminding us of just how much fun that world can be. Or at least to go back and check in on our villages once in a while. [Read more] | Read more »
Between 2 Taps - Tap for Tap interview M...
Hello, and welcome back to Between 2 Taps, Tap for Tap’s Indie Dev interview series. [Read more] | Read more »

Price Scanner via

iMobie Releases its Ace iOS Cleaner PhoneClea...
iMobie Inc. has announced the new update of PhoneClean 4, its iOS cleaner designed to reclaim wasted space on iPhone/iPad for use and keep the device fast. Alongside, iMobie hosts a 3-day giveaway of... Read more
Black Friday deals on the Apple Watch and App...
Apple resellers are offering discounts and bundles with the purchase of an Apple Watch this Black Friday weekend. Below is a roundup of the deals being offered by authorized Watch resellers: Apple... Read more
Early Black Friday sale at B&H Photo, up...
B&H Photo has all new Macs on sale for up to $500 off MSRP as part of their early Black Friday sale including free shipping plus NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1699 $300 off... Read more
NewerTech/OWC/MacSales Black Friday Deals 201... • Free Shipping available on nearly EVERYTHING on orders $35.00 & up within USA + • International Delivery Specials from $2.99+ Special Purolator... Read more
Walmart Black Friday deals: $100 off select i...
Walmart has released their Black Friday deals for 2015, now available online. Choose free shipping or free local store pickup (if available): - 16GB iPad Air 2: $399, $100 off MSRP - 16GB iPad Air: $... Read more
Photo Cleaner 1.0 Reclaims iPhone Storage Spa...
Seoul, Korea based mix1009 has announced the release and immediate availability of Photo Cleaner 1.0, their handy iPhone app that deletes the video portion of Live Photos, in order to reclaim space... Read more
Black Friday and Holiday sales on our price t...
Scan our Mac Price Trackers for the latest Black Friday and Holiday season information on sales, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. We update the... Read more
Best Buy Black Friday deals: Up to $200 off M...
Best Buy has posted their Black Friday sale prices for 2015. Save on MacBook Pros, MacBooks, MacBook Airs, iMacs, iPads, and Apple Watches. Choose free shipping or free local store pickup (if... Read more
Save $30-$40 on new Apple TVs after rebate
Adorama has new Apple TVs on sale for up to $40 off MSRP after mail-in rebate, good through December 15th. Shipping is free, and Adorama charges NY & NJ sales tax only: - 32GB Apple TV: $119.99... Read more
13-Inch Haswell MacBook Air At Two Years – Th...
The 13-inch mid-2013 “Haswell” MacBook Air I ordered in Apple’s November 2013 Black Friday sale was my first new Mac in four and a half years — the longest interval I’ve gone between system upgrades... Read more

Jobs Board

Storefront Operations Coordinator, *Apple* -...
# Storefront Operations Coordinator, Apple -Latin America Job Number: 43587750 Miami, Florida, United States Posted: Oct. 16, 2015 Weekly Hours: 40.00 **Job Summary** The Read more
*Apple* Enterprise / Government Professional...
# Apple Enterprise / Gove ment Professional Services Engineer Job Number: 42292976 Reston, Virginia, United States Posted: Aug. 18, 2015 Weekly Hours: 40.00 **Job Read more
iOS Wallet & *Apple* Pay Engineer - App...
# iOS Wallet & Apple Pay Engineer Job Number: 40586801 Santa Clara Valley, Califo ia, United States Posted: Nov. 16, 2015 Weekly Hours: 40.00 **Job Summary** The iOS Read more
Software Engineer, *Apple* Watch - Clock Fa...
# Software Engineer, Apple Watch - Clock Face Team Job Number: 44368761 Santa Clara Valley, Califo ia, United States Posted: Nov. 14, 2015 Weekly Hours: 40.00 **Job Read more
Administrative Assistant, *Apple* Online St...
# Administrative Assistant, Apple Online Store Job Number: 43992352 Santa Clara Valley, Califo ia, United States Posted: Nov. 9, 2015 Weekly Hours: 40.00 **Job Summary** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.