From Nutcracker Wiki
Jump to: navigation, search

Here you will find answers to the most common and frequently asked questions.



Is xLights Nutcracker Free?

  • Yes. Both Matt and Sean have always believed their software should be made available free to the lighting community. The sources of xLights/Nutcracker is available to download from github. You can download the free sources from Sean's Github.

What platforms can xLights/Nutcracker run on?

  • XLNC can run on Windows and MAC and Linux, systems. You can go here for the latest program release.

What do I need to install and run xLights/Nutcracker ?

  • The software is self-contained , but utilizes the VAMP plug-ins to create timing marks such as beats and bars. Therefore it is recommended that you also install Audacity, though you don't have to, to utilize all the other functionality. Refer to the Installation chapter in the manual for details.

How do I get started ?

How do I organize my sequence and media files ?

  • Everyone has a slightly different way of doing it.
    • A common approach is to create a show directory for a particular event i.e. Xmas2015 , then create different sub directories within it for the sequence files and media files.
    • Another way is to have the sequence and media files share one common show directory.
    • After completing a sequencing , copy all its files to another directory - if you have a number of songs.
  • Note: When you use the F10 key or Backup function, only the xml files in the show directory are backed up.

What program do you use to resize pictures or images?

  • Photoshop, MSPaint , Ezgif (www.ezgif.com) , PicResize (www.picresize.com)

How can I capture a screen image ?

  • In Windows, you can use the Snipping Tool. Click start and then in the run/search box type Snipping and a link should show up. Just drag a window around what you want and snip. You can even use a pen to circle to highlight items in the snip.


My models are gone, where did they go?

  • If you have any model groups selected (layout, select model groups), then ONLY those model groups will show on your layout screen. Uncheck all of those model groups and the rest of your models will re-appear.

Why don't my effects show on the preview after I've placed them on the model?

  • Some effects require that you press F5 to update or that you render the sequence before you see them on the layout screen.

I can't seem to save and re-use my Effect Presets.

  • Highlight the effects, right click, select Effect Preset. Ensure that you have your own Group created via Add Group, then click and add as a new preset. Create your own group - do not use the top level or the default group.

Can I save my selected models so that I don't have to re-select them for each sequence?

  • Use the View functionality to define the models and order you require in a View once. Then select that view when you open a sequence. Simple! . Refer to the Views section in the manual.

What happened to the Whole House Model (WHM)?

  • The WHM feature was dropped because of the increased functionality with Model Groups. Get an equivalent WHM, just make a model group with all your models in it.

Can I copy effects from one sequence to another?

You can use Effect Presets to save and load effects later as these are stored permanently. Or you can highlight the effects , copy to clipboard , open the second sequence and paste as required.

How to I define the starting corner for my model display ?

CCreate the models in xLights exactly how you will physically build the model. If you have a string of lights and you plug node #1 into the upper left corner of your mega-tree, then xLights should have the mega-tree defined as starting in the upper left corner. All models are controller independent.

In what order are data layers, model layers and models / model groups rendered ?

The Data Layer order renders bottom to top. Therefore what is on the top layer will be done last.

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.

Effects and Editing

I have a group of cells with a ramp effect, but I cant move them to form a chase.

  • Highlight the effects , hold the ALT key and then drag the bottom right corner of the bottom-most effect in the highlighted group.

How do I do a chase effect - I don't see a chase effect icon

  • Select a block of cells and hit 'd' for a fade down or 'u' for a fade up. To create the chase, highlight the block of cells, hold the ALT key and drag the lower right corner of the effect block to create the chase.

My Single Channel model (blue) wont turn on.

  • Single Channel colors react only to the color that they are defined as.
    • If you define them as single color blue then it will only react to the blue channel. You can set any color and it will route the blue portion of that color to that model.
    • If you send White (R=255, G=255 B=255), to a single color blue model then it will turn fully blue. If you send blue it will turn fully blue. If you send red or green it won't turn on at all. If you send pink which is R=255, G=0, B=128 you will get a half brightness blue.
    • You can therefore include those single color models inside a group and they will react to the colors dropped on the group. Any of the "blue" components of the RGB values assigned to that model will cause it to fire at the associated brightness of the component.
    • The strings will light up with the intensity of the color for each channel. So if you send Purple R=128, G=0, B=128) , that will light up all the Red and Blue strings but only about 50% intensity.
  • If you just want a string to turn on full brightness without worrying about it then use White

The colors of my effects on the grid are not consistent

  • One you tailor an effect then use the effect again to a new timing mark, the effect will have all the same settings as the previous effect did.
  • However, if you were to highlight any other effect with different colors selected then the colors will change to the colors of the effect that you have selected.

Is there a way of making all effects fade or turn off at the end of a song?

There is no global setting, however you can click each effect at the end and paste in a Fade Out value.

Use the "off" effect on your whole house model/ all model group in the last timing mark to ensure they turn off (only if required for your setup).

I have a large number of single channel DMX lights. How should I set them up  ?

Create models and group a number the channels into one or more models. This way you can drop an effect on the top level model to control them all at once. If needed you can drill down to the node level when you want to control a single channel and drop or change the effect at that level. Name the nodes.

How do you set up zig-zag for a mega tree - in the controller or in xLights ?

  • You can set it up in either location , but not in both.
  • To set it up in a controller e.g. E682, for an example with 8 strings of 100 pixels each. On the E682, set the ZigZag/Fold to 50 pixels.
  • In xL, configure the tree model with as follows:

Actual number of strings = 16, # of RGB nodes per string =50, # of strands per string = 1

I have 16 X 50 strings for my mega tree. How do I get the xlights to do a zig zag on the preview window?

  • If you have 16 strings, and string 1 starts from the bottom, 2 from the top, 3 from the bottom etc , in that case, make your tree model so that the strings are 2x the actual length and then configure the strings to have 2 strands per string. So, the model is 8 strings of 100 with 2 strands.

Is there a way, after a sequence has been made, to make a global adjustment to the brightness of all the effects?

You can do a brightness setting on each model in the model properties, then re-render each sequence.

Timing Grid and Timing Marks

I did not create timing marks whilst creating a new sequence. Can I add then later ?

  • Click on the Settings -> Sequence Settings. then select the Timings tab where you can add / delete / rename and Import timings. Click on the New button and choose a timing plugin from the dropdown.

None of the VAMP or Audacity timing marks appear in the list when I try to create timing marks

  • Do you have Audacity loaded on your computer > If not then you need to install the VAMP plug in separately. The process is described in the manual

Can I import timing marks from my LOR sequence ?

  • Yes. From the Timings tab on the Sequence Settings menu , select the Import button. Change the FileType to the type of LOR file you have (LMS,LAS) and xl will present you with a dialog window of all the timing tracks in that sequences allowing you to select the ones to import.

I accidentally deleted the line connecting the timing marks.How do I restore the line?

  • Timings are created just like effects which means they have a duration. Every timing effect has a starting edge and an ending edge. So you can have a timing effect that goes from 1 to 2 seconds and then another from 3 to 4 seconds with nothing in between 2 and 3 seconds. If you want one in there just select a range and hit "t" then drag the edges over to connect to the existing timing effects.

Importing from Other Sequencers and xLights Sequences

I have sequences from LOR and LSP. How can I import them into xLights ?

  • There are two ways of importing your sequences.
    • The most efficient way is to import the sequence as a data layer. You cannot edit the data imported, but you can layer effects on top of the data imported without affecting the imported data. The Nutcracker effect will play on the lights, however the imported data will not be touched.
    • The other way is to import effects. You can edit the sequence data imported. Refer to the Data layers and Import Effects sections in the xLights/Nutcracker manual.

How can I use a model that someone else has shared in my sequence ?

  • Since models are defined using xml, you can copy them into your xlights_rgbeffects xml file in the models section. Then update the channel assignment to your setup.
  • Use an editor that works well with XML such as Notepad++. Ensure that after you paste the xml, that the </models> end tag is returned to its original position on a new line.
  • If a person has used a data layer to import his/her effects , you will get an error message when you try and save indicating that an iseq file is missing. Just delete the data layer as it is of no use to you.

How do I get my models from one computer to another?

  • All models are stored in the xlights_rgbeffects.xml file. Make sure computer B has that file copied over from Computer A and in the Show Directory folder configured on the setup tab.

I have Models/Layout for my Halloween Display. How do i start a new layout for Christmas models without loosing my Halloween models and Layout

  • Use multiple Show directories to manage multiple layouts. Copy the xlights_rgbeffects.xml file over to the new show directory. Then delete the models you don't require.

Importing from LOR and only LOR

I'm still using LOR for 8 controllers this year. How do I set them up?

  • The general rule is that you can do 96 channels of LOR with xLights if the LOR controllers are in LOR mode. Your best bet would be to put the LOR controllers in DMX mode and then xLights can do it all. You can import all your LOR sequences, schedule them play them, edit them, etc.

I have an e682 and an e6804 running pixels and 2 cmb16 and 1 cmb24 controllers. How do I configure? Do I need a cross over cable?

  • Plug in the USB, same com port that you would use , if running it from LOR. No crossover cable needed if running from a LOR network. On the setup screen , Add LOR channels via USB device at 20fps. Put in at least 48 channels. Set the com port as required After the LOR USB row, then add in universes of 510 for the E68x controllers.

I'm using comm4 and the USB to ethernet dongle. How do I configure my LOR controllers?

  • Network Type – LOR, Port – COM4, Baud rate – 57600, Num channels (160 as example).

Note: Baud Rate of 250000 is for DMX only

When I convert LOR to XL, during the process it tells me that the channels are unmapped

  • All your channels in LOR must be mapped exactly including blank ones in between . Setup your AC LOR channels first in XL4 and then start with your first prop in the same order as your LOR sequences.


I can't see a model on my Layout tab.

  • Check the Layout/Model Groups window. If any model groups are selected, ONLY THOSE models will show on the layout window.
  • Check that the model has the 'Part of my display' attribute ticked.
  • If you are using Model Groups, check that the model is part of a group that has been selected via the Edit Groups window.
  • You may need to drag the handles of the model from the bottom left corner of the Layout Window

Why does a model show up as red on my layout .

  • You probably have a channel overlap with another one - the model that is highlighted in yellow. Check the start and end channels of each in the list to the left of the layout.

How can I work with and move multiple models?

1) select a single mode by left clicking 2) Select a group of models by Shift-Left clicking a box around a group 3) Select a group of individual models by click-left clicking models To move the selected models, ctl-left click the group and drag

Papagayo & Singing Faces

Does xLights support Papagayo singing faces?

  • Yes ,the 3.x functionality to import Papagayo PGO files is still available.
    • However, you can also create Singing Faces natively within xLights. Refer to the manual for details.


What media format is required for sequencing?

  • Nutcracker currently only supports the MP3 format for audio files. Ensure that the MP3 file is saved with constant bit rate (CBR), preferably 128K or 192K. Use Audacity to export the audio as a constant bit rate file.

How can I play a movie in my sequence ?

  • You need to use the ffmpeg utility to split the movie into images and use the Pictures effect. This is explained with examples in the manual.

Can I use a wav file in my sequence?

  • No, the wav file should be converted to am mp3 file - using Audacity or ffmpeg. Ensure that the mp3 file has a Constant Bit Rate.


When using the xLights test tab, the colors don't match on my lights, why?

  • The test tab pattern will always send in 'RGB'. It is are actually turning on every 3rd channel, i.e. 1,4,7,10 etc for red and 2,5,6,11, etc for green, etc and then all channels for white.

To check the correct colors, create a small sequence, with ON red, then ON green, then ON blue, each of 5 secs or so and then click on Output To lights and run it from there. Alternatively, you can turn on channel #1. That will ALWAYS be Red.

Matrix Panels

How do I configure my P10 matrix panels ?

  • Define it as a horizontal matrix.
  • Set # of strings = number of rows on panels, # of RGB nodes per string = number of columns on panels and # of strands per string = 1. Starting corner = Top Left. Channel number as per your configuration (say 5800).
  • Refer to the section on Configuring Matrix Panels as Models in the manual (next publication)