com.flagstone.transform.util
Class FSSoundConstructor

java.lang.Object
  extended by com.flagstone.transform.util.FSSoundConstructor

public class FSSoundConstructor
extends java.lang.Object

The FSSoundConstructor class is used to generate the objects used to define and control the sounds that are played in a Flash movie. The FSSoundConstructor can be used to generate definitions for:

The FSSoundConstructor contains constructors and methods that allow sound data to be loaded from an external file simplifying the process of adding sound to a movie. The FSSoundConstructor currently supports uncompressed PCM format (with either big-endian or little-endian byte ordering) and MP3 format files. Once loaded, the PCM sound data should be compressed to ADPCM format as the relatively large sizes make PCM coded sounds generally unsuitable for inclusion in a Flash movie. ADPCM is a compressed format and Flash supports a modified ADPCM algorithm with compressed samples taking 2, 3, 4 or 5 bits. This results in much smaller file sizes when a movie is encoded. Code, developed at Centre for Mathematics and Computer Science, Amsterdam, The Netherlands, is available on Flagstone's web site to perform the ADPCM compression. For sounds containing more than one channel, the sound levels for each channel are interleaved for each sample. For example a stereo sound the order of the samples and channels levels are:
 Sample       0          1          2
          +---+---+  +---+---+  +---+---+
          | 1 | 2 |  | 1 | 2 |  | 1 | 2 | ....
          +---+---+  +---+---+  +---+---+
NOTE: The byte order for the PCM data in WAVE sound files may vary according to the platform on which the sound file was created. The FSSoundConstructor currently only supports WAVE files with little-endian byte order. Examples The following code samples illustrate how to use the FSSoundConstructor class to add sounds to a Flash file. 1. Playing an uncompressed WAVE file.\n
 int soundId = movie.newIdentifier();

 // Generate an FSDefineSound object using the attributes defined in the wave file.
 // An FSSound object is used to instruct the Flash Player to start playing a sound.

 FSSoundConstructor soundGenerator = new FSSoundGenerator("sound.wav");

 movie.add(soundGenerator.defineSound(soundId));
 movie.add(new FSSound(soundId, FSSound.Start));
2. Streaming Sounds.\n Larger sound files may be streamed to the Flash Player - splitting the sound data into a sequence of blocks which is synchronised with the frames as they are displayed. Typically block of sound data is generated for each frame displayed.
 int framesPerSecond = 12;

 FSSoundConstructor soundGenerator = new FSSoundGenerator("soundTrack.wav");

 // Calculate the number of decoded sound samples played for each frame

 int samplesPerBlock = soundGenerator.getSampleRate() / framesPerSecond;
 int numberOfBlocks = soundGenerator.getSamplesPerChannel() / samplesPerBlock;

 // An FSSoundStreamHeader2 object defines the attributes of the streaming sound.

 movie.add(soundGenerator.streamHeader(samplesPerBlock));

 // Add a streaming block for each frame so the sound is played as each frame is displayed.

 for (int i=0; i<numberOfBlocks; i++)
 {
     movie.add(soundGenerator.streamBlock(i, samplesPerBlock));
     movie.add(new FSShowFrame());
 }
 


Constructor Summary
FSSoundConstructor()
          Creates a new uninitialized FSSoundConstructor object.
FSSoundConstructor(java.lang.String fileName)
          Creates a new FSSoundConstructor object initialised with the contents of the specified sound file.
 
Method Summary
 FSDefineSound defineSound(int anIdentifier)
          Generates an FSDefineSound object from the sound data.
 int getFormat()
          Accessor method returning the format for the encoded sound data.
 int getNumberOfChannels()
          Accessor method returning the number of channels in the sound.
 int getSampleRate()
          Accessor method returning the rate at which the sound will be played.
 int getSampleSize()
          Accessor method returning the number of bytes for each decoded sound sample.
 int getSamplesPerChannel()
          Accessor method returning the number of samples in each channel.
 byte[] getSound()
          Accessor method returning a copy of the encoded sound data.
 void setSound(int format, int channelCount, int sampleCount, int sampleRate, int sampleSize, byte[] bytes)
          Initialises the FSSoundConstructor with the sound data and set of parameters.
 void setSound(java.lang.String filename)
          Initialises the FSSoundConstructor with the contents of the specified file.
 FSSoundStreamBlock streamBlock(int blockNumber, int samplesPerBlock)
          Generates an FSSoundStreamBlock object containing a block sound data.
 FSSoundStreamHead2 streamHeader(int samplesPerBlock)
          Generates an FSSoundStreamHead2 object to stream the sound data to the Flash Player.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FSSoundConstructor

public FSSoundConstructor()
Creates a new uninitialized FSSoundConstructor object. Use setSound to provide the content.


FSSoundConstructor

public FSSoundConstructor(java.lang.String fileName)
                   throws java.io.IOException,
                          java.util.zip.DataFormatException
Creates a new FSSoundConstructor object initialised with the contents of the specified sound file.

Parameters:
fileName - the name of the file containing the sound.
Throws:
java.io.FileNotFoundException - - if the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.
java.io.IOException - - if an I/O error occurs while reading the file.
java.util.zip.DataFormatException - if the file contains a sound format not supported by the FSSoundConstructor.
Method Detail

getFormat

public int getFormat()
Accessor method returning the format for the encoded sound data.

Returns:
the format of the encoded sound, either FSSound.NATIVE_PCM (platform dependent byte-order), FSSound.PCM (PCM little-endian byte-order), FSSound.ADPCM or FSSound.MP3.

getNumberOfChannels

public int getNumberOfChannels()
Accessor method returning the number of channels in the sound.

Returns:
the number of sound channels, typically this will be 1 (mono) or 2 (stereo).

getSamplesPerChannel

public int getSamplesPerChannel()
Accessor method returning the number of samples in each channel.

Returns:
the number of samples in each channel.

getSampleRate

public int getSampleRate()
Accessor method returning the rate at which the sound will be played. The playback rate should be a value supported by the Flash Player 5512, 11025, 22050 or 44100 Hertz. Although the sound rate may be changed using the changeSampleRate method the FSSoundConstructor class does not support the filtering required to change the sample rate from an arbitrary value to one of the rates supported by the Flash Player. MP3 formatted sounds have playback rates of 11025, 22050 or 44100.

Returns:
the playback rate for the sound, either 5512, 11025, 22050 or 44100 Hertz.

getSampleSize

public int getSampleSize()
Accessor method returning the number of bytes for each decoded sound sample.

Returns:
the number of bytes in each sample.

getSound

public byte[] getSound()
Accessor method returning a copy of the encoded sound data.

Returns:
encoded sound data.

setSound

public void setSound(java.lang.String filename)
              throws java.io.IOException,
                     java.util.zip.DataFormatException
Initialises the FSSoundConstructor with the contents of the specified file.

Parameters:
filename - the name of a file containing encoded sound data.
Throws:
java.io.FileNotFoundException - - if the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.
java.io.IOException - - if an I/O error occurs while reading the file.
java.util.zip.DataFormatException - if the file contains a sound format not supported by the FSSoundConstructor.

setSound

public void setSound(int format,
                     int channelCount,
                     int sampleCount,
                     int sampleRate,
                     int sampleSize,
                     byte[] bytes)
Initialises the FSSoundConstructor with the sound data and set of parameters. This method can be used to update the sound following processing for example to convert a stereo sound to mono to reduce the size of the encoded data.

Parameters:
format - the format of the encoded sound either FSSound.PCM, FSSound.ADPCM or FSSound.MP3.
channelCount - the number of sound channels, 1 = mono, 2 = stereo.
sampleCount - the number of samples in each channel.
sampleRate - the rate at which the sound is played in kiloHertz. Flash supports 5512, 11025, 22050 or 44100.
sampleSize - the number of bytes for each uncompressed sound sample, either 1 or 2.
bytes - an array of sound samples encoding in the specified format.

defineSound

public FSDefineSound defineSound(int anIdentifier)
Generates an FSDefineSound object from the sound data. The FSDefineSound object is created using the encoded sound data so if the sound was decoded in order to change the number of channels, sample rate or sample size it must be re-encoded.

Parameters:
anIdentifier - a unique identifier for the FSDefineSound object.
Returns:
an FSDefineSound object initialised with the encoded sound data.

streamHeader

public FSSoundStreamHead2 streamHeader(int samplesPerBlock)
Generates an FSSoundStreamHead2 object to stream the sound data to the Flash Player.

Parameters:
samplesPerBlock - the number of samples in each subsequent FSSoundStreamBlock object.
Returns:
an FSDefineSound object initialised with the encoded sound data.

streamBlock

public FSSoundStreamBlock streamBlock(int blockNumber,
                                      int samplesPerBlock)
Generates an FSSoundStreamBlock object containing a block sound data. This method is used to divide the encoded sound into a sequence of blocks to allow a sound to be streamed to the Flash Player. If the number of samples in the last block to stream is less than the samplesPerBlock, the size of the FSSoundStreamBlock object is reduced accordingly. It is not padded to maintain the specified length.

Parameters:
blockNumber - the nth block of samples.
samplesPerBlock - the number of samples to stream.
Returns:
an FSSoundStreamBlock object containing a block of bytes from the encoded sound.