QTAudioXtra
version 1.1 of 23-May-03
by Kent Kersten
A free add-on for Director Lingo programmers
Contents
Creating an Instance of the Xtra
Appendix A. Complete Listing of Error Codes
QTAudioXtra and its documentation were created by Kent Kersten. Contact me via kent at kblab dot net (I spelled it out to try and defeat spambots).
The most current versions of my xtras will be at http://www.kblab.net/xtras.
QTAudioXtra is provided on an "as-is" basis which means that I assume no responsibility for how it is used and have no liability if it does not suit your needs.
QTAudioXtra is designed to run on Macromedia Director versions 6 and newer for Macintoshes with System 8.5 or newer (including OS X) as well as PC's running Windows 98-XP.
QTAudioXtra is Shockwave-safe.
Send me an email with the following information:
Code snippets can be helpful, but don't expect me to write or debug your application for you.
I had a project where I needed to manipulate tracks within a Quicktime movie. These tracks were all audio with an added text track that provided cue points. Some of the tracks were soloing versions of musical instruments playing over the bed tracks. Sometimes I would need to enable the solo tracks and others I would need them turned off.
Obviously I could not depend on Director to reliably synchronize the playback of multiple .aif's, and it was a cinch to place multiple tracks within a Quicktime.
Director does about 95% of what you need to manipulate tracks within a Quicktime but does not provide you with a way to set the volume of an individual track. And using Director to turn tracks on and off causes clicking in the audio playback. So I needed a way to set the volume of a track to 0 or to maximum.
I stumbled on an xtra called MultiMixer but soon discovered that it did not work with Director 8.5, so I started to write my own. This xtra has less functionality than Multimixer but handles the essentials that I needed for my projects. Peter & Phillip generously provided the source code to Multimixer so I could get over some Quicktime hurdles on this project. I don't think Multimixer is available any longer.
As with FileXtra I believe in producing xtras that are is invisibly cross-platform as possible. This saves me (and you) extra work having to code around platform-specific methods. A lot of my projects are hybrids that need to run on both Macs & PCs.
QTAudioXtra depends upon volume, folder and file “paths.” These paths are specified the same between platforms with the exception of the path “separator” character. This character is a colon (‘:’) for the Macintosh and a backslash (‘\’) for Windows.
These are known as absolute paths, because they are “unambiguous.”
Note also that the xtra does not support the Director “@” path shortcut
specifier. Please remember these two points for happier programming.
Windows volumes typically start with a drive letter, such as ‘A’
or ‘C’, and include a colon. To specify the root or top-most directory
on a Windows machine you would use something like “C:\”.
To refer to shared or network volumes on Windows you use something called UNC
names. While these UNC-named volumes can be “mapped” to drive letters
on a Windows machine, the xtra does not require that. QTAudioXtra works with
UNC-named volumes, such as “\\LinuxBox\kkersten\big_audio.mov”.
Macintoshes of course do not have this split personality when it comes to naming
volumes, whether they be local or networked. A typical Macintosh pathname might
be “Linux Server:kkersten:big_audio.mov”.
To use QTAudioXtra, place it into your “Xtras” folder that resides in the same folder as your Director executable.
To see a list of the methods available in the Message window, type the following:
put xtra(“QTAudioXtra”).interface()
To “instantiate” or create an instance of the xtra, use the following code:
qxObj = xtra(“QTAudioXtra”).new("filepath")
After instantiation, you can use any of the xtra’s methods as many times as you like.
I use the “dot” syntax (available since at least Director 7) in
my method calls, like so:
verStr = qxObj.qx_GetVersion()
Although you could also write the previous line as:
verStr = qx_GetVersion(qxObj)
When you are done using the xtra, free up its memory with the following code:
qxObj = 0
Creating an Instance of the Xtra
In order to use the xtra, you must write Lingo to tell Director to create an "instance" of the xtra using the new() method.
Name
new - create an instance of the xtra
Synopsis
objectVar = new(string movie_file_path)
Description
Create an instance of QTAudioXtra and return its object reference. You must pass the complete path to the QuickTime movie to use with this instance of the xtra.
Return Type
Object reference
Example
qxObj = xtra("QTAudioXtra").new("Macintosh HD:Footprints.mov")
put qxObj
-- <Xtra child "QTAudioXtra" 2 419f330>
qxObj = 0
Error Codes
-2: Specified file does not exist
-3: Error during OpenMovieFile()
-4: Error during NewMovieFromFile()
There is only one informational method, and that returns the current version of the xtra.
Name
qx_GetVersion - return the version of the xtra
Synopsis
strVar = qx_GetVersion(object me)
Description
This method returns a string that represents the version of QTAudioXtra that is in use.
Return Type
String
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_GetVersion()
-- "1.1 QTAudioXtra of 23-May-2003 by Kent Kersten"
qxObj = 0
Error Codes
None
There are several methods for getting and setting global movie information.
Name
qx_MovieIdle - give QuickTime time to process movie requests
Synopsis
intVar = qx_MovieIdle(object me)
Description
You should call this method in your frame script(s) to give QuickTime CPU time to handle requests made by the movie being played.
Return Type
Integer; this routine always returns 1 or True.
Example
qxObj = xtra("QTAudioXtra").new("Toad Hall:jugheads.mov")
put qxObj.qx_MovieIdle()
qxObj = 0
Error Codes
None
Name
qx_MovieStart - start playing the movie
Synopsis
intVar = qx_MovieStart(object me)
Description
To start playing the movie from the current position.
Returns True (1) if successful, False (0) if not or if an error occurs.
Return Type
Integer
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_MovieStart()
-- 1
qxObj = 0
Error Codes
-5: Error during LoadMovieIntoRam()
Name
qx_MovieStop - stop playing the movie
Synopsis
intVar = qx_MovieStop(object me)
Description
Call this method to stop playing the QuickTime movie. No rewind is performed.
Return Type
Integer; this method always returns 1.
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_MovieStop()
-- 1
qxObj = 0
Error Codes
None.
Name
qx_MovieIsDone - return whether the movie has finished playing
Synopsis
intVar = qx_MovieIsDone(object me)
Description
Test whether the movie has finished playing with this method.
Returns True (1) if the movie has finished, False (0) if not.
Return Type
Integer
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_MovieIsDone()
-- 1
qxObj = 0
Error Codes
None
Name
qx_MovieGetRate - return the playback rate
Synopsis
intVar = qx_MovieGetRate(object me)
Description
Return the rate the current movie is playing. A rate of 1 is normal forward speed while 2 means it is playing at double speed. A rate of -1 would indicate normal speed reverse playback.
Return Type
Integer
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_MovieGetRate()
-- 1
qxObj = 0
Error Codes
None
Name
qx_MovieSetRate - set the playback speed for the movie
Synopsis
intVar = qx_MovieSetRate(object me, integer rate)
Description
Set the playback rate for the current movie. A rate of 1 is normal forward speed while 2 would playback at double speed. A rate of -1 would play back at normal speed in reverse.
Return Type
Integer; this method always returns 1.
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_MovieSetRate(1)
-- 1
qxObj = 0
Error Codes
None
Name
qx_MovieGetDuration - return the length of the movie in the movie's timescale
Synopsis
intVar = qx_MovieGetDuration(object me)
Description
The default time scale is 600 "units" per second.
Return Type
Integer
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_MovieGetDuration()
-- 48600
qxObj = 0
Error Codes
None
Name
qx_MovieGetTime - return the current movie time
Synopsis
intVar = qx_MovieGetTime(object me)
Description
This method returns the current time in the movie where the "playback" head is located, in the movie's timescale.
Return Type
Integer
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_MovieGetTime()
-- 862
qxObj = 0
Error Codes
None
Name
qx_MovieSetTime - give QuickTime time to process movie requests
Synopsis
intVar = qx_MovieSetTime(object me, integer timeValue)
Description
Set the location of the playback for the movie using the movie's timescale.
Return Type
Integer; this method always returns 1.
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_MovieSetTime(4800)
-- 1
qxObj = 0
Error Codes
None
Name
qx_MovieGetVolume - return the volume setting for the movie
Synopsis
intVar = qx_MovieGetVolume(object me)
Description
Return the current volume of the movie in the range of 0..255 with 0 being mute and 255 being the highest setting.
Return Type
Integer
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_MovieGetVolume()
-- 200
qxObj = 0
Error Codes
None
Name
qx_MovieSetVolume - set the volume for the movie
Synopsis
intVar = qx_MovieSetVolume(object me, integer movieVolume)
Description
Set the volume for the movie in the range of 0..255 with 0 being mute and 255 being the highest setting.
Return Type
Integer; this method always returns 1.
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_MovieSetVolume(255)
-- 1
qxObj = 0
Error Codes
None
These are the methods for getting and setting information about individual tracks.
Name
qx_TrackGetCount - return the number of tracks within the movie
Synopsis
intVar = qx_TrackGetCount(object me)
Description
Use this method to determine how many tracks are within the current movie.
Return Type
Integer
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_TrackGetCount()
-- 12
qxObj = 0
Error Codes
None
Name
qx_TrackGetType - determine the media type of a given track
Synopsis
intVar = qx_TrackGetType(object me, integer trackNumber)
Description
Returns the type of media for the specified track as a four-character string.
Valid types are:
Type Meaning vide Video media soun Sound media text Text track gnrc Base media MPEG MPEG media musi Music media tmcd Time Code media sprt Sprite media flsh Flash media moov Movie media twen Tween media qd3d 3D media hndl Handle Data Handler subtype ptr Pointer Data Handler subtype null Null Data Handler subtype rsrc Resource Data Handler subtype url URL Data Handler subtype wire Wired action handler For more information on these media types refer to the Quicktime developer's guide from Apple.
Return Type
String
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_TrackGetType(1)
-- "soun"
qxObj = 0
Error Codes
None
Name
qx_TrackGetName - return the label of the specified track
Synopsis
stringVar = qx_TrackGetName(object me, integer trackNumber)
Description
Return the text string used as the label for the specified track.
Return Type
String
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_TrackGetName(1)
-- "Mandolin"
qxObj = 0
Error Codes
-6: Could not retrieve track name
Name
qx_TrackGetEnabled - determine if a track is turned on
Synopsis
intVar = qx_TrackGetEnabled(object me, integer trackNumber)
Description
Returns 1 (True) if the specified track is turned on, 0 (False) if not.
Return Type
Integer
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_TrackGetEnabled(1)
-- 1
qxObj = 0
Error Codes
None
Name
qx_TrackSetEnabled - turn a track on or off
Synopsis
intVar = qx_TrackSetEnabled(object me, integer trackNumber, integer trackEnabled)
Description
Call this method to turn on (trackEnabled = 1) or turn off (trackEnabled = 0) the specified track.
Return Type
Integer; this method always returns 1.
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_TrackSetEnabled(7, 0)
-- 1
qxObj = 0
Error Codes
None
Name
qx_TrackGetVolume - return the current volume for the specified track
Synopsis
intVar = qx_TrackGetVolume(object me, integer trackNumber)
Description
Use this method to determine the volume for a particular track.
Return Type
Integer
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_TrackGetVolume(7)
-- 192
qxObj = 0
Error Codes
None
Name
qx_TrackSetVolume - set the current volume for the specified track
Synopsis
intVar = qx_TrackSetVolume(object me, integer trackNumber, integer trackVolume)
Description
Call this method to set the volume for a particular track.
Return Type
Integer; this method always returns 1.
Example
qxObj = xtra("QTAudioXtra").new("c:\big_audio.mov")
put qxObj.qx_TrackSetVolume(1, 255)
-- 1
qxObj = 0
Error Codes
None
These two methods report the error code of the last method to be invoked and provide a text string interpreting what the error means or what happened to cause the error.
Name
qx_ErrorNumber - return the error code generated by the last Xtra method call
Synopsis
intVar = qx_ErrorNumber(object me)
Description
If this number is not 0 then an error occurred during the most recent method call.
Return Type
Integer
Example
...
put qxObj.qx_ErrorNumber()
-- -3
...
Error Codes
None
Name
qx_ErrorString - return a human-readable error report about the last method call
Synopsis
stringVar = qx_ErrorString(object me)
Description
Returns a string that explains (sort of) what happened with the last method call.
Return Type
String
Example
...
put qxObj.qx_ErrorString()
-- "Error during OpenMovieFile()"
...
Error Codes
None
| Code | Message | Platform |
| 0 | Successful completion | both |
| -1 | General error of unknown origin | both |
| -2 | Specified file does not exist | both |
| -3 | Error during OpenMovieFile() | both |
| -4 | Error during NewMovieFromFile() | both |
| -5 | Error during LoadMovieIntoRam() | both |
| -6 | Could not retrieve track name | both |