libsswf: sswf::TagSound Class Reference

# sswf::TagSound Class Reference

Declare a sound. More...

`#include <libsswf.h>`

Inheritance diagram for sswf::TagSound:

List of all members.

## Public Types
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...
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...
## 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 | ParseTag (swf_tag_t tag, const Data &data)
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...

## Detailed Description

This class defines a sound rate, samples, mono or stereo, 8 or 16 bits, etc.

Todo:
  This sound does not yet support for streaming sound.

See also:
  SWF Alexis' Reference—Define Sound

  SWF Alexis' Reference—swf_tag

## Member Enumeration Documentation

enum sswf::TagSound::sound_endian_t

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.

## Constructor & Destructor Documentation

TagSound::TagSound | ( | TagBase * | parent | ) |

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.

## Member Function Documentation

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

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

Referenced by LoadMP3File().

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

References f_samples.

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

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

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

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

virtual ErrorManager::error_code_t sswf::TagSound::ParseTag | ( | swf_tag_t | tag,
|  | const Data & | data |
| ) |  |  | `[private, virtual]`

Implements sswf::TagBase.

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.

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.

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

Referenced by CheckMP3Header().

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

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

Referenced by Resample(), and SetData().

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

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

Referenced by SetData().

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.

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

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.

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

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

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

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)

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

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.

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

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.

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

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.

References SWF_TYPE_DEFINE, and SWF_TYPE_HAS_ID.

## Member Data Documentation

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

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

int sswf::TagSound::f_data_maxsize`[private]`

Referenced by LoadMP3File(), and TagSound().

int sswf::TagSound::f_data_size`[private]`

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

sound_format_t sswf::TagSound::f_format`[private]`

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

int sswf::TagSound::f_latency_seek`[private]`

Referenced by Save(), and TagSound().

int sswf::TagSound::f_rate`[private]`

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

size_t sswf::TagSound::f_samples`[private]`

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

bool sswf::TagSound::f_stereo`[private]`

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

int sswf::TagSound::f_width`[private]`

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

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

Referenced by CheckMP3Header().

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

Referenced by CheckMP3Header().

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

Referenced by SetData().

The documentation for this class was generated from the following files:

- libsswf.h
- libsswf_tag_sound.c++