Skip to content

Utils

Util

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

Height()

Returns the height of a rectangle

Returns:
  • int: height

Width()

Returns width of a rectangle

Returns:
  • int: width

__init__(left, top, right, bottom)

Create a TRect object representing a rectangle

Args:

  • left (int): left position

  • top (int): top position

  • right (int): right position

  • bottom (int): bottom position

ColorToRGB(Color)

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

DivModU(A, B)

Return integer division and modulus

Args:

  • A (int): int 1

  • B (int): int 2

Returns:

  • int: integer division

  • int: modulus

FadeColor(StartColor, EndColor, Value)

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

GetNoteName(NoteNum)

Return the note name given a note number

Args:

  • NoteNum (int): note number

Returns:

  • str: note name

HSVtoRGB(H, S, V)

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)

InterNoSwap(X, A, B)

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

KnobAccelToRes2(Value)

TODO

Args:

  • Value (type): [description]

Returns:

LightenColor(Color, Value)

Lighten a color by a certain amount

Args:

  • Color (int): color integer

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

Returns:

  • int: lightened color

Limited(Value, Min, Max)

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

OffsetRect(R, dx, dy)

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

RGBToColor(R, G, B)

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

RGBToHSV(R, G, B)

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(Color)

Convert an RGB color to a HSV color

Args:

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

Returns:

  • H: hue

  • S: saturation

  • V: value (brightness)

RectOverlap(R1, R2)

Returns whether two rectangles are overlapping

Args:

  • R1 (TRect): rectangle 1

  • R2 (TRect): rectangle 2

Returns:

  • bool: whether rectangles overlap

RectOverlapEqual(R1, R2)

Returns whether two rectangles are overlapping or touching

Args:

  • R1 (TRect): rectangle 1

  • R2 (TRect): rectangle 2

Returns:

  • bool: whether rectangles overlap or touch

Sign(value)

Equivalent to SignOf()

Args:

  • value (float | int): number

Returns:

  • int: sign

SignOf(value)

Return the sign of a numerical value

Args:

  • value (float | int): number

Returns:

  • int: sign:

    • 0: zero

    • 1: positive

    • -1: negative

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

VolTodB(Value)

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

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

TODO

Args:

  • value (type): [description]

  • nChars (type): [description]

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

Returns:

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