Version 3.1

Contents

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

Introduction

First of all we'd like to thank you for using FlashAmp Lite, the sound-visualization utility for Adobe Flash™. FlashAmp can produce the data you need to create engaging Flash audio animations based on amplitude information.

Marmalade Multimedia produces three different editions of FlashAmp:

• FlashAmp Pro
• FlashAmp Standard (or just 'FlashAmp' for short)
• FlashAmp Lite

This User Guide deals specifically with FlashAmp Lite.

If this User Guide doesn't answer all of your questions about FlashAmp then check the FAQ page on the website or email our support address and we'll try to answer any questions you have.

What's new

FlashAmp Lite 3.1 is a maintenance relase that addresses a number of issues in version 3.0.1 and adds some useful features:

• A new Preferences setting to restore the configuration of the application to the same state that it was on last exit.
• Restrictions when running FlashAmp unregistered have been eased - output data arrays now contain 60 elements, equivilent to 5 seconds of audio data at 12 frames per second.

The following issues have been fixed:

• A bug producing invalid data output and occassional crashing when processing unsupported compressed WAVE files.
• Output files are now named correctly when processing sound files with long file names (more than 31 characters) on Mac OS X.
• Restored the use of "&ampdone=1" at the end of the loadVars() output format as per FlashAmp 2.
• Numerous button enabled state bugs in the main window.
• Removed the use of "..." in the output data files when running FlashAmp unregistered.
• Numerous minor bugfixes and tweaks.

[Contents]

How FlashAmp works

All editions of FlashAmp work in basically the same way - they read a sound file and analyze the sample data to produce arrays of data that can be used in Flash. FlashAmp Lite can produce two types of data arrays:

• amplitude data - which represents the changing pattern of loudness that occurs over the duration of the sound, and;
• cue point data - cue points are associated with specific time points in a sound file which can be used to trigger events in Flash.

When FlashAmp Lite generates amplitude data, it breaks up the sound into a series of "slices" over time (like frames in Flash). These slices are individually scanned to derive a single amplitude value. The duration, or 'width', of each slice is determined by the Frame rate setting in FlashAmp so, for example, the default value of 15 will process the sound in slices that occupy 1/15th of a second.

FlashAmp takes advantage of the way that Flash handles sound - setting a sound in Flash to 'Stream' means that the relationship between the sound and the playback of your Flash movie will remain synchronized. So as the sound plays you can find the current amplitude value by using simple actionscript to determine the current position of the sound. This can be done by using the .position property of the Flash sound object or, if the sound is on the main timeline, the _currentFrame property.

So, how do you get the FlashAmp data into your Flash movie? The easiest way is to use the #include output file format in FlashAmp. This will create a text file with the FlashAmp data and setting states using actionscript syntax that can be loaded directly into your movie via a single #include statement. You can also output a text file formatted for use with loadVariables() in Flash, or simply paste the data directly into a Flash script.

One of the main advantages of FlashAmp simply producing raw data is that it gives you, the Flash developer, maximum flexibility in how you use it. And, because it's non-proprietary, it doesn't break every time a new version of Flash is released. After all, it's just data.

[Contents]

Installing FlashAmp

Windows – unzip the FlashAmp Lite zip archive and place the FlashAmp folder in a convenient location on your hard drive. FlashAmp is a complete stand-alone application and it makes no changes to the Windows registry.

Macintosh – unstuff the FlashAmp Lite Stuffit archive and double-click the .dmg file to mount the disk image. Drag the FlashAmp folder from the disk image window to your Applications folder.

[Contents]

Registering FlashAmp

Output arrays generated by an unregistered copy of FlashAmp are limited to 60 elements.

To purchase FlashAmp go to our Order page here,

http://www.marmalademedia.com.au/order/

Orders are normally processed automatically and you will receive your user name and serial number on completion of your order (a confirmation email containing these details will also be sent to you). Enter your user name and serial number into the Registration tab of the Setup window to unlock FlashAmp.

[Contents]

How to use FlashAmp

FlashAmp main window is divided into 6 panels and we recommend that you move from the Input panel, near the top of the window, to the Control panel at the bottom when processing a sound. There are also a number of separate windows. This section describes the options available on each panel and each window.

Buttons in the FlashAmp interface are color-coded:

Dark gray: the button will open a FlashAmp window.
Light gray: general settings
Red: file operations
Green: commit current settings

[Contents]

Top panel

The top panel consists of:

• The gray drag bar at the top – use this to drag the main FlashAmp window. The yellow button at the right end of the drag bar minimizes all open FlashAmp windows and the red button quits FlashAmp (you can also quit using the Escape key or Control-Q (Windows), Command-Q (Macintosh).
• The Setup button opens the Setup window.
• The Help button opens this User Guide.

[Contents]

Setup window

The Setup window is divided into three tabs; Preferences, Registration and About. You can drag the Setup window using the title bar at the top. The Preferences tab contains settings for: #include file extension – this sets the file name extension for the #include output file. This can be either .as (the default) or .txt (as used by FlashAmp 2) Remember settings (NEW for FlashAmp 3.1) – when set to Yes (the default) all settings will be remembered between FlashAmp sessions. This includes the state of all controls and custom band widths if set. Remember i/o paths – when set to Yes (the default) all input and output paths will be remembered between FlashAmp sessions. This includes the input and output folders, and whether an output folder has been specified. Check for updates – when set to Yes (the default) FlashAmp will check the Marmalade website for any available FlashAmp updates. This function is included for your convenience only – apart from the FlashAmp version number, no information of any kind is transmitted to Marmalade Multimedia. If you're not 100% comfortable with this then simply turn it off.

The Registration tab allows you to enter your user name and serial number in order to register FlashAmp. Be sure to enter this information exactly as shown in your registration email – the safest way is to copy and paste each one. Click the Register button once you have entered the information. If the details are correct then you will see a confirmation alert and the About tab of the Setup window will automatically be displayed. The Registration tab is disabled when FlashAmp has been registered. Your registration details will be displayed in the About tab shown to the right. Click the OK button at the bottom of the window to close the Setup window and save any changes to the Preferences, or click the Cancel button to discard any changes. [Contents]

Input panel

Use the Select File button to choose a single sound file to process. The name of the file will appear in the text area next to the button. The location of the input file will be the default location of the output file produced by FlashAmp but you can also set a different output directory in the Output panel.

[Contents]

Common panel

The common panel contains settings that are 'common' to all FlashAmp operations.

Frame Rate – if your sound is on the root timeline of your Flash movie then enter the frame rate of your Flash file into this field in order for synchronization between the sound and the arrays produced by FlashAmp to be maintained during playback. If you are using the Flash sound object then you can set the frame rate to any value you want but it should be at least the same value as your Flash frame rate if you want to get a true representation of the sound's characteristics in Flash.

The Frame rate value determines the size of the "slices" that FlashAmp uses to scan the sound file so you can also think of it as setting the 'resolution' of the FlashAmp output data. The default value is 15fps and the maximum possible Frame rate value for is 100fps.

Scale – enter the scale for the amplitude values that FlashAmp will produce, the default is 100. For 16bit sounds the possible range is 1 to 32767 and for 8bit sounds the range is 1 to 128. Generally, it makes sense to to get FlashAmp to scale the data to a value such as 100 so you can easily control animations in Flash.

Unless you have the DB Scale button switched on in the Amplitude panel then the values in the output data will be scaled from 0 (silence) to the set Scale value. The Scale entry field is disabled if the DB Scale button is on.

Mono/Stereo – FlashAmp produces mono amplitude arrays by default. If you are processing a stereo sound then the Stereo button will be enabled and selecting it will produce separate arrays for the left and right channels. If you select Mono when processing a stereo sound, then FlashAmp will produce a summed mono amplitude array. The Stereo button is also enabled for batch process operations, if it's on then stereo arrays will be generated for any stereo sound files and mono arrays will be generated for any mono sound files.

Normalize – switch this button on if you want FlashAmp to normalize the sample values of the sound before processing. Normalizing boosts the level of the sound so that the loudest part is as loud as possible without clipping. So this option can be useful for sound files that are relatively quiet and it can result in a slightly larger dynamic range that will be reflected in the output values. Note that normalizing will result in increased processing time for FlashAmp. The sound file is not updated with the normalized sample data.

[Contents]

Amplitude panel

This panel holds all the settings for generating amplitude data.

Generate List – Switch this button on to tell FlashAmp to create an amplitude array.

Smoothing – this 'smoothes out' the values in the amplitude array created by FlashAmp. This creates a less jagged amplitude curve so you will get smaller steps in the amplitude values between frames in your Flash movie. Selecting 0 disables smoothing. Selecting 3, 5 or 7 instructs FlashAmp to execute a 3, 5 or 7-point smoothing calculation on the amplitude curve. The higher the number, the greater the degree of smoothing.

DB Scaling – more correctly written as 'dB' scaling, this setting instructs FlashAmp to use the decibel scale for amplitude values. This is a logarithmic scale that's a better representation of the way that humans perceive loudness than the default linear scale. It's typically used to implement VU meters. When using this option the amplitude values use a scale where 0 is loudest and anything above 50 can be regarded as very quiet.

Zero Ending – this setting effectively fades out the last 5 values in the the amplitude array to zero. This is handy for Flash lip-sync applications when you want to be sure that the character's mouth is shut when the sound finishes.

[Contents]

Cue points panel

Switch on the Generate List button to tell FlashAmp to create a cue points array. The input sound file must be either WAVE or AIFF format with cue points embedded within it. Note that some sound editors use the term 'Markers' instead of cue points. Cue points are useful if you want to trigger events within Flash at specific times during a sound such as switching between animated characters when using amplitude data for lip sync.

When the Fill Frames button is on then the array elements ('frames') between adjacent cue point names will be filled with the first cue point name. So, for example, with Fill Frames switched off a cue point array may look like:

["", "", "", "CuePoint_1", "", "", "", "CuePoint_2", "", "", "", "", "CuePoint_3", "", ""]

With Fill Frames on it will look like this:

["", "", "", "CuePoint_1", "CuePoint_1", "CuePoint_1", "CuePoint_1", "CuePoint_2", "CuePoint_2", "CuePoint_2", "CuePoint_2", "CuePoint_2", "CuePoint_3", "CuePoint_3", "CuePoint_3"]

This avoids the possibility of missing a cue point due to dropped frames as your Flash file is playing.

See the Cue Points section for more information.

[Contents]

Output panel

This panel controls how the output files are handled.

Create File – switch this on to generate output data files. If it's switched off then you can still access the output data using the View Data button in the Control panel below.

Format: #include/loadVars() – these buttons switch between the two output file types. See the Output formats section for more information about each format.

Select Folder – this allows you to set a specific folder as the destination for all output files. By default the output file is created in the same folder as the input sound file. When an output folder has been selected then a red dot will appear at the right end of the output path text area:

[Contents]

Control panel

Process – this button will process the input sound file using the current settings. The Progress bar will update. If the sound has been previewed and no settings have been changed then the output file will be created without the sound being re-processed.

View Data – this button becomes active when a single input file has been processed. Selecting it will open the Output window which displays the data in a single text field. The data can be copied to the clipboard using Control-C on Windows or Command-C on Macintosh.

[Contents]

Output formats

FlashAmp creates two different output file formats: #include and loadVars() as set in the Output panel. This section provides specific details for both of these formats.

#include

This format allows the output file to be used directly in Flash via an #include statement when authoring your Flash movie. FlashAmp formats the output file as ActionScript statements which means you don't need to copy and paste the data produced by FlashAmp into your Flash movie. It also makes it easy to update the data – just replace the #include file and re-publish. To make use of this format, make sure the output file is located in the same folder as your Flash movie then use an #include statement as shown in the following example:

onClipEvent(load)         { 
  // load array(s) and variables for this sound 
  #include "my_sound.txt"
}

When the movie clip loads and this handler is executed then all the data in the the file produced by FlashAmp will be available for immediate use in your movie with no further processing. This is by far the simplest way to make use of the data produced by FlashAmp.

The content of an Authoring #include file depends upon the options selected in FlashAmp. For mono amplitude data the format of the output file is as follows:

faFile="my_sound.aif";
fps=15;
scale=100;
smoothing=1;
dBValues=0;
stereo=0;
amplitude=[a1, a2, a3, a4, ...];

The first lines of the output detail the settings used to process the file: faFile is the name of the input sound file, fps is the Frame Rate setting used, scale is the Scale setting used, smoothing is the Smoothing setting used (> 0 if switched on), dBValues is the dB Scale setting used (1 if switched on) and stereo is the Stereo setting used (1 if switched on and the processed sound file was stereo). This is followed by the amplitude array where a1, a2 etc. represent amplitude values.

If you have chosen to output stereo data then the file will contain 2 arrays, one for each channel, and the stereo variable will be set to 1. In an #include file, stereo amplitude arrays are output as:

amplitudeLeft=[a1, a2, a3, a4, ...];
amplitudeRight=[a1, a2, a3, a4, ...];

If you choose to generate a cue point array then this will appear as the last array in the #include file, for example mono amplitude data with cue points will be output as:

faFile="my_sound.aif";
fps=15;
scale=100;
smoothing=1;
dBValues=0;
stereo=0;
amplitude=[a1, a2, a3, a4, ...];
cuePoints=[cp1, cp2, cp3, ...];

where cp1, cp2 etc. are cue point names or empty strings (""), unless the Fill Frames option is switched on. See the Cue Points section for more information.

loadVars()

This format allows the data in the FlashAmp output file to be loaded when your published Flash movie (.swf) file plays. This is accomplished by using the Flash loadVariables() handler, or equivalent.

The content of an loadVars() file depends upon the options selected in FlashAmp. For mono amplitude data the format of the output file is as follows:

&faFile=player1.aif&fps=15&scale=100&smoothing=0&dBValues=0&stereo=0&amplitude=(a1, a2,a3,..)&ampDone=1

The first part of the output file details the settings used to process the input sound file: faFile is the name of the input sound file, fps is the Frame Rate setting used, scale is the Scale setting used, smoothing is the Smoothing setting used (1 if switched on), dBValues is the dB Scale setting used (1 if switched on) and stereo is the Stereo setting used (1 if switched on and the processed sound file was stereo) .

This is followed by the amplitude data where a1, a2 etc. are amplitude values. At the end of the output is the string "&ampDone=1" to facilitate the reading of the file if required. Simply declare ampDone as a variable with an initial value of 0 and when this variable has a value of 1 then the file data has been successfully read.

Note: the variables and array(s) will be strings when read by Flash using loadVariables() or similar. This means that the string holding the data array(s) will have to be converted to a numerical array by Flash using the string.split() function, or an equivalent ActionScript function, before the data can be used by Flash.

If you have chosen to output stereo arrays then the output will contain 2 data arrays, one for each channel.

Stereo amplitude arrays are output as:

amplitudeLeft=(a1, a2,a3,..)&amplitudeRight=(a1, a2,a3,..)&ampDone=1

If you additionally select to generate a cue point array then this will appear as the last array in the output, for example a mono amplitude array with cue points will be output as:

&faFile="my_sound.aif"&fps=15&scale=100&smoothing=1&dBValues=0&amplitude=(a1, a2,a3,..)&cuePoints(cp1, cp2, cp3,...)&ampDone=1

where cp1, cp2 etc. are cue point names or empty strings (""), unless Fill Frames is switched on. See the Cue Points section for more information.

[Contents]

Cue points

FlashAmp can output cue point names from AIFF and WAVE files in a format that can be used in Flash. Cue points are useful for triggering events at a specific point as a sound plays. If you choose to output cue point data then FlashAmp will produce an array based on the Frame Rate setting in the Common panel. So, if you are processing amplitude data and cue points (with Fill Frames switched off) then the arrays are arranged as follows (using example data):

So, for each element in the amplitude array there is a corresponding element in the cue point array.

If Fill Frames had been switched on then frames 4 to 'x' of the cue point array would be filled with the "itchy" string and frames x+1 onwards would be filled with the "scratchy" string.

Note: if FlashAmp finds more then one cue point in a frame of the sound, then only the last cue point in the frame will be stored in the cue point array.

[Contents]

Using FlashAmp data in Flash

Using FlashAmp data in Flash requires some basic ActionScript coding. This section explains some basic ActionScript code for using amplitude data in Flash.

Complete example Flash source files and an ActionScript 2 class library for use with FlashAmp, can be found on the Marmalade website at,

http://www.marmalademedia.com.au/flashamp/examples.html

Amplitude data

FlashAmp will produce an array of amplitude values that looks like this (only the first few values are shown here; "..." is an abbreviation for the remaining values):

amplitude=[32, 64, 51, 33, 32, 36, 36, 55, 76, 58, ...];

One way to get the list into Flash is to copy it from the FlashAmp Pro Output window or the output file and paste it directly into a frame script in your Flash movie. Here's an example script that scales a graphic object ("ball") so that it pulsates in sync with the sound:

var gFrame: Number = 0
var gAmp: Number = 0 
var amplitude:Array = new Array(32, 64, 51, 33, 32, 36, 36, 55, 76, 58, ...)      
      

function onEnterFrame() {
  this.gFrame = _root._currentframe; // get the current frame
  this.gAmp = this.amplitude[this.gFrame-1]; // get the current amplitude value
  _root.ball._xscale = 100 + this.gAmp;
  _root.ball._yscale = 100 + this.gAmp;
}

It's simple but the code above is all that's required to make the animation stay in sync with the sound.

This example assumes that the sound is on the _root timeline starting on frame 1. The line,

this.gAmp = this.amplitude[this.gFrame-1];

references the array using gFrame-1 to take account of the fact that Flash arrays are 0-indexed so frame 1 should reference amplitude[0].

There are a few limitations to putting the sound on the timeline in Flash – for example, you can't control the volume and pan of the sound. Generally, you get much more control creating a sound object and using attachSound() or loadSound(). But in that case you can't find the current index in the FlashAmp data arrays using the _currentFrame property. Instead you need to calculate the current index using the .position property of the sound object and this is simple, reliable and accurate. The code above can be re-written to use a sound object like this:

// include the FlashAmp data...
#include "my_sound.as" 

var gFrame: Number = 0
var gAmp: Number = 0 
var faTrack: Sound

function init() {
  this.faTrack = new Sound(); // create a new sound object
  this.faTrack.attachSound(this.faFile); // attach the sound from the library
  this.faTrack.start(); // start the sound
}

function onEnterFrame () {
  // get the current frame...
  this.gFrame = Math.floor((this.faTrack.position/1000)*this.fps); 
  this.gAmp = amplitude[this.gFrame]; // get the current amplitude value
  _root.ball._xscale = 100 + this.gAmp;
  _root.ball._yscale = 100 + this.gAmp;
}

init()

Note that the variables faFile and fps come from the FlashAmp #include file, and that there is no need to offset the gFrame value using this method.

Both methods will reliably sync animation to sound, even if the sound is streaming and drops in and out. This example is scaling a vector graphic but the data could just as easily be used to draw the sound waveform or lip sync animated characters.

[Contents]

Supported sound formats

FlashAmp can process any of the following formats,

• AIFF (uncompressed)
• WAVE (uncompressed)
• SWA (Shockwave Audio)
• MP3 (MPEG 3 audio) including Variable Bit Rate (VBR) and Joint Stereo encoding

FlashAmp supports all standard sample rates as well as 16 and 8 bit sounds. MP3 and SWA files will take longer to process than AIFF or WAVE files of the same duration because of the additional time it takes to decompress these files.

Also see the Technical specifications and Hints and tips sections.

[Contents]

Technical specifications

Adobe Flash™ compatibility

• Flash 9 (CS3)
• Flash 8
• Flash MX2004 Professional and MX2004
• Flash MX
• Flash 5 (requires reformatting of arrays to Flash 5 lists)

Supported sound formats

• AIFF (uncompressed)
• WAVE (uncompressed)
• SWA (Shockwave Audio)
• MP3 (MPEG 3 audio) including Variable Bit Rate (VBR) and Joint Stereo encoding

Supported sample rates

• 48000Hz
• 44100Hz
• 22050Hz
• 11025Hz

Supported bit depths

• 16bit
• 8bit

Settings

Maximum frame rate: Amplitude=100
Maximum scale: Amplitude 16bit = 32767, Amplitude 8bit = 128

Minimum system requirements

[Contents]

Hints and tips

The best sound formats to use

There are two basic things that will help you get the best possible results with FlashAmp,

• use 16bit sound files
• try to use sounds with a large dynamic range

Both of these points says the same thing in different ways; 16bit sounds can hold a wider range of amplitude values (in other words, a larger dynamic range - the difference between loud and soft parts of the sound) than 8bit sound in exactly the same way that 16bit images can display many more colors than 8bit images. The larger the dynamic range, the more effective your animations will be in conveying the details of the sound.

But even if a particular sound does not have a large dynamic range it's often possible to customize the animation (or whatever other function you're using the amplitude values for) by looking at the amplitude values to determine the range of values that does change most frequently and work from that.

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 products is mono, 22050Hz at 16bit which is perfectly adequate as far as the performance of FlashAmp is concerned.

FlashAmp and sound in Flash

There are three different ways you can use FlashAmp with sounds in Flash. Each of them have advantages and disadvantages which mainly relate to the way that Flash handles sound - FlashAmp works basically the same way in each case.

1) Putting the sound on the timeline

If you put the sound on the timeline then you must set it to stream in order to maintain sync with the FlashAmp array(s). You should put the sound on the root timeline. This means that it will actually play as it streams off the server. If you place it inside a movie clip then the whole clip has to download before the sound starts to play even if it is set to stream.

Using this option you can of course stop and start the sound and jump to any place in the sound by merely controlling the main timeline e.g., use code such as stop();, play();, gotoAndPlay(100);, etc.

The advantage of this method is that it’s very simple; your .swf file will stream off the server and you can start and stop sounds without losing sync. The disadvantage is that you cannot load and play a different sound at runtime or use any sound object properties such as volume and pan.

2) Attaching a sound from the Library

To use this method, import the sound into Flash and select it in the Library. From the Library pop up menu choose Linkage… and select ‘Export for ActionScript’ and ‘Export in First Frame’. Flash will automatically set the identifier name for you. Then use code equivalent to the following in your sound function:

soundObject.attachSound("mySound.mp3");

The downside of using attachSound is that the whole sound will load in the first frame of your movie before anything else happens. The upside is that you will have full control to stop, pause and play because Flash can track the position of the sound correctly. You can also use sound object properties like volume and pan.

3) Loading an external .mp3 file at runtime

This option may seem to be the most attractive and mostly it is, however there are some downsides.

To use this option use code equivalent to the following in your sound function:

soundObject.loadSound("mySound.mp3", true);

Note that the second parameter is setting streaming to true.

You do not need to import the sound file into Flash. You just have to make sure that the .mp3 file is in the same directory as the .swf file.

One benefit of this method is that the .mp3 starts to stream when the loadSound() function executes. It also plays as it streams although there will be a slight delay as it buffers (Flash will maintain the correct .position value so you won't lose sync with the FlashAmp arrays).

While you can use sound object properties like volume and pan with this method, the downside is that Flash has issues tracking the sound position if you stop the sound and play it again. This is because the sound is not inside the .swf file. Sync will be maintained if the sound is simply played from beginning to end but if the sound is stopped and started again from the beginning then Flash will not automatically reset the soundObject.position value so you will not be able to keep the sound in sync with the array. The workaround is to clear the sound object when the sound is stopped and create a new one when sound is started again.

Processor load at runtime

Processor load is not as much of an issue as it used to be. The performance of the Flash player (especially version 8) has improved a great deal and the average spec of end-users computers has improved as well. But performance is still something that you should not take for granted, so if you're using FlashAmp data then we strongly recommend thorough testing on all your target systems.

[Contents]

Support

Registered users can receive technical support via email. When reporting an error please supply the full text of the error message and details of your hardware and operating system as well as the sound being processed.

Copyright ©2000-2007 Marmalade Multimedia
Last updated: 1 June, 2007

'Flash' is a trademark or registered trademark of Adobe, Inc