-
Notifications
You must be signed in to change notification settings - Fork 3
channel
FMOD Object: Channel
This module holds functionality related to Channels, which are a source of audio signal that connects to the ChannelGroup mixing hierarchy.
Create a channel with fmod_system_play_sound or fmod_system_play_dsp.
This module offers a collection of functions designed to address specific tasks and provide utilities for various purposes. Explore the available functions to make the most of the functionalities provided by this module.
- fmod_channel_set_frequency
- fmod_channel_get_frequency
- fmod_channel_set_priority
- fmod_channel_get_priority
- fmod_channel_set_position
- fmod_channel_get_position
- fmod_channel_set_channel_group
- fmod_channel_get_channel_group
- fmod_channel_set_loop_count
- fmod_channel_get_loop_count
- fmod_channel_set_loop_points
- fmod_channel_get_loop_points
- fmod_channel_is_virtual
- fmod_channel_get_current_sound
- fmod_channel_get_index
- fmod_channel_get_system_object
FMOD Function: Channel::setFrequency
This function sets the frequency or playback rate.
Note
Sounds opened as FMOD_MODE.CREATESAMPLE (not FMOD_MODE.CREATESTREAM or FMOD_MODE.CREATECOMPRESSEDSAMPLE) can be played backwards by giving a negative frequency.
Syntax:
fmod_channel_set_frequency(channel_ref, frequency)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
| frequency | Real | The playback rate, expressed in Hertz. |
Returns:
N/A
FMOD Function: Channel::getFrequency
This function retrieves the playback frequency or playback rate.
Syntax:
fmod_channel_get_frequency(channel_ref)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
Returns:
FMOD Function: Channel::setPriority
This function sets the priority used for virtual voice ordering.
Note
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 fmod_channel_control_get_audibility value will be stolen first.
See the FMOD Virtual Voices guide for more information.
Syntax:
fmod_channel_set_priority(channel_ref, priority)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
| priority | Real | The priority value where 0 represents most important and 256 represents least important. The default is 128. |
Returns:
N/A
FMOD Function: Channel::getPriority
This function retrieves the priority used for virtual voice ordering.
The function returns the priority value where 0 represents most important and 256 represents least important.
Note
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 fmod_channel_control_get_audibility value will be stolen first.
Syntax:
fmod_channel_get_priority(channel_ref)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
Returns:
FMOD Function: Channel::setPosition
This function sets the current playback position.
Note
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.
Note
If playing a Sound created with fmod_system_create_stream or FMOD_MODE.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_MODE.NONBLOCKING. This will cause the stream to go into FMOD_OPENSTATE.SETPOSITION state (see fmod_sound_get_open_state) and Sound commands will return FMOD_RESULT.ERR_NOTREADY. fmod_channel_get_position will also not update until this non-blocking set position operation has completed.
Note
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_MODE.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.
Syntax:
fmod_channel_set_position(channel_ref, position, time_unit)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
| position | Real | The playback position. |
| time_unit | FMOD_TIMEUNIT | The time units in which the position parameter is expressed. |
Returns:
N/A
FMOD Function: Channel::getPosition
This function retrieves the current playback position.
Note
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.
Note
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.
Syntax:
fmod_channel_get_position(channel_ref, time_unit)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
| time_unit | FMOD_TIMEUNIT | The time units in which the position parameter is expressed. |
Returns:
FMOD Function: Channel::setChannelGroup
This function sets the channelgroup this object outputs to.
Note
A channelgroup may contain many channels.
Note
Channels may only output to a single channelgroup. This operation will remove it from the previous group first.
Syntax:
fmod_channel_set_channel_group(channel_ref, channel_group_ref)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
| channel_group_ref | Real | A reference to the channelgroup to use as the output group. |
Returns:
N/A
FMOD Function: Channel::getChannelGroup
This function retrieves the ChannelGroup this object outputs to.
Syntax:
fmod_channel_get_channel_group(channel_ref)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
Returns:
FMOD Function: Channel::setLoopCount
This function sets the number of times to loop before stopping.
Note
The 'mode' of the sound or channel must be FMOD_MODE.LOOP_NORMAL or FMOD_MODE.LOOP_BIDI for this function to work.
Syntax:
fmod_channel_set_loop_count(channel_ref, loop_count)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
| loop_count | Real | The number of times to loop before stopping where 0 represents "oneshot", 1 represents "loop once then stop" and -1 represents "loop forever". |
Returns:
N/A
FMOD Function: Channel::getLoopCount
This function retrieves the number of times to loop before stopping.
The returned value is the times to loop before stopping where 0 represents "oneshot", 1 represents "loop once then stop" and -1 represents "loop forever".
Note
This is the current loop countdown value that will decrement as it plays until reaching 0. You can reset it with fmod_channel_set_loop_count.
Syntax:
fmod_channel_get_loop_count(channel_ref)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
Returns:
FMOD Function: Channel::setLoopPoints
This function sets the loop start and end points.
Loop points may only be set on a channel playing a sound, not a channel playing a DSP (See fmod_system_play_dsp).
Note
Valid FMOD_TIMEUNIT types are FMOD_TIMEUNIT.PCM, FMOD_TIMEUNIT.MS, FMOD_TIMEUNIT.PCMBYTES. Any other time units return FMOD_RESULT.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.
The Channel's mode must be set to FMOD_MODE.LOOP_NORMAL or FMOD_MODE.LOOP_BIDI for loop points to affect playback.
See also: Streaming Issues
Syntax:
fmod_channel_set_loop_points(channel_ref, loop_start, loop_start_type, loop_end, loop_end_type)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
| loop_start | Real | The loop start point. |
| loop_start_type | FMOD_TIMEUNIT | The time units in which the loop_start parameter is expressed. |
| loop_end | Real | The loop end point. |
| loop_end_type | FMOD_TIMEUNIT | The time units in which the loop_end parameter is expressed. |
Returns:
N/A
FMOD Function: Channel::getLoopPoints
This function retrieves the loop start and end points.
Note
Valid FMOD_TIMEUNIT types are FMOD_TIMEUNIT.PCM, FMOD_TIMEUNIT.MS, FMOD_TIMEUNIT.PCMBYTES. For all other time units fmod_last_result returns FMOD_RESULT.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.
Syntax:
fmod_channel_get_loop_points(channel_ref, loop_start_type, loop_end_type)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
| loop_start_type | FMOD_TIMEUNIT | The time units in which to return loop_start
|
| loop_end_type | FMOD_TIMEUNIT | The time units in which to return loop_end
|
Returns:
FMOD Function: Channel::isVirtual
This function retrieves whether the channel is being emulated by the virtual voice system.
If true is returned, the channel is silent / emulated. If false is returned, the channel is audible / real.
See the FMOD Virtual Voices guide for more information.
Syntax:
fmod_channel_is_virtual(channel_ref)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
Returns:
FMOD Function: Channel::getCurrentSound
This function retrieves the currently playing sound.
Note
The function may return 0 if no sound is playing.
Syntax:
fmod_channel_get_current_sound(channel_ref)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
Returns:
FMOD Function: Channel::getIndex
This function retrieves the index of this object in the system channel pool.
Note
This value is in the range [0, max_channels value passed to fmod_system_init - 1].
Syntax:
fmod_channel_get_index(channel_ref)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
Returns:
FMOD Function: ChannelControl::getSystemObject
This function retrieves the system that created this object.
Syntax:
fmod_channel_get_system_object(channel_ref)
| Argument | Type | Description |
|---|---|---|
| channel_ref | Real | A reference to a channel. |
Returns:
YoYoGames 2024