7. Core API Reference | Channel

A source of audio signal that connects to the ChannelGroup mixing hierarchy.

Create with System::playSound or System::playDSP.

Playback control:

• Channel::setFrequency Sets the frequency or playback rate.
• Channel::getFrequency Retrieves the playback frequency or playback rate.
• Channel::setPriority Sets the priority used for virtual Channel ordering.
• Channel::getPriority Retrieves the priority used for virtual Channel ordering.
• Channel::setPosition Sets the current playback position.
• Channel::getPosition Retrieves the current playback position.
• Channel::setChannelGroup Sets the ChannelGroup this object outputs to.
• Channel::getChannelGroup Retrieves the ChannelGroup this object outputs to.
• Channel::setLoopCount Sets the number of times to loop before stopping.
• Channel::getLoopCount Retrieves the number of times to loop before stopping.
• Channel::setLoopPoints Sets the loop start and end points.
• Channel::getLoopPoints Retrieves the loop start and end points.

Information:

• Channel::isVirtual Retrieves whether the Channel is being emulated by the virtual Channel system.
• Channel::getCurrentSound Retrieves the currently playing Sound.
• Channel::getIndex Retrieves the index of this object in the System Channel pool.

The following APIs are inherited from ChannelControl:

Playback:

• ChannelControl::isPlaying Retrieves the playing state.
• ChannelControl::stop Stops the Channel (or all Channels in nested ChannelGroups) from playing.
• ChannelControl::setPaused Sets the paused state.
• ChannelControl::getPaused Retrieves the paused state.
• ChannelControl::setMode Sets the playback mode that controls how this object behaves.
• ChannelControl::getMode Retrieves the playback mode bits that control how this object behaves.
• ChannelControl::setPitch Sets the relative pitch / playback rate.
• ChannelControl::getPitch Retrieves the relative pitch / playback rate.

Volume levels:

• ChannelControl::getAudibility Retrieves an estimation of the output volume.
• ChannelControl::setVolume Sets the volume level.
• ChannelControl::getVolume Retrieves the volume level.
• ChannelControl::setVolumeRamp Sets whether volume changes are ramped or instantaneous.
• ChannelControl::getVolumeRamp Retrieves whether volume changes are ramped or instantaneous.
• ChannelControl::setMute Sets the mute state.
• ChannelControl::getMute Retrieves the mute state.

Spatialization:

• ChannelControl::set3DAttributes Sets the 3D position and velocity used to apply panning, attenuation and doppler.
• ChannelControl::get3DAttributes Retrieves the 3D position and velocity used to apply panning, attenuation and doppler.
• ChannelControl::set3DConeOrientation Sets the orientation of a 3D cone shape, used for simulated occlusion.
• ChannelControl::get3DConeOrientation Retrieves the orientation of a 3D cone shape, used for simulated occlusion.
• ChannelControl::set3DConeSettings Sets the angles and attenuation levels of a 3D cone shape, for simulated occlusion which is based on direction.
• ChannelControl::get3DConeSettings Retrieves the angles and attenuation levels of a 3D cone shape, for simulated occlusion which is based on direction.
• ChannelControl::set3DCustomRolloff Sets a custom rolloff shape for 3D distance attenuation.
• ChannelControl::get3DCustomRolloff Retrieves the current custom rolloff shape for 3D distance attenuation.
• ChannelControl::set3DDistanceFilter Sets an override value for the 3D distance filter.
• ChannelControl::get3DDistanceFilter Retrieves the override values for the 3D distance filter.
• ChannelControl::set3DDopplerLevel Sets the amount by which doppler is scaled.
• ChannelControl::get3DDopplerLevel Retrieves the amount by which doppler is scaled.
• ChannelControl::set3DLevel Sets the blend between 3D panning and 2D panning.
• ChannelControl::get3DLevel Retrieves the blend between 3D panning and 2D panning.
• ChannelControl::set3DMinMaxDistance Sets the minimum and maximum distances used to calculate the 3D rolloff attenuation.
• ChannelControl::get3DMinMaxDistance Retrieves the minimum and maximum distances used to calculate the 3D rolloff attenuation.
• ChannelControl::set3DOcclusion Sets the 3D attenuation factors for the direct and reverb paths.
• ChannelControl::get3DOcclusion Retrieves the 3D attenuation factors for the direct and reverb paths.
• ChannelControl::set3DSpread Sets the spread of a 3D sound in speaker space.
• ChannelControl::get3DSpread Retrieves the spread of a 3D sound in speaker space.

Panning and level adjustment:

• ChannelControl::setPan Sets the left/right pan level.
• ChannelControl::setMixLevelsInput Sets the incoming volume level for each channel of a multi-channel signal.
• ChannelControl::setMixLevelsOutput Sets the outgoing volume levels for each speaker.
• ChannelControl::setMixMatrix Sets a 2 dimensional pan matrix that maps the signal from input channels (columns) to output speakers (rows).
• ChannelControl::getMixMatrix Retrieves a 2 dimensional pan matrix that maps the signal from input channels (columns) to output speakers (rows).

Filtering:

• ChannelControl::setReverbProperties Sets the wet / send level for a particular reverb instance.
• ChannelControl::getReverbProperties Retrieves the wet / send level for a particular reverb instance.
• ChannelControl::setLowPassGain Sets the gain of the dry signal when built in lowpass / distance filtering is applied.
• ChannelControl::getLowPassGain Retrieves the gain of the dry signal when built in lowpass / distance filtering is applied.

DSP chain configuration:

• ChannelControl::addDSP Adds a DSP unit to the specified index in the DSP chain.
• ChannelControl::removeDSP Removes the specified DSP unit from the DSP chain.
• ChannelControl::getNumDSPs Retrieves the number of DSP units in the DSP chain.
• ChannelControl::getDSP Retrieves the DSP unit at the specified index in the DSP chain.
• ChannelControl::setDSPIndex Sets the index in the DSP chain of the specified DSP.
• ChannelControl::getDSPIndex Retrieves the index of a DSP inside the Channel or ChannelGroup's DSP chain.

Sample accurate scheduling:

• ChannelControl::getDSPClock Retrieves the DSP clock values at this point in time.
• ChannelControl::setDelay Sets a sample accurate start (and/or stop) time relative to the parent ChannelGroup DSP clock.
• ChannelControl::getDelay Retrieves a sample accurate start (and/or stop) time relative to the parent ChannelGroup DSP clock.
• ChannelControl::addFadePoint Adds a sample accurate fade point at a time relative to the parent ChannelGroup DSP clock.
• ChannelControl::setFadePointRamp Adds a volume ramp at the specified time in the future using fade points.
• ChannelControl::removeFadePoints Removes all fade points between the two specified clock values (inclusive).
• ChannelControl::getFadePoints Retrieves information about stored fade points.

General:

• ChannelControl::setCallback Sets the callback for ChannelControl level notifications.
• ChannelControl::setUserData Sets a user value associated with this object.
• ChannelControl::getUserData Retrieves a user value associated with this object.
• ChannelControl::getSystemObject Retrieves the System that created this object.

Channel::getChannelGroup

Retrieves the ChannelGroup this object outputs to.

FMOD_RESULT Channel::getChannelGroup(
  ChannelGroup **channelgroup
);

FMOD_RESULT FMOD_Channel_GetChannelGroup(
  FMOD_CHANNEL *channel,
  FMOD_CHANNELGROUP **channelgroup
);

RESULT Channel.getChannelGroup(
  out ChannelGroup channelgroup
);

Channel.getChannelGroup(
  channelgroup
);

channelgroup Out

Output group. (ChannelGroup)

See Also: Channel::setChannelGroup

Channel::getCurrentSound

Retrieves the currently playing Sound.

FMOD_RESULT Channel::getCurrentSound(
  Sound **sound
);

FMOD_RESULT FMOD_Channel_GetCurrentSound(
  FMOD_CHANNEL *channel,
  FMOD_SOUND **sound
);

RESULT Channel.getCurrentSound(
  out Sound sound
);

Channel.getCurrentSound(
  sound
);

sound Out

Currently playing sound. (Sound)

May return NULL or equivalent if no Sound is playing.

See Also: System::playSound

Channel::getFrequency

Retrieves the playback frequency or playback rate.

FMOD_RESULT Channel::getFrequency(
  float *frequency
);

FMOD_RESULT FMOD_Channel_GetFrequency(
  FMOD_CHANNEL *channel,
  float *frequency
);

RESULT Channel.getFrequency(
  out float frequency
);

Channel.getFrequency(
  frequency
);

frequency Out

Playback frequency.

• Units: Hertz

See Also: Channel::setFrequency

Channel::getIndex

Retrieves the index of this object in the System Channel pool.

FMOD_RESULT Channel::getIndex(
  int *index
);

FMOD_RESULT FMOD_Channel_GetIndex(
  FMOD_CHANNEL *channel,
  int *index
);

RESULT Channel.getIndex(
  out int index
);

Channel.getIndex(
  index
);

index Out

Index within the System Channel pool.

• Range: [0, 'maxchannels' value from System::init - 1]

See Also: System::getChannel

Channel::getLoopCount

Retrieves the number of times to loop before stopping.

FMOD_RESULT Channel::getLoopCount(
  int *loopcount
);

FMOD_RESULT FMOD_Channel_GetLoopCount(
  FMOD_CHANNEL *channel,
  int *loopcount
);

RESULT Channel.getLoopCount(
  out int loopcount
);

Channel.getLoopCount(
  loopcount
);

loopcount Out

Times to loop before stopping where 0 represents "oneshot", 1 represents "loop once then stop" and -1 represents "loop forever".

This is the current loop countdown value that will decrement as it plays until reaching 0. Reset with Channel::setLoopCount.

Channel::getLoopPoints

Retrieves the loop start and end points.

FMOD_RESULT Channel::getLoopPoints(
  unsigned int *loopstart,
  FMOD_TIMEUNIT loopstarttype,
  unsigned int *loopend,
  FMOD_TIMEUNIT loopendtype
);

FMOD_RESULT FMOD_Channel_GetLoopPoints(
  FMOD_CHANNEL *channel,
  unsigned int *loopstart,
  FMOD_TIMEUNIT loopstarttype,
  unsigned int *loopend,
  FMOD_TIMEUNIT loopendtype
);

RESULT Channel.getLoopPoints(
  out uint loopstart,
  TIMEUNIT loopstarttype,
  out uint loopend,
  TIMEUNIT loopendtype
);

Channel.getLoopPoints(
  loopstart,
  loopstarttype,
  loopend,
  loopendtype
);

loopstart OutOpt

Loop start point.

• Range: [0, Sound::getLength - 1].

loopstarttype

Time units for loopstart. (FMOD_TIMEUNIT)

loopend OutOpt

Loop end point.

• Range: [0, Sound::getLength - 1].

loopendtype

Time units for loopend. (FMOD_TIMEUNIT)

Valid FMOD_TIMEUNIT types are FMOD_TIMEUNIT_PCM, FMOD_TIMEUNIT_MS, FMOD_TIMEUNIT_PCMBYTES. Any other time units return FMOD_ERR_FORMAT.
If FMOD_TIMEUNIT_MS or FMOD_TIMEUNIT_PCMBYTES are used, the value is internally converted from FMOD_TIMEUNIT_PCM, so the retrieved value may not exactly match the set value.

See Also: Channel::setLoopPoints

Channel::getPosition

Retrieves the current playback position.

FMOD_RESULT Channel::getPosition(
  unsigned int *position,
  FMOD_TIMEUNIT postype
);

FMOD_RESULT FMOD_Channel_GetPosition(
  FMOD_CHANNEL *channel,
  unsigned int *position,
  FMOD_TIMEUNIT postype
);

RESULT Channel.getPosition(
  out uint position,
  TIMEUNIT postype
);

Channel.getPosition(
  position,
  postype
);

position Out

Playback position.

postype

Time units for position. (FMOD_TIMEUNIT)

Certain FMOD_TIMEUNIT types are always available: FMOD_TIMEUNIT_PCM, FMOD_TIMEUNIT_PCMBYTES and FMOD_TIMEUNIT_MS. The others are format specific such as FMOD_TIMEUNIT_MODORDER / FMOD_TIMEUNIT_MODROW / FMOD_TIMEUNIT_MODPATTERN which is specific to files of type MOD / S3M / XM / IT.

If FMOD_TIMEUNIT_MS or FMOD_TIMEUNIT_PCMBYTES are used, the value is internally converted from FMOD_TIMEUNIT_PCM, so the retrieved value may not exactly match the set value.

See Also: Channel::setPosition

Channel::getPriority

Retrieves the priority used for virtual Channel ordering.

FMOD_RESULT Channel::getPriority(
  int *priority
);

FMOD_RESULT FMOD_Channel_GetPriority(
  FMOD_CHANNEL *channel,
  int *priority
);

RESULT Channel.getPriority(
  out int priority
);

Channel.getPriority(
  priority
);

priority Out

Priority where 0 represents most important and 256 represents least important.

• Range: [0, 256]
• Default: 128

Priority is used as a coarse grain control for the virtual Channel system, lower priority Channels will always be stolen before higher. For channels of equal priority, those with the quietest ChannelControl::getAudibility value will be stolen first.

See the Virtual Voices guide for more information.

See Also: Channel::setPriority

Channel::isVirtual

Retrieves whether the Channel is being emulated by the virtual Channel system.

FMOD_RESULT Channel::isVirtual(
  bool *isvirtual
);

FMOD_RESULT FMOD_Channel_IsVirtual(
  FMOD_CHANNEL *channel,
  FMOD_BOOL *isvirtual
);

RESULT Channel.isVirtual(
  out bool isvirtual
);

Channel.isVirtual(
  isvirtual
);

isvirtual Out

Virtual state. True = silent / emulated. False = audible / real.

• Units: Boolean

See the Virtual Voices guide for more information.

See Also: ChannelControl::getAudibility

Channel::setChannelGroup

Sets the ChannelGroup this object outputs to.

FMOD_RESULT Channel::setChannelGroup(
  ChannelGroup *channelgroup
);

FMOD_RESULT FMOD_Channel_SetChannelGroup(
  FMOD_CHANNEL *channel,
  FMOD_CHANNELGROUP *channelgroup
);

RESULT Channel.setChannelGroup(
  ChannelGroup channelgroup
);

Channel.setChannelGroup(
  channelgroup
);

channelgroup

Output group. (ChannelGroup)

A ChannelGroup may contain many Channels.

Channels may only output to a single ChannelGroup. This operation will remove it from the previous group first.

See Also: Channel::getChannelGroup

Channel::setFrequency

Sets the frequency or playback rate.

FMOD_RESULT Channel::setFrequency(
  float frequency
);

FMOD_RESULT FMOD_Channel_SetFrequency(
  FMOD_CHANNEL *channel,
  float frequency
);

RESULT Channel.setFrequency(
  float frequency
);

Channel.setFrequency(
  frequency
);

frequency

Playback rate.

• Units: Hertz

Default frequency is determined by the audio format of the Sound or DSP.

Sounds opened as FMOD_CREATESAMPLE (not FMOD_CREATESTREAM or FMOD_CREATECOMPRESSEDSAMPLE) can be played backwards by giving a negative frequency.

See Also: Channel::getFrequency, Sound::setDefaults

Channel::setLoopCount

Sets the number of times to loop before stopping.

FMOD_RESULT Channel::setLoopCount(
  int loopcount
);

FMOD_RESULT FMOD_Channel_SetLoopCount(
  FMOD_CHANNEL *channel,
  int loopcount
);

RESULT Channel.setLoopCount(
  int loopcount
);

Channel.setLoopCount(
  loopcount
);

loopcount

Times to loop before stopping where 0 represents "oneshot", 1 represents "loop once then stop" and -1 represents "loop forever".

The 'mode' of the Sound or Channel must be FMOD_LOOP_NORMAL or FMOD_LOOP_BIDI for this function to work.

See Also: Streaming Issues, Channel::getLoopCount, ChannelControl::setMode, Sound::setMode, System::createSound

Channel::setLoopPoints

Sets the loop start and end points.

FMOD_RESULT Channel::setLoopPoints(
  unsigned int loopstart,
  FMOD_TIMEUNIT loopstarttype,
  unsigned int loopend,
  FMOD_TIMEUNIT loopendtype
);

FMOD_RESULT FMOD_Channel_SetLoopPoints(
  FMOD_CHANNEL *channel,
  unsigned int loopstart,
  FMOD_TIMEUNIT loopstarttype,
  unsigned int loopend,
  FMOD_TIMEUNIT loopendtype
);

RESULT Channel.setLoopPoints(
  uint loopstart,
  TIMEUNIT loopstarttype,
  uint loopend,
  TIMEUNIT loopendtype
);

Channel.setLoopPoints(
  loopstart,
  loopstarttype,
  loopend,
  loopendtype
);

loopstart

Loop start point.

• Range: [0, Sound::getLength - 1].

loopstarttype

Time units for loopstart. (FMOD_TIMEUNIT)

loopend

Loop end point.

• Range; [loopstart + 1, Sound::getLength - 1].

loopendtype

Time units for loopend. (FMOD_TIMEUNIT)

Loop points may only be set on a Channel playing a Sound, not a Channel playing a DSP (See System::playDSP).

Valid FMOD_TIMEUNIT types are FMOD_TIMEUNIT_PCM, FMOD_TIMEUNIT_MS, FMOD_TIMEUNIT_PCMBYTES. Any other time units return FMOD_ERR_FORMAT.
If FMOD_TIMEUNIT_MS or FMOD_TIMEUNIT_PCMBYTES, the value is internally converted to FMOD_TIMEUNIT_PCM.

See Also: Streaming Issues, Channel::getLoopPoints

Channel::setPosition

Sets the current playback position.

FMOD_RESULT Channel::setPosition(
  unsigned int position,
  FMOD_TIMEUNIT postype
);

FMOD_RESULT FMOD_Channel_SetPosition(
  FMOD_CHANNEL *channel,
  unsigned int position,
  FMOD_TIMEUNIT postype
);

RESULT Channel.setPosition(
  uint position,
  TIMEUNIT postype
);

Channel.setPosition(
  position,
  postype
);

position

Playback position.

postype

Time units for position. (FMOD_TIMEUNIT)

Certain FMOD_TIMEUNIT types are always available: FMOD_TIMEUNIT_PCM, FMOD_TIMEUNIT_PCMBYTES and FMOD_TIMEUNIT_MS. The others are format specific such as FMOD_TIMEUNIT_MODORDER / FMOD_TIMEUNIT_MODROW / FMOD_TIMEUNIT_MODPATTERN which is specific to files of type MOD / S3M / XM / IT.

If playing a Sound created with System::createStream or FMOD_CREATESTREAM changing the position may cause a slow reflush operation while the file seek and decode occurs. You can avoid this by creating the stream with FMOD_NONBLOCKING. This will cause the stream to go into FMOD_OPENSTATE_SETPOSITION state (see Sound::getOpenState) and Sound commands will return FMOD_ERR_NOTREADY. Channel::getPosition will also not update until this non-blocking set position operation has completed.

Using a VBR source that does not have an associated seek table or seek information (such as MP3 or MOD/S3M/XM/IT) may cause inaccurate seeking if you specify FMOD_TIMEUNIT_MS or FMOD_TIMEUNIT_PCM. If you want FMOD to create a PCM vs bytes seek table so that seeking is accurate, you will have to specify FMOD_ACCURATETIME when loading or opening the sound. This means there is a slight delay as FMOD scans the whole file when loading the sound to create this table.

See Also: Channel::getPosition

Channel::setPriority

Sets the priority used for virtual Channel ordering.

FMOD_RESULT Channel::setPriority(
  int priority
);

FMOD_RESULT FMOD_Channel_SetPriority(
  FMOD_CHANNEL *channel,
  int priority
);

RESULT Channel.setPriority(
  int priority
);

Channel.setPriority(
  priority
);

priority

Priority where 0 represents most important and 256 represents least important.

• Range: [0, 256]
• Default: 128

Priority is used as a coarse grain control for the virtual Channel system, lower priority Channels will always be stolen before higher. For channels of equal priority, those with the quietest ChannelControl::getAudibility value will be stolen first.

See the Virtual Voices guide for more information.

See Also: Channel::getPriority