Firelight Technologies FMOD Studio API

FMOD_CREATESOUNDEXINFO

Use this structure with System::createSound when more control is needed over loading. The possible reasons to use this with System::createSound are:

• Loading a file from memory.
• Loading a file from within another larger (possibly wad/pak) file, by giving the loader an offset and length.
• To create a user created / non file based sound.
• To specify a starting subsound to seek to within a multi-sample sounds (ie FSB/DLS) when created as a stream.
• To specify which subsounds to load for multi-sample sounds (ie FSB/DLS) so that memory is saved and only a subset is actually loaded/read from disk.
• To specify 'piggyback' read and seek callbacks for capture of sound data as fmod reads and decodes it. Useful for ripping decoded PCM data from sounds as they are loaded / played.
• To specify a MIDI DLS sample set file to load when opening a MIDI file.

See below on what members to fill for each of the above types of sound you want to create.

C/C++ Syntax

typedef struct {
  int cbsize;
  unsigned int length;
  unsigned int fileoffset;
  int numchannels;
  int defaultfrequency;
  FMOD_SOUND_FORMAT format;
  unsigned int decodebuffersize;
  int initialsubsound;
  int numsubsounds;
  int *inclusionlist;
  int inclusionlistnum;
  FMOD_SOUND_PCMREAD_CALLBACK pcmreadcallback;
  FMOD_SOUND_PCMSETPOS_CALLBACK pcmsetposcallback;
  FMOD_SOUND_NONBLOCK_CALLBACK nonblockcallback;
  const char *dlsname;
  const char *encryptionkey;
  int maxpolyphony;
  void *userdata;
  FMOD_SOUND_TYPE suggestedsoundtype;
  FMOD_FILE_OPEN_CALLBACK fileuseropen;
  FMOD_FILE_CLOSE_CALLBACK fileuserclose;
  FMOD_FILE_READ_CALLBACK fileuserread;
  FMOD_FILE_SEEK_CALLBACK fileuserseek;
  FMOD_FILE_ASYNCREAD_CALLBACK fileuserasyncread;
  FMOD_FILE_ASYNCCANCEL_CALLBACK fileuserasynccancel;
  void *fileuserdata;
  int filebuffersize;
  FMOD_CHANNELORDER channelorder;
  FMOD_CHANNELMASK channelmask;
  FMOD_SOUNDGROUP *initialsoundgroup;
  unsigned int initialseekposition;
  FMOD_TIMEUNIT initialseekpostype;
  int ignoresetfilesystem;
  unsigned int audioqueuepolicy;
  unsigned int minmidigranularity;
  int nonblockthreadid;
  FMOD_GUID *fsbguid;
} FMOD_CREATESOUNDEXINFO;

JavaScript Syntax

struct FMOD_CREATESOUNDEXINFO
{
  length,
  fileoffset,
  numchannels,
  defaultfrequency,
  format,
  decodebuffersize,
  initialsubsound,
  numsubsounds,
  inclusionlistnum,
  pcmreadcallback,
  pcmsetposcallback,
  nonblockcallback,
  dlsname,
  encryptionkey,
  maxpolyphony,
  userdata,
  suggestedsoundtype,
  fileuseropen,
  fileuserclose,
  fileuserread,
  fileuserseek,
  fileuserasyncread,
  fileuserasynccancel,
  fileuserdata,
  filebuffersize,
  channelorder,
  channelmask,
  initialsoundgroup,
  initialseekposition,
  initialseekpostype,
  ignoresetfilesystem,
  audioqueuepolicy,
  minmidigranularity,
  nonblockthreadid,
};

Members

cbsize

[w] Size of this structure. This is used so the structure can be expanded in the future and still work on older versions of FMOD Studio.

length

[w] Optional. Specify 0 to ignore. Number of bytes to load starting at 'fileoffset', or size of sound to create (if FMOD_OPENUSER is used). Required if loading from memory. If 0 is specified, then it will use the size of the file (unless loading from memory then an error will be returned).

fileoffset

[w] Optional. Specify 0 to ignore. Offset from start of the file to start loading from. This is useful for loading files from inside big data files.

numchannels

[w] Optional. Specify 0 to ignore. Number of channels in a sound mandatory if FMOD_OPENUSER or FMOD_OPENRAW is used. Can be specified up to FMOD_MAX_CHANNEL_WIDTH.

defaultfrequency

[w] Optional. Specify 0 to ignore. Default frequency of sound in Hz, mandatory if FMOD_OPENUSER or FMOD_OPENRAW is used. Other formats use the frequency determined by the file format.

format

[w] Optional. Specify 0 or FMOD_SOUND_FORMAT_NONE to ignore. Format of the sound, mandatory if FMOD_OPENUSER or FMOD_OPENRAW is used. Other formats use the format determined by the file format.

decodebuffersize

[w] Optional. Specify 0 to ignore. For streams. This determines the size of the double buffer (in PCM samples) that a stream uses. Use this for user created streams if you want to determine the size of the callback buffer passed to you. Specify 0 to use FMOD's default size which is currently equivalent to 400ms of the sound format created/loaded.

initialsubsound

[w] Optional. Specify 0 to ignore. In a multi-sample file format such as .FSB/.DLS, specify the initial subsound to seek to, only if FMOD_CREATESTREAM is used.

numsubsounds

[w] Optional. Specify 0 to ignore or have no subsounds. In a sound created with FMOD_OPENUSER, specify the number of subsounds that are accessable with Sound::getSubSound. If not created with FMOD_OPENUSER, this will limit the number of subsounds loaded within a multi-subsound file. If using FSB, then if FMOD_CREATESOUNDEXINFO::inclusionlist is used, this will shuffle subsounds down so that there are not any gaps. It will mean that the indices of the sounds will be different.

inclusionlist

[w] Optional. Specify 0 to ignore. In a multi-sample format such as .FSB/.DLS it may be desirable to specify only a subset of sounds to be loaded out of the whole file. This is an array of subsound indices to load into memory when created. A single subsound index can be encoded in-place by setting inclusionlistnum to 0, setting the low bit of inclusionlist to 1 and OR the index into inclusionlist shifted left by 1 (optional advanced technique to avoid pointing to additional memory).

inclusionlistnum

[w] Optional. Specify 0 to ignore. This is the number of integers contained within the inclusionlist array.

pcmreadcallback

[w] Optional. Specify 0 to ignore. Callback to 'piggyback' on FMOD's read functions and accept or even write PCM data while FMOD is opening the sound. Used for user sounds created with FMOD_OPENUSER or for capturing decoded data as FMOD reads it.

pcmsetposcallback

[w] Optional. Specify 0 to ignore. Callback for when the user calls a seeking function such as Channel::setTime or Channel::setPosition within a multi-sample sound, and for when it is opened.

nonblockcallback

[w] Optional. Specify 0 to ignore. Callback for successful completion, or error while loading a sound that used the FMOD_NONBLOCKING flag. Also called duing seeking, when setPosition is called or a stream is restarted.

dlsname

[w] Optional. Specify 0 to ignore. Filename for a DLS sample set when loading a MIDI file. If not specified, on Windows it will attempt to open /windows/system32/drivers/gm.dls or /windows/system32/drivers/etc/gm.dls, on Mac it will attempt to load /System/Library/Components/CoreAudio.component/Contents/Resources/gs_instruments.dls, otherwise the MIDI will fail to open. Current DLS support is for level 1 of the specification.

encryptionkey

[w] Optional. Specify 0 to ignore. Key for encrypted FSB file. Without this key an encrypted FSB file will not load.

maxpolyphony

[w] Optional. Specify 0 to ignore. For sequenced formats with dynamic channel allocation such as .MID and .IT, this specifies the maximum voice count allowed while playing. .IT defaults to 64. .MID defaults to 32.

userdata

[w] Optional. Specify 0 to ignore. This is user data to be attached to the sound during creation. Access via Sound::getUserData. Note: This is not passed to FMOD_FILE_OPEN_CALLBACK - use fileuserdata for that.

suggestedsoundtype

[w] Optional. Specify 0 or FMOD_SOUND_TYPE_UNKNOWN to ignore. Instead of scanning all codec types, use this to speed up loading by making it jump straight to this codec.

fileuseropen

[w] Optional. Specify 0 to ignore. Callback for opening this file.

fileuserclose

[w] Optional. Specify 0 to ignore. Callback for closing this file.

fileuserread

[w] Optional. Specify 0 to ignore. Callback for reading from this file.

fileuserseek

[w] Optional. Specify 0 to ignore. Callback for seeking within this file.

fileuserasyncread

[w] Optional. Specify 0 to ignore. Callback for seeking within this file.

fileuserasynccancel

[w] Optional. Specify 0 to ignore. Callback for seeking within this file.

fileuserdata

[w] Optional. Specify 0 to ignore. User data to be passed into the file callbacks.

filebuffersize

[w] Optional. Specify 0 to ignore. Buffer size for reading the file, -1 to disable buffering, or 0 for system default.

channelorder

[w] Optional. Specify 0 to ignore. Use this to differ the way fmod maps multichannel sounds to speakers. See FMOD_CHANNELORDER for more.

channelmask

[w] Optional. Specify 0 to ignore. Use this to specify which channels map to which speakers. See FMOD_CHANNELMASK for more.

initialsoundgroup

[w] Optional. Specify 0 to ignore. Specify a sound group if required, to put sound in as it is created.

initialseekposition

[w] Optional. Specify 0 to ignore. For streams. Specify an initial position to seek the stream to.

initialseekpostype

[w] Optional. Specify 0 to ignore. For streams. Specify the time unit for the position set in initialseekposition.

ignoresetfilesystem

[w] Optional. Specify 0 to ignore. Set to 1 to use fmod's built in file system. Ignores setFileSystem callbacks and also FMOD_CREATESOUNEXINFO file callbacks. Useful for specific cases where you don't want to use your own file system but want to use fmod's file system (ie net streaming).

audioqueuepolicy

[w] Optional. Specify 0 or FMOD_AUDIOQUEUE_CODECPOLICY_DEFAULT to ignore. Policy used to determine whether hardware or software is used for decoding, see FMOD_AUDIOQUEUE_CODECPOLICY for options (iOS >= 3.0 required, otherwise only hardware is available)

minmidigranularity

[w] Optional. Specify 0 to ignore. Allows you to set a minimum desired MIDI mixer granularity. Values smaller than 512 give greater than default accuracy at the cost of more CPU and vice versa. Specify 0 for default (512 samples).

nonblockthreadid

[w] Optional. Specify 0 to ignore. Specifies a thread index to execute non blocking load on. Allows for up to 5 threads to be used for loading at once. This is to avoid one load blocking another. Maximum value = 4.

fsbguid

[r/w] Optional. Specify 0 to ignore. Allows you to provide the GUID lookup for cached FSB header info. Once loaded the GUID will be written back to the pointer. This is to avoid seeking and reading the FSB header.

Remarks

This structure is optional! Specify 0 or NULL in System::createSound if you don't need it!

Loading a file from memory.

• Create the sound using the FMOD_OPENMEMORY flag.
• Mandatory. Specify 'length' for the size of the memory block in bytes.
• Other flags are optional.

Loading a file from within another larger (possibly wad/pak) file, by giving the loader an offset and length.

• Mandatory. Specify 'fileoffset' and 'length'.
• Other flags are optional.

To create a user created / non file based sound.

• Create the sound using the FMOD_OPENUSER flag.
• Mandatory. Specify 'defaultfrequency, 'numchannels' and 'format'.
• Other flags are optional.

To specify a starting subsound to seek to and flush with, within a multi-sample stream (ie FSB/DLS).

• Mandatory. Specify 'initialsubsound'.

To specify which subsounds to load for multi-sample sounds (ie FSB/DLS) so that memory is saved and only a subset is actually loaded/read from disk.

• Mandatory. Specify 'inclusionlist' and 'inclusionlistnum'.

To specify 'piggyback' read and seek callbacks for capture of sound data as fmod reads and decodes it. Useful for ripping decoded PCM data from sounds as they are loaded / played.

• Mandatory. Specify 'pcmreadcallback' and 'pcmseekcallback'.

To specify a MIDI DLS sample set file to load when opening a MIDI file.

• Mandatory. Specify 'dlsname'.

Setting the 'decodebuffersize' is for cpu intensive codecs that may be causing stuttering, not file intensive codecs (ie those from CD or netstreams) which are normally altered with System::setStreamBufferSize. As an example of cpu intensive codecs, an mp3 file will take more cpu to decode than a PCM wav file.

If you have a stuttering effect, then it is using more cpu than the decode buffer playback rate can keep up with. Increasing the decode buffersize will most likely solve this problem.

FSB codec. If inclusionlist and numsubsounds are used together, this will trigger a special mode where subsounds are shuffled down to save memory. (useful for large FSB files where you only want to load 1 sound). There will be no gaps, ie no null subsounds. As an example, if there are 10,000 subsounds and there is an inclusionlist with only 1 entry, and numsubsounds = 1, then subsound 0 will be that entry, and there will only be the memory allocated for 1 subsound. Previously there would still be 10,000 subsound pointers and other associated codec entries allocated along with it multiplied by 10,000.

Members marked with [r] mean the variable is modified by FMOD and is for reading purposes only. Do not change this value.
Members marked with [w] mean the variable can be written to. The user can set the value.

JavaScript only :

Not all fields are currently supported or may not work as expected at this time. To initialize an new instance in javascript use "FMOD.CREATESOUNDEXINFO()", no 'new' keyword is required.

See Also

• System::createSound
• System::setStreamBufferSize
• FMOD_MODE
• FMOD_SOUND_FORMAT
• FMOD_SOUND_TYPE
• FMOD_CHANNELMASK
• FMOD_CHANNELORDER
• FMOD_MAX_CHANNEL_WIDTH

Version 1.10.03 Built on Feb 1, 2018