Skip to content

Channels

Channels

FL Studio built-in module.

Allows you to control and interact with the FL Studio Channel Rack, and with instrument channels.

Note

  • Channels are zero-indexed.

channelCount(globalCount=False)

Returns the number of channels on the channel rack. Respect for groups is controlled by the mode flag.

Args

  • globalCount (bool, optional): Whether the number of channels should be global. Defaults to False (groups respected).

Returns

  • int: number of channels.

Included since API version 1. (updated with optional parameter in API version 3).

channelNumber(canBeNone=False, offset=0)

Returns the global index of the first selected channel, otherwise the nth selected channel where n is offset + 1. If n is greater than the number of selected channels, the global index of the last selected channel will be returned.

If canBeNone is 1, no selection will return -1. Otherwise, no selection will return 0 (representing the first channel).

Args

  • canBeNone (bool, optional): Whether the function will return -1 or 0 when there is no selection. Defaults to False (returning 0).

  • offset (int, optional): return other selected channels after offset. Defaults to 0.

Returns

  • int: global index of first selected channel.

Included since API version 1.

closeGraphEditor(index)

???

WARNING

  • This function has no official documentation

Included since API Version 33?

deselectAll()

Deselects all channels in the current channel group.

Included since API version 1.

focusEditor(index, useGlobalIndex=False)

Focus the plugin window for the channel at index.

Args

  • index (int): channel index.

  • useGlobalIndex (bool, optional): whether to use the global channel index when

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

getActivityLevel(index, useGlobalIndex=False)

Return the note activity level for channel at index. Activity level refers to how recently a note was played, as well as whether any notes are currently playing.

Args

  • index (int): channel index.

  • useGlobalIndex (bool, optional): whether to use the global channel index when

Returns

  • float: activity level.

Included since API version 9.

API Changes

  • v33: add useGlobalIndex flag.

getChannelColor(index, useGlobalIndex=False)

Returns the color of the channel at index.

Note that colors can be split into or built from components using the functions provided in the utils module.

Args

  • index (int): index of channel.

  • useGlobalIndex (bool, optional): whether to use the global channel index when getting the channel color.

Returns:

  • int: channel color (0x--BBGGRR).

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

getChannelIndex(index)

Returns the global index of a channel given the group index.

Args

  • index (int): index of channel (respecting groups).

Returns

  • int: global index of channel.

Included since API version 1.

getChannelMidiInPort(index, useGlobalIndex=False)

Returns the MIDI-in port associated with the channel at index.

Channel MIDI-in ports can be used to send data directly to channels. Although channels are unassigned by default, a user can configure plugins to receive MIDI on a certain channel which can unlock many useful plugin-specific features.

Note that triggering notes using channels.midiNoteOn means that this functionality may be lost, so developers should take care to ensure that getChannelMidiInPort is checked to ensure that scripts don't inadvertently override this behavior.

Args

  • index (int): channel index.

  • useGlobalIndex (bool, optional): whether to use the global channel index when querying channel MIDI-in port.

Returns

  • int: MIDI port associated with channel.

  • -3: Channel receiving notes from touch keyboard.

  • -2: Channel not assigned to a MIDI port.

  • -1: Channel receiving notes from typing keyboard.

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

getChannelName(index, useGlobalIndex=False)

Returns the name of the channel at index.

Args

  • index (int): index of channel.

  • useGlobalIndex (bool, optional): whether to use the global channel index when getting the channel name.

Returns:

  • str: channel name.

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

getChannelPan(index, useGlobalIndex=False)

Returns the normalized pan of the channel at index, where -1.0 is 100% left, and 1.0 is 100% right. Note that the default pan for channels is 0.0 (centered).

Args

  • index (int): index of channel.

  • useGlobalIndex (bool, optional): whether to use the global channel index when getting channel pan.

Returns

  • float: channel pan.

Included since API version 1

API Changes

  • v33: add useGlobalIndex flag.

getChannelPitch(index, mode=0, useGlobalIndex=False)

Returns the current pitch bend (or range) of the channel at index. The mode parameter is used to determine the type of pitch returned.

Args

  • index (int): index of channel.

  • mode (int, optional):

    • 0 (default): return the current pitch bend as a factor of the current range (usually -1.0 to 1.0). Larger values might be reached if the pitch is automated with events, for example.

    • 1: return the current pitch offset in cents.

      • BUG: Official API docs incorrectly state "semitones".

    • 2: return the current pitch range in semitones.

      • BUG: This is not guaranteed to be correct. For more information, see setChannelPitch on modifying the pitch range of a channel.

  • useGlobalIndex (bool, optional): whether to use the global channel index when getting channel pitch.

Returns

  • float: channel pitch (when mode is 0).

  • int: channel pitch range (when mode is 1 or 2).

Included since API version 8.

API Changes

  • v33: add useGlobalIndex flag.

getChannelType(index, useGlobalIndex=False)

Returns the type of instrument loaded into the channel rack at index.

Args

  • index (int): index of channel.

  • useGlobalIndex (bool, optional): whether to use the global channel index when querying channel type.

Returns

  • int: type of channel:

    • GT_Sampler (0): internal sampler.

    • GT_Hybrid (1): generator plugin feeding internal sampler.

    • GT_GenPlug (2): generator plugin.

    • GT_Layer (3): layer (refer to the FL Studio manual).

    • GT_AutoClip (4): automation clip.

Included since API Version 19.

API Changes

  • v33: add useGlobalIndex flag.

getChannelVolume(index, mode=False, useGlobalIndex=False)

Returns the normalized volume of the channel at index, where 0.0 is the minimum value, and 1.0 is the maximum value. Note that the default volume for channels is 0.78125. By setting the mode flag to True, the volume is returned in decibels.

Args

  • index (int): index of channel.

  • mode (int, optional): whether to return as a float between 0 and 1 (False) or a value in dB (True). Defaults to False.

  • useGlobalIndex (bool, optional): whether to use the global channel index when getting channel volume.

Returns

  • float: channel volume.

Included since API version 1

API Changes

  • v33: add useGlobalIndex flag.

getCurrentStepParam(index, step, param, useGlobalIndex=False)

Get current step parameter for channel at index and for step at step.

HELP WANTED

Args

  • index (int): channel index.

  • step (int): step (grid bit index) to get parameter for.

  • param (int): one of the parameter types (see below).

  • useGlobalIndex (bool, optional): whether to use the global channel index.

Returns

  • int: value for step parameter.

Step parameter types

  • 0: Note pitch (MIDI note number, default 60 for middle C)
  • 1: Velocity (0 - 127, default 100)
  • 2: Release velocity (0 - 127, default 64)
  • 3: Fine pitch (in cents: 0 - 240, with default 120 for no tuning)
  • 4: Panning (0 - 127, with default 64 for centered)
  • 5: Mod X (0-127, with default 64 for midpoint)
  • 6: Mod Y (0-127, with default 64 for midpoint)
  • 7: Number of ticks to offset the note by (0 - PPQN / 4; , with default 0 for no shifting)

Included since API version 1

API Changes

  • v33: add useGlobalIndex flag.

getGridBit(index, position, useGlobalIndex=False)

Returns whether the grid bit on channel at index in position is set.

Args

  • index (int): channel index.

  • position (int): index of grid bit (horizontal axis).

  • useGlobalIndex (bool, optional): whether to use the global channel index.

Returns

  • bool: whether grid bit is set.

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

getGridBitWithLoop(index, position, useGlobalIndex=False)

Get value of grid bit on channel index in position accounting for loops.

Args

  • index (int): channel index.

  • position (int): position on grid (horizontal axis).

  • useGlobalIndex (bool, optional): whether to use the global channel index.

Returns

  • bool: whether grid bit is set.

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

getRecEventId(index, useGlobalIndex=False)

Return the starting point of REC event IDs for the channel at index.

See the event mapping tutorial. for more information on REC events.

Args

  • index (int): channel index

  • useGlobalIndex (bool, optional): whether to use the global channel index.

Returns

  • int: REC event ID offset for accessing midi.REC_Chan_* parameters

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

getStepParam(step, param, offset, startPos, padsStride=16, useGlobalIndex=False)

Get the values of properties associated with a step in the step sequencer. This provides an interface to access the graph editor.

Args

  • step (int): step (grid bit index) to get parameter for.

  • param (int): one of the parameter types (see below).

  • offset (int): ???

  • startPos (int): ????

  • padsStride (int, optional): ?????. Defaults to 16.

  • useGlobalIndex (bool, optional): whether to use the global channel index.

Returns

  • int: value for step parameter.

See also

Step parameter types

  • 0: Note pitch (MIDI note number, default 60 for middle C)
  • 1: Velocity (0 - 127, default 100)
  • 2: Release velocity (0 - 127, default 64)
  • 3: Fine pitch (in cents: 0 - 240, with default 120 for no tuning)
  • 4: Panning (0 - 127, with default 64 for centered)
  • 5: Mod X (0-127, with default 64 for midpoint)
  • 6: Mod Y (0-127, with default 64 for midpoint)
  • 7: Number of ticks to offset the note by (0 - PPQN / 4; , with default 0 for no shifting)

Included since API version 1.

getTargetFxTrack(index, useGlobalIndex=False)

Returns the mixer track that the channel at index is linked to.

Args

  • index (int): index of channel.

  • useGlobalIndex (bool, optional): whether to use the global channel index.

Returns

  • int: index of targeted mixer track.

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

incEventValue(eventId, step, res=1 / 24)

Get event value increased by step.

This can be used to map encoder-style controls to events, by allowing them to adjust a parameter using a delta value.

Use result as new value in general.processRECEvent().

Example usage

# Increases the volume of channel 0 by a small delta of 1
delta = 1
# Calculate the event ID for the volume of channel 0
event_id = midi.REC_Chan_Vol + channels.getRecEventId(0)
# Get the value adjusted by the delta
new_value = channels.incEventValue(event_id, delta)
# Process the new value
general.processRECEvent(event_id, new_value, midi.REC_UpdateValue | midi.REC_UpdateControl)

Args

  • eventId (int): event ID (see the event mapping tutorial).

  • step (int): delta value for the event.

  • res (float, optional): increment resolution, used as a multiplier to ensure that encoders are responsive. Defaults to 1/24.

Returns

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

isChannelMuted(index, useGlobalIndex=False)

Returns whether channel is muted (True) or not (False).

Args

  • index (int): index of channel.

  • useGlobalIndex (bool, optional): whether to use the global channel index when getting the channel's mute status.

Returns

  • bool: mute status.

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

isChannelSelected(index, useGlobalIndex=False)

Returns whether the channel at index is selected.

Args

  • index (int): channel index.

  • useGlobalIndex (bool, optional): whether to use the global channel index.

Returns

  • bool: whether the channel is selected.

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

isChannelSolo(index, useGlobalIndex=False)

Returns whether channel is solo (True) or not (False).

Args

  • index (int): index of channel.

  • useGlobalIndex (bool, optional): whether to use the global channel index when getting channel solo status.

Returns

  • bool: solo status.

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

isGraphEditorVisible()

Returns whether the graph editor is currently visible.

isGridBitAssigned(index, useGlobalIndex=False)

Returns True when the grid bit at index is assigned.

HELP WANTED

What does it mean for a grid bit to be assigned?

Args

  • index (int): channel index.

  • useGlobalIndex (bool, optional): whether to use the global channel index.

Returns

  • bool: whether the grid bit is assigned.

Included since API Version 1

isHighLighted()

Returns True when a red highlight rectangle is displayed on the channel rack. This rectangle can be displayed using ui.crDisplayRect().

These hints can be used to visually indicate on the channel rack where your script is mapping to.

Returns

  • bool: whether highlight rectangle is visible.

Included since API version 1

midiNoteOn(indexGlobal, note, velocity, channel=-1)

Set a MIDI Note for the channel at indexGlobal (not respecting groups).

This can be used to create extra notes (eg mapping one note to a chord).

Note that triggering notes using this function rather than allowing FL Studio to process them may result in users' manual note mappings won't be respected. Developers should be sure to check channels.getChannelMidiInPort on all channels to ensure that no channels receive MIDI events from this script.

Note

  • Specifying a channel doesn't appear to do anything.

Args

  • indexGlobal (int): channel index (not respecting groups).

  • note (int): note number (0-127).

  • velocity (int): note velocity (1-127, 0 is note off).

  • channel (int, optional): MIDI channel to use. Defaults to -1.

Included since API version 1.

muteChannel(index, value=-1, useGlobalIndex=False)

Toggles the mute state of the channel at index.

Args

  • index (int): index of channel.

  • value (int, optional): new value for mute state.

  • useGlobalIndex (bool, optional): whether to use the global channel index when muting channel.

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

processRECEvent(eventId, value, flags)

Processes a recording event.

WARNING

  • This function is deprecated here, and moved to general.processRECEvent as of API version 7.

Included since API version 1.

Deprecated since API version 7.

quickQuantize(index, startOnly=1, useGlobalIndex=False)

Perform a quick quantize operation on the channel at index

Args

  • index (int): channel index, respecting groups

  • startOnly (int, optional): ???. Defaults to 1.

  • useGlobalIndex (bool, optional): whether to use the global channel index when quantizing notes on the channel.

Included since API Version 9.

API Changes

  • v33: add useGlobalIndex flag.

selectAll()

Selects all channels in the current channel group.

Included since API version 1.

selectChannel(index, value=-1, useGlobalIndex=False)

Select the channel at index (respecting groups).

Using global indexes to select a channel outside of the current group has no effect.

Args

  • index (int): channel index.

  • value (int, optional): Whether to select or deselect the channel.

    • -1 (default): Toggle

    • 0 : Deselect

    • 1: Select

  • useGlobalIndex (bool, optional): whether to use the global channel index when selecting channels.

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

selectOneChannel(index, useGlobalIndex=False)

Exclusively select the channel at index (deselecting any other selected channels).

Using global indexes to select a channel outside of the current group deselects all channels.

Args

  • index (int): channel index.

  • useGlobalIndex (bool, optional): whether to use the global channel index when selecting channels.

Included since API version 8.

API Changes

  • v33: add useGlobalIndex flag.

selectedChannel(canBeNone=False, offset=0, indexGlobal=False)

Returns the index of the first selected channel, otherwise the nth selected channel where n is offset + 1. If n is greater than the number of selected channels, the global index of the last selected channel will be returned. If indexGlobal is set to 1, this will replicate the behavior of channels.channelNumber() by returning global indexes.

Note

  • This function replaces the functionality of channelNumber() entirely, with the added functionality of providing indexes respecting groups (when indexGlobal is not set).

Args

  • canBeNone (bool, optional): Whether the function will return -1 or 0 when there is no selection. Defaults to False (returning 0).

  • offset (int, optional): return other selected channels after offset. Defaults to 0.

  • indexGlobal (bool, optional): Whether to return the group index (False) or the global index (True).

Returns

  • int: index of first selected channel.

Included since API version 5

setChannelColor(index, color, useGlobalIndex=False)

Sets the color of the channel at index.

Note that colors can be split into or built from components using the functions provided in the utils module.

Args

  • index (int): index of channel.

  • color (int): new color for channel (0x--BBGGRR).

  • useGlobalIndex (bool, optional): whether to use the global channel index when setting the channel color.

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

setChannelName(index, name, useGlobalIndex=False)

Sets the name of the channel at index.

If a channel's name is set to "", its name will be set to the default name of the plugin or sample.

Args

  • index (int): index of channel.

  • name (str): new name for channel.

  • useGlobalIndex (bool, optional): whether to use the global channel index when setting the channel name.

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

setChannelPan(index, pan, pickupMode=midi.PIM_None, useGlobalIndex=False)

Sets the normalized pan of the channel at index, where -1.0 is 100% left, and 1.0 is 100% right. Note that the default pan for channels is 0.0 (centered). Use the pickup mode flag to set pickup options.

Args

  • index (int): index of channel.

  • pan (float): channel pan.

  • pickupMode (int, optional): define the pickup behavior. Refer to the FL Studio manual.

  • useGlobalIndex (bool, optional): whether to use the global channel index when setting channel pan.

Included since API version 1

API Changes

  • v33: add useGlobalIndex flag.

setChannelPitch(index, value, mode=0, pickupMode=midi.PIM_None, useGlobalIndex=False)

Sets the pitch of the channel at index to value. The mode parameter is used to determine the type of pitch set. Use the pickup mode flag to set pickup options. The final pitch will be clamped to the current pitch range.

Args

  • index (int): index of channel.

  • value (float): value to set.

  • mode (int, optional):

    • 0 (default): set pitch as a factor of the current pitch bend range (between [-1.0, 1.0]).

    • 1: set pitch in cents.

    • 2: UTTERLY BROKEN. Set the pitch range in semitones.

      BUG: This only affects the range reported by getChannelPitch. This will desynchronize the reported range from what is visible in the UI.

  • pickupMode (int, optional): define the pickup behavior. Refer to the FL Studio manual.

  • useGlobalIndex (bool, optional): whether to use the global channel index when setting channel pitch.

Included since API version 8.

API Changes

  • v33: add useGlobalIndex flag.

setChannelVolume(index, volume, pickupMode=midi.PIM_None, useGlobalIndex=False)

Sets the normalized volume of the channel at index, where 0.0 is the minimum value, and 1.0 is the maximum value. Note that the default volume for channels is 0.78125. Use the pickup mode flag to set pickup options.

Args

  • index (int): index of channel.

  • volume (float): channel volume.

  • pickupMode (int, optional): define the pickup behavior. Refer to the FL Studio manual.

  • useGlobalIndex (bool, optional): whether to use the global channel index when setting channel volume.

Included since API version 1

API Changes

  • v33: add useGlobalIndex flag.

setGridBit(index, position, value, useGlobalIndex=False)

Sets the value of the grid bit on channel at index in position.

Args

  • index (int): channel index.

  • position (int): index of grid bit (horizontal axis).

  • value (bool): whether grid bit is set (True) or not (False).

  • useGlobalIndex (bool, optional): whether to use the global channel index.

Included since API version 1

API Changes

  • v33: add useGlobalIndex flag.

setStepParameterByIndex(index, patNum, step, param, value, useGlobalIndex=False)

Set the value of a step parameter at the given location.

Args

  • index (int): channel index.

  • patNum (int): pattern number to set step parameter on (1-indexed).

  • step (int): step index.

  • param (int): step parameter to set (see below).

  • value (int): value to set parameter to.

  • useGlobalIndex (bool, optional): whether to use a global index for the channel. Defaults to False.

Step parameter types

  • 0: Note pitch (MIDI note number, default 60 for middle C)
  • 1: Velocity (0 - 127, default 100)
  • 2: Release velocity (0 - 127, default 64)
  • 3: Fine pitch (in cents: 0 - 240, with default 120 for no tuning)
  • 4: Panning (0 - 127, with default 64 for centered)
  • 5: Mod X (0-127, with default 64 for midpoint)
  • 6: Mod Y (0-127, with default 64 for midpoint)
  • 7: Number of ticks to offset the note by (0 - PPQN / 4; , with default 0 for no shifting)

Included since API Version 1.

setTargetFxTrack(channelIndex, mixerIndex, useGlobalIndex=False)

Sets the mixer track that the channel at index is linked to.

Args

  • channelIndex (int): index of channel to link from.

  • mixerIndex (int): index of mixer track to link to.

  • useGlobalIndex (bool, optional): whether to use the global channel index.

Included since API version 1.

API Changes

  • v33: add useGlobalIndex flag.

showCSForm(index, state=1, useGlobalIndex=False)

Show the channel settings window (or plugin window for plugins) for channel at index.

This appears to perform the same action as channels.focusEditor().

Args

  • index (int): channel index

  • state (int, optional): whether to hide (0), show (1) or toggle (-1) the plugin window. Defaults to 1.

  • useGlobalIndex (bool, optional): whether to use the global channel index when

Included since API version 1.

API Changes

  • v9: Add state parameter.

  • v33: add useGlobalIndex flag.

showEditor(index, value=-1, useGlobalIndex=False)

Toggle whether the plugin window for the channel at index is shown. The value parameter can be used to control whether the editor is hidden or shown.

Args

  • index (int): channel index.

  • value (int): whether to hide (0) or show (1) the plugin window. Defaults to -1 (toggle).

  • useGlobalIndex (bool, optional): whether to use the global channel index when

Included since API version 1.

API Changes

  • v3: Add value parameter.

  • v33: add useGlobalIndex flag.

showGraphEditor(temporary, param, step, index, useGlobalIndex=True)

Show the graph editor for a step parameter on the channel at index.

Args

  • temporary (bool): whether the editor should be temporary or stay open.

  • param (int): step parameter, see the FL Studio manual

  • step (int): step ???.

  • index (int): index of channel.

  • globalIndex (int, optional): whether index should be global (True) or not (False). Defaults to True.

Included since API Version 1.

API Changes

  • v20: add useGlobalIndex flag.

soloChannel(index, useGlobalIndex=False)

Toggles the solo state of the channel at index.

Args

  • index (int): index of channel.

  • useGlobalIndex (bool, optional): whether to use the global channel index when soloing channel.

Included since API version 1

API Changes

  • v33: add useGlobalIndex flag.

updateGraphEditor()

???

WARNING

  • This function has no official documentation

Included since API Version 20?