The following is a list of scripting functions available after installation of Audio Xtra.

axRegister([1111,2222,3333]) - global function, used to register Audio Xtra. It can be called at any time, usually when the Director movie starts. Unregistered versions of the Xtra are fully functional for evaluation purposes, but they will display a warning the first time an Audio Xtra function is used. Returns TRUE if registration is successful, FALSE otherwise.

Audio Xtra serial number are strings, and have the generic format AUXZZ-1111-2222-3333, where ZZ is the major Xtra version. In order to protect your serial number from being included as a string in your Director projectors or dcr movies, the axRegister function requires only the three groups of numbers 1111, 2222 and 3333 inside a Director list. Leading zeroes do not need to be entered.

An example: if your serial number is AUX50-0123-4567-0089 then you should register using the following command, usually on a startmovie handler:

Lingo:

axRegister([123, 4567,89])

JavaScript syntax :

axRegister(list(123, 4567,89))

axOpenRecorder(bufferSizeInteger) where bufferSizeInteger is the size in bytes of the RAM buffer to reserve when recording to RAM. Returns an error number or 0 for no error. This command pens the sound recorder and allocates space in RAM for recording a sound to RAM or member. The bufferSize must be the maximum expected size of the recorded sound. The minimum recording buffer size for RAM recording is 10K on Windows and 20K on Mac. Passing a buffer size parameter of less than the required minimum will cause axOpenRecorder to fail and return an error.

For recording to a file, set bufferSize to 0 because a RAM buffer will not be used for recording. Setting a bufferSize other than 0 for recording to a file wastes RAM, since the memory will be allocated but never used. If you are recording to RAM or recording to a member keep in mind that after recording the sound will be copied out of the buffer to either a RAM location or a member, which means that the total memory requirement is actually twice the size of the sound. For instance if you set a buffer size of 40K and record a 40K sound into it you will need 80K of free memory to accomplish it - 40 for the buffer and 40 to store the finished sound in RAM or in a member.

The recorded sound will use the system default values for recording depth, sampling rate and number of channels, unless you have used axSetEnvironmentInfo to set other values. It is recommended to set the values for depth, rate and number of channels before the recorder is open. Settings changed while the recorder is open will be ignored unless the recorder is closed and reopened.

Example:

err = axOpenRecorder(102400)

-- sets the recording RAM buffer to 100K

If axOpenRecorder returns an error, you must use axCloseRecorder, before trying to open the recorder again, or recording may not function correctly.

axCloseRecorder() - Closes the sound recorder and releases the sound recording driver for use by other applications. The sound recorder must be closed before you can play sound if your sound card is not full duplex. Returns an error number or 0 for no error.

Example:

on mouseUp

axStopRecording()

axCloseRecorder()

end

axRecordSoundToFile(soundNameString, filePathString) where soundNameString is the name for the sound that will be added to the sound list and filePathString is the full file path or file name to save the recorded sound to in the sounds directory. Returns an error number or 0 for no error. An error will be returned if recording could not begin for some reason. In Shockwave the error -8718: "This feature is not supported in Shockwave" returns if the file already exists, for security reasons. axDeleteSound can be used in this case if the file has been created in the same recording section, or you must supply a different filename. If an error happened during recording, that will be returned from the axStopRecording command.

If a full path is not given, records sound to the specified file name in the sounds directory previously set with axSetEnvironmentInfo or axPromptForSoundsDirectory ,and adds the sound to the sound list. The recorder must be open for this command to work.

If a sounds directory is set and you pass a full path to the file for filePathString, the path is appended to the sounds directory path and will probably not result in a valid recording.

Recording in Shockwave will not begin until the user responds to any permissions dialog. If you are doing timed recording, start your timer after this command rather than before.

Although you can convert recorded sounds to other formats after recording, on Win you must record initially to a WAVE file and you must specify WAV as the file extension . On Mac you must record initially to an AIF file.

Note: Audio Xtra handles sound file extensions differently on the Mac and PC platform.

Examples:

-- next line contains no path so the sounds directory is assumed

err = axRecordSoundToFile ("New Sound", "TEST1.WAV")

err = axRecordSoundToFile ("Another", "C:\TEMP\TEST1.WAV")

axRecordSoundToRAM(soundNameString) where soundNameString is the name for the sound that will be added to the sound list. Returns an error number or 0 for no error. An error will be returned if recording could not begin for some reason. If an error happened during recording, that will be returned from the axStopRecording command. Records sound to memory and adds the sound to the sound list. The recorder must be open for this command to work.

Example:

err = axRecordSoundToRAM ("New Sound")

axRecordSoundToMember(soundNameString, memberReference) where soundNameString is the name for the sound that will be added to the sound list and memberReference is the member to hold the recorded sound. Returns an error number or 0 for no error. An error will be returned if recording could not begin for some reason. If an error happened during recording, that will be returned from the asStopRecording command. Records sound to to the specified member and adds the sound to the sound list. You can use the utility method axGetEmptyMember to find an empty cast member to receive the sound. The recorder must be open for this command to work.

Example:

err = axRecordSoundToMember ("Audio 1", axGetEmptyMember() )

axServiceRecording() - Previous versions of Audio Xtra required this function to be called repeatedly during the recording process. In version 5.0 and later this is no longer necessary, as the Xtra will automatically service recording during idle events. However, this function is still present to provide compatibility with older content and Shockwave movies authored with previous versions.

axStopRecording() - Returns an error number or 0 for no error. Stops recording and creates a sound file or new member if the sound was designated to record to a file or to a member. A new sound in the process of recording will not appear in the sound list until axStopRecording() is called.

The amount of time you can record is determined by the size of the buffer set when you open the recorder. If you exceed the size of the buffer, recording will automatically stop. If that happens, and you then issue axStopRecording, Audio Xtra will return -8809, No sound is recording. A sound will be created with the recording up to the point the buffer filled up.

Example:

err = axStopRecording()

axPauseRecording() - Returns an error number or 0 for no error. Pauses recording. Does not create a new file or member because the sound is not yet finished. Waits for a resume to continue recording.

If the RAM buffer is too full to later resume recording, this command can return a -8820 error, and what has been recorded will be saved as a sound if there is enough RAM to do so.

Example:

err = axPauseRecording()

axResumeRecording() - Returns an error number or 0 for no error. Resumes a paused recording.

If the RAM buffer is too full to continue recording, this command can return a -8820 error, and what has been recorded will be saved as a sound if there is enough RAM to do so.

Example:

err = axResumeRecording()

axGetInputLevel() - Returns an integer between 0 and 255, or a negative error number. This command is only available on the Mac platform. Returns the current sound input volume level. The sound recorder must be open to get a level. On OSX, Director must be running to get a level. Calling the function from the Message Window while Director is stopped will always return 0.

Example:

axOpenRecorder(19249)

level = axGetInputLevel()

axLoadSound(soundNameString, typeString, memberRefOrFilePathString) where soundNameString is the name for the sound in the sound list, typeString is either "file" or "member" and memberRefOrFilePathString is either a member reference or a file path string. Returns an error number or 0 for no error.

Puts a sound that exists either in the Director movie's castlib or in an external file into Audio Xtra's sound list so that it can work with the member or file. If a file is specified, using this command creates a pointer from the sound list to the file but does not actually load the file into memory. If a member is specified however, using this command loads the member in to memory. It does the equivalent of Lingo's load member command.

If a sounds directory has been set with axSetEnvironmentInfo or axPromptForSoundsDirectory specifying a file name with no file path will automatically load the specified file from the sounds directory. You cannot specify a full file path in Shockwave. You must specify only a file name, which will load the sound file of that name from the sounds directory.

Note: Audio Xtra handles sound file extensions differently on the Mac and Windows platform.

Example:

axLoadSound("Happy Birthday","member",member 5)

axLoadSound("Narration1","file","My CD:sound:narr1.aif")

axLoadSoundIntoRAM(soundNameString, filePathString) where soundNameString is the name for the sound in the sound list and filePathString is the file path for the sound file to be loaded. Returns an error number or 0 for no error.

Puts an existing external sound file into Audio Xtra's sound list so that it can work with the file and loads the file into memory. This command is not available for cast members because axLoadSound automatically loads them in to memory. A sound loaded in to RAM will play back smoothly. You may want to use this function for a sound that skips when playing from disk.

If a sounds directory has been set with axSetEnvironmentInfo or axPromptForSoundsDirectory specifying a file name with no file path will automatically load the specified file from the sounds directory. You cannot specify a full file path in Shockwave. You must specify only a file name, which will load the sound file of that name from the sounds directory.

Note: Audio Xtra handles sound file extensions differently on the Mac and Windows platform.

Example:

axLoadSoundIntoRAM("Bird Song","D:\TEMP\BIRD.WAV")

-- loads BIRD.WAV from the sounds directory

axLoadSoundIntoRAM("Bird Song","BIRD.WAV")

axRemoveSound(soundNameString) where soundNameString is the name of a sound present in the sound list. Returns an error number or 0 for no error. Removes a sound from the sound list. If the sound was recorded into RAM, this command also releases the memory used by the sound.

Example:

axRemoveSound("Bird Song")

axDeleteSound(soundNameString) where soundNameString is the name of a sound present in the sound list. Returns an error number or 0 for no error. Removes a sound from the sound list and deletes its source media. The source member is deleted from the Director cast or the source file is deleted from the hard drive. If the sound was recorded into RAM, this command also releases the memory used by the sound. In Shockwave this command will only delete a sound file if it was recorded during the current session.

Note: The recorder must be closed (axCloseRecorder) or this command may return the error "-8224 file permission, device in use" and not delete the file, although the file will disappear from the sound list.

Example:

err = axDeleteSound("Narration 1")

axGetSoundList()

axGetSoundList(#all)

axGetSoundList(propertySymbol, propertySymbol...) where propertySymbol are the names of properties requested for listing. Returns an error number or a list containing the requested information for each sound on the sound list.

This command when issued with no arguments returns a list of the sound names in the sound list. When called with #all it returns the full sound list with every possible property and value listed for each sound on the list. When passed a variable number of property symbols, the listing still contains all of the sounds, but only returns the properties requested for each sound. See the Sound List Table for a list of the properties that can be requested with this command.

Example:

put axGetSoundList()

-- ["Song", "Horn Fanfare"]

put axGetSoundList(#all)

-- ["Song": [#name: "Song", #source: "file", #format: "WAVE", #start: 3991, #end: 0, #totalLength: 3998, #length: 3998, #position: 0, #depth: 8, #rate: 11127, #numChannels: 1, #volume: 255, #channel: 0, #preLoad: 1, #interleaveSeeking: 1], "Horn Fanfare": [#name: "Horn Fanfare", #source: "file", #format: "AIFF", #start: 4118, #end: 0, #totalLength: 4129, #length: 4129, #position: 0, #depth: 8, #rate: 11128, #numChannels: 1, #volume: 255, #channel: 0, #preLoad: 1, #interleaveSeeking: 1]]

put axGetSoundList(#source,#format)

-- ["Song": [#source: "file", #format: "WAVE"], "Horn Fanfare": [#source: "file", #format: "AIFF"]]

axSetSoundInfo(soundNameString, propertyString, propertyValue) where soundNameString is the name of a sound present in the sound list, propertyString is the name of the property to set and propertyValue is the new value for the property. Returns an error number or 0 for no error. Replaces an existing sound property value with the new value. See the Sound List Table for a list of the available properties and the subset that can be changed with this command.

Example:

axSetSoundInfo("Song","volume",125)

axGetSoundInfo(soundNameString, propertyString) where soundNameString is the name of a sound present in the sound list and propertyString is the name of the property to read. Returns the property value requested or a negative error number. Reads the requested property for the sound specified. See the Sound List Table for a list of the available properties. Since the sound list is formatted as a Lingo property list you can also read it directly using Lingo property list commands on the list returned from axGetSoundList()

Example:

put axGetSoundInfo("Song","format")

-- "WAVE"

axPlay(soundNameString) where soundNameString is the name of a sound present in the sound list. Returns an error number or 0 for no error. Plays the specified sound, which must be present in the sound list. On Windows, if the sound card is not full duplex you must use axCloseRecorder first or the sound will not play, or play with distortion.

Example:

err = axPlay("Song")

axStop(soundNameString) where soundNameString is the name of a sound present in the sound list. Returns an error number or 0 for no error. Stops playing the specified sound. Resets the position to 0.

Example:

err = axStop("Song")

axGetStatus(soundNameString ) where soundNameString is the name of a sound present in the sound list. Returns a string describing the playback status of the sound or an error number if an error occurred. Returns the current playback status of a sound in the sound list.

The possible return values from a GetStatus call are:

"stopped" - Not playing

"playing" - Playing

"recording" - Recording

"record paused" - Paused while recording

"invalid" - Bad sound name argument passed

"error" - Not enough memory to complete the command - very unlikely

Example:

status = axGetStatus("Narration")

put status

-- "stopped"

axGetVersion() - Returns a string containing version number of Audio Xtra.

Example:

put axGetVersion()

-- "6.0"

axSetEnvironmentInfo(infoTypeString, newValue) where infoTypeString is the name of the environment property to set and newValue is the new value for the property. Returns an error number or 0 for no error. Sets a property that applies to Audio Xtra's recording and playback environment as a whole, rather than to a particular sound. The Environment Properties Table lists the available properties. Note that some properties only apply to one platform and some cannot be set.

Example:

sysTemp = axGetEnvironmentInfo("tempPath")

axSetEnvironmentInfo ("soundsDirectory", sysTemp )

axGetEnvironmentInfo(infoTypeString) where infoTypeString is the name of the environment property to read. Returns a value for the specified property or a negative error number. Reads the value for a property that applies to Audio Xtra's recording and playback environment as a whole, rather than to a particular sound. The Environment Properties Table lists the available properties. Some properties only apply to one platform.

Example:

put axGetEnvironmentInfo("availableSoundFormats")

-- "AIFF

WAV"

axGetFreeSpace()

axGetFreeSpace(driveNameString) where driveNameString is the drive letter on Windows or the name of the volume on Mac. Returns a positive number representing number of free K (1024 bytes per K) or a negative error number. Returns the free space on the disk to help in estimating recording time available. Use axBytesToMilliseconds to calculate recording time available based on space. If no argument is passed and the sounds directory has already been specified, it returns the free space on the drive containing the sounds directory.

In Shockwave, you can only use this command with no arguments to get the space for the drive containing the sounds directory. Passing an arbitrary drive will return an error in those environments.

Note: If you make repeated calls to the function in a loop you may get a -8234 error return. The system calculates the free space in real time and it may take as long as a second for the system to clean up after the call. Make repeated calls to this function no more frequently than one second apart for best results.

Example:

freeRecordingK = axGetFreeSpace("Macintosh HD")

recordingSeconds = axBytesToMilliseconds(freeRecordingK * 1024) / 1000

axGetEmptyMember()

axGetEmptyMember(castlibNumInteger) where castlibNumInteger is an optional cast library number. Returns a full member reference for the empty member slot. Returns a member reference for the first empty cast member. If no castlib is specified, the internal castlib (1) is used. If a castlib number is specified, that castlib is used. Use this function to easily locate an empty member slot to pass to axRecordSoundToMember.

Example:

put axGetEmptyMember()

-- (member 55 of castLib 1)

put axGetEmptyMember(2)

-- (member 4 of castLib 2)

err = axRecordSoundToMember( "new sound",axGetEmptyMember() )

axConvertToFile(soundNameString, filePathString, formatString) where soundNameString is the name of a sound present in the sound list, filePathString is the file name or full file path to save new file to and formatString is one of the supported file formats for export. Returns an error number or 0 for no error. Saves an existing sound in the sound list to a file on the hard drive. The environment properties convertSampleRate, convertSampleDepth and convertNumChannels determine the properties of the converted file, and should be set using axSetEnvironmentInfo before this command is executed. Does not add the sound to the sound list. Use axLoadSound to add the new sound to the sound list.

The available save formats to choose from for the new sound depend on the Xtras loaded, since some of Director's MIX Xtras are used to save the file. See the Getting Started section for a list of all of the possible Xtras to include. axGetEnvironmentInfo("availableSoundFormats") will return the current formats provided by loaded Xtras. Additionally, there are some limitations, as shown in the Export File Formats Supported table below.

If a sounds directory has been set with axSetEnvironmentInfo or axPromptForSoundsDirectory specifying just a filename with no path for filePathString will automatically create the specified file in the sounds directory. You cannot specify a full file path in Shockwave. You must specify only a file name, which will create the specified file in the sounds directory.

The filename, whether it is at the end of a path or by itself, must include a file extension that matches the specified file type on the PC. Refer to the File Format table above for the correct extension.

Note: Audio Xtra handles sound file extensions differently on the Mac and PC platform.

Limitations

When converting to AU files you must use settings of convertSampleRate = 8000, convertSampleDepth = 0, convertNumChannels = 0. The sound you are converting from must have an 8-bit sample depth. Any other settings will produce corrupted files. This problem lies in the Sun AU Import Export Xtra (version 8.0).

Example:

-- Saves existing sound "Recorded" in sound list to

-- the file "PRACTICE.WAV"

axConvertToFile ( "Recorded", "C:\MYDIR\PRACTICE.WAV", "WAVE")

-- Saves existing sound "BirdSong" in sound list to

-- the file "BIRD.AU" in the sounds directory.

axConvertToFile ( "BirdSong", "BIRD.AU", "AU")

axConvertToMember(soundNameString, newMemberNameString, newMemberReference) where soundNameString is the name of a sound present in the sound list, newMemberNameString is the name to use for the new cast member and newMemberReference is the member to put new sound into. The environment properties convertSampleRate, convertSampleDepth and convertNumChannels determine the properties of the converted file, and should be set using axSetEnvironmentInfo before this command is executed. Returns an error number or 0 for no error. Saves an existing sound in the sound list to an internal Director cast member. Does not add the sound to the sound list. Use axLoadSound or axLoadSoundIntoRAM to put the new sound onto the sound list. The format of the saved sound is Director's native internal sound format.

Example:

err = axConvertToMember("BirdSong","NewSong", axGetEmptyMember())

axConvertToSFData(soundNameString, filePathString, formatString) where soundNameString is the name of a sound present in the sound list, filePathString is the temporary file name created during the conversion and formatString is one of the supported file formats for export (see axConvertToFile for limitations.) Returns a property list compatible with ShockFiler's support for sending vList binary data files. The environment properties convertSampleRate, convertSampleDepth and convertNumChannels determine the properties of the converted file, and should be set using axSetEnvironmentInfo before this command is executed. This function was introduced in Audio Xtra 6, and provides an easier way for reducing the sample rate and size and preparing sound files to be uploaded with ShockFiler.

Example:

axSetEnvironmentInfo("useTempDirectory", 1)

axSetEnvironmentInfo("convertSampleRate", 11025)

axSetEnvironmentInfo("convertSampleDepth", 8)

axSetEnvironmentInfo("convertNumChannels", 1)

dataToSend = axConvertToSFData("recordedSound","tempfile.wav","WAVE")

remoteFileName = "recordedsound.wav"

remoteFileType = #bina

remotefileProperties = []

doappend = 0

showDialog = 1

dialogTitle = "Sending sound file ..."

error = sf_Send ("host", "directory", "usersname", "password" ,dataToSend, ", remoteFileName, remoteFileType, remotefileProperties, doappend, showDialog,dialogTitle)

axBytesToMilliseconds(numBytesInteger)

axBytesToMilliseconds(numBytesInteger, samplerateInteger, sampledepthInteger, numchannelsInteger) where numBytesInteger is the number of bytes and cannot exceed Lingo's the maxinteger, samplerateInteger is the sample rate to calculate, sampledepthIntegeris the sample depth to calculate and numchannelsInteger is the number of channels to calculate. Returns a positive number of milliseconds or a negative error number.Will not return a value higher than Lingo's the maxinteger. Converts a number of bytes to a sound duration in milliseconds.

If only one parameter is passed, Uses the current values set for recordSampleRate, recordSampleDepth and recordNumChannels as returned from axGetEnvironmentInfo to determine the disk space. If samplerate, depth and channels are passed, the calculation is done using those values and the recorder does not have to be open.

Example:

freeRecordingK = axGetFreeSpace("Macintosh HD")

recordingSeconds = axBytesToMilliseconds(freeRecordingK * 1024) / 1000

axMillisecondsToBytes(numMillsecsInteger)

axMillisecondsToBytes(numMillsecsInteger, samplerateInteger, sampledepthInteger, numchannelsInteger) where numMillsecsInteger is the number of milliseconds and cannot exceed Lingo's the maxinteger, samplerateInteger is the sample rate to calculate, sampledepthInteger is the sample depth to calculate and numchannelsInteger is the number of channels to calculate. Returns a positive number of bytes or a negative error number. Will not return a value higher than Lingo's the maxinteger. Converts a number of milliseconds of sound duration to an amount of disk space in bytes.

If only one parameter is passed, Uses the current values set for recordSampleRate, recordSampleDepth and recordNumChannels as returned from axGetEnvironmentInfo to determine the disk space. If samplerate, depth and channels are passed, the calculation is done using those values and the recorder does not have to be open.

Example:

diskSpace = axMillisecondsToBytes (9098777, 22050, 8, 2)

axSetForegroundColor(redInteger, greenInteger, blueInteger) where redInteger is the value for RGB red between 0 and 255, greenInteger is the value for RGB green between 0 and 255 and blueInteger is the value for RGB blue between 0 and 255. Returns an error number or 0 for no error. Sets the foreground color for the plotted waveform graphic. The default is white.

Example:

axSetForegroundColor(0,255,0)

axSetBackgroundColor(redInteger, greenInteger, blueInteger) where redInteger is the value for RGB red between 0 and 255, greenInteger is the value for RGB green between 0 and 255 and blueInteger is the value for RGB blue between 0 and 255. Returns an error number or 0 for no error. Sets the background color for the plotted waveform graphic. The default is black.

Example:

axSetBackgroundColor(125,0,255)

axPlotWaveform(soundNameString, displayMemberRef, widthInteger, heightInteger, resolutionSymbol, channelToPlotInteger) where soundNameString is the name of a sound present in the sound list; displayMemberRef is the member slot to create plot image and this can be an existing graphic member or an empty member; widthInteger is the width in pixels of plot image, timeBase param will override this; heightInteger is the height in pixels of plot image; resolutionSymbol is #low: 10-20 dots per X, #medium 30-50 dots per X, #high - 80-100 dots, #maximum - all dots; and channelToPlot is the number of the channel to plot. Returns an error number or 0 for no error.

Creates a plot graphic of the selected sound in the sound list and puts it into a bitmap cast member. The cast member specified can either be an existing bitmap cast member or an empty member slot. Audio Xtra cannot plot compressed sounds. Allocates memory the size of the environment variable plot buffer to perform the plot, and releases the memory after the plot. An out of memory error returned from this call means that a plot buffer of the specified size could not be allocated.

Note: very small sound files plotted over large-width plots may be not plottable at lower resolutions and will return an error. Try plotting at a higher resolution. This is a math limitation. Audio Xtra cannot create a plot image where there are more pixels horizontally than sound samples to plot.

Example:

axPlotWaveForm("BirdSong",member "plotImage",300,50,#medium,1)

-- Creates a plot bitmap in cast member "plotImage"

-- that is 300 pixels wide and 50 pixels high, at medium resolution.

axAskPermission(actionString, actionString ...) where actionString is the variable number of actions that user should be prompted for permission for. Returns 1 if the user granted permission, 0 if not, or a negative error number. Obtains permission from the user to perform a potentially unsafe action when the movie is running in Shockwave. You can pass one argument or multiple arguments to let the user grant multiple permissions at once. The following table shows the list of possible action strings and the corresponding Audio commands they ask permission for.

The dialog put up by this command obtains permission for the requested function(s) for the duration of the session. See the Shockwave security section for an overview of working with Audio Xtra in that environment. To use this command in authoring for testing, you must set the environment property "simulateShockwave" to TRUE using axSetEnvironmentInfo.

Example:

userResponse = axAskPermission("deleteFiles","recordFiles")

axPromptForSoundsDirectory() - Returns 1 if the user selected a directory, 0 if the user cancelled the dialog, or a negative error number. Displays a folder selection dialog to allow the user to pick a sounds directory. If the user chooses a directory the environment property "soundsDirectory" will contain the path to the directory and "soundsDirectoryIsSet" will be TRUE. Use axGetEnvironmentInfo to query these properties.

Once a sounds directory is set, you need only specify a file name as the argument for any command that usually requires a sound path. Audio Xtra will look for the sound in the specified sound directory. In authoring, use of a sounds directory is optional. In Shockwave, you must prompt the user for a soundsDirectory before working with any sound on disk.

In authoring or projectors you can set the "soundsDirectory" environment property directly with axSetEnvironmentInfo. In Shockwave you must prompt the user to set the property, and once the directory is set you can not read the path with axGetEnvironmentInfo, although Audio Xtra can use it to read and write files. See the Shockwave security section for an overview of working with Audio Xtra in that environment.

Example:

userResponse = axPromptForSoundsDirectory()

axCompressToOggFile(soundNameString, filePathString, soundQuality) where soundNameString is the name of a sound present in the sound list, filePathString is the file name to save the new file and soundQuality is a number from 1 to 10 that specifies the compression quality target used by the Ogg Vorbis encoder. Returns an error number or 0 for no error. The last parameters is optional, and if it is not included the encoder will use quality level 4, which equates roughly to 128Mb/s VBR compression. This funcion saves an existing sound in the sound list to a compressed file on the hard drive. The compressed sounds has the same sample rate and number of channels as the original sound, and 16 bit as the sample size. Does not add the sound to the sound list. Use axLoadOggSoundIntoRAM to add the new sound to the sound list. This function was introduced in AudioXtra 6.1.

Limitations

The Vorbis encoder needs to create temporary files in the soundsDirectory, so make sure you set it using either axSetEnvironmentInfo or axPromptForSoundsDirectory before attempting the compression.

Example:

-- Compresses existing sound "Recorded" in sound list to

-- the file "PRACTICE.OGG" using default settings

axPromptForSoundsDirectory()

axCompressToOggFile ( "Recorded", "PRACTICE.OGG")

-- Forces conversion to maximum compression

axCompressToOggFile ( "Recorded", "PRACTICE.OGG", 1)

-- Forces conversion to maximum quality

axCompressToOggFile ( "Recorded", "PRACTICE.OGG", 10)

axCompressToOggData(soundNameString, soundQuality) where soundNameString is the name of a sound present in the sound list and soundQuality is a number from 1 to 10 that specifies the compression quality target used by the Ogg Vorbis encoder. Returns a property list compatible with ShockFiler's support for sending vList binary data files. The last parameter is optional, and if it is not included the encoder will produce use quality level 4, which equates roughly to 128Mb/s VBR compression. The compressed sounds will have the same sample rate and number of channels as the original sound. This function was introduced in Audio Xtra 6.1, and provides an optimal way for greatly reducing the size and preparing sound files to be uploaded with ShockFiler.

Limitations

The Vorbis encoder needs to create temporary files in the soundsDirectory, so make sure you set it using either axSetEnvironmentInfo or axPromptForSoundsDirectory before attempting the compression.

Example:

axSetEnvironmentInfo("useTempDirectory", 1)

-- Forces conversion to maximum compression

dataToSend = axCompressToOggData ("Recorded", 1)

remoteFileName = "recordedsound.wav"

remoteFileType = #bina

remotefileProperties = []

doappend = 0

showDialog = 1

dialogTitle = "Sending sound file ..."

error = sf_Send ("host", "directory", "usersname", "password" ,dataToSend, ", remoteFileName, remoteFileType, remotefileProperties, doappend, showDialog,dialogTitle)

axCompressToOggByteArray(soundNameString, soundQuality) where soundNameString is the name of a sound present in the sound list and soundQuality is a number from 1 to 10 that specifies the compression quality target used by the Ogg Vorbis encoder. Returns a ByteArray object containing the binary data for the compressed file, which can be used with postNetByteArray to upload the recording to an online server. The last parameter is optional, and if it is not included the encoder will produce use quality level 4, which equates roughly to 128Mb/s VBR compression. The compressed sounds will have the same sample rate and number of channels as the original sound. This function was introduced in Audio Xtra 6.2, and requires Director 11.5, as ByteArray objects are not available in previous versions of Director. Users of Director 11 or earlier can use axCompressToOggBase64.

Limitations

The Vorbis encoder needs to create temporary files in the soundsDirectory, so make sure you set it using either axSetEnvironmentInfo or axPromptForSoundsDirectory before attempting the compression.

Example:

axSetEnvironmentInfo("useTempDirectory", 1)

dataToSend = axCompressToOggByteArray ("Recorded", 1)

put dataToSend

-- <ByteArrayObject length = 47655 ByteArray = 0x4f, 0x67, 0x67, 0x53, 0x0,

0x2, 0x0, 0x0, 0x0, 0x0>

axCompressToOggBase64(soundNameString, soundQuality) where soundNameString is the name of a sound present in the sound list and soundQuality is a number from 1 to 10 that specifies the compression quality target used by the Ogg Vorbis encoder. Returns a property list containing two properties: #data contains the compressed file encoded as a Bsae64 string, and #length indicates the size of the string. The data portion can be used with postNetText to upload content to an online server, and the property list is formatted in a way that is compatible with both vList and ShockFiler as well. The last parameter is optional, and if it is not included the encoder will produce use quality level 4, which equates roughly to 128Mb/s VBR compression. The compressed sounds will have the same sample rate and number of channels as the original sound. This function was introduced in Audio Xtra 6.2.

Limitations

The Vorbis encoder needs to create temporary files in the soundsDirectory, so make sure you set it using either axSetEnvironmentInfo or axPromptForSoundsDirectory before attempting the compression.

Example:

axSetEnvironmentInfo("useTempDirectory", 1)

dataToSend = axCompressToOggBase64 ("Recorded", 1)

pNetID = postNetText("http://myserver.com/page.cgi" , \

[ "Filename": "myfile.ogg", "Base64Data": dataToSend.data])"

axLoadOggSoundIntoRAM(soundNameString, fileNameString) where soundNameString is the name for the sound in the sound list and fileNameString is the file name for the external compressed Ogg Vorbis sound file to be loaded. Returns an error number or 0 for no error.

This function converts an external Ogg Vorbis file into WAVE format, and puts it into Audio Xtra's sound list so that it can work with the file, which is automatically loaded into memory. A sound loaded in to RAM will play back smoothly.

This function was introduced in AudioXtra 6.1.

Limitations

The Vorbis decoder needs to create temporary files in the soundsDirectory, so make sure you set it using either axSetEnvironmentInfo or axPromptForSoundsDirectory before attempting to load a file.

Example:

axPromptForSoundsDirectory()

-- loads BIRD.OGG from the sounds directory

axLoadOggSoundIntoRAM("Bird Song","BIRD.OGG")

axLoadOggByteArrayIntoRAM(soundNameString, ByteArrayObject) where soundNameString is the name for the sound in the sound list and byteArrayObject is a Director 11.5 ByteArray object containing the binary Ogg data to be loaded. Returns an error number or 0 for no error.

This function converts Ogg Vorbis data stored in a ByteArray into WAVE format, and puts it into Audio Xtra's sound list so that it can work with the file, which is automatically loaded into memory. A sound loaded in to RAM will play back smoothly.

This function was introduced in AudioXtra 6.2, and requires Director 11.5, as ByteArray objects are not available in previous versions of Director. It can be used with axCompressOggToByteArray to transfer compressed sounds to and from an online server using postNetByteArray and getNetByteArray operations.

Limitations

The Vorbis decoder needs to create temporary files in the soundsDirectory, so make sure you set it using either axSetEnvironmentInfo or axPromptForSoundsDirectory before attempting to load a file.

Example:

axPromptForSoundsDirectory()

axLoadOggByteArrayIntoRAM("Bird Song", myByteArray)

axLoadOggBase64DataIntoRAM(soundNameString, base64string) where soundNameString is the name for the sound in the sound list and base64string is a Lingo string containing an Ogg Vorbis sound file with Base64 encoding. Returns an error number or 0 for no error.

This function converts Ogg Vorbis data encoded as a Base64 string into WAVE format, and puts it into Audio Xtra's sound list so that it can work with the file, which is automatically loaded into memory. A sound loaded in to RAM will play back smoothly.

This function was introduced in AudioXtra 6.2, and can be used with axCompressOggToBase64 to transfer compressed sounds to and from an online server using postNetText and getNetText operations.

Limitations

The Vorbis decoder needs to create temporary files in the soundsDirectory, so make sure you set it using either axSetEnvironmentInfo or axPromptForSoundsDirectory before attempting to load a file.

Example:

axPromptForSoundsDirectory()

axLoadOggBase64DataIntoRAM("Bird Song", myBase64string)