From Nutcracker Wiki
Jump to: navigation, search


Sequencer 0.png

The sequencer is where the majority of time will be spent and where most of the functionality that the user sees resides. The main areas and functions of the Sequence tab are as follows:

Sequencer Main.png


On the left hand side of the sequencer, a list of open Windows are displayed. To select additional Windows, click on View, Windows and select the windows that you wish to have displayed, if the window is not open.

Sequencer 1.png

You can close a Window or move them around or if you have an additional monitor configured, then one or move Windows can be moved to the alternate monitor.

You can save the windows that you normally have open as your default perspective. These windows will then be opened when you load xLights.

Timing Tracks

xLights/Nutcracker can support multiple timing tracks on the sequencer, each with different frequencies of timing marks. By default, a timing track ‘New Timing’ is created for each sequence if you have not created one when creating a new sequence.

Timing Tracks can be added via the Settings , Sequence Settings , Timing Tracks menu. Then select a new Timing Grid.

When you create a timing track it gets added to all views that you have defined. Timing tracks are local to a sequence.

The timing marks create a grid but once the effects are dropped they have no relation to the original timing marks that were used to drop them. You can switch to any other timing track and have a completely different grid.

If you have multiple timing tracks defined,

  • Each timing track has a different color of timing marks.
  • You can select the timing track radio button (to the left of the timing track name) to enable that track. You can also select more than one timing track to be displayed at the same time, however only one timing track will be active for effects to calculate the start and end position.

Sequencer Timing.png

You can set up timing marks on any timing track manually, by placing your cursor on the waveform (above the grid) and while playing the sequence, press the ‘t’ key where you wish the timing mark to appear. You can add new timing tracks or delete an existing timing track at any time. You can also import timing marks created externally (the most common being those created via Audacity). In order to do this, right click on a timing track, and select Add Timing Track or Delete Timing Track.

Sequencer Timing2.png

To import one that has been created externally, select Import Timing Track, navigate to the .txt file containing the timing track and click OK to import it.


A model in xLights/Nutcracker defines the entire required characteristic about a single physical element of your display. Typically it will represent a common item such as an arch, a matrix, a straight line, flood light as well as more esoteric and custom made items such as singing trees, candy canes, a snowman etc.

It defines the type of lights, the number of channels and other characteristics required to render the sequence data. When a model is defined, it is retained in an xLights/Nutcracker configuration .xml file in the show directory. It can be reused for all subsequent sequences – however it needs to be added to the sequence grid of each sequence as required in order for effects to then be sequenced against the model.

A model is made up of one or more strands, and each strand is made up of one or more nodes.

Strand 1.png

To define a model, after opening an existing sequence or creating a new one,

  • Click on the Models icon on the top row of the canvas or
  • Click on the Models button on the Layout window
  • Right click when in the sequencer window, select Edit Display Elements and then Add Models

Clicking on the Models icon, the model list window will display any existing models that have already been defined.

Timeline and Waveform

The top section of the display window is the Timeline section and indicates the scale that the waveform and sequencer is displaying.

Timeline 1.png

You can select an area on the timeline – depicted by the arrows - and you can then play that section once independent of the section highlighted to be played on the waveform. At the end of playing that section, the highlighted arrows disappear, leaving the waveform highlight to be played. Clicking anywhere in the timeline or highlighting an area in the timeline initiates auto play, without losing the waveform selection.

Timeline 3.png

The waveform displays a sonographic representation of the audio portion of the media that has been associated with the sequence.

Timeline 2.pngTimeline 4.png

You can control the focus of the waveform.

  • Zoom in on the waveform by double clicking on the waveform. Keep double clicking until you've got a zoom setting you can use. Or click on the ‘+’ button.
  • To zoom out, hold the shift key and double click on the waveform or click on the ‘-‘- button.

When playing the sequence, a vertical line indicates the start position and another vertical line extending right through the grid indicates where the audio being played current is. The time counter displays the time from the beginning of the sequence that the current position is up to.

You can highlight a range on the waveform to play only that section. If you move your cursor on the waveform towards either edge of the highlighted area, a ‘hand’ appears and you can use that to move the edge.

  • If the Pause button is selected, and then pressed again, the sequence will restart from the current position that it stopped at.
  • If after a Pause, if the Play button is pressed, then the sequence will restart from the marked ‘start position’.
  • Clicking on the Stop button will reset the start position to the beginning of the sequence.
  • After Stop has been pressed the Rewind button will start from the beginning of the sequence and the fast forward button will play from the last component of the sequence.
  • Highlighting a portion of the waveform will cause only that section to be played. Pressing the spacebar will replay that section.
  • The ‘Replay’ button does not currently drive any functionality.

Clicking on an effect in the grid will not alter the waveform area that has been highlighted to be played. The effect becomes the focus point, if you zoom in and out, but the play range does not change. If you do want the start position to move to where your effect is, or to be based on the edit position in the grid, then double click in the grid and that will then remove any highlighted position/area in the waveform and set the start position in line with where you have double clicked.


A view is used to be able to easily select a list of models and the sequence in which they are to be displayed on the sequencer.

Views 1.png

Views work across sequences, so once you have setup a view with the models that you require, if you open any sequence, that view is available to use in that sequence.

If you define Model Groups in a view, then when you use the view in the sequencer, you will be presented with a list of the groups. Double Clicking each group will open up the list of models within the group.

Multiple views can be defined, with each view defining a list of models that are to be displayed and the sequence that they should be displayed in. For example:

  • A ‘Static Model’ view may contain all elements that are non RGB.
  • An ‘Import Model’ view may contain only elements that you wish to sequence after importing other data from other sequencers.
  • A ‘Halloween Model’ view may contain only elements that you wish to sequence for Halloween.

New models can be added to a view by selecting that view from the Views window within the Sequence Elements window (or from the View window to the left of the Waveform) and clicking on Add Models.

Similarly models can be removed from a View by highlighting the model in the Model window within the Sequence Elements window and clicking on Delete Model. The position that the model appears within the view can be changed by highlighting the model and clicking on Move Up or Move Down. Within each view, the models that are part of the view can be marked as visible or non visible via the button to the left of the model.

Note: The visibility is across all sequences and not specific to the sequence that is open. So if you make a model non visible, it will become non visible in all sequences.

The Master View is a special (system created) view. It contains all the models that have been defined for the sequence that is open only i.e. it does not span sequences. It also determines the rendering order. Any model added to any other view when a sequence is open automatically gets reflected in the Master View of that sequence. Models can be deleted (i.e. removed) from any view at any time.

Note: If you attempt to delete a model from the Master View, you will be prompted to confirm the deletion, as deleting the model from the Master View will remove all effects that you have created against that model for the sequence that you have open.

If you add a Timing Track to a view , it will be added to all views that you have defined.


Layering effects gives you the ability to create unlimited stunning effects that could not be created without layers.

First, let's go over the limits. Each model may have a up to 200 layers of effects. Each layer can be mixed 12 different ways with the layer below it for a combination of thousands possibilities within a single timing cell.

Usually 4-6 layers is plenty enough though for the most discriminating user depending on the model shape and size. Why would you even want multiple layers on a model?

Layers on a model is like layers on a cake. Each layer adds a bit to the effect produced at the end. Much like layering your popcorn with butter or salt. It's easy to think of each layer of being additive like a food recipe, but you can also use layers to be subtractive as well using layer masks to reveal only a portion of a layer. See the table below for the different layer blending options.

Think of a color wash in red, with a layer of snowflakes. Normally you would picture a red model with the white snowflakes. You could change the layer masking so that the model was black and showed red on the snowflakes. Some effects like Morph can be applied to only a portion of a model, so using layers you can get multiple morphs on a Megatree that look like interleaving fingers for example.

Combining two spirals in opposing directions on a megatree also can create stunning effects.

To add layers to a model right click the model in the sequencer tab and choose Add Layer above or below (the current layer).

When setting the layer blending modes, the current layer is considered layer 1 and the layer below is considered layer 2.

Layer Blending Modes Layer Blending mode results
Normal Both layers will show, with layer 2 showing only where there is blank space from layer 1 as in thin spirals for example.
Effect 1 Ignore effect 2 and only show effect 1. Good for being able to hide an effect if you’re not sure you want to use it.
Effect 2 Ignore effect 1 and only show effect 2.
1 is Mask Effect 2 will show wherever effect one is not showing.

If E1=Fire, E2=Spirals, then the spirals would show on top of the fire, but the fire would appear to be black.

2 is Mask Same as effect one, just reversed. Tip use Bars as the mask on layer 2 and you will have effect #1 reveal as if was coming from behind a curtain.
1 is Unmask Make Fire E1, Butterfly E2 and set both for 1 is Unmask. You’ll see the awesome power of this blending mode.
2 is Unmask Make Bars E1, Fire E2 and set both for 2 is Unmask. You’ll see the awesome power of this blending mode.
1 Reveals 2 Effect one will show on top of effect 2, except for areas in effect 1 that are black. Effect 2 will show on the black areas of Effect 1.
2 Reveals 1 See 1 reveals 2. Same result, just transposed.
Shadow 1 on 2 The the layer 2 effect will show in the shape of layer 1. Try E1=Circles, E2=Butterfly to see what this does.
Shadow 2 on 1 Effect 2 will overlay on effect #1, where there is no black in effect #2.
Layered Try Effect #1 as circles, E2=Bars with one of the colors as black
Average This what you would expect as layered. If E1 and E2 had yellow and blue circles, they would turn a dull green where the circles overlap.
Bottom Top Effect 2 will appear on the top half of the model.

Effect 1 will appear on the bottom half of the model.

Left Right Effect 1 will appear on the left half of the model.

Effect 2 will appear on the right half of the model.

Render All

The ‘Render All’ icon RenderAll.pngis used to force a render of all effects - that have either been created within xLights/Nutcracker, imported via the Import Effects function or has been imported as a Data layer.

Rendering order

The Data Layer order renders bottom to top. Therefore what is on the top layer will be done last – much like painting – the last brush strokes are on the top.

Model layers also render bottom to top. Therefore the bottom layer will be rendered first, then the layer above it and do on until the top layer is rendered last.

However, the Models themselves render top to bottom based on how they are laid out in the Master View of the sequence. So the top model is rendered first, then the next lower model until the last model is reached.

Tip: You can change the order of data layers by moving them up or down. You can similarly change the order of layers within a model . And you can also change the order of models in the master view.