Nutcracker: New, real time Nutcracker. Wow!


Dedicated elf
Jan 19, 2012
4217 Greenfinch Dr CO 80126
Hi All;

Matt Brown asked permission to rewrite Nutcracker into xLights. His version is what I want to do with Nutcracker next year. His version gives immediate feedback while creating effects. Think sliding bars for all my effects and watch the window as you slide them.

Amazing Matt!

Here was his post on the xLights thread
dowdybrown said:
Well, I have been working hard on xLights - as you will see if you download version 2012d. Once again, I have put it in my dropbox instead of SourceForge because I don't feel the Sequence tab is "fully baked". However, I know the 2012c version had some bugs and I wanted to get a new version out that addressed those. So here it is:

I have tried to address all of scheduling bugs (I am using this version to schedule my show). I also tried to fix the lag issue with the Etherdongle.

The Sequence tab is new and I know it will need some explaining - which I will try to do by responding to posts in this forum. To get started, the effects are based on Nutcracker (with Sean's permission). The Life and Snowstorm effects are not implemented yet and there isn't a Twinkle effect yet, but everything else is there. The nice thing is that all of the effects are created real time -- you can change the parameters by dragging a slider and instantly see the results. Some effects are enhanced - notably the Text effect allows you to choose any font installed on your system along with the font size. This includes fonts like Wingdings, or "Xmas dings" or other fonts with icons/graphics.

Model creation also has some enhancements: 1) you can start your string numbering from the left or right, 2) it can control strings that are not in RGB order.

Where things really differ from Nutcracker is in the way you string together effects. What I have put into this version is very rudimentary. I hope to make many improvements to this area in the next year. But what you have to do for now is open an xLights sequence (.xseq file), choose which model(s) will be included in the sequence when prompted, then insert rows into the grid and for every row type in the start time in seconds when that effect should start. To add an effect to the sequence, click on the grid cell in the desired display model column and the desired start time row, then click the Update button. When you are done creating effects for the sequence, click the save icon and the xLights sequence will be updated with the effects you stored in the grid. There is no export feature - you can only update xLights sequences. However, once updated you can convert the xLights sequence to Vixen format for viewing/tweaking.

That's it for now. Merry Christmas!


So how does this compare to the current Nutcracker, in almost all ways it is better!

What is missing?

watch out if strings dont fold evenly. take a 10x50 and make 3 strands out of each string. This would make 3 strands of 16 pixels each with two left over.

In nutcracker, if you say always start pixel 1 at the bottom of your tree you would end up with 480 out of the 500 pixels being used. in xLights it uses 498 pixels. In other words it used the extra two pixels. If your strings divide evenly this wont matter. if i had 50 pixels divided by 2, then everything would be the same as nutcracker and xlights. Most people want node 1 of a string to be at the bottom.

Like Nutrcracker it does not have the ability to start strings in the upper left or upper right corner.

As an additional feature, it does support starting at the bottom right. Nutcracker does not have this.

It has BOTH vertical AND horizontal matrices. For all of you with horizontal matrices, you could get effects this season.


What is working:
bars, butterfly, color wash, fire, garlands, meteors, pictures, snowflakes, text
Note; matt does not have vertical and horizontal bars. This was added to my effect after he converted. His Spirals DOES support vertical bars (And they work).

Text is so much better than mine. Matt implemented all of the fonts you have in windows and you can scale the font. Arial, Time Roman, .etc. 10 pt, 48pt. His text effect is very cool! In fact i am going to create text for my tree using his effect.

Here is what has not been implemented yet.
gif, life, snowstorm


Does not yet support audacity label files. It does support marking phrases. I would print out your project with the timing marks and enter them into xLights.


Vixen: vix, vir
LOR: lms,lcb
HLS: hlsnc
LSP: UserPatterns.xml
Vix vix
xLights xseq
Conductor seq

So i took a vix file converted it to xseq
Now i attach xLights effect to it. save it as updated xseq
I can use this xseq between my songs. I can also convert the xseq back to Vixen vix format.

Again, download xLights version D from

Here is a 20 minute video i made using Matt's xLights.

Awesome job Matt!



Full time elf
Sep 3, 2010
Granbury, Texas
and the just released xLights 2012e version adds several new features on top of the great things in 2012d

The next release of xLights is now available here:
Changes mostly involve the Sequence tab:
  • Added Life and Snowstorm effects
  • Node layout now shows string number
  • Added UpdateGrid button to Sequence tab
  • New Export button allows direct export of your RGB sequence to Vixen, LOR, and xLights (LSP and HLS will be added soon)
  • Sequence tab Open button now allows creating an empty sequence

  • Please post here if you find any problems or would like to suggest enhancements.