FMOD Engine User Manual 2.03

9. Plug-in API Reference | Codec

An interface that manages codec plug-ins.

General:




FMOD_CODEC_ALLOC_FUNC

Codec allocate memory function.

C
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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.

C
C++
JS

FMOD_RESULT F_CALL FMOD_CODEC_CLOSE_CALLBACK(
  FMOD_CODEC_STATE *codec_state
);

Not supported for C#.

Not supported for JavaScript.

codec_state
Codec state. (FMOD_CODEC_STATE)

Invoked by:

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.

C
C++
JS

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

Currently not supported for C#.

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.

C
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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.

C
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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.

C
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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.

C
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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.

C
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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.

C
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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:

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
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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:

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
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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.

C
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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.

C
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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:

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.

C
C++
JS

#define FMOD_CODEC_PLUGIN_VERSION   1
FMOD.CODEC_PLUGIN_VERSION

Currently not supported for C#.

See Also: FMOD_CODEC_DESCRIPTION

FMOD_CODEC_READ_CALLBACK

Codec read callback.

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

C
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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.

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:

See Also: FMOD_CODEC_DESCRIPTION

FMOD_CODEC_SEEK_METHOD

File seek methods.

C
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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.

C
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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:

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:

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.

C
C++
JS

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

Not supported for C#.

Not supported for JavaScript.

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.

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

FMOD_CODEC_STATE

Codec state structure that is passed into each callback.

C
C++
JS

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

Not supported for C#.

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.

C
C++
JS

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;

Not supported for C#.

Not supported for JavaScript.

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

C
C++
JS

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

Currently not supported for C#.

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)

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