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

QuickTime Toolkit

by Tim Monroe

Black Hawk Down

Developing QuickTime Applications with Awk

Introduction

Occasionally, we workaday programmers have one of those Aha! moments, in which an idea that had bounced around inside our heads with vagueness and imprecision becomes crystal clear. Suddenly things make sense; new ways of approaching a task are revealed; life is good. Most often, I think, these moments come about as a result of drawing connections between disparate items, of bringing techniques and capabilities from one domain to bear on some other domain. Sometimes, however, quite the reverse is true. An Aha! moment can arise from the realization that separations and distinctions can be drawn in a domain previously thought to present a unified structure. In this article, I want to tease out one such realization. On first glance it might look like a yawner, but I think that on closer examination it will reveal useful possibilities for developing QuickTime applications of a significantly different nature than any we have considered so far in this series of articles.

The realization is this: when we develop a QuickTime application, we need to work with at least three distinct kinds of software tools. First, and perhaps most obvious, there is the programming language. In past articles, we've seen how to develop QuickTime applications using C, Objective-C, Java, a couple variants of BASIC, Transcript (a HyperTalk offshoot), AppleScript, and Tcl. There are of course plenty of other popular programming languages that it might be nice to investigate, including C++, C#, Object Pascal, Perl, and perhaps even Lisp.

The second kind of tool we have worked with is a graphical user interface toolkit. Examples we've encountered hitherto include Cocoa's Application Kit, AWT, Swing, Tk, and the standard Macintosh User Interface Toolbox (comprised of the Window Manager, the Dialog Manager, the Control Manager, and their ilk). We even saw that we can use the Mac User Interface Toolbox on Windows, thanks to the magic of the QuickTime Media Layer. Often, the GUI toolkit is part of a larger application framework that provides extensive event-handling and document-based capabilities. Think here of Cocoa, PowerPlant, MFC, and the like.

The third kind of tool we need to bring into play is whatever else is necessary to get QuickTime movie playback and editing to work with a specific GUI toolkit. In some cases, this additional element is already included in the GUI toolkit, as is the case with Cocoa and its NSMovie and NSMovieView classes. But more often than not, we need some additional software components to display and manage QuickTime movies. In past articles, this third element has consisted of the QuickTime for Java package, QuickTimeTcl, a QuickTime-specific ActiveX control, or the QuickTime libraries themselves.

Now, I suspect that this division of labor is intuitively obvious when presented like this. However, I think that it's not at all obvious when approaching individual development environments with the intention of building a QuickTime-savvy application. Some of the RAD tools make very little distinction between the underlying language, the windowing toolkit, and their QuickTime support; rather, it's all built into the development environment and presented as a monolithic whole. Other languages and GUI toolkits are so closely connected as to be in practice indistinguishable: Tcl and Tk go so closely together that they are usually combined into the moniker "Tcl/Tk", and Java is almost always used with either AWT or Swing, or indeed both. So you will perhaps count it as understandable that I should have been lulled into conflating these three elements on some level. Or maybe I'm just dense.

At any rate, once we have clearly distinguished these three elements, interesting new possibilities open up. First and foremost, we can combine these elements in novel ways. In this article I want to illustrate some of the possibilities here by developing a QuickTime application (called "AwkEez") that uses Awk as the underlying programming language, Tk as the graphical user interface, and QuickTimeTcl as the additional element that provides QuickTime support. I chose Awk partly for its shock value, since it is a semi-outmoded language that very few people would suspect could be used to build a full-featured QuickTime application. But the techniques we'll learn here could just as easily be applied to more mainstream or more modern languages like Perl or Python or Ruby. As we'll see, all we really require of the underlying programming language is the ability to store data in some easy manner, to perform standard arithmetic and string operations, and to read data from a standard input source and write data to a standard output source. Those requirements are satisfied by an incredibly wide variety of existing languages.

We'll begin by taking a brief look at the Awk programming language and at the structure of a typical Awk program. Then we'll see how to use its capabilities to exchange data with the Tk graphical user interface toolkit. A good bit of the Tk and QuickTimeTcl code can be lifted neatly from the TickLeez application we built in the previous two articles ("Tickle Me" in MacTech, June 2004, and "Horse Feathers" in July 2004). So we can focus here on more interesting tasks.

Awk Overview

Awk was designed and developed in 1977 by three researchers at Bell Labs, Alfred Aho, Peter Weinberger, and Brian Kernighan. It's one of those fun utility languages that abound on UNIX and UNIX-like systems: small languages targeted at a specific problem domain. In the case of Awk, the problem domain is parsing text files, searching for patterns within those files, accumulating data from those patterns, and eventually printing a summary of parts of that data. In a nutshell, Awk is most often described as a pattern-matching language. It includes a robust regular expression syntax similar to what is found in other tools like Sed and Grep. It includes C-like flow-control statements, variables that can hold string and numeric values, the ability to define functions and procedures, and support for arrays and associative arrays for storing accumulated data. It also supports basic arithmetic operations and string operations (concatenation, substring, and the like).

The basic structure of an Awk program reflects this focus on pattern matching within text streams. Any nontrivial program contains four distinct sections: (1) definitions of functions used in the program; (2) a BEGIN section that is executed before any input is read; (3) a list of patterns and associated commands; and (4) and END section that is executed after all input has been read. Each line of input is examined to see whether it matches one or more of the patterns in the pattern list; for each matched pattern, the associated commands are executed. So the general structure of an Awk program looks like this:

function definitions
BEGIN {
   command
   command
   ...
   command
}
pattern   {command}
pattern   {command}
...
pattern   {command}
END {
   command
   command
   ...
   command
}

To repeat, Awk reads its standard input, matches each line of that input against the patterns, executes the commands associated with each matched pattern, and optionally prints some summary of the data before exiting.

Defining Functions

Awk provides a reasonably large assortment of built-in commands for manipulating strings and numbers. It also allows us to define functions that encapsulate sets of commands. For instance, Listing 1 shows an Awk version of the basename function that we've encountered in several previous articles. Given a full pathname, it returns the portion of the pathname following the rightmost path separator. This function is especially easy to implement in Awk, which provides the split function that splits a string into an array, using the specified delimiting character. In this case, the delimiting character is stored in a global data array so that, on application launch, it can be set to "/" on Macintosh systems and to "\" on Windows systems. The split function also returns as its result the number of components in the new array.

Listing 1: Getting the basename of a filename

basename
function basename (fileName) {
   numParts = split(fileName, paths, appData[PATHC_FIELD]);
   return(paths[numParts]);
}

Executing Shell Commands

In addition to the built-in operations and user-defined functions, Awk also supports several methods of executing arbitrary shell commands or other command-line tools. The simplest way to execute some external command is using the system command, like this:

system("rm " tempFile);

This command will remove from the file system the file specified by the tempFile variable.

In cases where we'd like our Awk script to capture the output of an external command, we can use a construct like this:

"uname" | getline appData[CUROS_FIELD];
close("uname");

This runs the uname command and grabs its output into the array element appData[CUROS_FIELD]. Awk's getline command, in the form used here, reads the first line of input from the uname command into the specified variable. Notice that we need to explicitly close the pipe with the close command.

As you probably know, the uname command prints the name of the current operating system. On Mac OS X, it returns the string "Darwin". So we can use the code in Listing 2 to determine which operating system the script is running on and to set the path separator character accordingly.

Listing 2: Setting the path separator

initApp
MACOS_TAG      = "Darwin";      # output of uname on Mac OS X

"uname" | getline appData[CUROS_FIELD];
close("uname");

if (appData[CUROS_FIELD] ~ MACOS_TAG) {
   appData[PATHC_FIELD] = "/";
} else {
   appData[PATHC_FIELD] = "\\";
}

Storing Data

Since AwkEez will be able to open multiple movies and (for instance) allow the user to cut and paste data from one movie to another, we need to keep track of the movie controller and other pieces of data associated with any particular movie. Awk does not provide any mechanism for defining structured data types, but we can simulate such types with associative arrays. So we'll maintain a global associative array called appData. In fact, we'll use the appData array for two purposes, to hold global data values (like the value appData[PATHC_FIELD] used above) and to hold data associated with a particular window. Listing 3 shows the definition of the initApp function, which initializes some of the values in the appData array.

Listing 3: Initializing the application

initApp
function initApp () {
   # constants identifying fields in the appData array
   DIRTY_FIELD            = 10;
   FNAME_FIELD            = 11;
   BNAME_FIELD            = 12;
   DNAME_FIELD            = 13;
   MOVIE_FIELD            = 14;
   UNDOL_FIELD            = 15;
   CTYPE_FIELD            = 16;
   OPRTN_FIELD            = 17;
   
   CUROS_FIELD            = 20;
   ABOUT_FIELD            = 21;
   NEWNO_FIELD            = 22;
   WINNO_FIELD            = 23;
   PATHC_FIELD            = 24;

   # the range of constants that are specific to a movie 
   FIRST_MOVIE_FIELD   = DIRTY_FIELD;   
   FINAL_MOVIE_FIELD   = CTYPE_FIELD;

   # values for the CTYPE_FIELD field
   CNTRL_LINEAR            = 0;
   CNTRL_VR                = 1;
   
   # some strings
   NEW_MOVIE_NAME            = "Untitled";
   APP_NAME                  = "AwkEez";
   WIN_NAME                  = "winRTM";
   MACOS_TAG                 = "Darwin";

   # global variables   
   appData[NEWNO_FIELD]   = 1;
   appData[WINNO_FIELD]   = 1;
   appData[ABOUT_FIELD]   = 0;
   
   # get the name of the current operating system
   "uname" | getline appData[CUROS_FIELD];
   close("uname");
   
   if (appData[CUROS_FIELD] ~ MACOS_TAG) {
      appData[PATHC_FIELD] = "/";
   } else {
      appData[PATHC_FIELD] = "\\";
   }
}

Values associated with a movie window are added to the appData array by creating "two-dimensional" array keys. For instance, we can store information about the dirty state of a movie window whose name is "winRTM1" like this:

winName = "winRTM1";
appData[winName,DIRTY_FIELD] = 0;

AwkEez Overview

Now, how do we hook an Awk script up to the Tk graphical user interface and the QuickTimeTcl extension? Quite easily, in fact. It turns out that when we install the Tcl/Tk package on Mac OS X, a shell script called wish is installed into the /usr/bin directory. This shell script merely launches the Wish Shell application and attaches the standard input of that application to the standard input of the script. This allows us to create windows and other user interface elements from the command line, for instance like this:

[Kant: ~] monroe% echo "toplevel .win1" | /usr/bin/wish

Executing this command causes a new toplevel window to be displayed by Wish Shell.

So it's easy to get an Awk script to send the appropriate Tk and QuickTimeTcl commands to the Tcl/Tk interpreter:

[Kant: ~] monroe% awk -f AwkEez.awk | /usr/bin/wish

All that AwkEez needs to do is send Tcl/Tk or QuickTimeTcl commands to its standard output, using the doTk function defined in Listing 4.

Listing 4: Sending commands to the Wish Shell

doTk
function doTk (string) {
   print string;
   flush();
}

As you can see, doTk simply prints the specified string to its standard output and then flushes the output stream by calling the function flush. The flush function is defined in Listing 5. (I'm not entirely sure how or why this works, but indeed it does work.)

Listing 5: Flushing the output stream

flush
function flush () {
   system("/usr/bin/true");
}

But how do we get information back from the Tk interpreter to the Awk script? Ideally we would like to connect the standard output of the Wish Shell to the standard input of the Awk script. This then would give us bidirectional communication between Awk and the Wish Shell: Awk's standard output goes to the standard input of Wish, whose standard output is directed to the standard input of Awk.

Connecting Awk and Wish in this way requires a simple C program or a Perl script, which we'll investigate later in this article. In the meantime, let's suppose that we've successfully linked the standard inputs and outputs of Awk and Wish as described. Let's see how to exploit that linkage. First, when AwkEez starts up, it executes any commands contained in the BEGIN section of the script, shown in Listing 6. Notice that AwkEez defines some Tcl procedures and sends them to Wish using the doTk command.

Listing 6: Flushing the output stream

BEGIN
BEGIN {
   # initialize constants and global variables
   initApp();
   
   # prime the pump: define some Tcl procedures
   doTk("package require QuickTimeTcl");   
   doTk("proc doAwk {s} {puts stdout $s; flush stdout}");
   doTk("proc sendVal {v} {global $v; set varFile 
         [open varFileTmp.txt w+]; puts $varFile 
                  [set [set v]]; close $varFile}");
   doTk("proc topMovieWindow {} {set winlist 
      [wm stackorder .]; set index [expr 
            [llength $winlist] - 1]; return 
               [string range [lindex $winlist $index] 1 end]}");
   doTk("proc max {a b} {if {$a > $b} 
               {set a} else {set b}}");
   doTk("proc min {a b} {if {$a < $b} 
                  {set a} else {set b}}");
   
   if (appData[CUROS_FIELD] ~ MACOS_TAG) {
      setUpMenus(".");
      setUpEventBindings("");
      adjustMenus("");
   } else {
      doNew();
   }
   
   # hide the root window and the Console window
   doTk("wm withdraw .");
   doTk("console hide");
}

We can ignore most of this for the moment. Notice however the definition of the doAwk procedure. It essentially does what doTk does, but on the Tcl/Tk side: it prints the string argument on the standard output and flushes the output stream. This causes that string to be sent to Awk for immediate processing.

As you know, Awk's main role is to match lines in its standard input against some known patterns and to react accordingly. Listing 7 shows the pattern-matching segment of AwkEez.

Listing 7: Handling commands

$1 ~ /^doOpen$/                  { doOpen(); }
$1 ~ /^doNew$/                   { doNew(); }
$1 ~ /^doClose$/                 { doClose(); }
$1 ~ /^doSave$/                  { doSave(); }
$1 ~ /^doSaveAs$/                { doSaveAs(); }
$1 ~ /^doExit$/                  { doExit(); }

$1 ~ /^doUndo$/                  { doUndo(); }
$1 ~ /^doEdit$/                  { doEdit($2); }
$1 ~ /^doSelect$/                { doSelect($2); }

$1 ~ /^doToggleBar$/             { doToggleBar(); }
$1 ~ /^doAbout$/                 { doAbout(); }

$1 ~ /^openFileInWindow$/        { openFileInWindow($2, $3); }
$1 ~ /^setTopWindow$/            { topWindow = $2; }
$1 ~ /^doAttemptClose$/          { doAttemptClose($2, $3); }
$1 ~ /^doHandleKey$/             { doHandleKey($2, $3); }
$1 ~ /^adjustMenus$/             { adjustMenus($2); }

Most of these patterns correspond to menu item selections. We can get Wish to emit those strings for example like this:

$m add command -label "Open..." -accelerator "Command-O" 
                                             -command {doAwk "doOpen"}

In other words, the Awk script is essentially saying to the Wish interpreter: I want you to add a menu item to the File menu with the label "Open..."; when the user selects that menu item, send me the string "doOpen".

As you can see in Listing 7, when AwkEez receives the string "doOpen", it calls its function doOpen, which is shown in Listing 8. The doOpen function tells Tk to display the standard file-opening dialog box and then send AwkEez the "openFileInWindow" string followed by the filename and the parameter 0.

Listing 8: Opening a movie file

doOpen
function doOpen () {
   doTk("set filename [tk_getOpenFile -title \"" APP_NAME ": Open a Movie File\"]");
   doTk("if {$filename != \"\"} {doAwk \"openFileInWindow ${filename} 0\"}");
}

It's worth noting that this current implementation does not allow white space to occur in file names. Fixing that is left as an easy exercise for the reader.

Most of the Awk functions called from Listing 7 (or called by any of those functions) are quite easy to implement, given that we have at hand a working Tcl/Tk QuickTime application, TickLeez. For instance, Listing 9 shows the TickLeez version of the setWindowDirty function.

Listing 9: Marking a movie window as changed (TickLeez)

setWindowDirty
proc setWindowDirty {winName state} {
   global appData

   set appData($winName,dirty) $state
   if {[string match "mac*" $appData(os)]} {
      wm attributes .$winName -modified $state
   }
}

This can be fairly easily modified into the Awk function shown in Listing 10.

Listing 10: Marking a movie window as changed (AwkEez)

setWindowDirty
function setWindowDirty (winName, state) {
   appData[winName,DIRTY_FIELD] = state;
   if (appData[CUROS_FIELD] ~ MACOS_TAG) {
      doTk("wm attributes ." winName " -modified " state);
   }
}

Interprocess Communication

One key step remains, which is to see how to form a bidirectional communications link between our Awk script and the Tcl/Tk interpreter Wish. In a C program this is reasonably easy to do using the socketpair(2) system call, which creates a pair of connected sockets. It's actually even easier to do in Perl, which supports the Socket module. Lsiting 11 shows the complete definition of a Perl script that establishes the desired bidirectional links. Because this script forms the glue between an Awk script and the Wish interpreter, let's call it AwkwA (for "Awk-to-Wish-Adhesive").

Listing 11: Connecting Awk to Wish

AwkwA.pl
#!/usr/bin/env perl
use Socket;
use IO::Handle;

use strict;
use warnings;

{
   my ($awkScript, $line, $pid_a, $pid_b, $pid_c, 
         $tclInterp);

   $tclInterp = '/usr/bin/wish';
  $awkScript = '/Users/monroe/QuickQuid/AwkEez/AwkEez.awk';

   socketpair(WISH, AWKWA, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
        or die "socketpair failed: $!\n";

   WISH->autoflush(1);
   AWKWA->autoflush(1);

   if ($pid_a = fork()) {
      close(AWKWA);

      socketpair(AWKEEZ, AWKWA_CHILD, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
            or die "socketpair failed: $!\n";

      AWKEEZ->autoflush(1);
      AWKWA_CHILD->autoflush(1);

      if ($pid_b = fork()) {
         if ($pid_c = fork()) {
            while (defined($line=<AWKEEZ>)) {
               chomp($line);
            # print "AwkEez => Wish: $line\n";
               print WISH "$line\n";
            }
         } elsif (defined($pid_c)) {
            while (defined($line=<WISH>)) {
               chomp($line);
               # print "Wish => AwkEez: $line\n";
               print AWKEEZ "$line\n";
            }
         } else {die "fork failed: $!\n";}

         close(AWKEEZ);
         close(WISH);
      } elsif (defined($pid_b)) {
         open(STDOUT, '>&AWKWA_CHILD');
         open(STDIN,  '>&AWKWA_CHILD');
         close(AWKEEZ);
         close(AWKWA_CHILD);
         select STDOUT; $| = 1;
         exec "awk -f $awkScript --";
      } else {die "fork failed: $!\n";}

   } elsif (defined($pid_a)) {
      open(STDOUT, '>&AWKWA');
      open(STDIN,  '>&AWKWA');
      close(WISH);
      close(AWKWA);
      select STDOUT; $| = 1;
      exec "$tclInterp --";
   } else {die "fork failed: $!\n";}
}

Notice that by uncommenting two lines in the script, we can have AwkwA print on its standard output the strings it is passing between Awk and Wish. This is a very useful debugging tool.

Once we launch the AwkwA.pl script, we'll have three interpreters running simultaneously: the Awk interpreter is doing most of the data storage and program control; the Tcl/Tk interpreter is handling user interface commands from the Awk script and sending strings back to it; and the Perl interpreter is handling the bidirectional communication between the Awk and Tcl/Tk interpreters. This might seem like a recipe for really slow operation, but in fact the whole thing works fairly well.

Immediate Evaluation

The simple sting-passing mechanism that we have used so far to connect our Awk script to the Tcl/Tk interpreter, via the AwkwA Perl script, works quite marvelously in most cases. The user interface elements of our application are configured to send strings like "doOpen" and "doEdit cut" back to the Awk script, which matches those strings in its "main event loop" and then calls the corresponding function. And the Awk script sends Tk commands to the Tcl/Tk interpreter to create and configure the application's menus, windows, and dialog boxes.

Occasionally, however, this mechanism is not powerful enough to fit our needs. At times, we need an immediate response from the Tcl/Tk side of the ledger during the execution of an Awk function. For instance, inside the openFileInWindow function, we need to determine whether a given movie is a QuickTime VR movie (for instance, so that we can set up the correct key bindings and adjust the application's menus correctly).

It might well be possible to solve this problem by suitably refactoring the AwkEez script. When we determine that we need a value from the Tcl/Tk interpreter, we could send it a request for that value and then wait for a response to arrive in the standard input stream. This solution however might introduce as many problems as it solves. We would need to maintain more state information and make sure that certain operations do not happen until a movie window is fully loaded and configured.

A better solution is to devise a way to get immediate responses from the Tcl/Tk interpreter, without reentering the AwkEez "main event loop". That is to say, we want to figure out a way for the Awk script to communicate with the Tcl/Tk interpreter within the execution of an Awk function. We can accomplish that like this: our Awk script will send a request for a specific value, which the Tcl/Tk interpreter writes into a temporary file. The Awk script then suspends operation and waits for a value to be written into that file; when a value is written into the file, Awk reads the value and then continues operation.

Listing 12 shows our definition of the getTkVal function, which implements this strategy.

Listing 12: Getting immediate values from Wish

getTkVal
function getTkVal (string) {
   tempFile = "varFileTmp.txt";
   
   doTk("global answer; set answer " string "; 
                                                         sendVal answer");   
   while ((getline ans < tempFile) != 1) {
      # spin our heels
   }
   
   close(tempFile);
   system("rm " tempFile);
   
   return(ans);
}

Here we're using a slightly different form of the getline command, which reads a line from a specified file into a variable (in this case, ans). A value is written into that file by the Tcl function sendVal, defined in Listing 13.

Listing 13: Writing a value into a file

sendVal
proc sendVal {v} {
   global $v

   set varFile [open varFileTmp.txt w+]
   puts $varFile [set [set v]]
   close $varFile
}

Now we can get immediate responses from the Tcl/Tk interpreter fairly easily. For instance, in the doSaveAs function we can elicit a filename from the use like this:

newFile = getTkVal("[tk_getSaveFile]");

Wish will display the standard file-saving dialog box and then return the name of the selected file to the AwkEez script, via a temporary file.

Conclusion

Incredible as it may seem, it's really quite straightforward to build a QuickTime playback and editing application that relies for basic program control and data storage on the Awk scripting language. The key is to realize that the Tcl/Tk interpreter Wish can be driven from the command line or from other scripts; in particular, Wish can have its standard input and standard output hooked up to the standard output and standard input of our Awk script, by executing a fairly simple Perl program.

In theory, we could use this technique to rely on virtually any programming language that can read from its standard input and write to its standard output. (QuickTime programming in Sed anyone?) But in practice this is a moderately messy and unsatisfying solution. As we've seen, the careful quoting required to embed Awk variables into Tk commands can get fairly tedious (look again at Listing 8). There are better solutions available. For instance, there is a Perl/Tk package that provides access to Tk commands from Perl scripts. And there is a RubyCocoa framework that allows Cocoa programming to be done using Ruby. If your goal is to drive a QuickTime application using a scripting language like Awk, Perl, Ruby, or Python, your best bet is probably to look for a package that binds that language to an existing GUI package like Tk or Cocoa.

Acknowledgements

The AwkwA Perl script was loosely inspired by the perlwafe script written by Gustaf Neumann, subsequently modified for use with Tcl/Tk by Dov Grobgeld. Thanks are due to Vicki Brown and Rich Morin for providing useful feedback on my Perl programming.

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.