9. Plug-in API Reference | Codec

An interface that manages codec plug-ins.

General:

• FMOD_CODEC_DESCRIPTION Codec description.
• FMOD_CODEC_STATE Codec state structure that is passed into each callback.
• FMOD_CODEC_STATE_FUNCTIONS Struct containing functions to give plug-in developers the ability to query system state and access system level functionality and helpers.
• FMOD_CODEC_WAVEFORMAT Codec wave format.

• 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_GETWAVEFORMAT_CALLBACK Codec get wave format 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_ALLOC_FUNC Codec allocate memory function.
• FMOD_CODEC_FREE_FUNC Codec free memory function.
• FMOD_CODEC_FILE_READ_FUNC Codec file read function.
• FMOD_CODEC_FILE_SEEK_FUNC Codec file seek function.
• FMOD_CODEC_FILE_SIZE_FUNC Codec file size function.
• FMOD_CODEC_FILE_TELL_FUNC Codec file function to retrieve the current file position.
• FMOD_CODEC_LOG_FUNC Codec log function.
• FMOD_CODEC_METADATA_FUNC Codec metadata function.

• FMOD_CODEC_PLUGIN_VERSION The codec plug-in API version the plug-in was built with.
• FMOD_CODEC_SEEK_METHOD File seek methods.

FMOD_CODEC_ALLOC_FUNC

Codec allocate memory function.

void * F_CALL FMOD_CODEC_ALLOC_FUNC(
  unsigned int size,
  unsigned int align,
  const char *file,
  int line
);

size

Allocation size.

• Units: Bytes

align

Memory alignment.

• Units: Bytes

file

Source code file name where the allocation was requested.

line

Line of allocation in file.

See Also: FMOD_CODEC_STATE

FMOD_CODEC_CLOSE_CALLBACK

Codec close callback.

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

FMOD_RESULT F_CALL FMOD_CODEC_CLOSE_CALLBACK(
  FMOD_CODEC_STATE *codec_state
);

codec_state

Codec state. (FMOD_CODEC_STATE)

Invoked by:

• Sound::release

See Also: FMOD_CODEC_DESCRIPTION, FMOD_CODEC_OPEN_CALLBACK, FMOD_CODEC_SOUNDCREATE_CALLBACK

FMOD_CODEC_DESCRIPTION

Codec description.

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

typedef struct FMOD_CODEC_DESCRIPTION {
  unsigned int                        apiversion;
  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
{
  apiversion,
  name,
  version,
  defaultasstream,
  timeunits,
  open,
  close,
  read,
  getlength,
  setposition,
  getposition,
  soundcreate,
  getwaveformat,
};

apiversion

The codec plug-in API version this plug-in is built for. Set to this to FMOD_CODEC_PLUGIN_VERSION.

name

Name of the codec.

version

Plug-in'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_FILE_READ_FUNC

Codec file read function.

FMOD_RESULT F_CALL FMOD_CODEC_FILE_READ_FUNC(
  FMOD_CODEC_STATE *codec_state,
  void *buffer,
  unsigned int sizebytes,
  unsigned int *bytesread
);

codec_state

Codec state. (FMOD_CODEC_STATE)

buffer Out

Buffer to read data into.

sizebytes

Number of bytes to read into buffer.

• Units: Bytes

bytesread Out

Number of bytes read into buffer.

• Units: Bytes

If there is not enough data to read the requested number of bytes, return fewer bytes in the bytesread parameter and and return FMOD_ERR_FILE_EOF.

See Also: FMOD_CODEC_FILE_SEEK_FUNC, FMOD_CODEC_FILE_TELL_FUNC, FMOD_CODEC_FILE_SIZE_FUNC

FMOD_CODEC_FILE_SEEK_FUNC

Codec file seek function.

FMOD_RESULT F_CALL FMOD_CODEC_FILE_SEEK_FUNC(
  FMOD_CODEC_STATE *codec_state,
  unsigned int pos,
  FMOD_CODEC_SEEK_METHOD method
);

codec_state

Codec state. (FMOD_CODEC_STATE)

pos

Absolute position to seek to in file with respect to the seek method.

• Units: Bytes

method

Method of seeking. (FMOD_CODEC_SEEK_METHOD)

See Also: FMOD_CODEC_FILE_READ_FUNC, FMOD_CODEC_FILE_TELL_FUNC, FMOD_CODEC_FILE_SIZE_FUNC

FMOD_CODEC_FILE_SIZE_FUNC

Codec file size function.

FMOD_RESULT F_CALL FMOD_CODEC_FILE_SIZE_FUNC(
  FMOD_CODEC_STATE *codec_state,
  unsigned int *size
);

codec_state

Codec state. (FMOD_CODEC_STATE)

size Out

Size of the file.

• Units: Bytes

See Also: FMOD_CODEC_FILE_READ_FUNC, FMOD_CODEC_FILE_SEEK_FUNC, FMOD_CODEC_FILE_TELL_FUNC

FMOD_CODEC_FILE_TELL_FUNC

Codec file function to retrieve the current file position.

FMOD_RESULT F_CALL FMOD_CODEC_FILE_TELL_FUNC(
  FMOD_CODEC_STATE *codec_state,
  unsigned int *pos
);

codec_state

Codec state. (FMOD_CODEC_STATE)

pos Out

Current absolute position in file.

• Units: Bytes

See Also: FMOD_CODEC_FILE_READ_FUNC, FMOD_CODEC_FILE_SEEK_FUNC, FMOD_CODEC_FILE_SIZE_FUNC

FMOD_CODEC_FREE_FUNC

Codec free memory function.

void F_CALL FMOD_CODEC_FREE_FUNC(
  void *ptr,
  const char *file,
  int line
);

ptr

Allocation pointer.

file

Source code file name where the allocation is freed.

line

Line of free call in file.

See Also: FMOD_CODEC_STATE

FMOD_CODEC_GETLENGTH_CALLBACK

Codec get length callback.

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

FMOD_RESULT F_CALL 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.

FMOD_RESULT F_CALL 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.

FMOD_RESULT F_CALL 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_LOG_FUNC

Codec log function.

Call this function in an codec plug-in context to utilize FMOD's debugging system.

void F_CALL FMOD_CODEC_LOG_FUNC(
  FMOD_DEBUG_FLAGS level,
  const char *file,
  int line,
  const char *function,
  const char *string,
  ...
);

level

Log type or level. (FMOD_DEBUG_FLAGS)

file

Source code file name from where the log is called. (UTF-8 string)

line

Line of log call in file.

function

Name of the logging function. (UTF-8 string)

string

Log codec string. (UTF-8 string)

See Also: FMOD_CODEC_STATE

FMOD_CODEC_METADATA_FUNC

Codec metadata function.

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

FMOD_RESULT F_CALL 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.

FMOD_RESULT F_CALL 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)

• Default: FMOD_DEFAULT

userexinfo Opt

Extra info structure that the user supplied via System::createSound or System::createStream. (FMOD_CREATESOUNDEXINFO)

Invoked by:

• System::createSound
• System::createStream

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.

See Also: FMOD_CODEC_DESCRIPTION, FMOD_CODEC_CLOSE_CALLBACK, FMOD_CODEC_SOUNDCREATE_CALLBACK

FMOD_CODEC_PLUGIN_VERSION

The codec plug-in API version the plug-in was built with.

#define FMOD_CODEC_PLUGIN_VERSION   1

FMOD.CODEC_PLUGIN_VERSION

See Also: FMOD_CODEC_DESCRIPTION

FMOD_CODEC_READ_CALLBACK

Codec read callback.

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

FMOD_RESULT F_CALL 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_SEEK_METHOD

File seek methods.

#define FMOD_CODEC_SEEK_METHOD_SET     0
#define FMOD_CODEC_SEEK_METHOD_CURRENT 1
#define FMOD_CODEC_SEEK_METHOD_END     2

FMOD_CODEC_SEEK_METHOD_SET

Seeks from the beginning.

FMOD_CODEC_SEEK_METHOD_CURRENT

Seeks from the current position.

FMOD_CODEC_SEEK_METHOD_END

Seeks from the end.

See Also: FMOD_CODEC_FILE_SEEK_FUNC

FMOD_CODEC_SETPOSITION_CALLBACK

Codec set position callback.

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

FMOD_RESULT F_CALL 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.

See Also: Channel::getPosition, FMOD_CODEC_READ_CALLBACK, FMOD_CODEC_GETLENGTH_CALLBACK, FMOD_CODEC_GETPOSITION_CALLBACK

FMOD_CODEC_SOUNDCREATE_CALLBACK

Codec sound create callback.

This callback is called after a Sound is created.

FMOD_RESULT F_CALL 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:

• System::createSound
• System::createStream

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

See Also: System::createSound, System::createStream

FMOD_CODEC_STATE

Codec state structure that is passed into each callback.

typedef struct FMOD_CODEC_STATE {
  void                          *plugindata;
  FMOD_CODEC_WAVEFORMAT         *waveformat;
  FMOD_CODEC_STATE_FUNCTIONS    *functions;
  int                            numsubsounds;
} FMOD_CODEC_STATE;

FMOD_CODEC_STATE
{
  plugindata;
  waveformat;
  functions;
  numsubsounds,
};

plugindata

Data that the plugin writer wants to attach to this object.

waveformat Opt

Array of format structures containing information about each sound. (FMOD_CODEC_WAVEFORMAT)

functions R/O

Struct containing functions to give plug-in developers the ability to query system state, access system level functionality and helpers. (FMOD_CODEC_STATE_FUNCTIONS)

numsubsounds

Number of 'subsounds' in this sound. Anything other than 0 makes it a 'container' format.

'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 array 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_STATE_FUNCTIONS

Struct containing functions to give plug-in developers the ability to query system state and access system level functionality and helpers.

typedef struct FMOD_CODEC_STATE_FUNCTIONS {
    FMOD_CODEC_METADATA_FUNC     metadata;
    FMOD_CODEC_ALLOC_FUNC        alloc;
    FMOD_CODEC_FREE_FUNC         free;
    FMOD_CODEC_LOG_FUNC          log;
    FMOD_CODEC_FILE_READ_FUNC    read;
    FMOD_CODEC_FILE_SEEK_FUNC    seek;
    FMOD_CODEC_FILE_TELL_FUNC    tell;
    FMOD_CODEC_FILE_SIZE_FUNC    size;
} FMOD_CODEC_STATE_FUNCTIONS;

metadata R/O

This will return a callable FMOD metadata function to use from codec. (FMOD_CODEC_METADATA_FUNC)

alloc R/O

Function to allocate memory using the FMOD memory system. (FMOD_CODEC_ALLOC_FUNC)

free R/O

Function to free memory allocated with FMOD_CODEC_ALLOC_FUNC. (FMOD_CODEC_FREE_FUNC)

log R/O

Function to write to the FMOD logging system. (FMOD_CODEC_LOG_FUNC)

read R/O

Function to read using a file handle. (FMOD_CODEC_FILE_READ_FUNC)

seek R/O

Function to seek using a file handle. (FMOD_CODEC_FILE_SEEK_FUNC)

tell R/O

Function to get the current read cursor position of a file handle. (FMOD_CODEC_FILE_TELL_FUNC)

size R/O

Function to get the size using a file handle. (FMOD_CODEC_FILE_SIZE_FUNC)

See Also: FMOD_CODEC_STATE

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

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 audio 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.

See Also: FMOD_CODEC_STATE, FMOD_CODEC_DESCRIPTION