Audio Xtra can be used in Shockwave: the distribution package provides packaged Xtras that are downloaded automatically to the user's machine, and installed on demand. Please consult Macromedia's web site for a complete overview of the Xtras automated download mechanism: read the Shockwave Xtras downloading overview technote. The basic steps required to make Audio Xtra available for download are outlined below.
To create a Shockwave movie that will auto-download the Xtra to the user's hard drive you must do the following, in this order:
1. Upload the packaged Xtra files to your web server
2. Modify the entry for Audio Xtra in file xtrainfo.txt to point to the packaged Xtra files on your server
3. Do Modify -> Movie -> Xtras, select Audio Xtra, and check the "Download if Needed" option
Once you have completed steps 1 and 2, you can create other Shockwave movies by doing only step 3.
PACKAGED FILES
Your Audio Xtra archive contains a subfolder called "Shockwave". There are four files inside it:
AudioXtra.w32 - Win 32 packaged Audio Xtra
AudioXtra.ppc - Mac Classic package
AudioXtra.carb - Mac OSX Carbon package
AudioXtra.xpku - Mac OSX Universal Binary package
All packages contain the Audio Xtra for that platform. Depending on the user's platform, a package autodownloaded to the user's hard drive will install the correct Audio Xtra for the user's platform into their Shockwave support folder.
If, for some reason, you choose not to make your Shockwave movies autodownload the package files, you can have the user install the right Xtra for their platform into the Shockwave support folder manually.
Upload all package files to the same directory on your web server. Use a "binary" or "raw", not "text" transfer. If the packages are uploaded to two different directories, autodownloading will not work. Do not rename the package files.
If you are going to distribute Audio Xtra with Shockwave movies, we recommend that you use your own web server to do so. Packages are available at Tabuleiro's download services, but we reserve the right to refuse access, without notice, to any referring URL that generates excessive traffic.
The Audio Xtra packages included with the download have been signed and packaged by Tabuleiro, and will present the following security message to users of your Shockwave movies when they are installed for the first time:
You may choose to repackage Audio Xtra and sign it with your own Verisign certificate. You might want to do this if you want your own company name to appear in the auto-download dialog box the user sees when an auto-download is initiated. Adobe is the best source of information on applying for a Verisign certificate and packaging files.
XTRAINFO.TXT
The text file xtrainfo.txt resides in your Director authoring directory. It contains information about Xtras such as file version names for an Xtra on both platforms and the URL for the packages. The information contained in xtrainfo.txt is saved with each movie you create and used by projectors and Shockwave.
You must create an entry for Audio Xtra in your xtrainfo.txt file that specifies the URL on your server for the package files. The last part of the path will always be "AudioXtra". That specifies the filename of the packages within the directory, without the file extension. Do not include a file extension at the end of the path.
[#namePPC:"Audio Xtra", #nameW32:"AudioXtra.x32", #package:"http://www.domain.com/folder/AudioXtra"]
Make sure that the line above does not contain any return character after you paste it into your xtrainfo.txt file. Open your text editor wide and make sure the line does not wrap. If the opening and closing brackets are not on the same line, Director will not be able to create a valid list from the entry and the "Download if needed" button will be dimmed for Audio Xtra in Director.
If you edit xtrainfo.txt while Director is open you should quit and restart Director to read in the changed information in xtrainfo.
EDITING THE MOVIE'S XTRAS LIST
Open the Director movie that you want to save as Shockwave. Choose Modify -> Movie -> Xtras and add Audio Xtra. Select Audio Xtra from the list and check the "Download if needed" option. Director will initiate an internet connection and look for the packages at the URL you specified in xtrainfo.txt.
If Director finds the packages, it will transfer information about the package contents for both platforms such as file names and version numbers and embed the information into your Director movie. An informational dialog box will appear that tells you that the packages for both platforms are "downloading". The packages themselves are not downloading, just information about them that the Shockwave movie will need later to compare the version of the Xtra the user possibly already has to the version currently on the server in order to determine if autodownloading is necessary. The Director movie needs information about both platforms because it may find itself running on either platform once it is on the web.
Once "downloading" of the packages has finished, save the movie, then publish as Shockwave. The finished Shockwave movie can reside at any URL. It does not have to be in the same directory or even on the same server as the packaged Xtras.
If a connection cannot be opened, or the packages cannot be found at the specified location, Director will uncheck the "Download as needed" option automatically. You must have a successful connection for the box to remain checked. A Shockwave made out of a Director movie with the "Download as needed" button unchecked will not autodownload Audio Xtra.
MACROMEDIA XTRAS THAT AUDIO XTRA NEEDS
Audio Xtra uses some services provided by Macromedia Xtras. Depending on what Audio Xtra operations you are going to perform you must include at least four of the following Xtras in your movie's Xtras list and possibly all 5:
Mix Services: always needed
MacroMix: always needed
DirectSound: always needed
Sound Import Export: always needed
Sun AU Import Export: optionally needed to record and play Sun AU files
All of the Xtras can download if needed and their paths are already set up in Director's xtrainfo.txt. Some of them are automatically installed with the standard Shockwave install. To include them in your movie choose Modify -> Movie -> Xtras and check "Download if needed". A web connection must be open for the Xtras to be added successfully.
SECURITY
Audio Xtra records files to the user's hard drive and queries the system for information that it needs, such as writeable hard drives. In a Shockwave environment the user must be informed of such activity and given an opportunity to grant or refuse permission. Audio Xtra restricts access to certain functions and system properties when running in Shockwave. For testing, you can simulate a Shockwave environment in authoring by doing:
axSetEnvironmentInfo("simulateShockwave",TRUE)
OBTAINING USER PERMISSION
Some Audio Xtra commands display a permission dialog box in Shockwave when they are issued. The dialog box looks like this:
This is what happens, depending on the user's response:
No: command returns error -8713, "No Shockwave permissions"
Yes, don't ask again: command is carried out and user will not be prompted for permission for that command again during the session unless the Shockwave movie changes
Yes: command is carried out, but user will be prompted again the next time the command is issued
Audio Xtra's default permission behavior is to display the permission dialog every time a command needing permission is issued. You can head off the default behavior by using axAskPermission to display a permission dialog early on, listing the commands you plan to use during the session. Once the user grants permission in this dialog the user is no longer prompted again during the session for the commands that were displayed in the dialog, unless the Shockwave movie changes. This is what the dialog displayed by axAskPermission looks like, although the list of commands will differ depending on what commands you have requested it to list:
This is what happens, depending on the user's response:
No: command returns error -8713, "No Shockwave permissions"
Yes: command is carried out and user will not be prompted for permission for the listed command(s) again during the session unless the Shockwave movie changes
PRIVATE SOUNDS DIRECTORY
In Shockwave you must have a sounds directory specified before you can record audio files. In authoring or projectors you can specify any path for a recorded sound and load files from any path. If you decide to use a sounds directory in authoring or projector for convenience you can either set the path to the sounds directory using axSetEnvironmentInfo ("soundsDirectory") or you can prompt the user for the path using axPromptForSoundsDirectory.
In Shockwave, there are two options: the first is to prompt the user for the path using axPromptForSoundsDirectory. The second option is to set the environment option "useDswMediaDirectory" to TRUE, and Audio Xtra will automatically detect and use the DswMedia support folder for your Shockwave player installation. This option was introduced in version 5.1 of Audio Xtra.
In both cases you cannot set or query the "soundsDirectory" property using axSet or GetEnvironmentInfo, for security reasons. The path to the final sounds directory is stored internally and only available to Audio Xtra. The Shockwave movie can only work with files in the sounds directory. This applies to recording, playback and sound conversion.
SYSTEM INFORMATION
Some system properties returned from axGetEnvironmentInfo are not available when running under Shockwave. They return error -8718, "This feature is not supported in Shockwave". The properties not available in Shockwave are:
tempPath
driveList
writeDriveList
soundsDirectory