Interface

• • This page is under development **

File

The File menu enables you to create a new xLights/Nutcracker sequence, open an existing xLights/Nutcracker sequence, Save, Save As or Close a sequence that is currently open, select a show directory, backup xLights/Nutcracker sequences to another directory and quit the xLights/Nutcracker application. These actions can also be done using shortcut keys and via icons on the top bar of the canvas.

New Sequence

To create a new sequence, either use the New Sequence icon, select New Sequence from the File menu or press Ctrl N.

Musical Sequence

If creating a music sequence, click on Musical Sequence.

Select your media file.

Select the frames per second (fps) for your sequence. The most common one used is 20fps (50ms).

Skip on the next screen

If creating an xLights/Nutcracker sequence, at this stage you can select ‘Done’ and import timing marks later (either via the Timings menu or by Right Clicking on the Sequencer menu ). Alternatively, you can click on the Timings tab now – this will lead to the Timings menu. On the Timing menu, you can select one or more of a number of timing bar options, which will generate timing marks automatically (similar to those that can be done via Audacity).

If you click on the Edit Metadata tab, this will lead to the Sequence Settings dialog box.

At this stage a new empty sequence has been created. You can...

• Select Save to save the sequence in your show directory – you will be prompted for a sequence name.
• Click on the Sequencer tab and continue with
• Adding models for this sequence to the sequencer view,
• Creating/adding timing marks
• Dropping effects on the sequencer grid
• Playing the sequence

Animation Sequence

If creating an animation sequence, click on Animation Sequence. No media/audio file is required or requested for. The subsequent process is the same as in the Musical Sequence.

Open Sequence

To open an existing sequence, either use the Open Sequence icon, select Open Sequence from the File menu or press Ctrl O. You will be presented with the ‘Choose Sequence file to open’ window, with the directory defaulting to your show directory. You can select an xLights/Nutcracker (xml) sequence or an xLights/Nutcracker fseq file to open.

Save Sequence

To save an open sequence, either use the Save Sequence icon, select Save Sequence from the File menu or press Ctrl S. If the sequence has not been saved previously, you will be presented with the Save As dialogue window to enter the name for the sequence. If the Render on Save setting (under the Settings menu) is set (i.e. ticked) then all the effects on all the models will be rendered first before the sequence is saved in the fseq file. This is the default. Progress status messages are displayed on the last line of the window. When the sequence has completed saving, a message will be displayed on the last line indicating the name of the fseq file and how long the save process took.

Save As Sequence

To save an open sequence with a different name, either use the Save As Sequence icon or select Save As Sequence from the File menu. You will be presented with the Save As dialogue window to enter the name for the sequence. If the Render on Save setting (under the Settings menu) is set (i.e. ticked) then all the effects on all the models will be rendered first before the sequence is saved in the fseq file. This is the default.

Progress status messages are displayed on the last line of the window. When the sequence has completed saving, a message will be displayed on the last line indicating the name of the fseq file and how long the save process took.

Close Sequence

To close the currently open sequence, select Close Sequence from the File menu. If the sequence data has not been saved since the last change, you will be presented with warning.

If you click No, then you will be returned to the sequence. If you select and click Yes, then the sequence will be closed without any sequence changes being saved.

Select Show Folder

In order to change your show Directory, select Select Show Folder from the File menu, press F9 or click on the Change button against the Show Directory on the Setup tab.You will be prompted to navigate to and select a new directory folder to select.

Ensure that you have the correct xLights/Nutcracker xml files (xlights_keybindings.xml, xlights_networks.xml and xlights_rgbeffects.xml) in your new directory.

BackUp

Backing up your critical files and sequences should be done regularly – as good practice. What should be backed up? Anything you require to run your show, but in particular your xml sequences, your media files and your user specific xLights/Nutcracker configuration files.

The xLights/Nutcracker configuration files are located in your show directory and are: xlights_keybindings.xml, xlights_networks.xml and xlights_rgbeffects.xml

Tip: Pressing F10 anytime, anywhere will backup your XML files for your and store them in a zip file with the date and time the backup was created. You can press F10 as many times as you like and should do this at least once per sequencing session.

Alternatively, from the File menu, select Backup.

You will be presented will a message indicating where a backup will be created. Click Yes to proceed.

Every time this step is executed, a copy will be created of all the ‘*xml’ files from your show directory into the Backup subdirectory of your show directory. A new subfolder is created each time a backup is executed.

Tip: It is a good practice to also separately backup any files that you may have used as inputs to your sequences such as LSP, LOR, Papagayo files that you imported, media files that may have amended with audacity, gif or jpegs etc. You may also wish to backup any fseq files, though this can be recreated by saving the sequence again.

Backing up the show directory (and media directory if it is different) to an alternate location is the simplest way to ensure that you have the files required.

Quit

To quit xLights/Nutcracker, select Quit from the File menu or press ALT F4. If you have a sequence open and the sequence data has not been saved since the last change, you will be presented with a warning.

If you click No, then you will be returned to the sequence. If you select and click Yes, then the sequence will be closed without any sequence changes being saved.

Playlist

Playlists are created to be used within the xLights/Nutcracker scheduler if you plan on using xLights/Nutcracker to run your show rather than the Falcon Player on a Raspberry Pi.

Add

To create a new playlist, click on the Add button and provide a name for the Playlist in the pop up window. A split screen will be displayed. On the left, the Available Files from the Show Directory are displayed. On the right, the Playlist and the items within are displayed. Filtering on the options against the Files line, enables xLights/Nutcracker sequences, video and audio files to be selected from the Show Directory. Use the arrows provided to add / remove files (one or all files) from the Available File list to the Playlist. Within the Playlist section, use the Green arrows to change the sequence of the item.

In order to introduce a pause (i.e. delay) between items in the playlist, click on the item and then click the Set delay button. Specify the number of seconds for the delay. Click on Save Playlists to save the Playlist. The playlist will be displayed as a tab next to the Sequencer tab.

Rename

To rename a Playlist, click on the Playlist tab that you wish to change, then click on the Playlist tab, then select Rename. You will be prompted for a new name.

Delete

To delete a Playlist, click on the Playlist tab that you wish to delete, then click on the Playlist tab , then select Delete. You will be prompted to confirm the deletion. Click OK to delete or Cancel to return.

Refresh

This option is used to refresh the screen with a list of Available files. To be used if you have just added any new Audio, Video or xLights/Nutcracker sequence files to your show directory. Select Playlist and then Refresh.

Custom Script

If this option is elected for a playlist, the BASIC language scripts used to run the playlist is displayed. You can then edit/ add custom scripts to perform actions such as send out RDS data, play a video etc. You can also set Playback options for the Playlist

View

The view menu enables you to zoom in or out on the sequencer view, define and use Perspectives and nominate which windows you want to have open.

Zoom in

Selecting this option while on the sequencer tab will zoom in details on the sequencer grid.

Zoom out

Selecting this option while on the sequencer tab will zoom out the details on the sequencer grid

Perspectives

Perspectives saves the location and size of the "windows" you use.

Particularly for dual monitor setups, it lets you move and size the Preview and Color windows away, giving you a bigger program area. Going to View / Perspectives / Save Current will store your settings to the currently selected perspective.

You can have multiple perspective saved and easily recall them by selecting the perspective desired from the Perspectives window.

Windows

There are a number of windows that enable simultaneous display of different views in xLights/Nutcracker. When xLights/Nutcracker first loads, a default set of windows are displayed. Which windows are open can be controlled via the Windows menu by selecting View, Windows and then clicking on the required window to open it. The window is dropped by default on the left side of the screen, however each window can be moved and docked to alternate locations on the same screen or moved to an alternate display screen if connected to your PC/ MAC.

Display Elements

The Display Sequence Elements window enables views, Timings as well as models to be defined and updated. Functionality for these functions is described in the Views, Timings and Models section of this document.

Model Preview

The Model Preview window displays the effects on a model as the sequence is playing. With the window open, right click on the model name when on the sequencer tab and select Play model.

House Preview

The House Preview window displays the effects of your entire display where the ‘Part of my Display’ attribute of model has been ticked.

Effect Settings

The Effect Settings window displays the current or last effect that is being worked with. If an effect on the grid is selected or a new effect dragged to the grid, then this window gets updated with the ‘current’ effect. Use the window to modify the attributes of the effect as required. The results of the change are displayed in the model window when selected and in the House Preview window when the sequence is played.

Colors

The Colors window enables the user to change displays the current or last effect that is being worked with. If an effect on the grid is selected or a new effect dragged to the grid, then this window gets updated with the ‘current’ effect. Use the window to modify the attributes of the effect as required. The results of the change are displayed in the model window when selected and in the House Preview window when the sequence is played.

By clicking on one of the colors, the color box will appear allowing you to choose or create any color you desire. To create a custom color, click on the Define Custom Colors >> button.

Layer Blending

The first option of Morph is used with two or more layers. If selected, effect #1 will morph/blend/fade into Effect #2 midway through the timing interval in which the effects are placed. The drop down list has 12 different blending.

Effect Dropper

The Effect Dropper window displays all the supported effects and enables you to select a required effect and drag it to the sequence grid.

The same functionality can also be obtained using the effects from the effects window:

Effect Assist

The Effect Assist Window is an additional window that helps you determine how an effects is being drawn via a panel view. For example, if you open this window against a morph effect, the windows will display a grid corresponding to the x,y coordinates. If you then grab a slider for the morph effect and move it, the Effect Assist window shows exactly where the coordinate is being moved to, making it easier to determine what is being done to the effect.

You can also grab a corner of the image in the Effect Assist window and move it and have the slider values update in real time.

Perspectives

The Perspectives Window enables you to save your current windows is an additional window that helps you determine how an effects is being drawn via a panel view. 

Audio

Speeds

This function enables you to to play the audio during sequencing at normal speeds or at slower speeds.

Click in the waveform and then select one of the speed options. Click Play. The audio will then be played at the selected speed and the vertical visual indicator will move along at the speed being played. To return to normal speed, select Play Full Speed.

Import

Import Effects

This option enables you to import sequences from other sequencers as editable effects. However, in many cases it generates a large number of effects. In most cases, importing of RGB effects as Data Layers will suffice. There could be some cases (A/C channel data or LOR singing face sequences) where it is desirable to import using the Import Effects function.

Sequence

Sequence Settings

Timings

The Timings tab enables you to create or import one or more sets of timing marks on timing tracks for the audio of your sequence. This screen is part of the flow when creating a new sequence or can be accessed via this tab at any time after creating a sequence to add additional timing tracks.

New Clicking on New will present you with a list of options. You can either select a fixed value such as 50 or 100 ms or select from one of the options in the list.

Note: This component uses the VAMP plug-ins to generate the timing marks.

Selecting one of the options then presents a window where you can either select the defaults or change the timing name or any of the plug-in settings. The audio track will be analysed and a timing track will be created.

Import The Import button enables you to import timing marks created externally for example using Audacity or where you have created a timing track manually or wish to import one from another sequencer in a supported format. You will be presented with a window to navigate to and select a file containing the timing marks. This can be a text file (.txt), a LOR lms file or a LOR LAS file.

Select the required file to import the timing marks. You can repeat this process to import another file.

Data Layers

When should you use the data layer to import effects ? Typically if you have sequences from other sequencers such as LSP, LOR, Vixen, HLS that you wish to use within xLights/Nutcracker. The imported sequence is mapped very efficiently as a data image rather than individual effects. After importing the sequencer you can:

• Save it ( an .fseq file is created) and run it within xLights/Nutcracker or via the Falcon Player
• Add xLights/Nutcracker effects to new models via the sequencer
• Selectively override some of the effects from the imported models within xLights/Nutcracker.

You cannot however ‘edit’ any of the imported effects directly. In order to do that see the Import Effects function. The data layer embeds the CONVERT tab into the sequence. The process is used to convert an incoming file from another sequencer into an *.iseq file. Therefore, Vix, Lms, Seq, and Hls data into an ISEQ file.

This conversion is done in two places.

• When you a import a data layer
• When you press the ‘Render’ All button

Note: The purpose of ‘Render All’ is to render all the effects and data layers to the sequence object without saving to disk. The already imported ISEQ file data is used. If the source (‘LMS’, ‘SEQ’, ‘HLS’ etc) file is changed, then you need to go to the Data Layer tab, click on that layer and select the Re-Import function.

Import

Before using this function, a new sequence should have been created or an existing sequence opened. From the Main Menu tab, select Sequence Settings and then Data Layers. Click on Import, navigate to where your input file (‘LMS’, ‘LSP’ etc) is, change the file type as required and select the file to be imported. Click ok.

On completion of the import, the Data layer details and the number of channels imported to the data later will be displayed. The file has been imported/converted and stored in an .iseq file.

On the Main Menu, click on the ‘Render All’ button, after which the sequence can be played. Click on the ‘Save’ or ‘Save All’ buttons to save the sequence.

To view the details of the data that has been imported, double-click on the model's row title to reveal the strands and then the nodes. The imported effects are at the node level.

Delete Use this function if you wish to delete a data layer that has been created via the import function. Select on the layer and delete.

Move Up/Move Down You can import multiple layers to be rendered at the same time. Using the Up/Down buttons allow you to determine which layer will take precedence over the others. The highest layer will render on top of the others and so forth. This would be useful if you had multiple sequences of the same song, yet you had different models in each sequence.

Re-Import Use this function, if you wish to re-import and overwrite an imported data layer. Normally required if the source ie LSP, LOR sequence has been amended in any way and you wish to overwrite the previous import without affecting any other effects that may have been added to the sequence within xLights/Nutcracker. Select the data layer and click on the re-import function, after which, functionality is the same as the Import function.

Help

The help tab contains two options within it.

Pressing F1 displays a Help or information window depending on tab the user currently is on.

Selecting the About option display a window containing xLights/Nutcracker release information, websites, copyright and acknowledgements.