libsswf: sswf::TagSound Class Reference

This type lists all the endians supported by the sswf library.

Enumerator:

SOUND_ENDIAN_LITTLE	The data is in little endian. Little endian means that the first byte is the least significant and the last byte is the most significant. Pentium or older MIPS based computers are in little endian. unsigned short file_samples[10]; char ptr = (char ) file_samples; unsigned short machine_samples[10]; machine_samples[0] = ptr[0] + ptr[1] * 256; ...
SOUND_ENDIAN_BIG	The data is in big endian. Big endian means that the first byte is the most significant and the last byte is the least significant. PowerPC or newer MIPS based computers are in big endian. unsigned short file_samples[10]; char ptr = (char ) file_samples; unsigned short machine_samples[10]; machine_samples[0] = ptr[0] * 256 + ptr[1]; ...
SOUND_ENDIAN_SAME	The data is in the same endian. This is used whenever the data is known to be of the same endian as of the currently running machine. So if you system is a little endian machine, this tells the system to use little endian. unsigned short file_samples[10]; unsigned short machine_samples[10]; machine_samples[0] = file_samples[0]; ...
SOUND_ENDIAN_DONTUSE	The data is defined on 8 bits. For data defined on 8 bits, the endian is not defined and thus it can be marked as "don't use".
SOUND_ENDIAN_UNKNOWN	The data endianess is not known. At this time this value cannot be used. It is not expected that it will be possible to use this value since in all cases we must know the endianess of the samples before to be able to use them.

enum sswf::TagSound::sound_format_t

This type lists all the formats supported by the Flash players.

Todo:: Note that all of these formats are not yet supported by the SSWF library. The ADPCM and NELLYMOSER have no support.

Enumerator:

SOUND_FORMAT_UNKNOWN	An undefined or unknown format. By default a sound tag is defined as having an unknown format. It is not valid to call SetData() with this value. See also: sswf::TagSound::SetData()
SOUND_FORMAT_RAW	This format is used to save uncompressed sound data. Most of the time, sound samples will be compressed to save space. Very small sounds may be saved in an uncompressed format for better quality. This format should not be used with 16 bits data since it is not possible to know for sure whether the sound effects are in little or big endian (it is dependent on the machine on which you created the Flash animation!)
SOUND_FORMAT_ADPCM	This format is used to save compressed sound data using the ADPCM format. This is a simple compression scheme somewhat similar in concept to the RLE for images. This is better suited for sound samples of effects than for songs. Todo: The libsswf library does not support this compression mode yet.
SOUND_FORMAT_MP3	This format is used to save compressed music data using the MP3 format. This is a complex compression scheme somewhat similar in concept to JPEG for images. This is better suited for sound samples of musics than for talk or effects. Todo: The libsswf library does not yet support this compression. However, it can load and use an existing MP3 file.
SOUND_FORMAT_UNCOMPRESSED	This format is used to save small uncompressed sound effect with full quality. This is the uncompressed format to use with uncompressed data. This format ensures the endianess of the data is known (i.e. little endian.) This can be created and played on any system with no problem.
SOUND_FORMAT_NELLYMOSER	This format is used to save compressed voice with high quality. This is the compressed format to use with voices (with no music in the background). Though MP3 can also be used for voices, you general get a better result with this compression scheme for voices. Todo: This compression format is not yet supported by the sswf library.

TagSound::TagSound ( TagBase * parent )

This constructor initializes the sound as empty.

Parameters:

[in] parent The TagHeader where this sound is added

int TagSound::CheckMP3Header	(	FILE *	f,
		unsigned char *	header,
		int &	frame_size
	)			`[private]`

This function checks the validity of an MP3 header.

Parameters:

`[in]`	f	The file descriptor of the MP3 file to check
`[in]`	header	A pointer to the header buffer
`[out]`	frame_size	Set to the frame size

Returns:: 0 when no error occurs; -1 on errors

size_t TagSound::GetSamplesCount ( void ) const

This function returns the current number of samples defined in this TagSound.

Returns:: The number of samples or zero when none

int TagSound::LoadMP3File ( FILE * f ) [private]

This function is called with a file descriptor to read a file which is expected to be an MP3 file. If the file cannot be read properly, the function returns with an error (-1).

Parameters:

[in] f The file descriptor

Returns:: 0 when the function succeeds in reading the entire file; -1 otherwise

int TagSound::LoadWaveFile ( FILE * f ) [private]

This function is called with a file descriptor to read a file which is expected to be a RIFF or WAVE file. If the file cannot be read properly, the function returns with an error (-1).

Parameters:

[in] f The file descriptor

Returns:: 0 when the function succeeds in reading the entire file; -1 otherwise

ErrorManager::error_code_t TagSound::PreSave ( void ) [private, virtual]

This function checks that the sound can properly be saved.

This means that all the parameters such as the width, format, stereo, etc. all are acceptable.

Returns:: ErrorManager::ERROR_CODE_NONE when the sound is valid; some other ErrorManager::error_code_t otherwise

Reimplemented from sswf::TagBase.

int TagSound::ReadMP3Header	(	FILE *	f,
		unsigned char *	header
	)			`[private]`

This function reads one MP3 header.

Note:: If we can't find the next Sync. then we tell the caller that we found the end of the file.

Todo:: These MP3 functions badly need to handle a large buffer instead of reading the file byte per byte!

Returns:: 0 when no error occured; 2 when the end of the file is reached and -1 when an error occurs

short TagSound::ReadSample	(	const unsigned char *	data,
		unsigned short	adjust,
		int	in_fmt
	)			`[private]`

This function reads one sample from a buffer expected to be of format in_fmt and adjusts it as required.

The function is used to resample input samples to samples valid for the specified mode (rate, format, mono or stereo, etc.)

Parameters:

`[in]`	data	The buffer to read from
`[in]`	adjust	The adjustment to make to the input value unsigned
`[in]`	in_fmt	The format of the input data

Returns:: The adjusted sample

void TagSound::Resample	(	unsigned char *	snd,
		unsigned int	out_bytes,
		const unsigned char *	src,
		size_t	size,
		unsigned int	in_bytes,
		size_t	max,
		double	fix,
		unsigned short	adjust,
		int	in_fmt
	)			`[private]`

This function is used whenever the SetData() or similar function is called with data in a format which is not directly supported by Flash. Then it is resampled to a way that works in Flash.

This means duplicating or removing some of the input samples. When removing samples, an average of a certain number of samples will be computed. This is not always the proper method, but in most cases it works well.

Parameters:

`[in]`	snd	The destination buffer
`[in]`	out_bytes	Size of one sample in the destination buffer (snd + out_bytes moves the pointer to the 2nd sample)
`[in]`	src	The source buffer
`[in]`	size	The size of the source buffer in bytes
`[in]`	in_bytes	Size of one sample in the source buffer (src + in_bytes moves the pointer to the 2nd sample)
`[in]`	max	The maximum number of samples to work on (i.e. size of the destination buffer)
`[in]`	fix	How much the samples need to be fixed to adjust for the rate difference
`[in]`	adjust	The adjustment to make the input value unsigned
`[in]`	in_fmt	The format of the samples in the input buffer

See also:: sswf::TagSound::ReadSample

ErrorManager::error_code_t TagSound::Save ( Data & data ) [virtual]

This function saves the sound samples in the specified Data buffer.

Parameters:

[in,out] data The data buffer where the tag is saved

Returns:: ErrorManager::ERROR_CODE_NONE when the save succeeds and another ErrorManager::error_code_t otherwise

Implements sswf::TagBase.

void TagSound::Set8Bits ( void )

This function transforms the current samples from 16 to 8 bits. If the samples already are set at 8 bits, then nothing happens.

This function does not try to adjust the sound, it simply drops the lower 8 bits of each sample.

Note:: It is not possible to transform an MP3 set of samples to 8 bits.

int TagSound::SetData	(	const void *	data,
		size_t	size,
		sound_endian_t	endian,
		int	width,
		unsigned int	rate,
		bool	stereo
	)

This function sets the specified user defined data in the TagSound object.

The data is expected to be valid sound samples.

The source samples must be mono or stereo, on 8, 16, 24 or 32 bits, at a reasonable rate (1024 to 88000), in little or big endian.

If the input data has samples which are signed (i.e. -128 to +127 or -32768 to +32767,) then the width must be passed negative (i.e. -8, -16, -24 or -32). Positive values indicate that the input samples are unsigned (i.e. 0 to 255 or 0 to 65535.)

Flash understands only a very limited set of rates:

5512
11025
22050
44100

This function understands any other rate, yet the sample data will be resampled when another rate is specified.

Note that Flash only understands 8 or 16 bits data. The low bits of 24 and 32 bits samples are dropped.

Stereo samples are expected to be interleaved with the left side sample first.

Parameters:

`[in]`	data	The source data samples
`[in]`	size	The number of bytes in the source buffer (should be a proper multiple)
`[in]`	endian	One of the sound endian (little, big, same or unused)
`[in]`	width	8, 16, 24 or 32; or negative to indicate signed data
`[in]`	rate	Any rate between 1024 and 88000 inclusive
`[in]`	stereo	Whether mono (false) or stereo (true) samples are passed

Returns:: zero when no error occured, -1 when something happens

ErrorManager::error_code_t TagSound::SetFilename ( const char * filename )

This function takes the name of a file representing a sound effect. The file is loaded on the spot and its content is kept in memory.

This function calls the LoadWaveFile() with a handle to the file it just opened. If that function fails to read the file, then this function tries again by calling the LoadMP3File().

Parameters:

[in] filename The name of the file to load

Returns:: ErrorManager::ERROR_CODE_NONE when no error occured, some other ErrorManager::error_code_t on an error

See also:: sswf::TagSound::LoadWaveFile(FILE *f)
sswf::TagSound::LoadMP3File(FILE *f)

void TagSound::SetFormat ( sound_format_t format )

This function changes the format of the samples.

Note:: If you loaded an MP3 file, then the format cannot be changed. This may change in a future version of the library.

Parameters:

[in] format The new format.

void TagSound::SetMono ( void )

Force the samples to be mono. The average of the left and right samples is computed.

Note:: At this time, it is not possible to transform an MP3 set of samples to mono. This would require a decompression and recompression which is not yet available.

TagBase::swf_type_t TagSound::TypeFlags ( void ) const [virtual]

The TagSound is a definition tag with an identifier

Returns:: SWF_TYPE_DEFINE | SWF_TYPE_HAS_ID

Implements sswf::TagBase.

unsigned char* sswf::TagSound::f_data [private]

int sswf::TagSound::f_data_maxsize [private]

int sswf::TagSound::f_data_size [private]

sound_format_t sswf::TagSound::f_format [private]

int sswf::TagSound::f_latency_seek [private]

int sswf::TagSound::f_rate [private]

size_t sswf::TagSound::f_samples [private]

bool sswf::TagSound::f_stereo [private]

int sswf::TagSound::f_width [private]

const int TagSound::g_bitrates [static, private]

Initial value:

{
        { -1, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, -1 },
        { -1, 8,  16, 24, 32, 40, 48, 56,  64,  80,  96, 112, 128, 144, 160, -1 }
}

const int TagSound::g_frequencies [static, private]

Initial value:

{
        { 11025, -1, -1, -1 },
        {    -1, -1, -1, -1 },
        { 22050, -1, -1, -1 },
        { 44100, -1, -1, -1 }
}

const int TagSound::g_sound_rates = { 5512, 11025, 22050, 44100 } [static]

Sound effects in Flash only support these rates.

Using an encoding like MP3 can be used to specify different rates in different packets. This is properly supported by newer Flash versions (version 7+)

If possible, you should use one of these rates whenever you call the SetData() function.

See also:: sswf::TagSound::SetData()


Public Types
	SOUND_ENDIAN_BIG
	The data is in big endian.
	SOUND_ENDIAN_DONTUSE
	The data is defined on 8 bits.
	SOUND_ENDIAN_LITTLE = 0
	The data is in little endian.
	SOUND_ENDIAN_SAME
	The data is in the same endian.
enum	sound_endian_t { SOUND_ENDIAN_LITTLE = 0, SOUND_ENDIAN_BIG, SOUND_ENDIAN_SAME, SOUND_ENDIAN_DONTUSE, SOUND_ENDIAN_UNKNOWN }
	Valid endians for sound samples. More...
	SOUND_ENDIAN_UNKNOWN
	The data endianess is not known.
	SOUND_FORMAT_ADPCM = 1
	This format is used to save compressed sound data using the ADPCM format.
	SOUND_FORMAT_MP3 = 2
	This format is used to save compressed music data using the MP3 format.
	SOUND_FORMAT_NELLYMOSER = 6
	This format is used to save compressed voice with high quality.
	SOUND_FORMAT_RAW = 0
	This format is used to save uncompressed sound data.
enum	sound_format_t { SOUND_FORMAT_UNKNOWN = -1, SOUND_FORMAT_RAW = 0, SOUND_FORMAT_ADPCM = 1, SOUND_FORMAT_MP3 = 2, SOUND_FORMAT_UNCOMPRESSED = 3, SOUND_FORMAT_NELLYMOSER = 6 }
	Valid formats of sounds in Flash. More...
	SOUND_FORMAT_UNCOMPRESSED = 3
	This format is used to save small uncompressed sound effect with full quality.
	SOUND_FORMAT_UNKNOWN = -1
	An undefined or unknown format.
Public Member Functions
size_t	GetSamplesCount (void) const
	Returns the number of samples in that TagSound.
virtual ErrorManager::error_code_t	Save (Data &data)
	Save the TagSound in the specified Data buffer.
void	Set8Bits (void)
	Force the samples to 8 bits.
int	SetData (const void *data, size_t size, sound_endian_t endian, int width, unsigned int rate, bool stereo)
	Set sample data in a TagSound object.
ErrorManager::error_code_t	SetFilename (const char *filename)
	Set the name of a sound file.
void	SetFormat (sound_format_t format)
	Change the format of the tag.
void	SetMono (void)
	Change the current samples to mono.
	TagSound (TagBase *parent)
	Initialize a sound tag.
virtual swf_type_t	TypeFlags (void) const
	Returns the type of this tag: Define with an ID.
Static Public Attributes
static const int	g_sound_rates [4] = { 5512, 11025, 22050, 44100 }
	The few valid sound rates supported by Flash.
Private Member Functions
int	CheckMP3Header (FILE f, unsigned char header, int &frame_size)
	Internal function to test the validity of an MP3 header.
int	LoadMP3File (FILE *f)
	Load an MP3 sound file.
int	LoadWaveFile (FILE *f)
	Load a RIFF or WAVE sound file.
virtual ErrorManager::error_code_t	PreSave (void)
	Check that the sound can be saved the way it is.
int	ReadMP3Header (FILE f, unsigned char header)
	Internal function used to read an MP3 header.
short	ReadSample (const unsigned char *data, unsigned short adjust, int in_fmt)
	Change the format of the tag.
void	Resample (unsigned char snd, unsigned int out_bytes, const unsigned char src, size_t size, unsigned int in_bytes, size_t max, double fix, unsigned short adjust, int in_fmt)
	Function used to resample a set of samples from some format to another.
Private Attributes
unsigned char *	f_data
int	f_data_maxsize
int	f_data_size
sound_format_t	f_format
int	f_latency_seek
int	f_rate
size_t	f_samples
bool	f_stereo
int	f_width
Static Private Attributes
static const int	g_bitrates [2][16]
	used by the MP3 loader
static const int	g_frequencies [4][4]
	used by the MP3 loader
Classes
struct	sound_wave_t
	defines an MP3 sound wave (format, channels, rate, alignment, etc.) More...

sswf::TagSound Class Reference

Public Types

Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Classes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation