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.

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.

This constructor initializes the sound as empty.

Parameters:

[in]

parent

The TagHeader where this sound is added

References f_data, f_data_maxsize, f_data_size, f_format, f_latency_seek, f_rate, f_samples, f_stereo, f_width, and SOUND_FORMAT_RAW.

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

References f_rate, f_samples, f_stereo, g_bitrates, g_frequencies, and ReadMP3Header().

Referenced by LoadMP3File().

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

Returns:

The number of samples or zero when none

References f_samples.

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

References CheckMP3Header(), f_data, f_data_maxsize, f_data_size, f_format, f_samples, f_width, sswf::MemoryManager::MemRealloc(), and SOUND_FORMAT_MP3.

Referenced by SetFilename().

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

References sswf::TagSound::sound_wave_t::channels, sswf::TagSound::sound_wave_t::format, sswf::MemoryManager::MemAlloc(), sswf::MemoryManager::MemFree(), sswf::TagSound::sound_wave_t::rate, SetData(), SOUND_ENDIAN_LITTLE, sswf::swap_int(), sswf::swap_short(), and sswf::TagSound::sound_wave_t::width.

Referenced by SetFilename().

Implements sswf::TagBase.

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.

References sswf::ErrorManager::ERROR_CODE_COMPRESSED_SOUND_8BITS, sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_UNSUPPORTED_SOUND_FORMAT, f_format, f_samples, f_width, sswf::TagBase::MinimumVersion(), sswf::TagBase::OnError(), SOUND_FORMAT_ADPCM, SOUND_FORMAT_MP3, SOUND_FORMAT_NELLYMOSER, SOUND_FORMAT_RAW, and SOUND_FORMAT_UNCOMPRESSED.

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

Referenced by CheckMP3Header().

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

References SNDINFMT, SOUND_ENDIAN_BIG, SOUND_ENDIAN_DONTUSE, SOUND_ENDIAN_LITTLE, and SOUND_ENDIAN_SAME.

Referenced by Resample(), and SetData().

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

References sswf::assert(), f_width, and ReadSample().

Referenced by SetData().

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.

References sswf::Data::Append(), sswf::assert(), sswf::Data::ByteSize(), sswf::ErrorManager::ERROR_CODE_INTERNAL_ERROR, sswf::ErrorManager::ERROR_CODE_NONE, f_data, f_data_size, f_format, f_latency_seek, f_rate, f_samples, f_stereo, f_width, sswf::TagBase::OnError(), sswf::Data::PutLong(), sswf::Data::PutShort(), sswf::TagBaseID::SaveID(), sswf::TagBase::SaveTag(), SOUND_FORMAT_MP3, SOUND_FORMAT_RAW, SOUND_FORMAT_UNCOMPRESSED, sswf::TagBase::SWF_TAG_DEFINE_SOUND, sswf::Data::Write(), and sswf::Data::WriteBits().

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.

References sswf::ErrorManager::ERROR_CODE_FORMAT_LOCKED, f_data, f_format, f_samples, f_stereo, f_width, sswf::TagBase::OnError(), and SOUND_FORMAT_MP3.

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

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

References sswf::assert(), f_data, f_format, f_rate, f_samples, f_stereo, f_width, g_sound_rates, sswf::MemoryManager::MemAlloc(), sswf::MemoryManager::MemFree(), ReadSample(), Resample(), SNDINFMT, SOUND_ENDIAN_BIG, SOUND_ENDIAN_DONTUSE, SOUND_ENDIAN_LITTLE, SOUND_ENDIAN_SAME, SOUND_ENDIAN_UNKNOWN, and SOUND_FORMAT_MP3.

Referenced by LoadWaveFile().

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)

References sswf::ErrorManager::ERROR_CODE_IO, sswf::ErrorManager::ERROR_CODE_NONE, LoadMP3File(), LoadWaveFile(), and sswf::TagBase::OnError().

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.

References sswf::ErrorManager::ERROR_CODE_FORMAT_LOCKED, f_format, sswf::TagBase::OnError(), and SOUND_FORMAT_MP3.

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.

References sswf::ErrorManager::ERROR_CODE_FORMAT_LOCKED, f_data, f_format, f_samples, f_stereo, f_width, sswf::TagBase::OnError(), and SOUND_FORMAT_MP3.

The TagSound is a definition tag with an identifier

Returns:

SWF_TYPE_DEFINE | SWF_TYPE_HAS_ID

Implements sswf::TagBase.

References SWF_TYPE_DEFINE, and SWF_TYPE_HAS_ID.

Referenced by LoadMP3File(), Save(), Set8Bits(), SetData(), SetMono(), and TagSound().

Referenced by LoadMP3File(), and TagSound().

Referenced by LoadMP3File(), Save(), and TagSound().

Referenced by LoadMP3File(), PreSave(), Save(), Set8Bits(), SetData(), SetFormat(), SetMono(), and TagSound().

Referenced by Save(), and TagSound().

Referenced by CheckMP3Header(), Save(), SetData(), and TagSound().

Referenced by CheckMP3Header(), GetSamplesCount(), LoadMP3File(), PreSave(), Save(), Set8Bits(), SetData(), SetMono(), and TagSound().

Referenced by CheckMP3Header(), Save(), Set8Bits(), SetData(), SetMono(), and TagSound().

Referenced by LoadMP3File(), PreSave(), Resample(), Save(), Set8Bits(), SetData(), SetMono(), and TagSound().

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 }
}

Referenced by CheckMP3Header().

Initial value:

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

Referenced by CheckMP3Header().

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()

Referenced by SetData().