© Andy Wilson, 1999

Tips and Tricks: Making Audio Talk the Lingo

Some of the recent advances in audio editing software and in Director itself since version 5 allow you to do some pretty useful things with audio files and their cue points. One of the biggest bugbears with Director when I first started using it (about the time when Director 4 was launched) was the difficulty you had trying to get different media streams and events within Director to synchronise. Today I want to show you how you can overcome many of these problems by making careful use of the cue points that it is now possible to embed in your media files. Specifically, I intend to use cue points in audio files, although you could apply many of the same principles to video just as easily. What we are actually going to do is to get an audio file issuing Lingo commands directly to the Director movie that is playing the file.

Setting Up an External Editor

Before we begin I'll say something about the working environment you'll need to set up in order to use these techniques. Above all else, you're going to need an audio editor capable of manipulating audio cue points. If, like me, you are working on Windows you'll want to install a copy of either CoolEdit 96 or SoundForge (version 4 or above). You'll also want to set up your Director environment to let you use your editor within Director itself. To do this, select the File->Preferences->Editors dialogue box, then select the media format you want to set up your editor for. In this case, you'll want to set up you audio editing program to be the external editor for both the AIFF Sound and WAVE Sound media types. To do this, first select the relevant media type, then click Edit. In the new dialogue box that appears select Use External Editor, then click Scan. A list of registered applications will appear from which you should select the sound editor you wish to use. I choose to use SoundForge. What this means is that you have now chosen an external editor for your sound files, so that you can at any point right-click on an audio cast member an select Launch External Editor to edit your sound files in the application of your choice.

Using Cue Points

What we are going to do is to use the cue points within an audio file to take control of our Director movie. The way cue points work within Director is that, as the sound file plays, any cue points embedded in the file are passed back to Director at the appropriate time. It is then up to you as the application developer to decide what to do in response. However, before we get into discussing these possibilities, let's look first at how we embed a cue point and then how we can trap it from within Director.

Basic Cue Points

To begin this exercise, first import a short sound file into Director. Pick a file that is long enough for you to embed several markers in - in my example I have used a piece of music around ten seconds long and edited it so that it loops quite smoothly. Having imported the file into Director you now need to open the file in the external editor, as I described above. Now you need to add a cue point to the file. To do this in SoundForge, simply click somewhere inside the audio window, then select Special->Drop Marker (or use the shortcut by simply typing 'M'). This will insert a marker into the audio at the point you selected. Now you need to edit the marker (right click on the marker arrow in the audio window and select Edit.) Name the marker 'Hello from the audio file'.

The next step is to do a little work in Director to trap the message from the audio file. Before we do this however, we first need to save the changes we have made to the audio file (click Save), then return to Director and click Done in the Mix Editing in Progress dialogue box that appeared when you fist chose to edit the file. Check that your cue point has been correctly saved by typing into the Message window:

put member(1).cuePointNames

(I'm assuming that your audio file was imported into cast member 1 in the default, internal cast library.) You should get a result as follows:

-- ["Hello from the audio file"]

Now we get on to the issue of how Director is going to trap this message. The first step is to drag the file into one of the audio channels in the score. Now we need to write a movie script as follows:

on cuePassed whichChannel, cueNumber, cueName
  put cueName
end

This cuePassed handler is there to trap the event that Director issues to itself whenever a media file passes a point at which it has a cue point embedded. This event is just like all of the other events that Director issues in that it can be trapped by an appropriately named handler, which allows you to respond to the event in whatever way you see fit. As you can see from the example, Director issues the cuePassed event along with a number of parameters that identify the specific cue point. The first parameter identifies the audio channel in which the file is playing. The second parameter identifies the cue point number. The third and final parameter identifies the title of the cue point in question.

The handler I've written here is pretty minimal in that it ignores the channel parameter and the cue point number - all it does is put the cue point name into the message window. To check that this all works, simply play the director movie. If everything has gone right for you so far you should see the words 'Hello from the audio file' appear in your message window at the point at which the audio file passes the cue point. So far so good.

Now we have to ask ourselves what use all of this is to us. Let's take the simple case where you have a long music file and you want to display the lyrics to the song exactly as they are sung. All you need to do is to embed cue points throughout the duration of the file and give each a name representing the lyrics being sung at that point. Now, instead of 'putting' the cueName parameter into the message window, put it into a message area on the Director stage that you've got one of your designer pals to make for you and, voila, the lyrics will appear on stage perfectly in synch with the audio you are playing.

More Advanced Cue Points

By now we have already achieved a nice level of synchronisation between audio and Director. We can, however, take this further. Consider the fact that the cue point name is passed to us, via the cuePassed event handler, as a string. Remember too that Director has a nice little internal Lingo function, the do function, which allows you to turn strings into Lingo commands. Damn it, you've already guessed what's coming - that's right, you can embed Lingo commands into your audio file that will be executed at the moment that the cue point is passed.

I have chosen a fairly simple example to illustrate this. What I decided to do was to set up a file so that the Director movie will go to different frames at the appropriate points during playback of the audio file. All this requires is that you set up cue points within the audio file and give the names that are actually Lingo commands that will tell your movie what to do at that point. I chose the simplest possible variation on this theme and created markers within the movie called StartFrame, MiddleFrame and EndFrame, then added cue point in the audio file called go to frame "StartFrame", and so on. Here's a screen shot of the SoundForge audio window showing the cue points:

Note that I also added a marker called myHandler() - I'll talk about that in a moment. To get this working all we need to do is modify our cuePassed event handler as follows;

on cuePassed whichChannel, cueNumber, cueName
  if (cueName <> EMPTY) then do (cueName)
end

Here is my Director Score. The cast members in channel one of the score are simply text fields identifying the start, middle and end of the song, and I had to add a movie handler that makes the movie pause on whatever frame it's in (on exitFrame go to the frame):

This really is fiendishly simple. All that happens is that whenever a cue point is passed, the name of the cue point is passed to our handler and the handler 'does' whatever the cue point name tells it to do. In other words, it executes the cue point name as if it were a Lingo command. In this case it means that, at the appropriate points during playback of the audio, Director goes to the associated frame within the movie. Of course there are endless variations to this theme: you could ignore the cueName and make the movie go to frame cueNumber instead, or go to the frame + 1. That way you would be stepping through your Director movie a frame at a time, whenever a cue point was passed. I'm sure you get the point. From here on in it's simply a matter of choosing the method that best suits the task in hand.

My final cue point I called myHandler(). This is just to illustrate the point that you aren't limited to executing single lines of Lingo code when using these methods. In this case, the cue point effectively issues a Lingo command, myHandler(), which you traps by writing a corresponding handler within your movie. This handler can then carry our as many Lingo calls and functions as you require, allowing your audio file to initiate very complex behaviours - launching other media files, downloading from the web, whatever you like. By now you should have enough control to achieve practically anything you like in terms of audio synchronisation in Director.

If you like, you can download the Director file from here to give you a starting point for experimenting these techniques. I'll remind you too that suggestions for future articles can be mailed to me at andyw@dircon.co.uk.