Product:

Version:

Search:

Plugin API Reference | Codec

FMOD API User Manual 2.00

9. Plugin API Reference | Codec

An interface that manages Codec plugins

Structures:

FMOD_CODEC_DESCRIPTION Codec description.
FMOD_CODEC_STATE Codec state structure that is passed into each callback.
FMOD_CODEC_WAVEFORMAT Codec wave format.
FMOD_CODEC_WAVEFORMAT_VERSION Codec Wave format version number.

Callbacks:

FMOD_CODEC_CLOSE_CALLBACK Codec close callback.
FMOD_CODEC_GETLENGTH_CALLBACK Codec get length callback.
FMOD_CODEC_GETPOSITION_CALLBACK Codec get position callback.
FMOD_CODEC_OPEN_CALLBACK Codec open callback.
FMOD_CODEC_READ_CALLBACK Codec read callback.
FMOD_CODEC_SETPOSITION_CALLBACK Codec set position callback.
FMOD_CODEC_SOUNDCREATE_CALLBACK Codec sound create callback.
FMOD_CODEC_GETWAVEFORMAT_CALLBACK Codec get wave format callback.

State function:

FMOD_CODEC_METADATA_FUNC Codec metadata function.

FMOD_CODEC_CLOSE_CALLBACK

Codec close callback.

This callback is called to shut down and release memory for the codec instance.

C++

FMOD_RESULT F_CALLBACK FMOD_CODEC_CLOSE_CALLBACK(
  FMOD_CODEC_STATE *codec_state
);

codec_state: Codec state. (FMOD_CODEC_STATE)

Invoked by:

Sound::release

FMOD_CODEC_DESCRIPTION

Codec description.

This description structure allows the plugin writer to define all functionality required for a user defined codec.

C++

typedef struct FMOD_CODEC_DESCRIPTION {
  const char                         *name;
  unsigned int                        version;
  int                                 defaultasstream;
  FMOD_TIMEUNIT                       timeunits;
  FMOD_CODEC_OPEN_CALLBACK            open;
  FMOD_CODEC_CLOSE_CALLBACK           close;
  FMOD_CODEC_READ_CALLBACK            read;
  FMOD_CODEC_GETLENGTH_CALLBACK       getlength;
  FMOD_CODEC_SETPOSITION_CALLBACK     setposition;
  FMOD_CODEC_GETPOSITION_CALLBACK     getposition;
  FMOD_CODEC_SOUNDCREATE_CALLBACK     soundcreate;
  FMOD_CODEC_GETWAVEFORMAT_CALLBACK   getwaveformat;
} FMOD_CODEC_DESCRIPTION;

FMOD_CODEC_DESCRIPTION
{
  name,
  version,
  defaultasstream,
  timeunits,
  open,
  close,
  read,
  getlength,
  setposition,
  getposition,
  soundcreate,
  getwaveformat,
};

name: Name of the codec.
version: Plugin writer's version number.
defaultasstream: Defaults as stream.
timeunits: Time units used with setposition codec. (FMOD_TIMEUNIT)
open: Open callback. (FMOD_CODEC_OPEN_CALLBACK)
close: Close callback. (FMOD_CODEC_CLOSE_CALLBACK)
read: Read callback. (FMOD_CODEC_READ_CALLBACK)
getlength: Get length callback. (FMOD_CODEC_GETLENGTH_CALLBACK)
setposition: Seek callback. (FMOD_CODEC_SETPOSITION_CALLBACK)
getposition: Get position callback. (FMOD_CODEC_GETPOSITION_CALLBACK)
soundcreate: Sound creation callback. (FMOD_CODEC_SOUNDCREATE_CALLBACK)
getwaveformat: Get wave format callback. (FMOD_CODEC_GETWAVEFORMAT_CALLBACK)

See Also: FMOD_CODEC_STATE, FMOD_CODEC_WAVEFORMAT

FMOD_CODEC_GETLENGTH_CALLBACK

Codec get length callback.

This callback is called to retrieve the length of the audio file of this codec type.

C++

FMOD_RESULT F_CALLBACK FMOD_CODEC_GETLENGTH_CALLBACK(
  FMOD_CODEC_STATE *codec_state,
  unsigned int *length,
  FMOD_TIMEUNIT lengthtype
);

codec_state: Codec state. (FMOD_CODEC_STATE)
length Out: Length of the sound in units determined by lengthtype.
lengthtype: Timeunit type of length. (FMOD_TIMEUNIT)

Invoked by:

Sound::getLength

See Also: FMOD_CODEC_DESCRIPTION

FMOD_CODEC_GETPOSITION_CALLBACK

Codec get position callback.

This callback is called to retrieve the current read position of the audio file of this codec type.

C++

FMOD_RESULT F_CALLBACK FMOD_CODEC_GETPOSITION_CALLBACK(
  FMOD_CODEC_STATE *codec_state,
  unsigned int *position,
  FMOD_TIMEUNIT postype
);

codec_state: Codec state. (FMOD_CODEC_STATE)
position Out: Codec position in units determined by postype.
postype: Time units for position. This will be one of the timeunits supplied by the codec author in the FMOD_CODEC_DESCRIPTION structure. (FMOD_TIMEUNIT)

Invoked by:

Channel::getPosition

See Also: FMOD_CODEC_DESCRIPTION

FMOD_CODEC_GETWAVEFORMAT_CALLBACK

Codec get wave format callback.

This callback is called to allow FMOD to retrieve the format of the file the codec instance represents.

C++

FMOD_RESULT F_CALLBACK FMOD_CODEC_GETWAVEFORMAT_CALLBACK(
  FMOD_CODEC_STATE *codec_state,
  int index,
  FMOD_CODEC_WAVEFORMAT *waveformat
);

codec_state: Codec state. (FMOD_CODEC_STATE)
index: Subsound index. This is only used in file formats which can store multiple sounds within them, otherwise it will be 0.
waveformat Out: Wave format of the sound object. (FMOD_CODEC_WAVEFORMAT)

Useful to reduce memory usage by limiting the number of FMOD_CODEC_WAVEFORMAT structures.

FMOD_CODEC_METADATA_FUNC

Codec metadata function.

This function is to be called when a codec's metadata is updated.

C++

FMOD_RESULT F_CALLBACK FMOD_CODEC_METADATA_FUNC(
  FMOD_CODEC_STATE *codec_state,
  FMOD_TAGTYPE tagtype,
  char *name,
  void *data,
  unsigned int datalen,
  FMOD_TAGDATATYPE datatype,
  int unique
);

codec_state

Codec state. (FMOD_CODEC_STATE)

tagtype

Source type of tag being updated. (FMOD_TAGTYPE)

name

Name of the tag being updated.

data

Contents of tag.

datalen

Data length of the tag data in bytes.

Units: Bytes

datatype

Data type of tag. (FMOD_TAGDATATYPE)

unique

Unique state. If this is true / non zero, then the tag (determined by the name) being updated is the only one of its type. If it is zero then there are multiple versions of this tag with the same name.

Codec metadata can be retrieved by the user with Sound::getTag

Codec metadata can be added during creation, or during playback. A common case for play time metadata is internet based streams.

See Also: FMOD_CODEC_DESCRIPTION

FMOD_CODEC_OPEN_CALLBACK

Codec open callback.

This callback is called to initialize a codec instance using the codec's file handle to verify if the file is of the type of the codec, and to do any file reading required for initialization of the codec.

C++

FMOD_RESULT F_CALLBACK FMOD_CODEC_OPEN_CALLBACK(
  FMOD_CODEC_STATE *codec_state,
  FMOD_MODE usermode,
  FMOD_CREATESOUNDEXINFO *userexinfo
);

codec_state: Codec state. Use this to access codec specific variables, the FMOD file system for reading/seeking, and codec user data. (FMOD_CODEC_STATE)
usermode Opt: Mode that the user supplied via System::createSound or System::createStream. (FMOD_MODE)
userexinfo Opt: Extra info structure that the user supplied via System::createSound or System::createStream. (FMOD_CREATESOUNDEXINFO)

Invoked by:

Implementation detail:

This callback is where the file format check is done, memory is allocated, and the codec is initialized.

The usermode and userexinfo parameters tell the codec what was passed in by the user. Generally these can be ignored, as the file format usually determines the format and frequency of the sound. If you have a flexible format codec (ie you don't mind what output format your codec writes to), you might want to use the parameter that was passed in by the user to specify the output sound format / frequency.

Read and seek within the file using the fileread and fileseek members of the FMOD_CODEC_STATE structure that is passed in.

Note!: Do not use your own filesystem.

The reasons for this are:

The user may have set their own file system via user filesystem callbacks.
FMOD allows file reading via disk, memory and TCP/IP. If you use your own file routines you will lose this ability.

Important! FMOD will ping all codecs trying to find the right one for the file the user has passed in. Make sure the first line of your codec open is a FAST format check. Ie it reads an identifying string, checks it and returns an error FMOD_ERR_FORMAT if it is not found.

FMOD_CODEC_READ_CALLBACK

Codec read callback.

This callback is called to read PCM data from the codec instance.

C++

FMOD_RESULT F_CALLBACK FMOD_CODEC_READ_CALLBACK(
  FMOD_CODEC_STATE *codec_state,
  void *buffer,
  unsigned int samples_in,
  unsigned int *samples_out
);

codec_state

Codec state. (FMOD_CODEC_STATE)

buffer

Target PCM data buffer. Note that the format of this data is the format described in FMOD_CODEC_WAVEFORMAT.

Units: Sample Data

samples_in

Number of PCM samples to decode

Units: Samples

samples_out

Number of PCM samples decoded

Units: Samples

This callback is issued when FMOD tries to read some data from the file to the destination format (the format specified in the FMOD_CODEC_OPEN_CALLBACK).

Implementation detail:

If you cannot read number of samples requested, simply return FMOD_OK and give samples_out the number of samples you decoded.

Read and seek within the file using the fileread and fileseek members of the FMOD_CODEC_STATE structure that is passed in.

Note!: Do not use your own filesystem.

The reasons for this are:

The user may have set their own file system via user filesystem callbacks.
FMOD allows file reading via disk, memory and TCP/IP. If you use your own file routines you will lose this ability.

See Also: FMOD_CODEC_DESCRIPTION

FMOD_CODEC_SETPOSITION_CALLBACK

Codec set position callback.

This callback is called to set the audible position of a codec instance.

C++

FMOD_RESULT F_CALLBACK FMOD_CODEC_SETPOSITION_CALLBACK(
  FMOD_CODEC_STATE *codec_state,
  int subsound,
  unsigned int position,
  FMOD_TIMEUNIT postype
);

codec_state: Codec state. (FMOD_CODEC_STATE)
subsound: Subsound within which to seek. This is only used in file formats which can store multiple sounds within them, otherwise it will be 0.
position: Seek position in units determined by postype.
postype: Time units for position. This will be one of the timeunits supplied by the codec author in the FMOD_CODEC_DESCRIPTION structure. (FMOD_TIMEUNIT)

Invoked by:

Channel::setPosition
Looping streams in the stream thread

Implementation detail:

Read and seek within the file using the fileread and fileseek members of the FMOD_CODEC_STATE structure that is passed in.

Note!: Do not use your own filesystem.

The reasons for this are:

The user may have set their own file system via user filesystem callbacks.
FMOD allows file reading via disk, memory and TCP/IP. If you use your own file routines you will lose this ability.

FMOD_CODEC_SOUNDCREATE_CALLBACK

Codec sound create callback.

This callback is called after a Sound is created.

C++

FMOD_RESULT F_CALLBACK FMOD_CODEC_SOUNDCREATE_CALLBACK(
  FMOD_CODEC_STATE *codec_state,
  int subsound,
  FMOD_SOUND *sound
);

codec_state: Codec state. (FMOD_CODEC_STATE)
subsound: Subsound index being created. This is only used in file formats which can store multiple sounds within them, otherwise it will be 0.
sound Out: Newly created Sound object. (Sound)

Invoked by:

Useful so the codec can set more parameters for the related created sound.

FMOD_CODEC_STATE

Codec state structure that is passed into each callback.

C++

typedef struct FMOD_CODEC_STATE {
  int                            numsubsounds;
  FMOD_CODEC_WAVEFORMAT         *waveformat;
  void                          *plugindata;
  void                          *filehandle;
  unsigned int                   filesize;
  FMOD_FILE_READ_CALLBACK        fileread;
  FMOD_FILE_SEEK_CALLBACK        fileseek;
  FMOD_CODEC_METADATA_FUNC       metadata;
  int                            waveformatversion;
} FMOD_CODEC_STATE;

FMOD_CODEC_STATE
{
  numsubsounds,
  plugindata,
  filehandle,
  filesize,
  fileread,
  fileseek,
  metadata,
  waveformatversion,
};

numsubsounds: Number of 'subsounds' in this sound. Anything other than 0 makes it a 'container' format.
waveformat Opt: Array of format structures containing information about each sound. (FMOD_CODEC_WAVEFORMAT)
plugindata: Plugin writer created data the codec author wants to attach to this object.
filehandle R/O: This will return an internal FMOD file handle to use with the callbacks provided.
filesize R/O: This will contain the size of the file in bytes.
fileread R/O: This will return a callable FMOD file function to use from codec. (FMOD_FILE_READ_CALLBACK)
fileseek R/O: This will return a callable FMOD file function to use from codec. (FMOD_FILE_SEEK_CALLBACK)
metadata R/O: This will return a callable FMOD metadata function to use from codec. (FMOD_CODEC_METADATA_FUNC)
waveformatversion: Must be set to FMOD_CODEC_WAVEFORMAT_VERSION in the FMOD_CODEC_OPEN_CALLBACK.

'numsubsounds' should be 1+ if the file is a container format, and does not contain wav data itself. Examples of these types would be FSB (contains multiple sounds), DLS (contain instruments).

The waveformat value should point to an arrays of information based on how many subsounds are in the format. If the number of subsounds is 0 then it should point to 1 waveformat, the same as if the number of subsounds was 1. If subsounds was 100 for example, there should be a pointer to an array of 100 waveformat structures.

When a sound has 1 or more subsounds, the caller must play the individual sounds specified by first obtaining the subsound with Sound::getSubSound.

FMOD_CODEC_WAVEFORMAT

Codec wave format.

This structure defines the attributes of a sound, and determines the format of the Sound object when it is created with System::createSound or System::createStream

C++

typedef struct FMOD_CODEC_WAVEFORMAT {
  const char*         name;
  FMOD_SOUND_FORMAT   format;
  int                 channels;
  int                 frequency;
  unsigned int        lengthbytes;
  unsigned int        lengthpcm;
  unsigned int        pcmblocksize;
  int                 loopstart;
  int                 loopend;
  FMOD_MODE           mode;
  FMOD_CHANNELMASK    channelmask;
  FMOD_CHANNELORDER   channelorder;
  float               peakvolume;
} FMOD_CODEC_WAVEFORMAT;

FMOD_CODEC_WAVEFORMAT
{
  name,
  format,
  channels,
  frequency,
  lengthbytes,
  lengthpcm,
  pcmblocksize,
  loopstart,
  loopend,
  mode,
  channelmask,
  channelorder,
  peakvolume,
};

name Opt

Name of sound. The codec must own the lifetime of the string memory until the codec is destroyed. (UTF-8 string)

format

Format for codec output. (FMOD_SOUND_FORMAT)

channels

Number of channels.

frequency

Default frequency of the codec.

Units: Hertz

lengthbytes Opt

Length of the source data. Used for FMOD_TIMEUNIT_RAWBYTES.

Units: Bytes

lengthpcm

Length of the file. Used for Sound::getLength and for memory allocation of static decompressed sample data.

Units: Samples

pcmblocksize Opt

Minimum, optimal number of decompressed PCM samples codec can handle.

loopstart Opt

Loop start position.

Units: Samples

loopend Opt

Loop end position.

Units: Samples

mode Opt

Default sound loading mode. (FMOD_MODE)

Default: FMOD_DEFAULT

channelmask Opt

Channel bitmask to describe which speakers the channels in the codec map to, in order of channel count. (FMOD_CHANNELMASK)

channelorder Opt

Channel order type that describes where each sound channel should pan for the number of channels specified. (FMOD_CHANNELORDER)

peakvolume Opt

Peak volume of sound.

The format, channels, frequency and lengthpcm tell FMOD what sort of sound buffer to create when you initialize your code.

If you wrote an MP3 codec that decoded to stereo 16bit integer PCM for a 44khz sound, you would specify FMOD_SOUND_FORMAT_PCM16, and channels would be equal to 2, and frequency would be 44100.

1.07 Note. 'blockalign' member which was in bytes has been removed. 'pcmblocksize' is now the replacement, and is measured in PCM samples only, not bytes. This is purely to support buffering
internal to FMOD for codecs that are not sample accurate.

Note: When registering a codec, format, channels, frequency and lengthpcm must be supplied, otherwise there will be an error.

This structure is optional if FMOD_CODEC_GETWAVEFORMAT_CALLBACK is specified.

An array of these structures may be needed if FMOD_CODEC_STATE::numsubsounds is larger than 1.

FMOD_CODEC_WAVEFORMAT_VERSION

Codec Wave format version number.

Use this for binary compatibility of the FMOD_CODEC_WAVEFORMAT structure and for future expansion.

C++

#define FMOD_CODEC_WAVEFORMAT_VERSION   3

FMOD.CODEC_WAVEFORMAT_VERSION

FMOD_CODEC_WAVEFORMAT_VERSION
:

Should be set into FMOD_CODEC_STATE in the FMOD_CODEC_OPEN_CALLBACK.

The version here represents the version of the FMOD_CODEC_WAVEFORMAT structure, which has evolved over time in FMOD. The FMOD_CODEC_STATE contains the waveformat member with the structure in question.

See Also: FMOD_CODEC_DESCRIPTION