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').

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)

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

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

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.

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.

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

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

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

string2ostype
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);
         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

ostype2string
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++ = ' ';
      }

      theCharPtr++;
   }

   *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

main
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);
            break;
      }
   }	
	
   argc -= optind;
   argv += optind;

	
#if !TARGET_OS_MAC
   InitializeQTML(kInitializeQTMLNoSoundFlag | 
                                    kInitializeQTMLUseGDIFlag);
#endif	

   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);
   }

#if !TARGET_OS_MAC
   TerminateQTML();
#endif	
   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.

MOVIE PLAYBACK IN THE TERMINAL

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.

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

main
Rect            myBounds;
GWorldPtr       myGW = NULL;

GetMovieBox(myMovie, &myBounds);
QTNewGWorld(&myGW, k32ARGBPixelFormat, &myBounds, NULL, 
                            NULL, 0);
if (myGW != NULL) {
   LockPixels(GetGWorldPixMap(myGW));
   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 {
   MCIdle(myMC);
} 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:

SetMovieDrawingCompleteProc(myMovie, 
                    movieDrawingCallWhenChanged, 
                    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?)

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

main
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

DrawCompleteProc
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 - myBounds.top) / 
               HEIGHT)));
      for (x = 0; x < WIDTH; ++x) {
         UInt32      color;
         long        Y, R, G, B;

         color = *(long *)((long)p + 4 * 
               (long)(x * (myBounds.right - myBounds.left) / 
               WIDTH));
         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
      putchar('\n');
   }

   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);

MOVIE PLAYBACK IN THE DOS CONSOLE

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>
#if TARGET_OS_MAC
#include <QuickTime/QuickTime.h>
#else
#include <windows.h>
#include <QTML.h>
#include <Movies.h>
#include <Quickdraw.h>
#include <QDOffscreen.h>
#include <string.h>
#include <FixMath.h>
#endif

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

DrawCompleteProc
#if TARGET_OS_MAC
GetPixBounds(GetGWorldPixMap(offWorld), &bounds);
baseAddr = GetPixBaseAddr(GetGWorldPixMap(offWorld));
rowBytes = GetPixRowBytes(GetGWorldPixMap(offWorld));
#else
bounds = (**GetGWorldPixMap(offWorld)).bounds;
baseAddr = (**GetGWorldPixMap(offWorld)).baseAddr;
rowBytes = (**GetGWorldPixMap(offWorld)).rowBytes & 0x3fff;
#endif

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:

HANDLE hStdOut = GetStdHandle(STD_OUTPUT_HANDLE);

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

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

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

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

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

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

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

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

CONCLUSION

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.

REFERENCES

The ASCIIMoviePlayer command-line tool for drawing movies using ASCII characters was written by Tom Dowdy and is available at http://developer.apple.com/samplecode/QuickTime/idxMovieBasics-date.html. An enhanced version of this project (which, among other things, adds support for color characters) can be found at http://quickascii.sourceforge.net. 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 http://www.omino.com/~poly/software/qt_tools.

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.