Skip to content
This repository has been archived by the owner on Jun 1, 2024. It is now read-only.

Commit

Permalink
Document useGlobalIndex
Browse files Browse the repository at this point in the history
  • Loading branch information
@MaddyGuthridge
MaddyGuthridge committed May 2, 2023
1 parent d82f82c commit 19cdd25
Showing 1 changed file with 122 additions and 36 deletions.
158 changes: 122 additions & 36 deletions src/plugins/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@
plugins.isValid(*index2)
```
Note that this may be unreliable if you are also specifying `useGlobalIndex`
## Interacting with VST plugins
VST plugins can behave somewhat unintuitively as a result of the system that FL
Expand All @@ -49,16 +51,23 @@


@since(8)
def isValid(index: int, slotIndex: int = -1) -> bool:
def isValid(
index: int,
slotIndex: int = -1,
useGlobalIndex: bool = False,
) -> bool:
"""Returns whether there is a valid plugin at `index`/`slotIndex`.
## Notes
* Audio samples are not considered to be plugins in FL Studio.
## Args:
* `index` (`int`): index on channel rack or mixer
* `index` (`int`): index on channel rack or mixer
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to `-1`.
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to -1.
* `useGlobalIndex` (`bool`, optional): whether to use global channel
indexes when modifying plugins on the channel rack. Defaults to `False`.
## Returns:
* `bool`: whether there is a valid plugin at `index`.
Expand All @@ -69,15 +78,27 @@ def isValid(index: int, slotIndex: int = -1) -> bool:


@since(12)
def getPluginName(index: int, slotIndex: int = -1, userName: int = 0) -> str:
def getPluginName(
index: int,
slotIndex: int = -1,
userName: bool = False,
useGlobalIndex: bool = False,
) -> str:
"""Returns the name of the plugin at `index`/slotIndex`. This returns the
original plugin name if `userName` is `False`, otherwise the name of the
plugin as set by the user.
## Args:
* `index` (`int`): index on channel rack or mixer
* `index` (`int`): index on channel rack or mixer
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to -1.
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to `-1`.
* `userName` (`bool`, optional): whether to return the user's name for the
plugin (`True`), or the default name for the plugin (`False`). Defaults
to `False`.
* `useGlobalIndex` (`bool`, optional): whether to use global channel
indexes when modifying plugins on the channel rack. Defaults to `False`.
## Returns:
* `str`: plugin name
Expand All @@ -89,7 +110,11 @@ def getPluginName(index: int, slotIndex: int = -1, userName: int = 0) -> str:


@since(8)
def getParamCount(index: int, slotIndex: int = -1) -> int:
def getParamCount(
index: int,
slotIndex: int = -1,
useGlobalIndex: bool = False,
) -> int:
"""Returns the number of parameters that the plugin at `index`/`slotIndex`
has.
Expand All @@ -102,7 +127,10 @@ def getParamCount(index: int, slotIndex: int = -1) -> int:
## Args:
* `index` (`int`): index on channel rack or mixer
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to -1.
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to `-1`.
* `useGlobalIndex` (`bool`, optional): whether to use global channel
indexes when modifying plugins on the channel rack. Defaults to `False`.
## Returns:
* `int`: number of parameters
Expand All @@ -113,7 +141,12 @@ def getParamCount(index: int, slotIndex: int = -1) -> int:


@since(8)
def getParamName(paramIndex: int, index: int, slotIndex: int = -1) -> str:
def getParamName(
paramIndex: int,
index: int,
slotIndex: int = -1,
useGlobalIndex: bool = False,
) -> str:
"""Returns the name of the parameter at `paramIndex` for the plugin at
`index`/`slotIndex`.
Expand All @@ -126,7 +159,10 @@ def getParamName(paramIndex: int, index: int, slotIndex: int = -1) -> str:
* `index` (`int`): index of plugin on channel rack or mixer
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to -1.
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to `-1`.
* `useGlobalIndex` (`bool`, optional): whether to use global channel
indexes when modifying plugins on the channel rack. Defaults to `False`.
## Returns:
* `str`: name of parameter
Expand All @@ -137,7 +173,12 @@ def getParamName(paramIndex: int, index: int, slotIndex: int = -1) -> str:


@since(8)
def getParamValue(paramIndex: int, index: int, slotIndex: int = -1) -> float:
def getParamValue(
paramIndex: int,
index: int,
slotIndex: int = -1,
useGlobalIndex: bool = False,
) -> float:
"""Returns the value of the parameter at `paramIndex` for the plugin at
`index`/`slotIndex`.
Expand All @@ -153,7 +194,10 @@ def getParamValue(paramIndex: int, index: int, slotIndex: int = -1) -> float:
* `index` (`int`): index of plugin on channel rack or mixer
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to -1.
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to `-1`.
* `useGlobalIndex` (`bool`, optional): whether to use global channel
indexes when modifying plugins on the channel rack. Defaults to `False`.
## Returns:
* `float`: parameter value, between `0.0` and `1.0`
Expand All @@ -168,14 +212,15 @@ def setParamValue(
value: float,
paramIndex: int,
index: int,
slotIndex: int = -1
slotIndex: int = -1,
useGlobalIndex: bool = False,
) -> None:
"""Sets the value of the parameter at `paramIndex` for the plugin at
`index`/`slotIndex`.
## Warnings:
* This appears to have poor performance, being 40x slower than many other
functions that interact with plugins.
* This appears to have poor performance before FL Studio 21, being 40x
slower than many other functions that interact with plugins.
## Args:
* `value` (`float`): new value of parameter (between `0.0` and `1.0`)
Expand All @@ -184,7 +229,10 @@ def setParamValue(
* `index` (`int`): index of plugin on channel rack or mixer
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to -1.
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to `-1`.
* `useGlobalIndex` (`bool`, optional): whether to use global channel
indexes when modifying plugins on the channel rack. Defaults to `False`.
Included since API version 8
"""
Expand All @@ -196,6 +244,7 @@ def getParamValueString(
index: int,
slotIndex: int = -1,
pickupMode: int = midi.PIM_None,
useGlobalIndex: bool = False,
) -> str:
"""
Returns a string value of the parameter at `paramIndex` for the plugin at
Expand All @@ -213,7 +262,10 @@ def getParamValueString(
* `index` (`int`): index of plugin on channel rack or mixer
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to -1.
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to `-1`.
* `useGlobalIndex` (`bool`, optional): whether to use global channel
indexes when modifying plugins on the channel rack. Defaults to `False`.
## Returns:
* `str`: string parameter value
Expand All @@ -227,22 +279,26 @@ def getParamValueString(
def getColor(
index: int,
slotIndex: int = -1,
flag: int = midi.GC_BackgroundColor
flag: int = midi.GC_BackgroundColor,
useGlobalIndex: bool = False,
) -> int:
"""Returns various plugin color parameter values for the plugin at
`index`/`slotIndex`.
## Args:
* `index` (`int`): index of plugin on channel rack or mixer
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to -1.
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to `-1`.
* `flag` (`int`, optional): color type to return:
* `GC_BackgroundColor` (`0`, default): The darkest background color
of the plugin.
* `GC_BackgroundColor` (`0`, default): The darkest background color
of the plugin.
* `GC_Semitone` (`1`): Retrieves semitone color (in FPC, returns
color of drum pads).
* `GC_Semitone` (`1`): Retrieves semitone color (in FPC, returns
color of drum pads).
* `useGlobalIndex` (`bool`, optional): whether to use global channel
indexes when modifying plugins on the channel rack. Defaults to `False`.
## Returns:
* `int`: color (`0x--BBGGRR`)
Expand All @@ -257,7 +313,8 @@ def getName(
index: int,
slotIndex: int = -1,
flag: int = midi.FPN_Param,
paramIndex: int = 0
paramIndex: int = 0,
useGlobalIndex: bool = False,
) -> str:
"""Returns various names for parts of plugins for the plugin at
`index`/`slotIndex`.
Expand All @@ -269,7 +326,7 @@ def getName(
## Args:
* `index` (`int`): index of plugin on channel rack or mixer
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to -1.
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to `-1`.
* `flag` (`int`, optional): name type to return. Names marked with a *
require the `paramIndex` parameter in order to work correctly.
Expand Down Expand Up @@ -306,6 +363,9 @@ def getName(
* `paramIndex` (`int`, optional): index required by requested flag (if
necessary)
* `useGlobalIndex` (`bool`, optional): whether to use global channel
indexes when modifying plugins on the channel rack. Defaults to `False`.
## Returns:
* `str`: name of requested parameter
Expand All @@ -319,7 +379,8 @@ def getPadInfo(
chanIndex: int,
slotIndex: int = -1,
paramOption: int = 0,
paramIndex: int = -1
paramIndex: int = -1,
useGlobalIndex: bool = False,
) -> int:
"""
Returns info about drum pads
Expand All @@ -333,7 +394,7 @@ def getPadInfo(
## Args:
* `chanIndex` (`int`): channel of plugin to check
* `slotIndex` (`int`, optional): slot of mixer track plugin. Defaults to -1.
* `slotIndex` (`int`, optional): slot of mixer track plugin. Defaults to `-1`.
* `paramOption` (`int`, optional): type of query:
* `0`: number of pads (note: given number is one greater than there
Expand All @@ -345,6 +406,9 @@ def getPadInfo(
* `paramIndex` (`int`, optional): drum pad number (0-indexed)
* `useGlobalIndex` (`bool`, optional): whether to use global channel
indexes when modifying plugins on the channel rack. Defaults to `False`.
## Returns:
* `int`: number of parameters, or
Expand All @@ -358,39 +422,61 @@ def getPadInfo(


@since(15)
def getPresetCount(index: int, slotIndex: int = -1) -> int:
def getPresetCount(
index: int,
slotIndex: int = -1,
useGlobalIndex: bool = False,
) -> int:
"""Returns the number of presets available for the selected plugin.
## Args:
* `index` (`int`): index of plugin on channel rack or mixer.
* `index` (`int`): index of plugin on channel rack or mixer.
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to `-1`.
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to -1.
* `useGlobalIndex` (`bool`, optional): whether to use global channel
indexes when modifying plugins on the channel rack. Defaults to `False`.
Included since API version 15
"""
return 0


@since(10)
def nextPreset(index: int, slotIndex: int = -1) -> None:
def nextPreset(
index: int,
slotIndex: int = -1,
useGlobalIndex: bool = False,
) -> None:
"""Navigate to the next preset for plugin at `index`/`slotIndex`.
## Args:
* `index` (`int`): index of plugin on channel rack or mixer
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to -1.
* `index` (`int`): index of plugin on channel rack or mixer
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to `-1`.
* `useGlobalIndex` (`bool`, optional): whether to use global channel
indexes when modifying plugins on the channel rack. Defaults to `False`.
Included since API version 10
"""


@since(10)
def prevPreset(index: int, slotIndex: int = -1) -> None:
def prevPreset(
index: int,
slotIndex: int = -1,
useGlobalIndex: bool = False,
) -> None:
"""Navigate to the previous preset for plugin at `index`/`slotIndex`.
## Args:
* `index` (`int`): index of plugin on channel rack or mixer
* `index` (`int`): index of plugin on channel rack or mixer
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to `-1`.
* `slotIndex` (`int`, optional): mixer slot if on mixer. Defaults to -1.
* `useGlobalIndex` (`bool`, optional): whether to use global channel
indexes when modifying plugins on the channel rack. Defaults to `False`.
Included since API version 10
"""

0 comments on commit 19cdd25

Please sign in to comment.