User Guide

Version 2.0

Platform version details:
AmplitudePro Xtra for Windows = V2.0
AmplitudePro Xtra for MacOS 8/9 = V2.0
AmplitudePro Xtra for MacOS X = V2.0

Contents

Overview
What's New
Installation
How it works
Supported sound formats
Required Xtras
Method Reference 
  General Methods
    new()
    ampProRegister()
    ampGetError()
    ampSetLoopPoints()
  Spectrum Methods
    ampSetSpectSound()
    ampGetSpectCurve()
    ampGetSpectMonoCurve()
    ampSetSpectCurve()
    ampSetSpectBands()
  Amplitude Methods
    ampSetSound()
    ampGetCurve()
    ampGetMonoCurve()
    ampSetCurve()
Property Reference
  General Properties
    normalize
    resolution
    scale
    ampIndex
  Spectrum Properties
    spectValue
    spectValueLeft, spectValueRight
    spectNumBands
    spectRangeLow
    spectRangeHigh
    spectLogBands
    spectBands
    spectScaleAllBands
  Amplitude Properties
    ampValue
    ampValueLeft, ampValueRight
    use_dB
    smoothed
    smoothValue
Example Lingo
Order of operations
JavaScript
Shockwave streaming audio
AmplitudePro Generator
Flash
Distribution in Projectors and Shockwave
Hints, Tips and Workarounds
Support

 

License Agreement - please be sure to read this. Use of the AmplitudePro Xtra means you automatically accept all the terms and conditions in the License Agreement.

Overview

The AmplitudePro xtra allows Macromedia Director™ movies to receive amplitude and spectrum values for sound cast members in real time as a sound is playing. Amplitude values represent the relative "loudness" of the sound at any given time and can be used to synchronize sound and vision in a variety of useful ways, including animating sprites, implementing basic lip-sync in animated characters or plotting waveforms and VU meters. Spectrum values represent the relative power of specific frequency bands that can be set by the xtra. These values can be used to create graphic eq displays, sound visualizations and other animations based on the frequencies of sounds that are playing.

The AmplitudePro Xtra,

The unregistered version of the AmplitudePro Xtra works without restriction during authoring* but will not work in either a Projector or a Shockwave movie. The registered version can be distributed in products made by a registered user without volume limitations or additional royalties. See the License document for complete details.

*with the exception of the ampGetCurve() and ampGetSpectCurve()methods.

[Contents]


What's New

Version 2.0 is a major release of the AmplitudePro Xtra and provides full compatibility with Director 11 and Shockwave 11, it also includes -

Bug fixes include:

This version of the AmplitudePro Xtra also marks the end of the Macintosh Classic (OS8-9) xtra. A MacOS X Carbon-only version of the xtra is included in the v2.0 package for backwards compatibility with Director/Shockwave 10 and earlier.


Installation

The AmplitudePro Xtra package is available from http://www.marmalademedia.com.au/download/index.html in Windows and Macintosh versions. The packages contain the following files,

AmplitudePro.xtra -- the MacOS X Universal Binary xtra (not present in the Windows package)
AmplitudePro.x32 -- the Windows xtra (this xtra can be used in any version of Director from 8-11 on Windows and to create Windows Projectors on Macintosh)
Amplitude Generator.dir -- an AmplitudePro Generator utility movie for use Director pre v11
Amplitude Generator_D11.dir -- an AmplitudePro Generator utility movie for use with Director 11
Carbon/AmplitudePro.sit -- the Carbon-only Macintosh xtra for use when authoring in Director pre v11 on a Macintosh (not present in the Windows package and archived as a Stuffit .sit file in the Macintosh package to avoid conflicts).
Mac Xtra for Win D11/AmplitudePro.cpio -- a data fork archive of the Mac UB xtra (for publishing OSX Projectors on Windows D11)
Mac Xtra for Win pre-D11/AmplitudePro.data -- data part of the OSX Amplitude Xtra (for publishing OSX Projectors on Windows pre-D11)
Mac Xtra for Win pre-D11/AmplitudePro.rsrc --
resource part of the OSX Amplitude Xtra (for publishing OSX Projectors on Windows pre-D11)
Shockwave Packaged Xtras/amplitudepropack.xpku
-- the Macintosh OSX UB Shockwave packaged xtra
Shockwave Packaged Xtras/amplitudepropack.carb -- the Macintosh OSX Carbon Shockwave packaged xtra
Shockwave Packaged Xtras/amplitudepropack.w32 -- the Windows Shockwave packaged xtra
Temp.aif -- a placeholder sound file for the Amplitude Generator utility
User Guide V2.0/Amplitude User Guide.html -- this document
User Guide V2.0/Amplitude License Agreement.html -- the License Agreement in HTML format

To make the xtra available in Director copy the entire "AmplitudePro" folder into the Xtras folder of your Director installation. If you are an existing user of the xtra then be sure to replace the whole "AmplitudePro" folder and not just the xtra(s), you will then get this updated User Guide and the new version of the AmplitudePro Generator utility. Start Director and you're ready to use the xtra.

NOTE 1: A single AmplitudePro Xtra license covers all AmplitudePro xtras on both platforms - your registration code will work on both Mac and Windows. We recommend downloading and using the appropriate package for the platform that you're authoring on.

NOTE 2: If you are authoring with Director MX2004 or earlier on Macintosh OSX then delete the AmplitudePro.xtra file (it will not load in any version of Director pre-11) and un-stuff the Carbon/AmplitudePro.sit file.

[Contents]

How it works

Before a sound cast member starts playing the AmplitudePro Xtra needs to scan the sample values in the sound to generate a list of amplitude or spectrum values. The xtra generates a single amplitude value, or a list of spectrum values, for a specified "slice" of sound samples (controlled by the resolution property) and stores the resulting list of values in RAM. As the sound plays, the xtra returns the current amplitude value or spectrum list to Director via an xtra Lingo property where it can be easily used. For large sounds the list generated by the xtra can be saved in a script and sent to the xtra at runtime to avoid any processing delay.

Note that a single instance of the xtra returns either amplitude or spectrum values generated from a sound cast member, but not both at the same time.

[Contents]

Supported sound formats

The AmplitudePro Xtra supports the following formats for both internal and external (linked) sound cast members,

Note: the use of .SWA or .MP3 Inserted Media (that is, imported using the Insert/Media Element/Shockwave Audio menu which is the standard method of enabling streaming Shockwave audio) requires the technique outlined in the Shockwave section.

 

Required Xtras

In order for the AmplitudePro Xtra to function correctly in either a Projector or Shockwave, some additional Macromedia xtras are required as outlined in the following table. Failure to include the required xtras is the most common cause of problems when using the xtra in a Projector or Shockwave. These problems can range from complete failure of the xtra to return amplitude or spectrum values and poor synchronization.

 
Required Xtras
Sound
Format
Authoring Projector Projector
(.DCR)
Browser
(.DCR)
Uncompressed 1 2 2 2
.SWA
1 3 3 3
.MP3
1 4 4 4

1. requires standard Macromedia Director xtras and the AmplitudePro Xtra

2. requires:

AmplitudePro Xtra
Mix Services xtra(+)
Sound Import Export xtra(+)

3. requires:

AmplitudePro Xtra
Mix Services xtra(+)
Sound Import Export xtra(+)
SWA Import Export xtra(+)
SWA Decompression xtra

4. requires:

AmplitudePro Xtra
Mix Services xtra(+)
Sound Import Export xtra(+)
MPEG 3 Import Export xtra(+)

NOTE: xtras marked (+) are not part of the 'slim' Shockwave 10/11 installs and need to be marked 'Download if Needed' in your Director movie if you're delivering a browser-based Shockwave movie. Please note that all of these xtras are part of the full Shockwave 10/11 installs.

In the above table, ".SWA" means Shockwave Audio, "MP3" means MPEG3 Audio, and ".DCR" means a Shockwave compressed Director movie.

[Contents]

Method Reference

General Methods:

new(xtra "AmplitudePro")

Example:
gAmpXtra = new(xtra "AmplitudePro")

returns a new instance of the AmplitudePro xtra. It's good practice when creating a new instance of any xtra to check that this call was successful, for example,

  gAmpXtra = new(xtra "AmplitudePro") 
  if not objectP(gAmpXtra) then -- error check
    alert gAmpXtra.ampGetError() 
    return 
  end if

ampProRegister(<user name>, <registration code>)

<user name>: a string, the name of the registered user.
<registration code>: a string, the registration code

Example:
   
   ampError = ampProRegister("Joe Bloggs", "XXXX-XXXX-XXXX-XXXX")    
   if ampError <> 0 then
     alert "Failed to register AmplitudePro Xtra!"
     return 
   end if 

This is a global method (no xtra instance reference is required) that registers the AmplitudePro Xtra and allows it to be used in a Projector and Shockwave. This method should be called before the xtra is instantiated with new(xtra "AmplitudePro"). It only needs to be called once, regardless of the number of xtra instances used in the movie. The user name and registration code should be entered exactly as they appear in the email that you will receive when you purchase the xtra. This method returns an error code if there is a problem with the information entered.


ampGetError(<xtra instance>)

<xtra instance>: obtained from new(xtra "AmplitudePro")

Example:
alert ampGetError(gAmpXtra)
or,
alert gAmpXtra.ampGetError()

This method returns the last error encountered by the specified instance of the AmplitudePro xtra. The error value is in the form of a string that is suitable for use in an alert. Use ampGetError() if an xtra method returns an error.


ampSetLoopPoints(<xtra instance>, <start time>, <end time>)

<xtra instance>: obtained from new(xtra "AmplitudePro")
<start time>: the start time of the loop region in whole milliseconds
<end time>: the end time of the loop region in whole milliseconds

Example:
ampError = ampSetLoopPoints(gAmpXtra, <start time>, <end time>)
or,
ampError = gAmpXtra.ampSetLoopPoints(<start time>, <end time>)

This is a Windows-only method. It's required on Windows due to the difficulty in obtaining the start and end times for loop points that are not located at the absolute beginning and end of an internal sound cast member. This can occur if a loop region is set in an AIFF file and the file is then imported into Director. Director will respect the loop region when the sound is played but the AmplitudePro xtra needs to be told the start and end points of the region. If the loop points are at the absolute start and end of the sound then call this method with both parameters = 0. For example,

ampSetLoopPoints(gAmpXtra, 0, 0)

and the AmplitudePro xtra will loop at the end of the sound. Most sound editors that support AIFF files will allow you to determine the start and end times for a loop region. This method should be used prior to calling ampSetSound(). This method returns an error code if there is a problem.

You do not need to use this method if the sound you are playing is not looping.

This method is ignored on a Macintosh.

 

Spectrum Methods:

ampSetSpectSound(<xtra instance>, <sound channel number>, <sound member ref>)

<xtra instance>: obtained from new(xtra "AmplitudePro")
<sound channel number>: the number of the Director sound channel that will be used to play the sound
<sound member ref>: the member reference of the sound to be targeted by the AmplitudePro xtra. This is usually in a form like
member("theSound")

Example:
ampError = ampSetSpectSound(gAmpXtra, 1, member("mySound"))
or,
ampError = gAmpXtra.ampSetSpectSound(1, member("mySound"))

Use this method if you want to receive spectrum data from the xtra. This method tells the AmplitudePro xtra to perform a spectral analysis (FFT) of the sound data from the specified sound cast member in accordance with the current xtra property settings and to watch sound channel 1. The xtra will assume that the next sound played in that channel is the one specified in the second parameter. The method returns an error code if any xtra-specific error occurs. It is good practice to check the result with some Lingo such as,

  ampError = gAmpXtra.ampSetSpectSound(1, member ("mySound"))
  if ampError <> 0 then
    alert gAmpXtra.ampGetError()
    return
  end if

The ampGetError() method is explained below.


ampGetSpectCurve(<xtra instance>)

<xtra instance>: obtained from new(xtra "AmplitudePro")

Example:
ampList = ampGetSpectCurve(gAmpXtra)
or,
ampList = gAmpXtra.ampGetSpectCurve()

For use with spectrum data.

This method returns the entire linear list of lists of spectrum power values for the sound currently targeted by an instance of the AmplitudePro xtra (determined by ampSetSpectSound()) using the current xtra property settings. This list can be used to conserve RAM at runtime and for streaming audio in combination with ampSetSpectCurve(). The list will be in the form:

[[b1,b2,b3,..], [b1,b2,b3,..], [b1,b2,b3,..]...]

where b1 is the value for the band 1 and b2 is the value for band 2 and so on up to the number of bands specified with the spectNumBands xtra property. Each sub-list represents a slice of time within the sound specified with the resolution xtra property.

If the sound is stereo the each sub-list will be split into two sub-lists, one for the left channel and one for the right channel:

[[[lb1,lb2,lb3,..], [rb1,rb2,rb3,..]], [[lb1,lb2,lb3,..], [rb1,rb2,rb3,..]],...]

If an error occurs then the returned value will be an error code instead of a list.

Using the ampIndex property it is possible to obtain the current index into this list while the sound is playing.

This method returns a maximum of 20 values if the xtra is not registered.

NOTE: depending on the xtra's property settings this list can be large - especially if the sound is stereo.


ampGetSpectMonoCurve(<xtra instance>)

<xtra instance>: obtained from new(xtra "AmplitudePro")

Example:
ampList = ampGetSpectMonoCurve(gAmpXtra)
or,
ampList = gAmpXtra.ampGetSpectMonoCurve()

For use with spectrum data.

This method returns the entire linear list of lists of spectrum power values for the sound currently targeted by an instance of the AmplitudePro xtra (determined by ampSetSpectSound()) using the current xtra property settings. This function is identical to ampGetSpectCurve() with the exception that it will always return a mono list regardless of whether the targeted sound is stereo or mono. If the sound is stereo then the values are the summed average of both channels. The list will be in the form:

[[b1,b2,b3,..], [b1,b2,b3,..], [b1,b2,b3,..]...]

where b1 is the value for the band 1 and b2 is the value for band 2 and so on up to the number of bands specified with the spectNumBands xtra property. Each sub-list represents a slice of time within the sound specified with the resolution xtra property.

If an error occurs then the returned value will be an error code instead of a list.

Using the ampIndex property it is possible to obtain the current index into this list while the sound is playing.

This method returns a maximum of 20 values if the xtra is not registered.


ampSetSpectCurve(<xtra instance>, <list>, <sound channel number>, <loopStart>, <loopEnd>)

<xtra instance>: obtained from new(xtra "AmplitudePro")
<list>: a list of spectrum values previously generated with ampGetSpectCurve()
<sound channel number>: the number of the sound channel that will be used to play the sound
<loopStart>: the start point for the loop in milliseconds
<loopEnd>: the end point for the loop in milliseconds. Set this value to 0 if the sound is not looped.

Example:
err = ampSetSpectCurve(gAmpXtra, ampList, 1, 0, 0)
or,
err = gAmpXtra.ampSetSpectCurve(ampList, 1, 0, 0)

For use with spectrum data.

This method sends a linear list of spectrum power values to the AmplitudePro xtra. The list should be generated using ampGetSpectCurve() during authoring. This method has two primary uses;

  1. for very large sounds it avoids excessive RAM usage at runtime because the list of spectrum values occupies much less RAM than is used when the AmplitudePro xtra loads and processes a sound using ampSetSpectSound(). And,
  2. it is also much quicker to complete than ampSetSpectSound() because loading/decompressing the sound and calculating the spectrum values has already been done.
  3. it can also be used for streaming audio (see the Shockwave section).

This method returns an error code if there is a problem.

NOTE: the AmplitudePro xtra will use the current value for the resolution property when it returns the list values to Director (this sets the size of each 'slice' of the sound that the xtra calculates spectrum values for). You need to make sure that this property is set to the same value that was used during ampGetSpectCurve() in order to avoid synchronization problems.


ampSetSpectBands(<xtra instance>, <bandList>)

<xtra instance>: obtained from new(xtra "AmplitudePro")
<bandList>: a linear list of frequencies to define custom band widths

Example:
ampError = ampSetSpectBands(gAmpXtra, myBandList)
or,
ampError = gAmpXtra.ampSetSpectBands(myBandList)

For use with spectrum data.

This method allows you to set the width of each band of frequencies that the xtra will use when calculating spectrum power values. Normally you will not need to use this method as the list is calculated automatically by the xtra depending on the settings of the xtra properties. However if you want to define custom band widths, for example to just get values for low frequencies, then you can use this method to achieve this.

The list must consist of 2-element sub-lists with each sub-list defining the frequency range in Hz of the bands from low to high. For example:

myBandList = [[20, 500], [501,1000], [1001,5000]]

This tells the xtra to return 3 bands corresponding to the frequency range in each sub-list Note that the values in the list must conform to the following rules:

If the list does not meet these rules then an error will be returned. In addition:

A successful call to this method will override any set values in the following xtra properties:

Once a custom band width list has been set then it is not possible to set any of these properties until a sound is played in the channel specified by ampSetSpectSound().

Notes:

  1. If your list contains just one band spanning the entire possible frequency range (20HZ to (sampleRate/2)Hz) then you will get better results using the amplitude methods of the xtra rather than spectrum methods.
  2. There is always a trade-off between time accuracy and frequency accuracy in FFT (spectrum) analysis. When the xtra performs the FFT the power values are calculated for frequency 'bins' with each bin containing a range of frequencies. The bin width represents the frequency accuracy of the FFT operation (also known as the 'frequency resolution') and can be calculated as follows:

    freqRes = sampleRate/1024

    So if you are using a sound sampled at 22050Hz the frequency resolution of the FFT operation will be 21.53Hz. This means that specifying band widths of anything less than this value will return meaningless results.

 

Amplitude Methods:

ampSetSound(<xtra instance>, <sound channel number>, <sound member ref>)

<xtra instance>: obtained from new(xtra "AmplitudePro")
<sound channel number>: the number of the Director sound channel that will be used to play the sound
<sound member ref>: the member reference of the sound to be targeted by the AmplitudePro xtra. This is usually in a form like
member("theSound")

Example:
ampError = ampSetSound(gAmpXtra, 1, member("mySound"))
or,
ampError = gAmpXtra.ampSetSound(1, member("mySound"))

Use this method if you want to receive amplitude data from the xtra. This method tells the AmplitudePro xtra to extract and evaluate the sample values from the specified sound cast member in accordance with the current xtra property settings and to watch sound channel 1. The xtra will assume that the next sound played in that channel is the one specified in the second parameter. The method returns an error code if any xtra-specific error occurs. It is good practice to check the result with some Lingo such as,

  ampError = gAmpXtra.ampSetSound(1, member ("mySound"))
  if ampError <> 0 then
    alert gAmpXtra.ampGetError()
    return
  end if

The ampGetError() method is explained above.


ampGetCurve(<xtra instance>)

<xtra instance>: obtained from new(xtra "AmplitudePro")

Example:
ampList = ampGetCurve(gAmpXtra)
or,
ampList = gAmpXtra.ampGetCurve()

This method returns a linear list of amplitude values for the sound currently targeted by an instance of the AmplitudePro xtra (determined by ampSetSound()) using the current xtra property settings. This list can then be used to draw the waveform of the sound or anything else you might think of. It can also be used to conserve RAM at runtime and for streaming audio in combination with ampSetCurve().

If an error occurs then the returned value will be an error code instead of a list.

If the sound used to generate the list was stereo then the values are interleaved for left/right channels,

[<L>,<R>,<L>,<R>,<L>,<R>...]

Using the ampIndex property it is possible to obtain the current index into this list while the sound is playing.

This method returns a maximum of 20 values if the xtra is not registered.

NOTE: depending on the xtra's property settings this list can be large. If you just need to plot the waveform then you normally only need as many values as the waveform occupies on the screen.


ampGetMonoCurve(<xtra instance>)

<xtra instance>: obtained from new(xtra "AmplitudePro")

Example:
ampList = ampGetMonoCurve(gAmpXtra)
or,
ampList = gAmpXtra.ampGetMonoCurve()

This method returns a linear list of amplitude values for the sound currently targeted by an instance of the AmplitudePro xtra (determined by ampSetSound()) using the current xtra property settings. This method is identical to ampGetCurve() except it will always return a mono list regardless of whether the targeted sound is stereo or mono. If the sound is stereo then the values are the summed average of both channels.

If an error occurs then the returned value will be an error code instead of a list.

Using the ampIndex property it is possible to obtain the current index into this list while the sound is playing.

This method returns a maximum of 20 values if the xtra is not registered.


ampSetCurve(<xtra instance>, <list>, <sound channel number>, <loopStart>, <loopEnd>, <stereo>)

<xtra instance>: obtained from new(xtra "AmplitudePro")
<list>: a list of amplitude values previously generated with ampGetCurve()
<sound channel number>: the number of the sound channel that will be used to play the sound
<loopStart>: the start point for the loop in milliseconds
<loopEnd>: the end point for the loop in milliseconds. Set this value to 0 if the sound is not looped.
<stereo>: a boolean - true if the sound is stereo, false otherwise

Example:
err = ampSetCurve(gAmpXtra, ampList, 1, 0, 0, false)
or,
err = gAmpXtra.ampSetCurve(ampList, 1, 0, 0, false)

This method sends a linear list of amplitude values to the AmplitudePro xtra. The list should be generated using ampGetCurve() during authoring (see also the AmplitudePro Generator utility). This method has two primary uses;
1) for very large sounds it avoids excessive RAM usage at runtime because the list of amplitude values occupies much less RAM than is used when the AmplitudePro xtra loads a sound using
ampSetSound(). And,
2) for streaming audio (see the Shockwave section). It is also much quicker to complete than
ampSetSound() because loading/decompressing the sound and calculating the amplitude values has already been done.

This method returns an error code if there is a problem.

NOTE: the AmplitudePro xtra will use the current value for the resolution property when it returns the list values to Director. You need to make sure that this property is set to the same value that was used during ampGetCurve() in order to avoid errors.


[Contents]

Property Reference

A range of xtra properties are available to control attributes of the xtra and to retrieve values. It is possible to use normal Director dot syntax to manipulate the properties providing a valid instance of the xtra exists. For example,

gAmpXtra.resolution = 15

See the Order of operations section for additional information on using xtra properties.

 

General Properties:

normalize: a boolean (true/false) property. If true then the xtra will normalize the sample data of the sound member specified by ampSetSound() or ampSetSpectSound() before the sound is processed by the xtra. The normalizing process scans the sample data for the largest (ie, loudest) value and boosts the entire signal so the highest value is the maximum possible (100%). This can result in greater variation of the values returned by the xtra. Note: this process does not normalize the sample values in the cast member - it process is only applied to the sample data held by the xtra. Setting this property to true will result in a longer processing time for both ampSetSound() and ampSetSpectSound(). The default for this property is false. You can get and set this property.

resolution: accepts a positive integer in the range 1..32767. This property determines the time period for each 'slice' of sound that the xtra will calculate values for. For example, if set to 15 then the xtra will calculate a value for each 1/15th of a second. This property should always be less than or equal to the current frame rate of the Director movie. The default is 15.

If, when generating amplitude values, you attempt to set this property to a value higher than the sample rate for the sound targeted by ampSetSound() it will be truncated to the sample rate. You can get and set this property.

When generating spectrum data the xtra needs at least 1024 samples per 'slice' in order to perform the FFT analysis. This means that there is a limit to the maximum possible resolution value for the sample rate of the sound being processed for spectrum data. The following table shows the maximum resolution values for common sample rates.

Sample Rate
Maximum Resolution Value
48000Hz
46
44100Hz
43
22050Hz
21
11025Hz
10

If you set the resolution property to a value that is greater that the maximum possible for the sound being processed for spectrum data then the AmplitudePro xtra will return an error. This limitation does not apply to amplitude processing.

scale: accepts a positive integer in the range 1..32767. This property controls the possible range of values returned to Director. A setting of 256 (the default) means that the values returned by the xtra will range from 0 (quietest possible) to 256 (loudest possible). This property is ignored if use_dB is set to true. The scale property has different range limitations for amplitude and spectrum values;

Amplitude: For a 16bit sound the actual possible range of raw sample values is -32768 to 32767. Both of these values are equal to the loudest possible value that can occur without distortion. Absolute silence has a sample value of 0. The AmplitudePro Xtra always returns the absolute (i.e., positive) value for the given 'slice' of sample values as set with the resolution property. For 8 bit sounds the possible range is -128 to 127. The AmplitudePro xtra will set this value to 127 if you attempt to set a scale value greater than 127 for an 8 bit sound. You can get and set this property.

Spectrum: the acceptable range is 1..32767 regardless of the sound's bit depth.

ampIndex: holds the current index into the list generated by the AmplitudePro xtra and returned by ampGetCurve(). You cannot set this property. There are numerous potential uses for this property including moving sprites to indicate the current position in a plotted waveform. You cannot set this property.

 

Spectrum Properties:

spectValue: used to obtain the current list of spectrum band values for the specified xtra instance at run time. If the sound is stereo then this property holds the list of summed mono values. This property should be evaluated from an exitFrame or enterFrame handler as the sound is playing. You cannot set this property.

spectValueLeft, spectValueRight: used to obtain the current spectrum band lists for the left and right channels of a stereo sound at runtime. If the sound is mono then these properties are undefined (use the spectValue property for mono sounds). These properties should be evaluated from an exitFrame or enterFrame handler as the sound is playing. You cannot set these properties.

spectNumBands: used to set the number of frequency bands returned by the xtra. The frequency ranges of each band are determined by the value of this property in combination with the values held in the spectRangeLow and spectRangeHigh properties. By default all bands will have an equal width (in Hz) and will be evenly distributed over the total frequency range set by spectRangeLow and spectRangeHigh, unless spectLogBands is set to true or custom band ranges have been set withampSetSpectBands(). You can get and set this property.

spectRangeLow: used to set the lowest frequency (in Hz) returned by the xtra. This value cannot be less than 20. The default is 20. You can get and set this property.

spectRangeHigh: used to set the highest frequency (in Hz) returned by the xtra. This value cannot be greater than half the sample rate of the sound being used (which is the default). You can get and set this property.

spectLogBands: a boolean (true/false) property. If set to true the frequency ranges returned by the xtra will be distributed logarithmically with the lowest band having the narrowest range and each successive band having a progressively larger range. This is useful for graphic eq displays. If this value is false (the default) then the bands are distributed linearly - each band having the same width. You can get and set this property.

spectBands: holds the list of frequency band ranges used by the xtra when returning values at runtime. Use this property to find the actual band ranges used by the xtra after calling ampSetSpectSound(). This property will return an empty list before a call to ampSetSpectSound(). Note that if you are not using custom band ranges then the band ranges used by the xtra are determined by the values in the spectRangeLow, spectRangeHigh, spectLogBands and spectNumBands properties as well as the sample rate of the sound. You can only get this property. Use the ampSetSpectBands() method to set the band list.

spectScaleAllBands: a boolean (true/false) property. If true then each band of spectrum values will be scaled to the maximum power value found per band. If false (the default) then all bands will scaled to the maximum power value found throughout all bands. Use this property with caution - it is basically forcing the xtra to return inaccurate results by ignoring relative power of each band. However it can be useful for sound visualizations in some cases.

 

Amplitude Properties:

ampValue: used to obtain the current amplitude value for the specified xtra instance at run time. If the sound is stereo then this property holds the summed mono value. This property should be evaluated from an exitFrame or enterFrame handler. You cannot set this property.

ampValueLeft, ampValueRight: used to obtain the current amplitude values for the left and right channels of a stereo sound at runtime. If the sound is mono then these properties are undefined (use the ampValue property for mono sounds). These properties should be evaluated from an exitFrame or enterFrame handler. You cannot set these properties.

use_dB: a boolean, true if you want the AmplitudePro Xtra to return decibel (dB) values for an amplitude list. The default is false. If use_dB is true then an 'inverse positive' dB scale is used where 0 is maximum power and anything above 50 can be regarded as too weak (ie, quiet) to worry about. This is a logarithmic scale that's a better representation of human hearing than the linear raw sample scale. This property is typically used to implement VU meters. Note that this property is not used for spectrum lists which use a dB scale by default. You can get and set this property.

smoothed: [redundant - maintained for backwards compatibility. Use the smoothValue property instead.] a boolean, true if you want the sample values smoothed to avoid rapid fluctuations in the returned amplitude values. If the smoothed property is true then the values returned by the ampValue, ampValueLeft and ampValueRight xtra properties are averaged using a 3-point smoothing algorithm before being sent to Director. This makes the amplitude curve less jagged so animations appear smoother. The default is false. This property is ignored if use_dB is set to true. You can get and set this property.

smoothValue: [new in version 3.0] allows you to set the degree of smoothing to be applied to amplitude values. Valid values range from 3 to 9 with larger values increasing the degree of smoothing that will be applied. A value of 0 turns smoothing off. Smoothing reduces rapid fluctuations in the returned amplitude values. When active, the values returned by the ampValue, ampValueLeft and ampValueRight xtra properties are averaged using an x-point smoothing algorithm (where x equals the smoothing value set) before being sent to Director. This makes the amplitude curve less jagged so animations, waveforms, etc, appear smoother. The default is 0 (off). The old smoothed property used a value of 3 when set to true. This property is ignored if use_dB is set to true. Note that this property only affects amplitude values. You can get and set this property.

[Contents]

Example Lingo

The following Lingo code snippets shows basic usage of the AmplitudePro Xtra.

To receive spectrum data from the xtra:

on initAmplitudePro
  global gAmpXtra
 
  if objectP(gAmpXtra) then -- if the instance exists then remove it
    gAmpXtra = 0
  end if
  gAmpXtra = new(xtra "AmplitudePro") -- create an instance of the xtra
  if not objectP(gAmpXtra) then -- error check
    alert gAmpXtra.ampGetError()
    return
  end if
  -- set some xtra properties...
  gAmpXtra.spectNumBands = 5 -- number of spectrum bands that will be returned
  gAmpXtra.spectRangeLow = 20 -- low range of spectrum 
gAmpXtra.spectRangeHigh = 10000-- high range of spectrum gAmpXtra.resolution = 15 -- calculate spectrum data 15 times per second gAmpXtra.scale = 128 -- scale the spectrum data from 0 to 128 -- tell the xtra to process the sound and target sound channel 1 err = gAmpXtra.ampSetSpectSound(1, member "mySound") if err <> 0 then -- check for errors alert gAmpXtra.ampGetError() return end if sound(1).play(member("mySound")) end --======================= on exitFrame global gAmpXtra -- set the height of some sprites to the current spectrum value... theList = gAmpProXtra.spectValue
repeat with i = 1 to gAmpProXtra.spectNumBands
sprite(i).height = theList[i]
end repeat

go the frame end --=======================

To receive amplitude data from the xtra:

on initAmplitudePro
  global gAmpXtra
 
  if objectP(gAmpXtra) then -- if the instance exists then remove it
    gAmpXtra = 0
  end if
  gAmpXtra = new(xtra "AmplitudePro") -- create an instance of the xtra
  if not objectP(gAmpXtra) then -- error check
    alert gAmpXtra.ampGetError()
    return
  end if
  -- set some xtra properties...

  gAmpXtra.resolution = 15 -- calculate amp data 15 times per second
  gAmpXtra.scale = 128 -- scale the amp data from 0 to 128    

  -- tell the xtra to scan the sound and target sound channel 1
  err = gAmpXtra.ampSetSound(1, member "mySound") 
  if err <> 0 then -- check for errors
    alert gAmpXtra.ampGetError()
    return
  end if

  sound(1).play(member("mySound"))

end

--=======================

on exitFrame
  global gAmpXtra

  -- set the size of a sprite to the current amplitude value...
  sprite(1).width = gAmpXtra.ampValue
sprite(1).height = gAmpXtra.ampValue end --=======================

[Contents]

Order of operations

It's important to realize that setting xtra properties affects the way that the AmplitudePro xtra will analyze the specified sound and subsequently the data that gets produced. As a result, xtra properties should be set before any of the following methods are called:

See the Example Lingo section for an example of the proper ordering of operations. If xtra properties have not been set at the time that one of these methods is called then the default property values will be used. Setting xtra properties after calling any of these methods will have no effect on the current values being returned by the xtra.

Note: the Windows method, ampSetLoopPoints() and ampSetSpectBands() should also be called before ampSetSound() or ampSetSpectSound().

[Contents]

JavaScript

JavaScript syntax was introduced in Director MX2004 as an alternative to Lingo syntax. If you follow a few basic rules then using the AmplitudePro Xtra with JavaScript is easy.

Creating an xtra instance
Use the following JavaScript code to create an instance of the AmplitudePro xtra and store it in a global variable.

  _global.gAmpProXtra = new xtra("AmplitudePro");  

Xtra methods
There is one basic rule when calling xtra methods from JavaScript syntax - you must use dot syntax with the instance of the xtra. For example:

   ampError = gAmpProXtra.ampSetSound(1, member("mySound"));

Xtra properties
If you use dot syntax then getting and setting xtra properties is identical in both Lingo and JavaScript, for example:

  gAmpProXtra.resolution = 20

Lists and arrays
There are several AmplitudePro xtra methods that either return Lingo lists or accept Lingo lists as parameters. JavaScript arrays cannot be used as parameters in xtra methods. There are several Lingo methods that can be used to create and manipulate Lingo lists with JavaScript (see the JavaScript list() function).

Providing that you do not alter the contents of a list generated by the xtra (using ampGetCurve() for example) then the list can be used as a parameter in a xtra methods using JavaScript (via ampSetCurve() for example).

[Contents]

Shockwave streaming audio

If you need to support streaming Shockwave audio then read this section. 'Streaming Shockwave audio' means playback of a cast member created using the Insert > Media Element > Shockwave Audio menu in Director. The sound format can be either .swa or .mp3.

See the Distribution section for information about Shockwave packaged xtras.

To support streaming Shockwave audio with the AmplitudePro xtra you need to use the following technique. Firstly, pre-scan the audio during authoring (using ampGetCurve() to get a list of amplitude values or ampGetSpectCurve() to get a list of spectrum values) and store the resulting list in a Lingo script, then return these values to the xtra at runtime using the appropriate method - ampSetCurve() for amplitude values or ampSetSpectCurve() for spectrum values. The xtra will maintain synchronization with the audio during streaming.

The following is an example of Lingo code for pre-scanning a sound for amplitude values during authoring:

on generateAmpList

  gAmpXtra.smoothed = true 
  gAmpXtra.resolution = 15 
  gAmpXtra.scale = 256 
  err = gAmpXtra.ampSetSound(1, member gCurrentSound) 
  if err <> 0 then
    alert gAmpXtra.ampGetError()
    return
  end if
  theList = gAmpXtra.ampGetCurve() 
  return theList
end

When generateAmpList() is called from the Message window in Director it will return the list of amplitude values from the sound referenced by gCurrentSound to the message window. Note that the sound cast member can be compressed, or uncompressed, linked or internal (but not an SWA member imported using the Insert->Media Element menu in Director). Copy and paste this list into a handler such as,

on getAmpList
   
  theList = [0, 63, 163, 166, 107, 83, 88, 93, 142, ...]
  return theList
end

Then use code like the following before issuing a play sound command at runtime to initiate the streaming audio,

on sendList2Xtra
   
  ampList = getAmpList()
  gAmpXtra.resolution = 15 
  err = gAmpXtra.ampSetCurve(ampList, 1, 0, 0, false) 
  if err <> 0 then
    alert gAmpXtra.ampGetError()
  end if
end

The following is the equivalent code for spectrum values:

on generateSpectList()

   gAmpXtra.spectRangeLow =20 
gAmpXtra.spectRangeHigh =10000
gAmpXtra.spectNumBands = 8 gAmpXtra.resolution = 15 gAmpXtra.scale = 256 err = gAmpXtra.ampSetSpectSound(1, member gCurrentSound) if err <> 0 then alert gAmpXtra.ampGetError() return end if theList = gAmpXtra.ampGetSpectCurve() return theList end on sendList2Xtra spectList = getAmpList() gAmpXtra.resolution = 15 err = gAmpXtra.ampSetSpectCurve(spectList, 1, 0, 0) if err <> 0 then alert gAmpXtra.ampGetError() end if end

Note that the getAmpList handler is the same for both amplitude and spectrum values.

It is obviously good practice to choose an appropriate bit rate setting for your target audience when you compress the audio in order to avoid gaps in the stream.

A utility Director movie called AmplitudePro Generator has been produced to facilitate the process of pre-scanning sounds. See the AmplitudePro Generator section for more details.

If you deliver a product that uses Shockwave compression, whether it is in a browser or a projector, then follow the guidelines for including xtras in the Required Xtras section.

[Contents]

AmplitudePro Generator 2

The AmplitudePro Generator 2 is a utility designed to simplify the process of pre-scanning sound files during authoring. It will output a list of spectrum or amplitude values for a specified sound file to the Message window in Director or, optionally, to a new script member that will contain scripts customized for the targeted sound. As a result, the process of creating these scripts is made much easier.

The AmplitudePro Generator 2 utility will work with Director 8.5, MX and MX2004. A separate version is included for use with Director 11 (AmplitudePro Generator_D11.dir).

Providing you have installed the Xtra in accordance with the instructions in the Installation section then this utility will be available from the Xtras/AmplitudePro/ menu in Director. The AmplitudePro Generator will open as a MIAW within Director.

The generated list will contain a maximum of 20 values if the AmplitudePro Xtra is unregistered. You can enter your username and serial number in the Registration screen accessed via the Register button. Your registration details will be saved to a non-encrypted text file in the AmplitudePro folder to enable the xtra to be registered when you run the Generator utility.

The Generator utility has two main screens; one for spectrum settings and one for amplitude settings.

The following image shows the spectrum settings screen,

To use the AmplitudePro Generator first select a sound file to process by clicking the Choose button. You can select a sound file that uses any of the supported sound formats. Next set the xtra functions and properties that you require. You can enter a list of custom band ranges by selecting the Custom band ranges - Set... button. See the ampSetSpectBands() function for information on the list format. Once this list has been set then the Custom band ranges checkbox will be selected and the entry fields for Low, High frequency limits, Number of bands, and the Logarithmic band widths checkbox, will be disabled as these xtra properties are not applicable when custom band ranges are being used.

The following image shows the amplitude settings screen,

If the dB scaling checkbox is selected then the Scale entry field and Smoothing dropdown will be disabled as these xtra properties are not applicable when a dB scale is being used.

Choose either the Message window or a New Movie Script as the destination for the generated list. If you choose New Movie Script then a new movie script cast member will be created with the name "Spectrum list script" or "Amplitude list script" in the main cast. It will contain the generated list and a handler that will send the list to the AmplitudePro Xtra with a single line of Lingo. Click the Generate button to process the selected sound. Any invalid settings or entries will result in an alert before the sound is processed. You can then scan additional sound files or close the AmplitudePro Generator window using the Close button or the window's close widget.

[Contents]

Flash

Spectrum and amplitude values generated by the AmplitudePro xtra can also be easily and efficiently used with Adobe Flash. Marmalade Multimedia produces a utility called FlashAmp that creates Flash compatible arrays without the need to use the AmplitudePro xtra with Director. FlashAmp outputs the arrays to a text file in two different formats; as an ActionScript #include file that can be used easily during authoring and a format suitable for use with a loadVariables() ActionScript call allowing sounds to be loaded dynamically at runtime. FlashAmp also has the ability to output an parallel array of cue point names - something that is not possible with the AmplitudePro Xtra. Please see http://www.marmalademedia.com.au/flashamp/ for details.

[Contents]

Distribution in Projectors and Shockwave

For distribution with Director Projectors the AmplitudePro Xtra should be included in the usual way - either packaged into the Projector or included in a folder named "Xtras" located in the same folder as the Projector. The latter option is preferred and results in the best compatibility across operating systems and a faster launch for your Projector. If the AmplitudePro Xtra fails to work in a Projector then check that you have included all the required xtras. Missing xtras is by far the most common cause of problems when using the xtra in a Projector or Shockwave.

The ability to publish cross-platform projectors has been available since Director MX2004 (10) and the details of the process are different depending on the target platform and the version of Director being used. In order to successfully publish a cross-platform projector, the AmplitudePro xtra needs to be installed in the locations shown in the following table and Director's xtrainfo.txt file needs to be modified as shown below.

Cross-platform file locations
Director 11
To publish a Macintosh Universal Binary Projector when authoring on Windows From the AmplitudePro folder, copy the Mac Xtra for Win D11/AmplitudePro.cpio file to -
<your Director folder>\Configuration\Cross Platform Resources\Macintosh\Xtras\
To publish a Windows Projector when authoring on Macintosh From the AmplitudePro folder, copy the AmplitudePro.x32 file to -
<your Director folder>/Configuration/Cross Platform Resources/Windows/Xtras/
Director MX 2004 (10.x)
To publish a Macintosh Carbon Projector when authoring on Windows From the AmplitudePro folder, copy the Mac Xtra for Win pre-D11/AmplitudePro.data and the Mac Xtra for Win pre-D11/AmplitudePro.rsrc files to -
<your Director folder>\Configuration\Cross Platform Resources\Macintosh\Xtras\
To publish a Windows Projector when authoring on Macintosh From the AmplitudePro folder, copy the AmplitudePro.x32 file to -
<your Director folder>/Configuration/Cross Platform Resources/Windows/Xtras/

IMPORTANT: Then add the following line to the xtrainfo.txt file (located inside the Director/Configuration/ folder).

[#namePPC:"AmplitudePro", #nameW32:"AmplitudePro.x32", #package:"http://www.mydomain.com/somepath/amplitudepropack", #info:"http://www.marmalademedia.com.au/amplitudepro"]

This should be on one line (no breaks). This data is valid for Director 11 and earlier on both platforms. The #package parameter is only referenced by Director if you mark the xtra as Download If Needed (typically if you're publishing to Shockwave, see below). The #namePPC parameter is used by Director to get the name of both the UB and Carbon Macintosh xtras.

Shockwave Publishing

To enable auto-downloading of the AmplitudePro Xtra for Shockwave products you will need to do the following steps in the order specified,

  1. upload the packaged xtra files to a server
  2. modify the xtrainfo.txt file in the Director/Configuration/ folder
  3. check the Download if Needed option for the AmplitudePro xtra and any other required xtras in your Director movie using the Modify/Movie/Xtras menu in Director

Three packaged files are included with the AmplitudePro Xtra,

amplitudepropack.w32
amplitudepropack.xpku
amplitudepropack.carb

All packages should be stored in the same directory on a server accessible from the Internet. When your Shockwave movie is accessed, the browser will attempt download the appropriate packaged files from the location you have specified in the xtrainfo.txt file. All packages should be located in the same directory on the server, do not rename any of the packages and be sure to upload them as binary files.

Do the following to modify the xtrainfo.txt file,

[#namePPC:"AmplitudePro", #nameW32:"AmplitudePro.x32", #package:"http://www.mydomain.com/somepath/amplitudepropack", #info:"http://www.marmalademedia.com.au/amplitudepro"]

This must be on a single line without line breaks. The #package parameter should specify the URL for the packaged xtras, do not include an extension following "amplitudepropack". You cannot link to packaged xtras at http://www.marmalademedia.com.au/.

Once you have edited the xtrainfo.txt file then perform the following steps:

Shockwave publishing has become more complex since the release of Shockwave 11. A new parameter, playerVersion, has been added to the html object/embed tags created by Director 11 to indicate the required player version. See the Director 11 whitepaper for details, you should be aware of the associated issues even if you're publishing to Shockwave 10 under Director MX2004,

http://www.adobe.com/support/director/ts/documents/kb403195/Director11_Whitepaper.pdf

[Contents]

Hints, Tips and Workarounds

The Best Sounds to Use...
This is one of the most common questions about using the AmplitudePro Xtra. Here are a few basic things that will help you get the best possible results,

Each of these points says the same thing in a different way; 16 bit sound can hold a wider range of amplitude values (in other words, a larger dynamic range - the difference between the loudest and quietest parts of a sound) than 8 bit sound in exactly the same way that 16 bit images can display many more colors than 8 bit images can. The larger the dynamic range, the more effective animations are in conveying the details of the sound. This is true for both spectrum and amplitude values.

The sample rate of a sound has much less effect on the dynamic range than the bit depth. The de-facto minimum spec for uncompressed sound in multimedia projects is mono, 22050Hz at 16 bits, which is perfectly adequate for use with the AmplitudePro Xtra.

For spectrum values the sample rate affects the total possible frequency range of the values calculated by ampSetSpectSound(). The total possible frequency range is equal to the sample rate / 2.

Large Sound Files...
The AmplitudePro Xtra uses two methods for scanning sound cast members; 1) it asks Director to supply the sample values using the Xtra's software interface, and 2) it loads them directly from external files using buffered input. Generally the xtra will attempt to use method 1) whenever possible - it's simpler, supports a wider range of formats and Director does some of the work. Method 2) is reserved for large uncompressed external files. With this method it is possible for the Xtra to scan very large files with very little RAM overhead.

Specifically method 1) is used for,

Method 2) is used for

Pre-scanning sound files in authoring, storing the data in a script member and then using ampSetCurve() / ampSetSpectCurve() is the generally recommended technique for all sound files where the overhead associated with ampSetSound() / ampSetSpectSound() and large sound members is considered to be unacceptable and/or when RAM may be in short supply at runtime. The technique ensures that any overhead occurs only once during authoring and that the performance at runtime is optimized. For most smaller uncompressed sounds there is no significant overhead associated with ampSetSound(). The calculations for ampSetSpectSound()are more processor intensive than ampSetSound() and this is also the recommended technique where the delay involved is considered unacceptable. Increases in processor speed have reduced any processing overhead significantly.

Spectrum values...
Generally, spectrum values cause more processor load than amplitude values at runtime due to the fact that there are more values to be handled per frame. Using stereo sounds with spectrum values will double the amount of values to be handled per frame. If you simply want to give the impression of a stereo spectrum display then consider using a 'mirror' of the values returned from a mono sound.

As usual, the Director developer's mantra should be invoked frequently: "test early, test often, test on all target platforms".

[Contents]

Support

All registered users of our products can receive technical support via email to our support address which generally operates 7 days a week. We always endeavor to respond to all support requests quickly, however delays due to international time differences can occur.

When requesting technical support for a functional or performance related issue then please include technical information for your computer and operating system.

[Contents]


©2003-2008 Marmalade Multimedia.
Last Modified: 15 April 2008

Director, Flash and Shockwave are trademarks or registered trademarks of Adobe, Inc