impact4: library_SoundControl and remote_SoundControl

**NOTE: You must update the Flash MX player to use the library.
Download the "Macromedia Flash Player 6 Update for Flash MX" here.

Basic Definitions

library_SoundControl - This is the actual library that holds the controls, and loading/sound control code. It is loaded at survey startup, and can then be accessed throughout the survey.

remote_SoundControl - This is the library "remote". Remotes are used to trigger library events, and pass detailed information to the library. In this case, the remote is used to pass the track information on to the library, and tell it to start playback. In actual use, you'll put the remote_SoundControl module in the survey wherever you want sound playback. (In most cases, inside a group tag).

Usage

To use SoundControl, you need to use two sets of tags in configuration.xml: one for the library, and one for each instance of the remote.

To include the library, place the following code inside the <configuration> section:

<library name="library_SoundControl"/>

When you want to use the library, include the remote as a module, with XML like this:

<module type="remote_SoundControl" name="remoteName">
   <const type="string" name="trackURL" value="http://liquidsilverzen.net/v5/music/Parabol - Parabola.bmp"/>
   <const type="string" name="trackName" value="Tool- Parabol/Parabola"/>
   <const type="string" name="trackPlayLength" value="9:08" />
   <const type="integer" name="trackVolume" value="100" />
   <const type="string" name="trackDoneAction" value="functionHere" />
   <const type="boolean" name="controlPlayPause" value="true" />
   <const type="boolean" name="controlRewind" value="true" />
   <const type="boolean" name="controlMute" value="true" />
   <const type="boolean" name="controlStop" value="true" />
   <const type="boolean" name="allowAdvance" value="false" />
</module>

You will need to include the remote_SoundControl module whenever you want to use library for sound playback. However, all you need to do is include the remote in the XML. All the actions happen automatically, and no other modules have to trigger events, or worry about the sound.

Here's what each of the consts mean and do (required fields are in bold):

name="remoteName" - the impact4 Instance Name. This MUST be unique, otherwise information from one instance will overwrite the others (resulting in repeated sounds all over the place).

trackURL - (required) URL of the track. This should be an mp3-encoded file (though the extension doesn't matter), and needs to be located in /Resources, or have an absolute URL (i.e. "http://pref1.ucsd.edu/filename1.mp3"). The library looks at the URL to see if it has an "http", and if not, assumes it's in resources. So, don't call your file "httpSound.mp3" and put it in resources and expect it to work. : )

trackName - (optional) This is text that describes the sound file. It is displayed on mouseover of the progress bar.

trackPlayLength - (required) Length of track. Format is m:ss. This value is necessary, since the MP3 spec doesn't give the track length until the end of the stream.

trackVolume
- (optional) volume of playback. (0-100, 0 is silence). Defaults to 100, and in the current implementation, this value can override the survey-wide volume setting. Unless you have a specific reason to change this value, it should probably be left at null.

trackDoneAction - (optional) This is the function to call when the track finishes playing. If you specify a function name, scoping needs to be correct. Alternatively, you can write an anonymous function. Mileage may vary.

controlPlayPause - (optional) Show the play/pause control. True shows, False hides. Boolean, defaults to true.

controlRewind - (optional) Show the rewind control. True shows, False hides. Boolean, defaults to true.

controlMute - (optional) Show the mute control. True shows, False hides. Boolean, defaults to true.

controlStop - (optional) Show the stop control. True shows, False hides. Boolean, defaults to true.

allowAdvance - (optional) Allow i4 to advance without the sound playing all the way through. Boolean, true allows advance, false holds advance until the sound has completed. Defaults to true.