Basic preset development

Introduction

For this and all of the other development pages, I assume that you have a basic understanding of the Python language, but not much background is necessary to understand preset development.

User-made presets are all subclasses of the Preset class. This class describes a common interface that each preset must implement. The following methods are designed to be overridden in your preset:

def setup():
    """This method is called once when a preset is loaded.  Put any initialization code here."""

def parameter_changed():
    """This method is called when any parameters are changed (by the GUI)."""

def reset():
    """This method is called right before the preset becomes active in the playlist."""

Tickers

Basic presets use a concept called a "ticker" to define the preset behavior. A ticker is a function that is called by the mixer during each frame, and can return the behavior of a single pixel or a group of pixels. Some tickers are defined in basic_tickers.py, but you can feel free to add others in your preset (or submit a pull request to add them to basic_tickers.py if they could be useful to other presets).

To understand how tickers work, let's take a look at a few examples. First, the simplest preset, RGBFade. This preset applies a rainbow color change to all pixels at the same time.

from lib.preset import Preset
from lib.basic_tickers import fade, speed
from lib.color_fade import Rainbow
from lib.parameters import FloatParameter

class RGBFade(Preset):
    """Simple RGB fade"""

    def setup(self):
        self.add_parameter(FloatParameter('speed', 0.2))
        self.add_ticker(speed(fade((), Rainbow), self.parameter('speed')))

Here, we use the speed and fade tickers. From the Preset.add_ticker() documentation:

def add_ticker(self, ticker, priority=0):
    """
    Adds a ticker. Tickers are run every tick and can yield any number of (lights, color) tuples.
 
    lights is one of:
        an empty tuple (to change all strands)
        a (strand) tuple (to change all addresses on the strand)
        a (strand, address) tuple (to change all pixels on the strand)
        a (strand, address, pixel) tuple (to change a single pixel)
        a list of any of the above tuples

    color is an (r, g, b) tuple where r, g, and b are either:
        integers between 0 and 255
        floats between 0 and 1
    """

The second argument to fade() is an instance of the ColorFade class. Rainbow is a pre-defined instance that fades between all the possible hues, but you can define your own (more on that later).