Plugin

Bases: _FLObject

Represents a native or VST2/VST3 effect or instrument.

Parses only Channel.EventID.Plugin/InsertSlot.EventID.Plugin.

Source code in pyflp/plugin/_plugin.py

class _Plugin(_FLObject):
    """Represents a native or VST2/VST3 effect or instrument.

    Parses only `Channel.EventID.Plugin`/`InsertSlot.EventID.Plugin`.
    """

    CHUNK_SIZE: Optional[int] = None
    """Expected size of event data passed to `parse_event`.

    Parsing is skipped in case the size is not equal to this.
    """

    def _save(self) -> List[EventType]:
        self._r.seek(0)
        self._events["plugin"].dump(self._r.read())
        return super()._save()

    def _parse_data_event(self, e: DataEventType) -> None:
        self._events["plugin"] = e
        if self.CHUNK_SIZE is not None:
            dl = len(e.data)
            if dl != self.CHUNK_SIZE:  # pragma: no cover
                return
        self._r = BytesIOEx(e.data)

CHUNK_SIZE: Optional[int] = None class-attribute

Expected size of event data passed to parse_event.

Parsing is skipped in case the size is not equal to this.

VSTPlugin

Info

A VSTPlugin event has events inside it. Their structure is as follows:

Name	Type	Offset
id	B	0
size	Q	1
data	N.A	9

This event is implemented by _QWordVariableEvent.

Bases: _Plugin

VST2/3 (including Waveshells, maybe AU as well) plugin data (ChannelEventID.Plugin & InsertSlotEventID.Plugin event).

Manual

Source code in pyflp/plugin/vst.py

class VSTPlugin(_Plugin):
    """VST2/3 (including Waveshells, *maybe AU as well*) plugin data
    (`ChannelEventID.Plugin` & `InsertSlotEventID.Plugin` event).

    [Manual](https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/plugins/wrapper.htm#wrapper_pluginsettings)
    """  # noqa

    PLUGIN_VST = 8, 10

    @dataclasses.dataclass(init=False)
    class PluginIOInfo:
        mixer_offset: int
        flags: int

    # TODO
    def _setprop(self, n: str, v: Any):
        if n not in ("name", "vendor", "plugin_path", "fourcc", "state", "guid"):
            raise NotImplementedError
        self.__vpe.dump(n, v)
        super()._setprop(n, v)

    # * Properties
    midi_in: Optional[int] = _UIntProperty(max_=255)
    """MIDI Input Port. Min: 0, Max: 255, Default: TODO."""

    midi_out: Optional[int] = _UIntProperty(max_=255)
    """MIDI Output Port. Min: 0, Max: 255, Default: TODO."""

    pb_range: Optional[int] = _UIntProperty()
    """VST Wrapper settings -> MIDI -> Send pitch bend range (semitones)."""

    flags: Optional[int] = _IntProperty()
    """VST Wrapper settings, boolean values TODO"""

    inputs: Optional[int] = _UIntProperty()
    """Number of inputs to a plugin. Depend on the plugin.
    VST Wrapper settings -> Processing -> Connections."""

    outputs: Optional[int] = _UIntProperty()
    """Number of outputs of a plugin. Depend on the plugin.
    VST Wrapper settings -> Processing -> Connections."""

    @property
    def input_infos(self) -> List[PluginIOInfo]:
        """Input information."""
        return getattr(self, "_input_infos", [])

    @property
    def output_info(self) -> List[PluginIOInfo]:
        """Ouput information."""
        return getattr(self, "_output_info", [])

    vst_number: Optional[int] = _UIntProperty()
    """TODO. Maybe related to Waveshells."""

    fourcc: Optional[str] = _StrProperty(minsize=4, maxsize=4, mustascii=True)
    """FourCC e.g. "GtYc" or "Syl1" - a unique VST ID.

    Reserved by plugin dev on Steinberg portal (in ASCII)."""

    # TODO Thought it was related to Waveshells only but see issue #8
    guid: Optional[bytes] = _BytesProperty()

    state: bytes = _BytesProperty()
    """The actual plugin data. Plugin specific.

    Can be a list of floats/ints, but devs generally use their own format."""

    name: str = _StrProperty(mustascii=True)
    """Factory name for VSTs (in ASCII)."""

    plugin_path: str = _StrProperty(mustascii=True)
    """The absolute path to the plugin .dll on the disk in ASCII."""

    vendor: str = _StrProperty(mustascii=True)
    """Plugin developer name (in ASCII)."""

    def parse_event(self, e: VSTPluginEvent) -> None:
        super()._parse_data_event(e)
        self.__vpe = e
        self._kind = e.kind
        self._name = e.name
        self._vendor = e.vendor
        self._plugin_path = e.plugin_path
        self._state = e.state
        self._fourcc = e.fourcc
        self._guid = e.guid

    # TODO: Improve this part
    def _save(self) -> VSTPluginEvent:
        new = bytearray(UInt.pack(self._kind))
        events = self.__vpe._parser._events
        for attr in events:
            new.extend(events[attr].to_raw())
        self.__vpe._data = new

        # ! `VSTPluginEvent.dump` works differently; `super()._save()` useless.
        # Also what it does is already achieved above
        return self.__vpe

flags: Optional[int] = _IntProperty() class-attribute

VST Wrapper settings, boolean values TODO

fourcc: Optional[str] = _StrProperty(minsize=4, maxsize=4, mustascii=True) class-attribute

FourCC e.g. "GtYc" or "Syl1" - a unique VST ID.

Reserved by plugin dev on Steinberg portal (in ASCII).

guid: Optional[bytes] = _BytesProperty() class-attribute

name: str = _StrProperty(mustascii=True) class-attribute

Factory name for VSTs (in ASCII).

plugin_path: str = _StrProperty(mustascii=True) class-attribute

The absolute path to the plugin .dll on the disk in ASCII.

state: bytes = _BytesProperty() class-attribute

The actual plugin data. Plugin specific.

Can be a list of floats/ints, but devs generally use their own format.

vendor: str = _StrProperty(mustascii=True) class-attribute

Plugin developer name (in ASCII).

vst_number: Optional[int] = _UIntProperty() class-attribute

TODO. Maybe related to Waveshells.

Native effects

Fruity Balance

Bases: _EffectPlugin

Implements Fruity Balance. 2 knobs. 8 bytes.

Manual

Source code in pyflp/plugin/effects/balance.py

class FBalance(_EffectPlugin):
    """Implements Fruity Balance. 2 knobs. 8 bytes.

    [Manual](https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/plugins/Fruity%20Balance.htm)
    """

    CHUNK_SIZE = 8

    def _setprop(self, n: str, v: int) -> None:
        r = self._r
        if n == "pan":
            r.seek(0)
        elif n == "volume":
            r.seek(4)
        r.write_i(v)

    # * Properties
    pan: int = _IntProperty(min_=-128, max_=127)
    """Panning. Min: -128, Max: 127, Default: 0 (0.50, Centred). Linear."""

    volume: int = _UIntProperty(max_=320)
    """Volume. Min: 0, Max: 320, Default: 256 (0.80, 0dB). Logarithmic."""

    def _parse_data_event(self, e: DataEventType) -> None:
        super()._parse_data_event(e)
        self._pan = self._r.read_I()
        self._volume = self._r.read_I()

pan: int = _IntProperty(min_=-128, max_=127) class-attribute

Panning. Min: -128, Max: 127, Default: 0 (0.50, Centred). Linear.

volume: int = _UIntProperty(max_=320) class-attribute

Volume. Min: 0, Max: 320, Default: 256 (0.80, 0dB). Logarithmic.

Fruity Soft Clipper

Bases: _EffectPlugin

Implements Fruity Soft Clipper. 2 knobs. 8 bytes.

Manual

Source code in pyflp/plugin/effects/soft_clipper.py

class FSoftClipper(_EffectPlugin):
    """Implements Fruity Soft Clipper. 2 knobs. 8 bytes.

    [Manual](https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/plugins/Fruity%20Soft%20Clipper.htm)
    """

    CHUNK_SIZE = 8

    def _setprop(self, n: str, v: int) -> None:
        r = self._r
        if n == "threshold":
            r.seek(0)
        elif n == "post":
            r.seek(4)
        r.write_I(v)

    # * Properties
    threshold: int = _IntProperty(min_=1, max_=127)
    """Threshold. Min: 1, Max: 127, Default: 100 (0.60, -4.4dB). Logarithmic."""

    post: int = _UIntProperty(max_=160)
    """Post gain. Min: 0, Max: 160, Default: 128 (80%). Linear."""

    def _parse_data_event(self, e: DataEventType) -> None:
        super()._parse_data_event(e)
        r = self._r
        self._threshold = r.read_I()
        self._post = r.read_I()

threshold: int = _IntProperty(min_=1, max_=127) class-attribute

Threshold. Min: 1, Max: 127, Default: 100 (0.60, -4.4dB). Logarithmic.

Fruity Stereo Enhancer

Bases: _EffectPlugin

Implements Fruity Stereo Enhancer. 6 knobs. 24 bytes.

Manual

Source code in pyflp/plugin/effects/stereo_enhancer.py

class FStereoEnhancer(_EffectPlugin):
    """Implements Fruity Stereo Enhancer. 6 knobs. 24 bytes.

    [Manual](https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/plugins/Fruity%20Stereo%20Enhancer.htm)
    """

    CHUNK_SIZE = 24

    class EffectPosition(enum.IntEnum):
        """Pre or post effect position. Used by `effect_position`."""

        PRE = 0
        POST = 1

    class PhaseInversion(enum.IntEnum):
        """None, left, right phase inversion. Used by `phase_inversion`."""

        NONE = 0
        LEFT = 1
        RIGHT = 2

    def _setprop(self, n: str, v: int) -> None:
        r = self._r
        if n == "pan":
            r.seek(0)
        if n == "volume":
            r.seek(4)
        elif n == "stereo_separation":
            r.seek(8)
        elif n == "phase_offset":
            r.seek(12)
        elif n == "effect_position":
            r.seek(16)
        elif n == "phase_inversion":
            r.seek(20)
        r.write_I(v)

    # * Properties
    pan: int = _IntProperty(min_=-128, max_=127)
    """Min: -128, Max: 127, Default: 0 (0.50, Centred). Linear."""

    volume: int = _UIntProperty(max_=320)
    """Min: 0, Max: 320, Default: 256 (0.80, 0dB). Logarithmic."""

    stereo_separation: int = _IntProperty(min_=-96, max_=96)
    """Min: -96 (100% separation), Max: 96 (100% merged), Default: 0. Linear."""

    phase_offset: int = _IntProperty(min_=-512, max_=512)
    """Min: -512 (500ms L), Max: 512 (500ms R), Default: 0 (no offset). Linear."""

    phase_inversion: PhaseInversion = _EnumProperty(PhaseInversion)
    """0: none, 1: left, 2: right Default: 0. Linear. Stepped."""

    effect_position: EffectPosition = _EnumProperty(EffectPosition)
    """0: pre, 1: post , Default: 0. Linear. Stepped."""

    # * Parsing logic
    def _parse_data_event(self, e: DataEventType) -> None:
        super()._parse_data_event(e)
        r = self._r
        self._pan = r.read_i()
        self._volume = r.read_I()
        self._stereo_separation = r.read_i()
        self._phase_offset = r.read_i()
        self._effect_position = self.EffectPosition(r.read_I())
        self._phase_inversion = self.PhaseInversion(r.read_I())

pan: int = _IntProperty(min_=-128, max_=127) class-attribute

Min: -128, Max: 127, Default: 0 (0.50, Centred). Linear.

volume: int = _UIntProperty(max_=320) class-attribute

Min: 0, Max: 320, Default: 256 (0.80, 0dB). Logarithmic.

stereo_separation: int = _IntProperty(min_=-96, max_=96) class-attribute

Min: -96 (100% separation), Max: 96 (100% merged), Default: 0. Linear.

phase_offset: int = _IntProperty(min_=-512, max_=512) class-attribute

Min: -512 (500ms L), Max: 512 (500ms R), Default: 0 (no offset). Linear.

phase_inversion: PhaseInversion = _EnumProperty(PhaseInversion) class-attribute

0: none, 1: left, 2: right Default: 0. Linear. Stepped.

effect_position: EffectPosition = _EnumProperty(EffectPosition) class-attribute

0: pre, 1: post , Default: 0. Linear. Stepped.

Soundgoodizer

Bases: _EffectPlugin

Implements Soundgoodizer. 2 knobs. 12 bytes

Manual

Source code in pyflp/plugin/effects/soundgoodizer.py

class Soundgoodizer(_EffectPlugin):
    """Implements Soundgoodizer. 2 knobs. 12 bytes

    [Manual](https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/plugins/Soundgoodizer.htm)
    """

    CHUNK_SIZE = 12

    class Mode(enum.IntEnum):
        """One of the Soundgoodizer modes. Used by `Soundgoodizer.mode`."""

        A = 0
        B = 1
        C = 2
        D = 3

    def _setprop(self, n: str, v: int) -> None:
        r = self._r
        if n == "mode":
            r.seek(4)
        elif n == "amount":
            r.seek(8)
        r.write_I(v)

    mode: Mode = _EnumProperty(Mode)
    """See `Mode`. Default: `Mode.A`"""

    amount: int = _UIntProperty(max_=1000)
    """Amount. Min: 0, Max: 1000, Default: 600. Logarithmic."""

    def _parse_data_event(self, e: DataEventType) -> None:
        super()._parse_data_event(e)
        r = self._r
        r.seek(4)  # 3, 0, 0, 0
        self._mode = r.read_I()
        self._amount = r.read_I()

amount: int = _UIntProperty(max_=1000) class-attribute

Amount. Min: 0, Max: 1000, Default: 600. Logarithmic.

mode: Mode = _EnumProperty(Mode) class-attribute

See Mode. Default: Mode.A

Mode

Bases: enum.IntEnum

One of the Soundgoodizer modes. Used by Soundgoodizer.mode.

Source code in pyflp/plugin/effects/soundgoodizer.py

class Mode(enum.IntEnum):
    """One of the Soundgoodizer modes. Used by `Soundgoodizer.mode`."""

    A = 0
    B = 1
    C = 2
    D = 3

A = 0 class-attribute

B = 1 class-attribute

C = 2 class-attribute

D = 3 class-attribute

Fruity Notebook 2

Bases: _EffectPlugin

Implements Fruity Notebook 2.

Manual

Source code in pyflp/plugin/effects/notebook2.py

class FNoteBook2(_EffectPlugin):
    """Implements Fruity Notebook 2.

    [Manual](https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/plugins/Fruity%20NoteBook%202.htm)
    """

    # 0,0,0,0 4b
    # active page number 4b
    # page number 4b - (data length / 2) varint - text in utf16 for each page
    # 255, 255, 255, 255 4b
    # Editing enabled or disabled 1b

    def __repr__(self) -> str:
        return "<Fruity Notebook 2 {}, {}, {}>".format(
            f"{len(self.pages)} pages",
            f"active_page_number={self.active_page}",
            f"editable={self.editable}",
        )

    # * Properties
    @property
    def pages(self) -> List[str]:
        """List of strings. One string per page."""
        return self._pages

    @pages.setter
    def pages(self, value: List[str]) -> None:
        self._r.seek(8)
        for page_num, page in enumerate(value):
            self._r.write_I(page_num)  # TODO: or page_num + 1?
            wstr = page.encode("utf-16", errors="ignore")
            self._r.write_v(len(wstr))
            self._r.write(wstr)  # NULL bytes are not appended at the end
        self._pages = value

    @property
    def active_page(self) -> Optional[int]:
        """Currently selected page number."""
        return getattr(self, "_active_page", None)

    @active_page.setter
    def active_page(self, value: int) -> None:
        num_pages = len(self._pages) + 1
        if value not in range(1, num_pages):
            raise ValueError(f"Expected a value in (1, {num_pages})")
        self._r.seek(4)
        self._r.write_I(value)
        super()._setprop("active_page", value)

    @property
    def editable(self) -> Optional[bool]:
        """Whether notebook is editable or read-only."""
        return getattr(self, "_editable", None)

    @editable.setter
    def editable(self, value: bool) -> None:
        self._r.seek(-1, 2)
        self._r.write_bool(value)
        super()._setprop("editable", value)

    def _parse_data_event(self, e: DataEventType) -> None:
        super()._parse_data_event(e)
        r = self._r
        r.seek(4)
        self._active_page = r.read_I()
        while True:
            page_num = r.read_i()
            if page_num == -1:
                break
            size = r.read_v()
            buffer = r.read(size * 2)
            self._pages.append(buffer.decode("utf-16", errors="ignore"))
        self._editable = r.read_bool()

    def __init__(self) -> None:
        self._pages = []
        super().__init__()

active_page() writable property

Currently selected page number.

Source code in pyflp/plugin/effects/notebook2.py

@property
def active_page(self) -> Optional[int]:
    """Currently selected page number."""
    return getattr(self, "_active_page", None)

editable() writable property

Whether notebook is editable or read-only.

Source code in pyflp/plugin/effects/notebook2.py

@property
def editable(self) -> Optional[bool]:
    """Whether notebook is editable or read-only."""
    return getattr(self, "_editable", None)

pages() writable property

List of strings. One string per page.

Source code in pyflp/plugin/effects/notebook2.py

@property
def pages(self) -> List[str]:
    """List of strings. One string per page."""
    return self._pages

Fruity Send

Bases: _EffectPlugin

Implements Fruity Send. 4 knobs. 16 bytes.

Manual

Source code in pyflp/plugin/effects/send.py

class FSend(_EffectPlugin):
    """Implements Fruity Send. 4 knobs. 16 bytes.

    [Manual](https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/plugins/Fruity%20Send.htm)
    """

    CHUNK_SIZE = 16

    def _setprop(self, n: str, v: int) -> None:
        r = self._r
        if n == "dry":
            r.seek(0)
        elif n == "pan":
            r.seek(4)
        elif n == "volume":
            r.seek(8)
        elif n == "send_to":
            r.seek(12)
        r.write_i(v)

    # * Properties
    dry: int = _UIntProperty(max_=256)
    """Dry/wet. Min: 0 (0%), Max: 256 (100%), Default: 256 (100%). Linear."""

    pan: int = _IntProperty(min_=-128, max_=127)
    """Pan. Min: -128 (100% left), Max: 127 (100% right),
    Default: 0 (Centred). Linear."""

    volume: int = _UIntProperty(max_=320)
    """Volume. Min: 0 (-INF db, 0.00), Max: 320 (5.6 dB, 1.90),
    Default: 256 (0.0 dB, 1.00). Logarithmic."""

    send_to: int = _IntProperty()
    """Target insert index; depends on insert routing. Default: -1 (Master)."""

    # * Parsing logic
    def _parse_data_event(self, e: DataEventType) -> None:
        super()._parse_data_event(e)
        r = self._r
        self._pan = r.read_I()
        self._dry = r.read_I()
        self._volume = r.read_I()
        self._send_to = r.read_i()

dry: int = _UIntProperty(max_=256) class-attribute

Dry/wet. Min: 0 (0%), Max: 256 (100%), Default: 256 (100%). Linear.

pan: int = _IntProperty(min_=-128, max_=127) class-attribute

Pan. Min: -128 (100% left), Max: 127 (100% right), Default: 0 (Centred). Linear.

volume: int = _UIntProperty(max_=320) class-attribute

Volume. Min: 0 (-INF db, 0.00), Max: 320 (5.6 dB, 1.90), Default: 256 (0.0 dB, 1.00). Logarithmic.

send_to: int = _IntProperty() class-attribute

Target insert index; depends on insert routing. Default: -1 (Master).

Fruity Fast Dist

Bases: _EffectPlugin

Implements Fruity Fast Dist. 5 knobs. 20 bytes.

Manual

Source code in pyflp/plugin/effects/fast_dist.py

class FFastDist(_EffectPlugin):
    """Implements Fruity Fast Dist. 5 knobs. 20 bytes.

    [Manual](https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/plugins/Fruity%20Fast%20Dist.htm)
    """

    CHUNK_SIZE = 20

    class Kind(enum.IntEnum):
        """One of the distortion types. Used by `kind`."""

        A = 0
        B = 1

    def _setprop(self, n: str, v: Union[int, Kind]):
        r = self._r
        if n == "pre":
            r.seek(0)
        elif n == "threshold":
            r.seek(4)
        elif n == "kind":
            r.seek(8)
        elif n == "mix":
            r.seek(12)
        elif n == "post":
            r.seek(16)
        r.write_I(v)

    # * Properties
    pre: int = _IntProperty(min_=64, max_=192)
    """Pre amp. Min: 64 (33%), Max: 192 (100%), Default: 128 (67%). Linear."""

    threshold: int = _IntProperty(min_=1, max_=10)
    """Threshold. Min: 1 (10%), Max: 10 (100%), Default: 10 (100%). Linear. Stepped."""

    kind: Kind = _EnumProperty(Kind)
    """Distortion type. Default: `Kind.A`. See `Kind`."""

    mix: int = _UIntProperty(max_=128)
    """Mix. Min: 0 (0%), Max: 128 (100%), Default: 128 (100%). Linear."""

    post: int = _UIntProperty(max_=128)
    """Post gain. Min: 0 (0%), Max: 128 (100%), Default: 128 (100%). Linear."""

    # * Parsing logic
    def _parse_data_event(self, e: DataEventType) -> None:
        super()._parse_data_event(e)
        r = self._r
        self._pre = r.read_I()
        self._threshold = r.read_I()
        self._kind = self.Kind(r.read_I())
        self._mix = r.read_I()
        self._post = r.read_I()

pre: int = _IntProperty(min_=64, max_=192) class-attribute

Pre amp. Min: 64 (33%), Max: 192 (100%), Default: 128 (67%). Linear.

threshold: int = _IntProperty(min_=1, max_=10) class-attribute

Threshold. Min: 1 (10%), Max: 10 (100%), Default: 10 (100%). Linear. Stepped.

kind: Kind = _EnumProperty(Kind) class-attribute

Distortion type. Default: Kind.A. See Kind.

mix: int = _UIntProperty(max_=128) class-attribute

Mix. Min: 0 (0%), Max: 128 (100%), Default: 128 (100%). Linear.

post: int = _UIntProperty(max_=128) class-attribute

Post gain. Min: 0 (0%), Max: 128 (100%), Default: 128 (100%). Linear.

Kind

Bases: enum.IntEnum

One of the distortion types. Used by kind.

Source code in pyflp/plugin/effects/fast_dist.py

class Kind(enum.IntEnum):
    """One of the distortion types. Used by `kind`."""

    A = 0
    B = 1

A = 0 class-attribute

B = 1 class-attribute

Native synths

BooBass

Bases: _SynthPlugin

Implements BooBass. 3 knobs. 16 bytes.

Manual

Source code in pyflp/plugin/synths/boobass.py

class BooBass(_SynthPlugin):
    """Implements BooBass. 3 knobs. 16 bytes.

    [Manual](https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/plugins/BooBass.htm)"""  # noqa

    CHUNK_SIZE = 16

    def _setprop(self, n: str, v: int) -> None:
        r = self._r
        if n == "bass":
            r.seek(4)
        elif n == "mid":
            r.seek(8)
        elif n == "high":
            r.seek(12)
        r.write_I(v)

    bass: int = _UIntProperty(max_=65535)
    """Min: 0, Max: 65535, Default: 32767."""

    mid: int = _UIntProperty(max_=65535)
    """Min: 0, Max: 65535, Default: 32767."""

    high: int = _UIntProperty(max_=65535)
    """Min: 0, Max: 65535, Default: 32767."""

    def _parse_data_event(self, e: DataEventType) -> None:
        super()._parse_data_event(e)
        r = self._r
        r.seek(4)  # 1, 0, 0, 0
        self._bass = r.read_I()
        self._mid = r.read_I()
        self._high = r.read_I()

bass: int = _UIntProperty(max_=65535) class-attribute

Min: 0, Max: 65535, Default: 32767.

mid: int = _UIntProperty(max_=65535) class-attribute

Min: 0, Max: 65535, Default: 32767.

high: int = _UIntProperty(max_=65535) class-attribute

Min: 0, Max: 65535, Default: 32767.