Skip to content

Utils

Module included in FL Studio Python lib folder.

Contains useful functions and classes for use when working with FL Studio's Python API.

Note

This code is taken from FL Studio's Python lib folder and included in this package in the hope that it will be useful for script developers. It is not the creation of the repository authors, and no credit is claimed for the code content. However, the documentation for the provided code is created by the authors of this repository.

WARNING

Many of the provided functions in the FL Studio installation have bugs that may result in unexpected behavior. These bugs have been left as-is in this file for your inspection and warnings have been added to the docstrings. Use any functions here with caution.

TRect

Represents a rectangle object

__init__ 

__init__(left: int, top: int, right: int, bottom: int)

Create a TRect object representing a rectangle

Args:

  • left (int): left position

  • top (int): top position

  • right (int): right position

  • bottom (int): bottom position

Width 

Width() -> int

Returns width of a rectangle

Returns:
  • int: width

Height 

Height() -> int

Returns the height of a rectangle

Returns:
  • int: height

RectOverlapEqual 

RectOverlapEqual(R1: TRect, R2: TRect) -> bool

Returns whether two rectangles are overlapping or touching

Args:

  • R1 (TRect): rectangle 1

  • R2 (TRect): rectangle 2

Returns:

  • bool: whether rectangles overlap or touch

RectOverlap 

RectOverlap(R1: TRect, R2: TRect) -> bool

Returns whether two rectangles are overlapping

Args:

  • R1 (TRect): rectangle 1

  • R2 (TRect): rectangle 2

Returns:

  • bool: whether rectangles overlap

Limited 

Limited(Value: float, Min: float, Max: float) -> float

Limit a value to within the range Min - Max

Args:

  • Value (float): Current value

  • Min (float): Min value

  • Max (float): Max value

Returns:

  • float: limited value

InterNoSwap 

InterNoSwap(X, A, B) -> bool

Returns whether A <= X <= B, ie. whether X lies between A and B

Args:

  • X (number): x

  • A (number): a

  • B (number): b

Returns:

  • bool

DivModU 

DivModU(A: int, B: int) -> tuple[int, int]

Return integer division and modulus

Args:

  • A (int): int 1

  • B (int): int 2

Returns:

  • int: integer division

  • int: modulus

SwapInt 

SwapInt(A, B)

Given A and B, return B and A

It's probably easier to just manually write 

A, B = B, A
in your code to begin with.

Args:

  • A (any): thing 1

  • B (any): thing 2

Returns:

  • tuple: B, A

Zeros 

Zeros(value, nChars, c='0')

TODO

Args:

  • value (type): [description]

  • nChars (type): [description]

  • c (str, optional): [description]. Defaults to '0'.

Returns:

Zeros_Strict 

Zeros_Strict(value, nChars, c='0')

TODO

Args:

  • value (type): [description]

  • nChars (type): [description]

  • c (str, optional): [description]. Defaults to '0'.

Returns:

WARNING
  • Strict trimming looks incorrect

Sign 

Sign(value: float | int) -> int

Equivalent to SignOf()

Args:

  • value (float | int): number

Returns:

  • int: sign

SignOf 

SignOf(value: float | int) -> int

Return the sign of a numerical value

Args:

  • value (float | int): number

Returns:

  • int: sign:

    • 0: zero

    • 1: positive

    • -1: negative

KnobAccelToRes2 

KnobAccelToRes2(Value)

TODO

Args:

  • Value (type): [description]

Returns:

OffsetRect 

OffsetRect(R: TRect, dx: int, dy: int) -> None

Offset a rectangle by dx and dy

Args:

  • R (TRect): rectangle

  • dx (int): x offset

  • dy (int): y offset

NOTE: Rectangle is adjusted in-place

RGBToHSV 

RGBToHSV(R: float, G: float, B: float) -> tuple[float, float, float]

Convert an RGB color to a HSV color

WARNING: Make sure to convert

Args:

  • R (float): red (0.0 - 1.0)

  • G (float): green (0.0 - 1.0)

  • B (float): blue (0.0 - 1.0)

Returns:

  • H: hue (degrees: 0.0-360)

  • S: saturation (0.0-1.0)

  • V: value/luminosity (0.0/1.0)

RGBToHSVColor 

RGBToHSVColor(Color: int) -> tuple[float, float, float]

Convert an RGB color to a HSV color

Args:

  • Color (int): color as integer (0x--BBGGRR)

Returns:

  • H: hue

  • S: saturation

  • V: value (brightness)

HSVtoRGB 

HSVtoRGB(H: float, S: float, V: float) -> tuple[float, float, float]

Convert an HSV color to an RGB color

WARNING: This function returns data in an unexpected format! Be sure to convert as required before usage.

Args:

  • H (float): hue (degrees: 0.0-360)

  • S (float): saturation (0-1.0)

  • V (float): value/luminosity (0-1.0)

Returns:

  • float: red (0.0-1.0)

  • float: green (0.0-1.0)

  • float: blue (0.0-1.0)

GetNoteName 

GetNoteName(NoteNum: int) -> str

Return the note name given a note number

Args:

  • NoteNum (int): note number

Returns:

  • str: note name

ColorToRGB 

ColorToRGB(Color: int) -> tuple[int, int, int]

Convert an integer color to an RGB tuple that uses range 0-255.

Args:

  • Color (int): color as integer

Returns:

  • int: red

  • int: green

  • int: blue

RGBToColor 

RGBToColor(R: int, G: int, B: int) -> int

convert an RGB set to an integer color. values must be 0-255

Args:

  • R (int): red

  • G (int): green

  • B (int): blue

Returns:

  • int: color

FadeColor 

FadeColor(StartColor: int, EndColor: int, Value: float) -> int

Fade between two colors

Args:

  • StartColor (int): color integer

  • EndColor (int): color integer

  • Value (float): fade position (0-255)

Returns:

  • int: faded color
WARNING
  • Blue value is incorrect, using green start value

LightenColor 

LightenColor(Color: int, Value: float) -> int

Lighten a color by a certain amount

Args:

  • Color (int): color integer

  • Value (float): amount to lighten by (0-255)

Returns:

  • int: lightened color

VolTodB 

VolTodB(Value: float) -> float

Convert volume as a decimal (0.0 - 1.0) to a decibel value

WARNING:
  • For zero volume, this returns 0 instead of -oo dB

Args:

  • Value (float): volume

Returns:

  • float: volume in decibels