# 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 voice ordering.
- Channel::getPriority Retrieves the priority used for virtual voice 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 voice 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 roll-off shape for 3D distance attenuation.
- ChannelControl::get3DCustomRolloff Retrieves the current custom roll-off 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 roll-off attenuation.
- ChannelControl::get3DMinMaxDistance Retrieves the minimum and maximum distances used to calculate the 3D roll-off 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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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 Out Opt

  Loop start point.

  - Range: [0, Sound::getLength - 1].
loopstarttype
  Time units for `loopstart`. (FMOD_TIMEUNIT)
loopend Out Opt

  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.

C
C++
C#
JS

    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 voice ordering.

C
C++
C#
JS

    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 voice system, lower priority Channels will always be stolen before higher ones. 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 voice system.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

The Channel's mode must be set to FMOD_LOOP_NORMAL or FMOD_LOOP_BIDI for loop points to affect playback.

See Also: Streaming Issues, Channel::getLoopPoints, ChannelControl::setMode

## Channel::setPosition

Sets the current playback position.

C
C++
C#
JS

    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 voice ordering.

C
C++
C#
JS

    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 voice system, lower priority Channels will always be stolen before higher ones. 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