The developers and authors of this manual are volunteers. A very special thanks goes out to our families for supporting us in this hobby. Without your support we could not do this. A very special thanks goes out to Matt Brown and Sean Meighan, the original authors of xLights and Nutcracker.

Getting Started

This section describes the steps required to install and use xLights for the first time to create a sequence. The details of each step are covered in the respective sections covering that functionality. The examples use a Windows operating system but the process would be similar for Macintosh OS X, though the installation will be different.

xLights & Nutcracker

xLights was created by Matt Brown in early 2010 and was released to the public on September 13th of that year. Matt wanted a program that would reliably play his LOR show after experiencing lagging. His original xLights application consisted of a testing and scheduling module only. The program could control a variety of lighting networks including LOR, D-Light, DMX and Renard. And it also ran under Windows, Mac OS X and Linux. xLights did not have its own sequencer at the time, but could run a mixture of LOR S2 and Vixen sequences.

Nutcracker, originally called rgbsb, was written by Sean Meighan in February 2012. Sean, who was new to animated Christmas lights, wanted an easier way of creating effects on smart RGB devices. He came up with the unique concept at the time of defining a model (megatree, matrix, arches, etc.) and then dropping effects (butterfly, spirals, text, .etc.) onto the model. Sean gave a presentation on the newly renamed Nutcracker software at the Texas Academy in the Summer of 2012. People were excited. Nutcracker could produce either lms or Vixen 2 files. Nutcracker 1 and 2 were developed as a web based php application. To create effects users would log into the web applicaton, define models and apply effects.

During the Fall of 2012 Matt had contacted Sean and asked if he could port the Nutcracker code into the xLights show player. By January 2013, Matt had taken the web based code that Sean wrote, re-wrote that code into C++ and made Nutcracker a part of xLights. January 2013 xLights v3 was released. Now Nutcracker could be natively ran on Windows, Macintosh or Linux systems. This capability came from Matt's design of his player code. This produced a real time Nutcracker product. For example the Snowflake effect took 5 minutes to generate effects using Nutcracker 2, in Nutcracker 3 (the xLights port), that same effect now took less than 5 seconds. Amazing work by Matt!

2013 found both Matt and Sean developing xLights/Nutcracker into a show player and sequencer.

Early into 2014, Matt was hired by Light-O-Rama to develope their software and left the xLights team at that time.

In 2014 Sean had discussions with Dave Pitts about making xLights resemble a video editor with a horizontal timeline, sound file waveform, drag & drop effects and multiple layers. Dave coded up the first Alpha xLights 4.0 in November 2014. In January 2015, Gil Jones and Dan Kulp came on to the team and took over the development from Dave. xLights 4.0 Beta was released on March 20th, 2015. Keith Westley joined the development team in late Summer/early Fall of that year.

With the release of version 4.3 on December 17th, 2015, Sean changed the name and dropped the reference to Nutcracker and was simply called xLights. Starting in 2016, xLights dropped the version 4.x numbering scheme and switched to a year/version scheme (i.e 2019.17).

On February 18th, 2017, the sequence player/scheduler was removed making xLights a light sequencer only application. This capability was replaced with a standalone application called xScheduler created by Keith Westley.

The Summer of 2018 saw the release of the 3D layout and rendering capabilities thanks to Gil Jones.

Both Matt and Sean have always believed their software should be made available free to the lighting community. As such you can download the source code from: https://github.com/smeighan/xLights.

Welcome to the xLights User Manual. We hope that you will find the information that you need to make your Halloween and Christmas shows shine!

Controllers

The controllers section defines how the channels are mapped to physical hardware and controllers. It is only used when outputting data to the controllers and can easily be changed at any time.

You do not have to define any controllers when you start , but you will need it defined before you can test any effects on physical lights from within xLights.

If you do want to define the controllers details at this stage, select the Controllers tab and add a controllers. The actual controllers settings does not have to be correct as you can change the details later.

To define a E131/DDP/Artnet type controller, Click on the Add Ethernet button:

Set the Name of the Controller, this can be any value, but make it something specific that is easy to remember for later use.

Set the Controller Vendor, Model, and Variant. Not all controllers have a variant type, this will be blank for some controllers.

After setting the Controller Type, Enable the Auto Layout Model option.

Set the controller "IP address", If unknown just use a generic value like "192.168.1.50". Set the "Start Universe" to 1, "Universe Count" to 20, "Channel per Universe" to 510, and press Enter.

This will create a basic controller with 20 universes. Each universe will have 510 channels. The start and end channel are automatically calculated and displayed in the mapping column.

Click on Save Button to save the controller setting that were added.

Defining a Show Directory

When the installation has completed, depending on your option selected, xLights will automatically launch or you can double click on the xLights icon/program to start it.

If this is the first time that you have installed xLights on the computer, then you need to set the show directory. The show directory is the location where all your xLights files are stored and where your sequences will be created.

The Show Folder should be in you personal documents folder i.e "My Documents" or "Documents".

You should be presented with the following screen:

This screen will allow you to navigate to "Documents" and create the show folder.

Right Click in the "Documents" folder and select New->Folder

Rename the folder to a unique name.

In the following example I created a show folder is called "xLights"

Highlight the "xLights" folder and click "Select Folder".

After setting up your show folder the main xLights window should appear.

"C:\Users\<username>\Documents\xLights"

Layout and Background Image definition

The next step is to add a Background Image for your House Preview Layout.

Click on the Layout tab. You will be presented with the list of Model definitions on the left (currently empty) and the House preview (shows up as black as no picture has been loaded).

You can proceed without a picture of your house/yard and add this in later.

Or you can select an image from any location. Click on the Background Image prompt and browse to and select your image.

Note that the image background, size and appearance does not drive any xLights functionality, but is more for the user to have a visual representation of where his or her models are and what they look like on the canvas.

Click on Save to set the image details.

Model Definition

In this section, we will define a Model, a Model Group, and add the model to the Model Group. Model and Model Group definitions are persistent, are to be defined once and can then be used in all your sequences.

As an example, I am creating an Arch model and will call it ‘Arch 1’. The arch is about 2.5 metres long and as such is made up of 25 RGB pixels.

Click on the Layout tab, then click on the Arches icon. The selected icon will have a blue square around it.

Then click anywhere on the Canvas and drag slightly. An image of an arch will be displayed and an Arch model called ‘Arches’ (the default name that is assigned to the model may be slightly different) will be created with a default set of model settings.

Change the Model name to ‘Arch-1’. Click the Tab or Enter Key to set the new name.

Change the Nodes Per Arch value to 25.

Set the controller to "Main Controller" or whatever name you set in the controller tab.

Set the Controller Connection Port to 1. This is the port of the controller the model will be physically connected too.

The Start and End channel will be automatically calculated by xLights based on the model settings and the controller settings selected.

If you are adding a second model to the same controller port, set the model chain order to determine the model order on the controller output.

Use the blue dots around the model to resize and rotate it if required. To move the model click and drag it to the desired location. The green dot should at the left side of the screen. When it is aligned horizontally, a red line is displayed between the green and blue dots.

The starting location of the model can be changed to the 'Blue' or 'Green' square.

Click on the Save button (just below the Models button) to save the work that you have done so far. This includes the Model definition and its position on the Layout.

Adding Effects

You can then drop and effect against either the Model Group or the Model. Model groups are identified by a small group icon after the name.

If you double Click on the Model Group name, it will expand and show you the models that have been defined as part of the Model group - in this case the ‘Arch 1’ model. Double Click again to collapse the Model Group.

Adding Effects To a Model

First Select a Timing marks you like to use. To do this, select the circle next to timing track. In the example below, The ‘Beats’ timing marks are selected.

Select an effect (in this case the Bars effect) and drag it onto the grid in line with the ‘Arch 1’ model.

This is effectively placing the effect on the model.

You could also place it against the Model Group - (one line higher), in which case it applies to all models under the Group.

You can grab the edge (in purple) and drag it to the right to stretch. Note that the effect shows in the Model window and in the House Preview window.

You can change effect settings via the Effects Window. For example, change the Bars 'Palette Rep' setting from 1 to 2 by dragging the slider bar. This window can be dragged out to an another location and expanded. The windows will resize.

You can change the color of the effect, by selecting a different set of colors from the Color window.

Use the highlighted keys to start, stop pause, rewind and play again. As the sequence plays, you can see the effects on the House Preview screen.

Select the Bars effect and drop it on the sequencer grid onto the ‘Arches’ Model Group. Play the sequence and observe the effect in the Model Preview window and House Preview windows.

Creating a New Sequence

Click on the New Sequence icon

and from the following screen, select Musical Sequence.

Select the media file for the audio.

Select the frames per second (FPS) - 50ms is the most commonly used one.

On the next screen, you can click on Quick Start and create timing marks later or you can create timing marks now by clicking on the Timings tabs.

If you forget to do it at this stage and move on to the next screen, you can always create timing marks later by accessing the Timing menu via the Settings menu.

Click on New to create a new Timing Marks Grid.

If the QM Vamp plugins have not been installed, then you will be presented with the following options only. In which case select 50 ms and continue. You can add new or additional Timing Mark intervals at any time later.

If the QM Vamp plugins have been (correctly) installed, then you will be presented with a number of different options.

You can also add new or additional Timing Mark grids at any time later.

Select the Beats Timing Interval.

(You can select any one - but this is one of the common timing marks used). Then Click Ok.

Leave the default values on this screen and click Ok.

You can click on ‘New’ again to add an additional timing mark if you wish or click on Done to move on to the next step.

(This example clicks on Done).

Adding Models to a View

Models added to the layout after a sequence was created must be added to a View so that the models are then available to place effects against. Each sequence has a ‘Master View’ that is automatically created. The Master View defines a list of models that are specific to that sequence only. For this example, we will use the Master View.

Right click on the Timing grid names (in the area highlighted on the screen).

Select the Edit Display Elements option from the pop up window.

Select the Master View from the top window.

From the Left window select the items you would like to add and Click the Right Arrow Button. If you select the Double Right Arrow all the items (All Models, Arch1, and Arches Group) will be added.

Click on Close when done.

Model Group Definition

The next step is to define a Model Group. You can work without using model groups. You can also do this at any time later, but it is good practice and most useful later to have each model part of a group.

Right Click in the Models Group panel. An ‘Add Group’ button will be displayed.

Click on the Add Group button. Enter a Model Group Name when prompted. I have called it ‘All Models Group‘. Every time I add a model, I will add it to this Model Group. A model can be part of more than one model group.

Next add the models that are part of the Model Group to the group. From the list of models, select the model and click on the right arrow to add to the model group window. Double clicking the model name will also add it to the group.

The model ‘Arch1’ is now part of the ‘All Models Group’ group. Click on Save when complete.

Repeat the above steps and add a second Model Group ‘Arches Group’. Click on OK and then click on Save.

Select the Model group ‘Arches Group’ and adding the model ‘Arch1’ to that group too.

Click on Save to save the Model group updates (and all changes to the layout, models or model groups since the last time this save button was clicked on).

Click on Save to save the Model group updates (and all changes to the layout, models or model groups since the last time this save button was clicked on).

This completes a definition of a single model ‘Arch1’ that is an ‘Arches’ type of model, is part of a Model Groups ‘All Models’ and ‘Arches Group’, that is to be displayed on the Layout display. The model image has been resized and placed against the fence in the layout.

Should you wish to Rename a Model group or delete it, highlight the Model group Name and right click. Use the resulting window to rename, delete, or clone the group.

You can also add additional groups. The next step is to create a new sequence.

Downloading xLights

The latest AppImage release of xLights for Linux can be found at the following link: https://github.com/smeighan/xLights/releases

You can also download the source from https://github.com/smeighan/xLights and compile as per the included README.linux file.

Installing xLights

AppImage Builds

1. Download the latest "xLights-xxxx.xx.glibc2.17-x86_64.AppImage" file from: https://github.com/smeighan/xLights/releases

2. Set the AppImage file as an executable (for example ‘chmod +x ./xLights-xxxx.xx.glibc2.17-x86_64.AppImage’) and then run the file directly.

Backup and Exit

Click on the File Menu.

The drop down list has options to backup files, close the sequence and Quit xLights.

Click on the Backup option (or press F10). The backup process will copy all xml files (including key xLights setup and the model definition from your show directory only.

You can also click on Alternate Backup or press F11 to backup to a different location.

A message is displayed indicating the name and location of the backup files.

Select Yes to accept. Then, from the file menu again, click on Close Sequence.

Then click on Quit.

If the following message is displayed, xLights has detected that there has been a change to the Model or View definitions that has yet to be saved.

Click on ‘Save Changes’ to save.

Downloading xLights

The latest release of xLights for Windows can be found at the following link: https://xlights.org/releases/. This page has a link to the 64 bit main xLights installer. There is also a link to the Queen Mary Vamp Plugins and the Microsoft Visual C++ 2015 Redistributable which is required by the QM Vamp Plugins.

Installing xLights

1. Download the required released executable file and save to any location on your Windows PC.

2. Double click on the downloaded executable.

3. The xLights setup window will be displayed.

4. Click on Next.

5. Select the destination location. Leave as is to upgrade to a new release. Follow the prompts and click on install when ready.

6. Click on Finish to complete the installation

The xLights software will be installed in the destination location. In addition to the software required to run the application, the installer also installs a few useful utilities, dictionaries and a songs subdirectory. The xLights application software is installed by default in the xLights directory within your Windows Program Files directory ( C:\Program Files\xLights\).

The location can be modified during the software install process by the user.

When xlights is installed, some browsers/virus scanners may flag the file and either prevent download or require you to provide extra assurances that you really want to download the file.

Installing Queen Mary Vamp Plugins

If you do not have Audacity installed on your computer, then you should at least install the Queen Mary Vamp plugins for Audacity.

For the QM vamp plugin packages that can be installed without Audacity installed you will need to download two installers, the first is the Microsoft Visual C++ 2015 Redistributable(vc_redist.x64.exe) and the second is the QM Vamp Plugins(Vamp_Plugin64.exe). Both installer can be found at: https://xlights.org/releases/. Run the "vc_redist.x64.exe" installer first and then the "Vamp_Plugin64.exe" installer.

Backup

If this is an upgrade to an existing xLights setup, make sure that you backup your existing files before installing a new version. The install process does not delete any of the files required for your sequences or setup, as these files are kept in the show and media directories. To backup your existing files, follow the procedure described on the Menus Page or just press F10.

If you have any sequence currently open, then changes to the effects, views, models etc may not have been saved until you exit xLights.

Please also refer to the Backup section in this document which describes how xLights handles current unsaved work.

In Greek mythology Sisyphus or Sisyphos (/ˈsɪsɪfəs/; Ancient Greek: Σίσυφος Sísuphos) was the king of Ephyra (now known as Corinth). He was punished for his self-aggrandizing craftiness and deceitfulness by being forced to roll an immense boulder up a hill only for it to roll down when it nears the top, repeating this action for eternity. Through the classical influence on modern culture, tasks that are both laborious and futile are therefore described as Sisyphean (/ˌsɪsɪˈfiːən/).

Installation

Download the xLights and QM Vamp Plugins installer from https://xlights.org/releases/

First, install the Queen Mary VAMP plugins which are used used by xLights.

Second, install the xLights, keep the default settings.

Installation options are further described in Chapter Three: Installation.

Controllers List

The Controller Panel is divided into two parts. The list on left displays all the controllers defined by the user. The right grid displays the setting for the currently highlighted controller.

Each controller should be defined as single line in controller list. These controllers are then used to determine the start channels for the models in the layout tab. The start channels can be automatically set by xLights or manually setup by the user.

Controller Types

Save

Clicking on Save will save the current configuration to the "xlights_networks.xml" file in the current show directory. After any changes are made to the Controller tab the Save button will turn red to identify there are unsaved changes.

Adding Controller

To add a controller, click the add button for the desired controller type.

Discovery

This will automatically find ZCPP and DDP controllers already attached to the local network.

Controller Settings Grid

The controller setting grid displays the settings for the currently selected controller. If no controller is selected , the settings grid will display global settings that affect all the controllers. The controllers settings vary based on the controller type and the settings selection.

Name

The controller name needs to be unique for each controller. This name is used by xLights to map the models to the controllers.

Description

The description field can be added by the user to add more details about the controller.

Id

For Artnet and E1.31 controllers, The ID field is used for the Universe ID's for the controller to receive data on. For other controller types the ID Filed can be see to an unique ID for use with start channel addressing.

Active

The "Active" drop-down determines if a controller is used when "Output to lights" is turned on. When "Active" xLights will output channel data to the controller. If "xLights Only" is selected, data will only be sent from xLights. If using xSchedule or when Uploading to FPP this controller will be set inactive. This is intended for FPP type controllers being used in Master/Slave mode. If set to "Inactive", no data output occurs. For example, if you have a controller not plugged in (testing a different controller) disabling that controller would not attempt to send anything to that specific controller. Trying to send data to a controller that is not connected and in some cases cause delays and lags on the output. When an controller is deactivated the row will be "grayed out" to show that it is not enabled.

Vendor, Controller, & Variant

The Vendor, Controller, and Variant fields are used to setup which hardware controller will be used. xLights will use this information to determine what protocols are supported and the max number of universe and/or channels allowed. Not all controller types require the variant field to be populated. If the controller being used is not listed, leave the fields blank.

Auto Size

When "Auto Size" is enabled, xLights will automatically adjust the controllers channel size based on the controller connections. This option only works when "Auto Layout Models" is enabled. It will not work with absolute or universe addressing.

Auto Layout Models

When "Auto Layout Models" is enabled, xLights will automatically change the models start channels based on the controller connections.

Auto Upload Configuration

When enabled, xLights will automatically upload the controller configuration when output to lights is turned on. This only works with FPP based controllers.

Full xLights Control

When "Full xLights Control" is enabled, xLights will erase all the current controller settings when preforming the upload process.

Suppress Duplicate Frames

By default, data will be sent every output frame, If this option is enabled, xLights will only output data if the data is different from the previous frame. This is useful for slow controllers to prevent lag. Most E1.31 and DDP controllers should not enable this option.

FPP Proxy IP/Hostname

This is needed when a FPP device is being used as proxy or bridge between your home network and show network, where the controller are attached. This is typically the WIFI IP of a FPP instance that bridges the wifi and Ethernet networks. The FPP Proxy IP/Host option is used in conjunction with FPP 2.8+ Controller Proxy.

USB Controller

USB Controller type is used to define a DMX, Pixelnet-Open, LOR dongle, LOR optimized, D-Light, Renard, or OpenDMX controller. The USB type can be used to for physical serial ports on the PC or "virtual" serial ports using a USB FTDI adapter.

Ethernet Controller

Ethernet Controller type is used to define a E1.31, Artnet, DDP or ZCPP controller. The controller will be attached to the PC thought the ethernet or Wifi interface.

NULL Controller

NULL controller type is used to generate channel blocks with no physical hardware or controller. This type of controller is used in setups, where the sequence output will not be used by xLights as a show player, but output data to be used for playback on a standalone controller.

Controller Buttons

Visualise

The Visualise buttons allows the user to visually arrange which models are connected to each controller.

Upload Input

Upload Input will copy all the E1.31 universe inputs defined to the selected controller. This requires a valid IP address, and that multicast is not being used. The E1.31 Input Definition's will only be preformed for the controller selected.

Upload Output

Upload Output uses the parameters from models controller connections in the Layout tab/Visualise and uploads these settings to the controller. This feature is available for the following boards : Falcon, Pixlite/Pixcon, SanDevices, J1SYS, AlphaPix, HinksPix, Espixelstick, and most FPP caps and capes. This feature is compatible with both universe/channel addressing and absolute addressing.

Open Controller

Open the currently selected controller in the default web browser.

Delete

This will delete the selected controller.

Controller Status Indicator

The green indicator identifies if the controller is connected and responding to ping requests. For serial ports this will indicate if the Com port can be opened. If red the controller is not responding.

USB Controller

USB Controller type is used to define a DMX, Pixelnet-Open, LOR dongle, LOR optimized, D-Light, Renard, or OpenDMX setup. The USB type can be used to for physical serial ports on the PC or "virtual" serial ports using a USB FTDI adapter.

Click the Add USB button to add a new USB controller. Select a row to highlight the controller and change the settings.

USB Controller Settings

Port

Sets the serial port used for the the serial device. The dropdown will populate with all the connected devices. Select "Not Connected" if the device is not currently attached.

Speed

Sets the speed of the serial device, normally listed as baud-rate or bit-rate.

Channels

Number of channels of the serial device. For most DMX devices this needs to be 512.

Protocol

LOR Optimised

LOR Optimized is much closer to true LOR protocol and utilizes some of the more advanced commands.

First, set an ID of the output, this is not the LOR unit ID of a controller box, it is a unique ID that xLights will use to direct the channel data to this output. The port is the COM port of the dongle in use, Baud Rate is adjustable. NOTE: Older black or white LOR dongles do not support speeds over 115200, Only the red LOR dongle will support higher speeds. Description is user defined value to identify the controller. The Devices setting sets the number of LOR Controller. Based on the Devices number, the settings grid will add setting for each LOR controller.

The settings grid will list the LOR controller. Each controller will be listed by controller type, Unit ID, Channels, and Address Mode. Note: xLights cannot set the unit ID to the controller, this must be done via the LOR software or from the DIP switches on the controller board if applicable.

Select the LOR controller type, the available choices are: AC Controller, RGB controller, CCR, CCB, and the 3 Pixie Controllers (4 ,8, 16 output boards). Then select the number of channels for this controller board. Next is the unit ID. This can be very confusing as LOR uses a hexadecimal system for numbering their UNIT ID's. Units 1 to 16 are 0x01-0x0F and units 17-32 are 0x11-0x1F. Make sure the hex number in bold matches the LOR unit ID in their software. Set the addressing mode as normal, legacy, and split. A description for each controller can be provided.

Testing

If you have a set of lights connected to your controller, you can test them directly via xLights.

To ensure that the Controller channels and outputs setting match xLight, an Upload to Controller must be preformed. To do this, switch to the controller tab highlight the controller to test.

Click the 'Upload Input' and 'Upload Output' to configure the controller. 'Upload Input' must be preformed first. Some controller types do not require the 'Upload Input' action to be preformed and this button may be grayed out. A dialog may appear asking the user to override the previous controller setting, Click 'Yes' on this dialog.

If successful, an Upload Compete message will appear in the bottom left status bar.

Then select the Test option from the Tools menu.

You will be presented with a screen that shows the controller and all the channels configured via the Controller Tab.

You can select the channels you want to test or in this case select the controller which then selects all channels.

Ensure that ‘Output to Lights’ is selected.

Select the test function (example Background Only) and use the sliders to increase the intensity.

To display Model groups or Models instead, click on Model Groups or Models across the top.

Different test functions are available for RGB, non RGB lights as well as the option to execute different test cycles. Set the Tools->Test section for more information.

Controllers

The Controllers tab is used to define the locations of the Show directory and the Sub Folders, as well as to configure the setting for each controller.

Downloading xLights

The latest release of xLights for MacOS can be found Mac App Store.

https://apps.apple.com/us/app/xlights/id1137297689

The link will redirect your browser to the App Store Preview, and will automatically launch the app bringing you to the xLights download page.

Apple App Store Method

Search for "xlights" in the Apple App Store.

Download xLights by Clicking the "Get" button.

After Entering your Apple ID and password, Click the "Install" Button.

After installing, "xLights" will appear in the Dock

Installing QM Vamp Plugin

For M1 based hardware, download the 'Vamp Plugin Pack Installer' from Dan Kulps website

https://dankulp.com/xlights/archive/qm-vamp-plugins-1.8.dmg

For Intel based hardwar,e download the 'Vamp Plugin Pack Installer' from https://code.soundsoftware.ac.uk/projects/vamp-plugin-pack

Double click the downloaded .dmg file and run the installer inside the dmg file. Restart xLight and the new timing track options to appear.

NULL Controller

NULL controller type is used to generate channel blocks with no physical hardware or controller. This type of controller is used in setups, where the sequence output will not be used by xLights as a show player, but output data to be used for playback on a standalone controller.

There could be large matrices to be implemented via P10 or P5 panels running off a BeagleBone Black controller. A null output can reserve a huge number of channels, but not actually output anything if the Output to Lights function is on. A model can still be sequenced as normal and viewed on all the windows just as any other output.

Channels

Number of channels of the null controller. It defaults to 512 channels but can be changed to a larger number.

Adding Controller

Click on Add Null and specify the number of channels to be reserved.

Models

A model in xLights 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(RGB, Single Channel, etc), the number of channels, and other characteristics required to render the sequence data. When a model is defined, it is retained in the xLights configuration "xlights_rgbeffects.xml" file in the show directory. It can be reused for all subsequent sequences.

Adding Models

At the top of the layout screen is a row of Model icons. If you hover the cursor on each icon, the model name will be displayed. The model icons represent an Arch, Candy Cane, Circle, Custom model, Icicles Matrix, Single Line, Spinner, Star, Tree, Window Frame, Wreath and Import Custom. The last icon labelled ‘Import’ Custom enables you to import and create a custom model that has been exported from another sequence.

To define a new Model, click on the Model icon that you wish to create once. The model icon will have a dark blue square around it. Then with your mouse left button click on the layout canvas , and keep your mouse button still held down. The model shape will appear on the canvas in yellow. If it does not , then left click on the canvas and drag slightly. At the same time , a model is created and displayed in the Model panel that is normally to the left of the Layout screen.

Depending on the type of model, it will either be bounded by four, three points or two points.

In this image, the Candy canes have three points. The bottom left is green and marks the beginning of the model, the bottom right is blue and marks the end of the model and the top center is blue and is used to rotate the model.

If you cannot locate your model after it has been created, click on the model name in the panel and the model image will be highlighted.

Note that the Preview window has the ‘Default’ preview displayed - indicating that the model that is being created will be assigned to and displayed on the default House Preview window.

By clicking and holding in the center of the model - you can drag the model to the required position. You can also use the three points to size the model on the layout.

When the model is aligned horizontally, a red horizontal line will be displayed.

When the model is aligned vertically, a blue vertical line will be displayed.

In this image, the Single Line model has two points. The bottom left is green and marks the beginning of the model, the bottom right is blue and marks the end of the model. The red superimposed red line indicates horizontal alignment.

If you double click on the Single Line model icon (instead of using a single click) , then you can draw a single line (say as part of the roof line), then click on the layout again and draw another segment from the end of the first segment - this will create another model and so on. Or you can use this technique to draw multiple arches at the same time. Click on the model icon again to deselect it.

On the left of the layout canvas is a window which displays the name of the model that has just been created and the settings of the model.

These are default values and you can then edit the values to suit your requirements - (change the name, start channel , number of nodes etc).

Click on the Preview attribute and change the Preview window if you so require. Set it to ’Unassigned’ if the model is not to be displayed in the House Preview window.

You can collapse or expand any of the windows of the model characteristics.

Deleting Models

To delete a model, highlight the model on the Layout canvas and press the Delete key or press Ctrl X. You can hold down the cursor and drag to form a rectangle around the model and then delete.

You can also Right Click on the Model name in the Model list panel. A ‘Delete’ pop up window will be displayed. Click on it to confirm and delete the model.

Undo

You can also use the Undo function i.e Ctrl-Z to remove the model that has just been added or undo the last model movement. The Undo function can be repeated.

Creating Multiple Model Instances

You can select the model image on the canvas, press Ctrl-C to copy and then Ctrl-V to paste. A new model instance will be created. You can also double-click on the Model icon that you wish to create. The model icon will have a grey/light blue square around it. Then with your mouse left button click on the layout canvas. The model shape will appear on the canvas (surrounded by five blue squares). A left click on the canvas again at the required location will create another instance of the model. And so on. To end the process, click on any of the model icons once.

Rename a Model

A model (name) can be renamed by simply changing the Model name.

Modify a Model

Details of a model configuration can be amended by updating the details in the relevant section of the model definition. Save the changes.

Copy a Model

Once a model has been defined, a quick way to duplicate definitions is to select the model in the Layout window, then use a Ctrl-C to copy it and a Ctrl V to paste it. Save the changes.

Overlap Checks

If the ‘Overlap checks enabled’ attribute is selected, when you click on the model name in the list, it will turn yellow in the layout display to the right. If there is a channel overlap with any other model, then the other model will turn red.

Right Click Menu

Reset

Resets the Current Window View to the default.

Correct Aspect Ratio

This will resize the model so the number of node in the vertical and horizontal direction are equally spaced.

Node Layout

The node layout window is then displayed. The s1, s2, etc. represent the string numbers, the n1,n2,n3,etc represent the node count.

Lock

Lock a model in place to prevent it from being moved. The Model handles will appear red when a model is locked.

Unlock

Unlock a model so a model can be moved.

Export as a Custom xLights Model

Create a Custom Model file from a built in Model Type. Use only if you wire your model in a non support format and a built in type will not work.

Wiring View

Displays a view of how to wire your model based on the Model properties. This can be saved or printed by right clicking on the dialog.

Export xLights Model

Export a Model as a .xmodel file and save to the local disk.

Replace a Model with a Model

"Swap" a new model with an existing model and kept the model name. Use this if want to change a model and keep the same name. This will prevent Model Groups and sequences from breaking.

Model Settings

The model settings determine the physical properties of the model or prop. These setting are critical for how xLights determines the render sequence data, start channels, and controller connections.

Name

The name of the model. The Model name can be changed by clicking on the existing name and changing to a new value.

# Strings

The # of Strings corresponds to the physical number of strings for that model and is generally 1.

Nodes/String

Nodes per String denotes the number of nodes/pixels per string. If your model has 2 strings and 50 node per string, the total number of nodes is 100.

Lights/Node

Lights per Node denotes the number of physical lights per node. (i.e. for pixel strips with 3 LEDs per controller chip, this would be 3).

Lights/String

Lights per String denotes the number of lights per string. This will be used instead of the Nodes/String and Lights/Node settings.

Start Location

Location of the first pixel or first channel location. "Green Square" means the starting location is the green square on the layout and "Blue Square" means the starting location is the blue square.

Controller

xLights has two systems to define model start channel locations. If the controller dropdown is set to a controller name specified in the controller tab, the start channel will be auto generated based on the Controller Port and Model Chaining settings. This is the preferred method of configuring start channels.

Start Channel

The Start Channel corresponds to the starting channel of the first node for the model. xLights will automatically calculate the end channel based on the model settings.

If the controller dropdown is set to "Use Start Channel", by Default, xLights will "chain" all you models together, this means the start channels will just follow the previously model.

In this example, the Start Channel has been set to start immediately after the ‘Candy Canes-2’ model.

xLights will automatically calculate the start channel and end channels, and if the ‘Candy Canes-2’ model’s channels change, then the start and end channels for this model will automatically be recalculated.

Click the ellipse button (three periods) to edit the start channel.

Model Start Channel can use Absolute, Universe, Start/End of Model or Controller based addressing.

Individual Start Channels

For models with multiple strands or elements, you can specify the start channel for each strand individually if required. This is useful where the channel numbering is not contiguous.

Preview Display

The Preview setting controls whether the model is to appear in the House Preview screen and also which Preview layout screen. Click within the setting to open up a window which lists all the available Previews. If you have created additional Preview layouts, they will be listed in the window.

The ‘Default’ value represents the default preview window.

‘All Previews’ indicates that the Model is to be displayed in all Preview Windows.

‘Unassigned’ indicates that the model will not be displayed as it is not assigned to a Preview window

‘Unassigned’ is sometimes useful where the same physical item has been re-defined using more than one model definition for ease of programming the effects. One of them should have the Preview set to ‘Unassigned’ and the other should not.

The ‘2nd Preview’ is one that has been user created.

Strand / Node Names

Click the ellipse button (three periods) to edit the Strand / Node Names.

Each strand and node can have a name assigned to it. This is useful where for example you have single channel models that are grouped together (singing faces, tombstones or DMX props etc). On the sequencer, double clicking on the strand reveals the nodes with meaningful names against them.

Faces

This setting is used to specify the Faces definition for custom models that support Singing faces.

Click the ellipse button (three periods) to edit the Faces.

Functionality has been covered in the Singing Faces section.

Dimming Curves

The Dimming Curves setting can be used to change/reduce the brightness of the lights for a specific model. The intensity of the lights is accordingly changed/reduced from its default value of 100%. Use the "Brightness" slider where you can reduce (or increase, but 99% of the time, you reduce) the brightness of the model in the FSEQ. Change the gamma curve of each of the red, blue or green values.

You can select from the options to have a single gamma value or change individual gamma values. You can also select the values from a file, in which case you are prompted for the location of the file.

State

This setting is used to specify the State definition for custom models. Functionality has been covered in the State Effect section.

Sub-Models

This setting is used to specify parts of a model to be controlled as if it were its own model. This is used for example if you have a wire frame with 2 arm positions you then can sub model those and control them without the need for adding a 2nd or 3rd model.

Click the ellipse button (three periods) to edit the Sub-Models

You will find the sub-model listed as parent model name/sub model name. This can be added to groupings and added to sequencing as a stand alone model.

See the Sub-Models Section for more info.

Controller connection

The Controller Connection settings are used for the Upload to Controller Options in the Controller Tab. Port specify which output of the controller is being used by this model. Protocol is the pixel type or serial type. If a serial protocol is set i.e. DMX the Port setting sets which DMX Port is used on the controller. If the Protocol is set to a pixel protocol i.e. ws2811 the Port setting sets which pixel output is used on the controller board. The additional settings(Null Pixels, Brightness, Gamma, Color Order, etc) will override the setting in the controller if checked. Not all controllers support all settings and some controllers only support one setting per controller port.

Upload to Controller is covered under controller tab.

String properties

String Type

The String Type enables you to set or change the ‘RGB’ orientation of your nodes.

The first six options in the list below are used for Pixels - these can also be set in the hardware controller. Dumb pixels are set to either 3 Channel RGB or 4 channel RGB and single “A/C” or store bought fairy lights are set to single channel.

Color

The Color setting is used for Single Color/Node Single Color String types to define which color the string responds to. If set to White , then only when the White is on, on the sequence , will it light. If set to say Red , then it will light if Red is on (which is 255,0,0) or if White is on (because White sets 255,255,255 on).

RGBW Color Handling

Appearance

The Appearance setting is used to determine how a particular element is displayed when viewed in the Layout, House Preview and Model windows. By increasing the Pixel Size, the appearance of the element (a flood or any other small element) can be made to display a bigger size. The Transparency and Black Transparency values can be used to adjust how opaque or transparent the element is on the display. If the Active option is unchecked the model will not be shown in the layout screen.

Tag Color adds at color indicator before the model name in the sequence tab.

Size/Location

The size/location settings describes where on the Layout screen a model has been place, and its relative size to the model grid. XYZ are the center point of the model. ScaleXYZ determine the size of the model. If a model is locked it cannot be moved. Locked models will have red handles in the layout window.

These values "auto adjusts" as you move or change the size and orientation of the model image and normally does not have to be manually set or adjusted. Model can be locked and unlocked with the right click menu.

Custom Model Creation

xLights enables you to define models that do not fit into the concept of predesigned common shapes. For example, a snowman outline, reindeer outline, a singing face, etc. In order to define such a model: Create a new model by selecting the Create new Custom Model icon. Select an area on the Layout screen and drag the mouse across. Note that there won't be anything displayed in the box as the custom model layout has not yet been defined. A new Custom Model will be created with an initial model name of ‘Custom’ or similar. You can rename it to something more suitable. Click within the Model Data box to enter the Custom Model setup window.

A custom model grid will be displayed in which you enter numbers in the grid representing the nodes/channels in your model.

Change the width and height values to increase the size of the grid to fit the layout.

The Right Click Menu Allows you to Flip, Rotate, Compress, Trim Unusued Space, and Shrink Space.

For example, to model a custom candy cane with 12 nodes, you could have a grid 4 columns wide and 10 rows high. Place the numbers 1-9 up the right hand side, 10 and 11 in the middle cells in the top row and 12 would go in column A row 2. This is shown below.

Click on the Wiring View Button to open a window which will display the nodes and wires as they would be installed in the actual model, based on the layout entered in the grid. Note that the wiring view is shown from the reverse view (back side of the model) below. This is the view as if the pixels are being pushed in from the backside. Right clicking on the wiring view will provide options for changing the background color, font side, and viewing from the front or backside, as well as a few others.

The Right Click on the Custom Menu grid gives options to Flip, Rotate, Compress, Trim Unusued Space, and Shrink Space.

Click on the Horizontal Flip or Vertical Flip buttons to shift the nodes in the grid horizontally or vertically, which will also change the output of the Wiring View if selected.

The following image is an example of a Singing Face custom model on a 50 by 50 grid.

To erase a number in a cell, selected the cell and press the Delete key.

You can delete multiple cells by drawing a box around them and then pressing Delete.

You can use the ‘+’ and ‘-‘ keys to make zoom in and out, respectively.

Click OK to save the model.

Custom Model Creation Using A Background Image

From the Layout screen, click on the custom model icon and drag and draw a custom model, as described above. Click on the ... button at the far right of the Background Image Row. A window will open to prompt for the location of an image file. Browse to and select the image.

Alternatively, open the Model Data window to open the Custom Model Window and select the file using the Browse button.

Click on the Model Data attribute. This will open up a window with the image in the background which will fill the grid size. Adjust the size of the grid by increasing the width and height values. Click on the ‘+’ and ‘-’ buttons to Zoom in and out of the grid.

The Background image slider can be used to adjust the brightness of the background so that the image is just visible. This will enable you to more easily see the numbers on the image and around the outline. Slide to the left for 100% brightness and to the right for 0% brightness. The magnifying glass at the right side of the slider will toggle the image on and off.

You can then start typing the numbers in the positions that the pixels would be located. In this example, it would be around the edges of the snowman and hat.

To erase a number in a cell, selected the cell and press the Delete key.

You can delete multiple cells by drawing a box around them and then pressing Delete.

If you select the Auto Numbering setting to be active, the channel number that is shown in the Channel number box will be added at any cells selected.

If the Auto Increment setting is set to be active, then after each selection, the number is automatically incremented. This is typically the case for smart strings of pixels.

Click on OK to return to the layout screen at any time to view the Custom Model that has been created.

To edit the custom model, select the Model Data the same as was done with the initial setup. This can be done at any time to edit the model.

Export Custom Model

A custom model can be exported so that it can be shared with others, used in different layout, or for adding additional copies of the model to this layout.

To export a Custom Model, select the model and right click. Select Export xLights Model.

You will be prompted to specify a location and filename. Enter the filename click on Save. Note that the xLights custom models use a ".xmodel" file extension.

The export process includes the faces and state definitions, as well as custom models, so these don’t need to be redefined when imported.

Import Custom Model

This function enables you to create a custom model from a previously exported custom model file (xmodel). This can be previously created by you or shared from another user or vendor.

Click on the ‘Create new Custom model’ icon and then click on the canvas where the new custom model is to be located. You will be prompted for the name and location of the custom model file (xmodel) to import.

Select the file name and a model will be created using information from the custom model file. The model name or other attributes can be edited as needed.

The model will be located at the point selected, and can be resized or moved using the blue connectors similar to any other model.

Controller Visualizer

The Controller Visualizer allows the user to drag and drop models onto the controller ports. All model setting are update and saved in real time. If the "Auto Layout Models" option is disabled for the controller, this dialog will only allow the user view the model port connections set in the layout tab.

Hover over a model to display its current settings.

Size Adjustment Sliders

The Box Size and Font Size sliders will change the size of the drag and drop boxes and font size.

Status Message Box

The Status Message Box will display errors that are found in the current controller configuration. If an error is displayed, xLights will not upload the controller configuration.

Adding/Moving Models

To add a model, Drag a model from the right model list to the desired controller port on the left.

Removing Model

To remove a model, drag a it from the controller port list on the right to the model list on the left.

Model Right Click Menu

Print

Prints the controller model layout of the Visualizer Screen.

Save As CSV

Saves controller model layout to a CSV file for editing.

Remove all models from controller

Removal all the models from all the controller ports.

Change String Count

Change the physical number of strings i.e controller ports a model consumes. When used, xLights will attempt to adjust the Nodes Per String and Stands per String to preserve the original total pixel count of the model. Only works with Tree/Matrix/Custom Models.

Smart Remotes

None/A/B/C/D/E/F

Set the Smart Receiver ID for Falcon/Kulp/FPP/HinksPix Controllers. None is used for "Dumb" or normal receivers.

Type

Set the Type of Smart Receiver. V1 "White" Receivers are "falconv1", "Blue" or "Black" Receivers are "falconv2" or "fppv2".

Cascade Down Port

When enable, this will change the string order to proceed down the daisy chained receivers on the current "chain" of remotes. This is needed for controllers that don't support 'Virtual Strings' like the HinksPix Pro.

Cascade Remotes

This allow multi-string models to use multiple smart receivers daisy chained together. When Cascade Remotes is set to 4, xLights will assign strings to 4 smart receivers chained together.

Smart Receiver Color

Smart Receivers will display as different colors if set. Green is 'A', Purple is 'B', Orange is 'C', and Light Blue is 'D'. The colors will repeat after 'D', Green is 'E', etc.

Set Brightness

Set the Model Brightness.

Clear Brightness

Clear the Model Brightness.

Controller Port Right Click Menu

Set Protocol

Set the Controller Port Protocol.

Remove all models from port

Removal all the models from the selected controller port.

Move all models to port

Move all models from the currently selected port to another port.

Arches Model

The ‘# Arches’ value can be set to the number of arches that the model represents (normally one). Similarly you can set the nodes per arch and lights per node (normally 1). The Arc Degrees determines the portion of a circle's circumference the arches use. 180 degrees mean the arch is half the circumference of a circle and 90 would be one forth circumference of a circle. The Arch Tilt will tilt the arches "hops" left or right. This is useful for arches on a incline.

The example above will contain two arches of 25 pixels each, for a total of 50 pixels. Each pixel contains 3 LED per pixel so there are 3 lights per node.

Layered Arch

With Layered Arch enabled, a multi layered arch will be created. The Layers attribute value describe the concentric arches in the model. This will create node count settings for each layer. The sum of the node counts must add up to the number of nodes in the model. 'Hollow %' will set the space "under" the arch.

Show Directory

The xLights Show Directory is where all the required xLights sequences, pictures, and user configuration files used to run the sequences are kept. When a sequence (.xsq) is saved and a binary file (.fseq) rendered, both files are created in the show directory. This is the same location where xLights configuration files can be found and the default location where the program will first prompt for, or look for files pertaining to several functions of xLights.

Specifying or changing the location of the Show directories can be done by clicking on the Change button found on the Controller tab screen.

In some cases if you copy your show directory to another location or drive xLights may still be able to successfully locate image files despite the absolute reference (in the case where the the last sub folder of the location has the same name).

If you have a show folder c:\show and you move it to e:\xxx\yyy\show it will seamlessly work as long as all the files your sequence needs are in the show folder or one of its subdirectories. Anything located elsewhere will not be seamlessly moved but if they are still there they will be used.

Change Permanently

The "Change Permanently" button will allow the user to specify the location of the their primary show directory on disk. This show directory location will be remembered when xLights is closed and reopened.

Change Temporarily

The "Change Temporarily" button will allow the user to temporary switch show directories. The show directory path name will turn the color yellow to signify a temporary show directory is being used. When xLights is closed and reopened, this "temporary" show directory will be forgotten and xLights will resume use of the "Permanent" Show directory. The "Restore to Permanent" button will also switch back to the "Permanent" Show directory. The "temporary" show directory should be used when importing a sequence.

Channel Block Model

The Channel Block can be used to define an arbitrary amount of channels. It can be used to 'model' generic channel to be used or AC Lights, relays, smoke machines, etc.

# Channels

Number(#) of Channels defines the size of the channel block. These Individual channels can then be used to control specific channels on a device or controller.

Channel Color

Channel Color determines what color in the sequencer will "activate" this channel block channel. If set to 'White' all three RGB channel values will be use to set the output channel value. If set to 'Red' only the Red channel values will be use to set the output channel value.

Circle model

# of Strings

The # of Strings corresponds to the physical number of strings for that model. This should match the number of controller ports you plan to use.

Nodes/String or Lights/String

The Nodes per String or Lights per String represents the physical number of light nodes, bulbs or pixels in each string. If the # of Strings is set to 2 and the Nodes per String is 100, the model will contain 200 total nodes.

Center %

The Center % is used to indicate how much area the empty area of the circle occupies. Decreasing it will drop the circles inwards and increasing it will push the circles outwards.

Layers

The Layers attribute value describe the concentric rings in the circle. This will create node count settings for each layer. The sum of the node counts must add up to the number of nodes in the model.

Starting Location

The default starting pixel is at the bottom of the circle, go clockwise on the outside ring and then the next inner ring wired and so on. The Starting Location can be changed to start at the top of circle, or start on the inter ring or run counterclockwise if needed.

Ethernet Controller

Ethernet Controller type is used to define a E1.31, Artnet, DDP or ZCPP controller. The controller will be attached to the PC thought the ethernet or Wifi interface.

Click the Add Ethernet button to add a new Ethernet controller. Select a row to highlight the controller and change the settings.

Ethernet Controller Settings

Multicast

(ArtNet/E1.31) When enabled, Multicast will send Ethernet data to all subscribed Ethernet controller on the network. IP address is not needed when enabled.

IP Address

Sets the IP Address of the Ethernet controller. The host name can also be entered in this field.

Protocol

Priority

(ZCPP/E1.31) Priority is supported by some controllers and is used to determine which data packet to use is multiple packets are received controlling the same channels.

Start Universe

(ArtNet/E1.31) This sets what is the first universe for the controller to listen for data on. Can be any value from 1 to 63999. It is recommend to not overlap universe between controllers.

Universe Count

(ArtNet/E1.31) The number of universe sets the number of channels allocated for the controller. This is multiplied by the universe size to get the total channels. If using Auto Size this will be grayed out and set automatically.

Universe Per String

(ArtNet/E1.31) The number of channels in each universe will be resizes to match the number of channel in each string of a model. This will align the Model's string channels with the universes. This is needed for controllers that don't support 'virtual strings' and require data in a fixed structure. The option is only available when 'Auto Layout' is enabled. It is needed for the HinksPix Controllers.

Universe Size

(ArtNet/E1.31) This sets the number of channel per universe. Universe can be any size up to 512 channels. Some controllers require a size of 510 or 512. 510 is recommended.

Individual Sizes

(ArtNet/E1.31) When Enabled, this allows the user to manually set each universe size independent of each other. Not recommended.

Channels Per Packet

(DDP) The number of channels sent in each packet, this should be left to the default of 1440.

Keep Channels Per Packet

(DDP) If checked absolute channel numbers will be sent, this sends the channel numbers to the controller. If unchecked the first channel sent to the DDP controller will be channel 1. Enabled is recommended.

Channels

(ZCPP/DDP) Channels is the total number of channels that the controller is using. If using Auto Size this will be grayed out and set automatically.

Automatic Start Channels

If Auto Layout Models is enabled in the Controller Tab, xLights will automatically calculate the Model Start and End Channels based on the controller settings.

First Set the Controller the model will be connecting to.

Then Set the Controller Port

If assigning multiple models to one controller port you must set the model chaining to determine the order of the models on the controller output.

Manually Changing Start Chanel

First Change the Controller Dropdown to "Use Start Channels" in the model settings.

Click within the Start Channel cell and then click on the highlighted box to open up The Start Chanel Window.

The 'Offset From' determines how the start address is calculated. If the offset is set to "None" the start channel is then used to define the absolute channel number.

However it is possible to use other definition setups:

If you select the ‘Universe Number’ option, the start channel for the model is calculated based on the “start channel” that is offset from this ‘Universe Number’.

If you have one controller setup on your controller tab with universes 10 through 14, all with 510 channels, for the model set as Start Channel “1”, From Universe “11”, its real absolute start channel in the FSEQ would be channel 511 (first channel of the Universe 11).

The “ANY” value indicates that the Universe is not specific to an IP address and therefore xLights searches for the universe number. (This is the recomended setting to use)

You can specify a specific IP address if you wish - in the unusual event that you have the same universes on different controllers on different IP addresses.

The start channel value can also be specified relative to other channels using the End of Model or Start of Model options. You can specify an offset from an output number or select the start channel to start from the end of another model or align with the start of another model (in the last two scenarios, the model name is to be selected from a drop down box).

This options works well if your models are reasonably static as the channel numbers are automatically calculated. If however, you delete models then it can break the chain . xLights will alert you to this , but the popup dialogs could be tricky to navigate through.

The ‘Controller’ option, uses the controller name to determine the start channel for the model. It is calculated based on the “start channel” that is offset from the Controller Start Channel in the Controller Tab. This option works well for P5 or P10 Panels running of a FPP controller.

Cube Model

The Cube model is a 3D model that is used to model objects like Pixel/Peace Stakes, Boxes, or Grids. While the model is 3D, xLights renders the effects in 2D.

Stand Style

Layers All Start in Same Place

All the wiring for each layer will start in the same location. Bottom Left in the example above.

Example Configurations

3W x 3H x 3D, Front Bottom Left, Horizontal Left/Right, ZigZag

3W x 3H x 3D, Front Bottom Left, Vertical Left/Right, ZigZag

3W x 3H x 3D, Front Bottom Left, Horizontal Front/Back, ZigZag

3W x 3H x 3D, Front Bottom Left, Stacked Left/Right, ZigZag

Layout

The layout tab displays a full preview of your show and provides a view of how all the models will appear. In addition you can :

• Define new Models or change existing Model definitions.

• Define new Model Groups or change existing Model Group definitions.

• Select which Models, or Model Groups are be displayed on the Layout.

• Select and adjust the layout background.

• Specify, position and adjust the model size, orientation and location on the layout.

• Check whether any models have overlapping channels.

• Review or change the detailed characteristics of a model’s attributes

• Create Additional Preview layout windows

• Assign Models to one or more Preview Layouts

• Assign Models to Specific Controller Connection

• Assign the Model Start Channels

Model Setup:

• Define most of the parameters the way you would for the existing moving head 3D model

• Use the "Orient to Zero" parameters to get the pan/tilt positions in layout to make the head look like it does when its commanded to 0 which is usually the bootup position.

• We want to define a Common starting position with the head point Up and facing Forward. All commands will be relative to that starting position I call the "Home" position. So we have a Zero position and a Home position.

• You define the Zero position by viewing the layout and you define the Home position by creating a blank sequence and dropping a Moving Head Effect on the head. Click the center of the position grid so that it will latch a Pan=0 Tilt=0 command into the heads settings. If the head is not pointing Up and Forward then you need to adjust the degrees in the Orient Forward and Orient Up parameters for the pan/tilt motors. Just change the settings and come back and click on the effect to see it change. If you use an old school effect to position the head you should see how it points to the Zero position when commanded to Zero whereas the Moving Head Effect should apply the Home position offset.

Parameters:

• Fixture: You need to set the fixture position for each head MH1 through MH8. This teaches xLights where each head is positioned so that when you tell it to do a Fan it know how to space out the heads. You can assign more than one head to a position if desired.

• PanMotor: Channel (Coarse): Required.....define the main pan channel Channel (Fine): For 16 bit heads. The Fine channel is optional and can be set to 0 to disable. Min Limit (deg): Limit how many degrees the head will pan to the left starting from facing forward Max Limit (deg): Limit how many degrees the head will pan to the right starting from facing forward Range of Motion: How many total degrees does the head pan when commanded from 0 to 255 Orient to Zero: Number of degrees to spin the head so it matches the position when commanded to 0 Orient Forward: Number of degrees to spin the head from its Zero position so it faces forward Slew Limit (deg/sec): Number of degrees your head can move per second to try to make the screen match reality Reverse: Check this box if your head moves counter-clockwise when commanded from 0 to 255 Upside Down: Check this box if you head is mounted inverted

• TiltMotor: Channel (Coarse): Required.....define the main tilt channel Channel (Fine): For 16 bit heads. The Fine channel is optional and can be set to 0 to disable. Min Limit (deg): Limit how many degrees the head will tilt backwards from facing up Max Limit (deg): Limit how many degrees the head will tilt forwards from facing up Range of Motion: How many total degrees does the head tilt when commanded from 0 to 255 Orient to Zero: Number of degrees to spin the head so it matches the position when commanded to 0 Orient Up: Number of degrees to spin the head from its Zero position so it faces up Slew Limit (deg/sec): Number of degrees your head can move per second to try to make the screen match reality Reverse: Check this box if your head moves counter-clockwise when commanded from 0 to 255 Upside Down: Check this box if you head is mounted inverted

• Most other properties are similar to the previous moving heads

• BaseMesh, YokeMesh, HeadMesh: These can be used to change the OBJ objects used to draw the head.

PolyLine Model

The Poly Line model enables several straight line or curved segments to be drawn as one model (rather than having to draw them as individual models).

This model is useful for the roof line, rafters, fences, etc where the lines are at an angle to each other.

To draw, select this model and drag on the layout as usual. At the end of each segment, click once with the mouse left button, then draw another segment. Left mouse button Click to end the segment.

At the end press the ESC key (after the Click) to deselect the drawing action. You can then grab any of the blue or green pixels and move it around to change the shape of the model image.

The # of Nodes defines the total number of nodes for the entire model, the Lights/Node is normally one and the Starting location can be the Green Square(Left) or Blue Square(Right).

Strings is the number of physical connections i.e ports to the controller.

The drop pattern allows the polyline to be used as icicles, this indicates how the pixels are arranged on each drop and how many.

Alternate Drop Nodes will skip every other hole to allow wiring up and down each icicle and prevent wire splicing.

Enabling the Individual Segments attribute selecting will present the different segments that form the poly line model.

You may end up with some in-between lines you don't want. So then check Indiv Segments and start clicking on each segment line in the property grid. It will highlight each segment as you click on them. Once you get to one of the "in-between" lines you don't want just type in a "0" for segment size and it will disappear from the drawing

You can change the number of nodes in each segment.

You can also name all your line segments.

Adding Segments

To add a segment to an existing model, right click on a segment of the poly line model; the segment color will change to red.

Then select Add Point and a point will be added to the segment. The number of segments will increase by one. You can then work with the new segment and change the number of nodes via the panel.

Segment Curves

If you Right click on a segment, the segment color will change to red.

You can then modify the straight line segment into a curved segment by selecting Define Curve. Grab one edge of the segment and drag it in the direction that you want the line to curve. Then select the other end of the segment and drag it in the direction you want to form a curve. Note the pink dots that denote the end of the curve that you are working with.

Click on the curved line and two straight red bars will be displayed from either end. You can then grab the end of the bar and drag it in any direction to stretch or move the curve.

Icicles Model

The # of Strings would normally be 1.

The Lights per String represents the physical number of light nodes, bulbs or pixels.

You can drag the green or top blue pixel to hang the icicles at an angle and then drag the lower blue pixel to cause the drop to sheer and hand vertically shear.

The drop pattern indicates how the pixels are arranged on each drop and how many.

So, if the total lights on the string is 80 and the drop pattern is 3,4,5,4, this indicates that the first drop has 3 nodes, the next 4 , then 5 then 4.

This pattern is then repeated until 80 nodes have been accounted for.

Alternate Nodes will skip every other hole to allow wiring up and down each icicle and prevent wire splicing.

Matrix Model

The direction can be defined as horizontal (the most common) or vertical. The ‘# Strings’ refers to the number of controller connections of the matrix. The Nodes/String refers to the number of nodes in each string. The 'Strands/String' is the number of 'rows' or zigzags per string. With AC lights ‘# Strings’ is the number of channels the Lights/string is the lights per string.

The starting location indicates where the matrix is connected to the controller (or where channel 1 of the matrix is).

Above is an example of a horizontal matrix with 16 rows and 50 pixels per row.

If the Strands/String is set to '2' it will add a zigzag and there will be 32 rows with 25 pixels per row.

Alternate Nodes will "hop" every other node down and back to have the string start and stop at the same location.

Single Line Model

The ‘# Strings’ is almost always set to 1 .

The Nodes / String indicates how many nodes the string has and the Starting Location indicates whether it runs from left to right or vice versa.

In this example, the single strand model has ten nodes and starts at channel 7240. It runs from left to right.

In the case if you have a vertical setup , then the first channel should match the node connected to the controller or end of the previous model.

Accordingly change the orientation of the model to match that. You can however, reverse the orientation in many hardware controllers as well.

Image Model

The Image Model is used to represent single channel props like blow-molds, inflatables or incandescent cutouts/wire-frames. You load a picture of the prop and xLights will illuminate the picture based on the channel value. The Off brightness can be set to a value above zero(10% in the example) so it is still visible in the layout when the channel is off. This Model only works with Single Channel or Single Channel Intensity string types not RGB lights or pixels.

Star Model

The # Strings is normally set to 1 and the Lights/String denotes the total number of nodes on the model. The # of Points describes the points of the star and the startling location indicates where the first node is and which direction it progressive.

Starting Location is where the string start location is set to begin.

Outer to Inner Ratio describes the "wideness" of star points.

The Layers attribute value describe the concentric layers in the star. This will create node count settings for each layer. The sum of the node counts must add up to the number of nodes in the model.

Sphere Model

Spinner Model

The number of Strings is normally set to 1.

The Arms/String represents the number of Spokes and the Lights/Arm represents the number of nodes on each arm.

The Hollow % is used to control the gap at the base (ie center) of the spinner model.

The Arc can be used to denote whether the model is a 360 degrees spinner or say a 180 (sem circular spinner) or anything in between.

The Starting Location, besides indicating which is the first channel of the model, is also used to denote how it is wired. There are 6 definitions supported (wired from the center, wired from the outside, alternate first/last node and for either whether the nodes move clockwise or counterclockwise ).

When wired from the centre, the starting location must be as indicated with the red rectangle and the pixel direction is outwards on all arms.

When wired at the edge, the starting location must be as indicated with the green rectangle and the pixel direction is inwards on all arms.

The zig zag attribute is to be selected if the wiring is say - inwards on one arm and then outwards on the next and then inwards etc or outwards on one arm and then inwards on the next and then outwards etc.

DMX model

The DMX model has a number of different styles and each has a different model representation.

After selecting the DMX Mode, a list of Sub Types will display.

General

Used to define any generic DMX Fixture. Can be used for 3/4 Channel RGBW lights or devices like Fog or smoke machines.

Floodlight/ Area Flood

Used for multichannel Flood lights. The Single Line Model can all be used for DMX Floodlights.

Moving Head/ Moving Head 3D

For DMX Moving Heads. Supports Shutter control, RGBW channels, Color Wheel, etc.

Servo

Induvial Servo Control, Supports 16 bit servos.

Skull

For Skulls with servos embedded in them. Skulltronix Skulls are also supported.

Wreath Model

The # Strings is the physical number of strings connected to the controller. Nodes/String is the nodes/pixels per light string.

Download/Import Models

Import Model

After Selecting the Import Model Button, You must click on the layout preview and drag out a box and release, to represent the imported model location.

Then select the local .xmodel file with the File Select Window

The imported model will be the same model type it was exported as. If the .xmodel file contains a custom Model, the imported model will also be a custom model.

Download Model

After Selecting the Download Model button, You must click and drag out a box and release on the layout screen to represent the downloaded model location.

The Model Dialog will appear where you can select the desired model you would like to insert.

Click Insert and Model will be added to your layout.

Window Frame Model

This model is used to represent window frames and door outlines. The # Lights Top is the number of light across the top of the window frame. The # Lights Left/Right is the number of lights per side. xLight will assume the sides are the same length and use this number for both sides. The # Lights Bottom is the number of light across the bottom. This can be set to zero for Door Frames. Direction specified the wiring direction. Starting Location is the location of the first node.

Model Groups

A Model Group defines a collection of models. It is an optional entity, but very useful, in that many effects can be sequenced against the Model Group and xLights will then generate effects on all the Models in the group.

A Model can belong to more than one Model Group. An an example a model ‘Arch1’ can belong to the ‘All Models Group’ Model group as well as the ‘Arches Group’

You can also have models that do not belong to a Model Group - for example a matrix that you wish to sequence effects on separately such that dropping an effect on the” All Models” group does not affect the matrix.

Add Group

To create a Model Group, from the layout tab right click within the Model list window. Click on Add Group, enter a Model Group name in the resultant window and click Ok.

In the layout windows, a Model Group can be added by highlight multiple models, right click, and select 'Create Group'.

In xLights, Model Groups are sequenced against an internal grid representation.

The Default Layout Mode and Max Grid Size provides options on how the ‘internal grid’ is to be calculated when effects run across a model group.

If ‘Grid as per preview’ is selected , then the buffer used will be exactly as to how the the house preview appears i.e will be quite large.

If ‘Minimal Grid’ is selected then the buffer area will be an area just surrounding the model group.

Modify Group

To modify the models that form part of a group, click on the group name.

The models that are currently in the group will be displayed in the ‘Models in Group’ right list and the other models will be displayed in the ‘Add to Group’ left list. Use the arrows to add or remove models as required and click on the Save when done.

Delete Group

To remove a Model Group, select the Model Group from the model list, right click and select Delete Group. This will not change or remove any of the underlying models, however any effects that have been placed at that group level on the sequencer will be removed and the Model group will be removed from the Layout display if it has been added to that display.

Rename Group

To rename a Model Group, select the Model Group from the same list , right click and select Rename Group. Enter the new name for the Model Group. 'Clone Group' will create a copy of the current group with the same models. 'Delete Empty Groups' will delete Model Group with containing no models.

Clone Group

Create a copy or clone of the currently selected group.

Delete Empty Groups

Delete any model group that is empty and contains no models or groups.

Tree Model

Type

The type of tree can either be Round, Flat, or Ribbon. A Round Tree is "classic" tree with a round style base. A Flat Tree will have a flat base and is intended for trees against a wall. A Ribbon Tree is the same as a flat tree but the top is tapered to a single point. Flat and Ribbon Tree are always 180 degrees.

Degrees

The Degrees attribute indicates whether the tree is a full (360), half (180) or three quarters (270) tree or any other value. This property is only available for Round Trees.

#/Strings

The # of Strings corresponds to the physical number of strings for that model. Typically an arch or a candy cane will have one string, but models such as a mega tree or a matrix will have many strings. This should match the number of controller ports you plan to use.

Nodes/String or Lights/String

The Nodes per String or Lights per String represents the physical number of light nodes, bulbs or pixels in each string of lights. A 8 string tree with 100 Nodes per String would have 800 total lights.

Strands/String

The Strands per String represents the number of "folds" in each string of lights. If the string of lights will go up once and terminate, the Strands per String is 1. If the string will go up once and return to the bottom the Strands per String is 2.

Spiral Wraps

The Spiral Wraps attribute defines many times a strand is wrapped around the tree. 1.0=one full wrap, 2.5 = 2 1/2 wraps from bottom to top. For spiral tree the # of Strings can be set to 1 and then this can be used to "Spiral Wrap" the tree.

Bottom/Top Ratio

The Bottom/Top Ratio determines the angle of the tree strands. A ratio of 6 will have a bottom 6 times larger than the top. A ratio of 1 will create a straight vertical cylinder. This can be used to adjust the cone shape of the tree.

Starting Location

The Starting Location is used to define where the first node starts in a multidimensional model (i.e. a matrix or mega tree). Set to the default value of Bottom Left if running from left to right or Bottom Right if running from right to left.

In this example, a 360 degree Mega Tree visually has 15 strings of 50 pixels on each string, with 2 Strands per String. This will "fold" the strings once causing the tree to be 30 strands wide and have strands of 25 pixels long.

Each string starts from the bottom, goes up to the top of the tree and loops back down. So half the number of physical strings are required.

The first node is in the front bottom left and starts from channel address 9200.

2D Background Image

The Background image to the layout section i.e your house/yard can be set or changed via the Background Image setting section.

Click where indicated and browse to and select the background image. Change the file type if required.

Adjust the width, height and brightness attributes to your preference. The width and height depends on your screen size and resolution. If unsure, start with a .jpg or .bmp image with a resolution of around 1100 * 500 and adjust the width and height for the best fit. The ‘fill’ attribute will scale the image to best fit your window. Click on the Save button to save the Layout settings.

3D Objects

Mesh

In 3D Mode, Meshes/Renders of your house or other object can be added to the Layout. OBJ file type is currently supported. OBJ files normally require a MTL Materials files that also must be put next to the OBJ file. It is recommended to put both files in your show folder and also remove any spaces from the file name.

Click Add OBJ button and Select the Mesh dropdown.

Click the Ellipsis(three dots) Button to select a OBJ file.

Once selected, the OBJ will be displayed in xLights.

Grid

In 3D Mode, Grids can be added to help align models. The grids can be rotated and moved to the desired location.

Pictures

In 3D Mode, Multiple Pictures can be added to the Layout. Images can be placed on the ground and also used as the house backdrop.

Click the Ellipsis(three dots) Button to select a image file.

The file name will appear after a image is selected.

Moving Objects Around

For a single object, you can left click on the object, (it turns yellow) and with the mouse button still held down, drag it around.

To move more than one object around together, press the Control key first and then left click on each object that you want to move as a group (holding down the control key all the time).

Then at the last object, drag to move all the selected objects around together. If you release the Control key at any time, the objects will not move as a group.

Another way is to Hold down shift, draw a box around the models to move, then let go of shift, and hold down alt, then move the group of models.

Aligning Objects

Select a group of objects, right click and select Align (top, bottom etc) to align the selected objects. Which object should they all align to ?

The object you selected first i.e. which will have the blue dots is the key object that others will align to.

When selecting a group, you can press shift, a box opens and you can drag the mouse around the objects to select the group to align.

Sequencer

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:

Layout Previews

You can select which models you wish to see on your Layout Preview. This is done by first selecting the Preview that you want to be active from the Preview selection window.

There are three built in preview options: ‘Default’, ‘All Models’ and ‘Unassigned’. You also have the ability to create new preview windows.

Default

If you only plan on having one preview, which is what most people will have, then this is the one to use.

Select the default ‘Default’ preview which will then display the models where either:

• The Preview attribute against the model definition has been set to ‘Default’.

• The Model is part of a Model Group where the Preview attribute has been set to ‘Default’.

Render Buffer

The Render Buffer is used to generated Effects data onto. For each Model/Group/Submodel, xLights creates a Rectangular Grid to render effects on to. The size of the buffer depends on the model type and settings. 16 strand by 40 pixels Mega Tree will have a 16x40 render buffer.

The Effect is overlaid onto the render buffer to calculate the color data of the individual pixels or lights.

Group Render Buffer

Default Minimal Grid will Draws a 2D grip over the models in the group and attempt to put each pixel in its own box, Up to the Max Grid Size, Normally 400x400.

Model Rendering Low Level Model

Node Range SubModels

This setting allows the user to specify parts of a model to be controlled as if it were its own model. For example, you could defined the horizontal and vertical section of a windows frame.

Click Add to create a new submodel. Then add the nodes that will be included in the submodel. On the right side you will see the model and selected nodes will be highlighted.

On the right side, the model will be displayed with the selected nodes highlighted. If the user clicks the row header(Top or Bottom), the display will highlight only the nodes in the selected row. If the user clicks the "Node Ranges" column header, all the nodes from all the rows will be highlighted.

The Node Ranges 'Grid' represents the submodels render buffer. A grid five row high with five nodes listed per row will create a 5x5 Render buffer.

Empty Commas(,) can be used to create empty spaces in the render buffer. The example below will create 5x5 a outline with a 3x3 'hole' in the middle.

To graphically select the nodes, double click the row header or row cell and select the desired nodes. This option will only populate one row at a time.

Draw Model

To Draw a model, like a Cross, across the whole model click the Draw Model Button.

Click and drag to select nodes(blue highlight). The selected node will turn grey once selected. Double clicking on a node number also toggles between selected and not selected. 'Select All' will select all the nodes. 'Select None' will deselect all the nodes. The 'Ordered Selection' checkbox enables a single select mode that disables 'Click and Drag'(blue highlight) Mode. 'Ordered Selection' is used to select the individual nodes in a specific order to be used by the underlying buffer.

The "From Model" button allows the user to select nodes based on the custom model "shape". For Example, you can import a snowflake model file to overlay it on a matrix.

Hold the 'Ctrl'/'Cmd' Key highlight the cells and press Ctrl+C to copy them. Ctrl+V can then be used to paste the cells. This data can also be copied to and from Excel.

Click Ok to Close the select window.

SubBuffer SubModel

The SubBuffer tab allows the user to select sections of the buffer instead of the nodes. This can be used to divide mega trees/matrices into slices for singing face or individual effects.

Click The Action Button and Select Generate Slices to automatically generate different size slices.

Vertical Slices will create 'count' number of vertical slices that are equal size.

Delete

Delete the currently selected submodel(s).

Copy

Copy the currently selected submodel.

Action

Generate Slices

Select Generate Slices to automatically generate Subbuffer style Submodels.

Flip All SubModels Vertical

This will flip all the node number rows, top to bottom, bottom to top.

Flip All SubModels Horizontial

This will flip all the node number row values, left to right, right to left.

Shift All Nodes in All SubModels

This will Shift all the submodels nodes numbering 1->21, 100->120

Reverse All Nodes in All SubModels

This will reverse all the submodels nodes numbering. 1->100, 100->1.

Import

Import SubModels from Model

This allows the user to 'copy' submodels from another similar model. Example, if multiple mini-trees, are defined in your layout, only create the sub-models on one tree and then use this option to import the sub-models on all the other trees.

Import SubModels from File

This allows the user to 'copy' submodels from a XModel file.

Import Custom Model Overlay

This option will use a custom model file(.xmodel) to create submodels based on X/Y location of the node locations. The height and width of the custom model file must be smaller than the matrix height and width. This will also import the singing face and model state defines.

Export

Export SubModels as CSV

This exports all the submodel definitions as a CSV file for viewer with Excel or other spreadsheet software.

Export SubModel as xModel

This generates a Custom Model xModel file of the currently selected submodel.

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.

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.

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

Zoom in and Zoom out

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.

• Click the edge of an effect, hold down control and use the mouse scroll wheel to go in or out.

Scroll Left/Right

Click on the waveform. Then hold down the Shift key and use the scroll key of the mouse to move the waveform and grid left or right.

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. The FPS value displays the Frames Per Second that the sequence is outputting the data at.

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 will replay the highlighted section of the waveform. It will start from the beginning of the highlighted area and when it reaches the end of the area , will loop back to play from the beginning of that area.

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.

To scroll Left/ Right, click in the grid. Then hold down the Shift key and use the scroll key of the mouse to move the grid left or right.

Audio Scrubbing

Hold the Ctrl key down and placing the mouse on the waveform, click and hold the mouse left button down and and drag it across the waveform.

The audio will be played as you scrub the line. Therefore you can play a small section again and again, backwards and forwards so as to identify a particular note inflection, timing mark or a word of a lyric.

Timeline Tags

Timeline Tags allow the user to create "bookmarks" or "shortcuts" on timeline numbered 0-9. You can then type CTRL + 0-9 to scroll the timeline to the numbered tag's location. To add a timeline tag right-click on the timeline at the desired timing location and select a number 0-9. Numbers with check-marks already have tags placed on the timeline. You can reuse a tag with a check-mark but the previous location will be overwritten.

To delete a timeline tag Right Click on the timeline and Select Delete and then the number of the tag you want to remove.

Editing Preview Layouts

The Preview Window displays the available preview windows, enables you to select a different view and also enables you to create additional Preview Layout windows. To create a new Preview Layout, select the <Create New Preview> option from the window.

Enter the name for the Preview Layout and click Ok.

The new preview window will be created and the image that has been used for the default Preview will be selected.

Click on the Background Image attributes to browse for and select a different image if required. Otherwise, adjust the fill attribute value and the brightness value.

The image size has to be the same as the default image and as such, it is not available to change. Click on the Save button to save it.

The preview window can now be used to create Models or Model Groups against similar to the Default Preview layout. Models can be reassigned to the different Preview by changing the "Preview" Model Setting.

If you wish to delete the preview , right click within the window and click on the ‘Delete this Preview’ option.

When a Preview is Deleted, All the Models currently assigned to it will become unassigned and need to be reassigned to another preview.

When an additional Preview is created, a ‘Previews’ option to select and open it on your sequencer will be available on the View menu. Click on the preview name to open the Preview window. This option is not available if only the Default preview exists.

Layer Blending

The Layer Blending window can be opened by clicking on the Layer Blending icon from the toolbar or via the View , Windows menus.

Reset panel when changing effects

This will reset the Layer Setting back to default every time you select or create a new effect. Checked is the recommended setting for most users.

Layer Blending

The Layer blending settings allows the user to dictate how effects on multiple layers will be merged together for a model/group/submodel.

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

Click the Question Mark(?) Button for more Information.

Morph

This is not to be confused with the Morph Effect. This is a layering option that can be applied to any two effects.

The morph option of layer blending will magically make effect 1 ‘morph’ into effect 2 during the length of the timing cell that the effects are in. You will not see effect 2 at the beginning of the timing cell, and you will not see effect 1 at the end of the timing cell. Somewhere near the middle you will see the effect 1 ‘morph’ into effect 2.

Suppress Effect Until Frame

This will hide the effect for the specified amount of frame and display it when the number of frames is reached. This can be used to "warm up" an effect and hide the undesired beginning frames.

Freeze Effect At Frame

This will pause or stop an effect at the specified frame and hold that frame and display it until the end of the effect.

Transitions

There are 19 layer blending transition choices. Using the transitions will help you bridge between effects providing a way to smooth out abrupt changes between different effects. A stylistic use would be between sections of a song such as the chorus to verse or verse to verse. Keep in mind that the blending is done within the boundary of the timing mark and does not transition between timing marks.

These transitions are common in the video editing world, and should be visually familiar to anyone who’s used video editing software or anyone who’s watched anything on TV in the past 20 years.

If an effect has a transitions applied a green bar will appear for an in transitions and a red bar for an out transitions. If the in and out transitions overlap, the overlap area will appear yellow.

Mix Slider

This slider adjusts the level of each effect in the combined output of the effects. You can use this to just put a hint (or more) of one effect on another.

Canvas

Canvas Mode is a special render mode that only works with specific effects. The default render mode in xLights will draw the effects on a blank buffer for each layer. Canvas Mode allows an effect to draw on a previous layer without "blanking it" out. This is used by effects like the Warp and Kaleidoscope Effect that manipulate data from the underlying layers.

Canvas Layer

This Dialog allows the user which layers to use when Canvas Mode is Enabled

Changing an Effect

Changing Effect Setting

To change an Effects setting, Select the effect in the sequencer timeline and open the Effects setting window using the shortcut in the top toolbar.

Each effect type has specific settings that can be used to manipulate the effect. These setting are specific to the currently selected effects. If multiple effect are selected the Effects setting panel will display the setting of the first effect. The "Update" button will change the settings of all the selected effects to current values used in the Effect Setting Dialog. To updated individual setting across multiple effects use the Bulk Edit option described below.

See the Effects Section for more information on the individual effect settings.

Changing Color Settings

From the Color window, you can change the Colors that apply to the effect, as well as the Sparkles, Brightness and Contrast values. How effects use the colors is defined by the effect.

Moving and Stretching effects

A single effect can be moved about on the sequencer horizontally , by selecting it with the mouse and dragging it left or right. A timing grid must be active. You can also select the effect and use the Left or Right arrow keys to move it left or right. When the effect encounters or is blocked by another effect, if you keep going, it will jump over the effect/effects and continue past.

Similarly an effect can also be moved vertically from one model to another. Use the Up or Down arrow keys to move it up or down. When the effect encounters or is blocked by another effect, if you keep going, it will jump over the effect/effects and continue past.

An effect or group of effects can be moved, by highlighting the effect, or range and moving it along the same model row/rows on the grid forwards or backwards. Hold the Shift key to move multiple effects.

Multiple effects can also be moved by using the Ctrl key. Click on the first effect , then hold down the Ctrl key and click on other effects. Then use the arrow keys (Up , Down , Left , Right) to move the selected effects together in the required direction.

Aligning effects

In order to align several effects to the same start or end times , drag a box around all the effects you want to align and then hold down shift and click the effect you want to be the reference. Then right click and select Alignment. You can then select one of the four options to align to the effect you selected as your reference. In the example below, the Start times of three effects have been aligned to the Start of the Bar effect just below them.

You can even select a timing effect as the reference and it will align to that timing effect.

Copy, Paste, Delete Effects

In order to copy and paste an effect, select the individual effect, right click and then select Copy. Move the cursor to where you want the effect to be copied to, right click and select Paste. You can also press Ctrl+C and Ctrl+V to copy and paste the effect.

In order to copy and paste a range of effects, use the cursor to highlight and select a range of cells. Then copy, followed by paste.

You can paste what is in the buffer (after a Copy) to multiple locations, by moving the cursor to each new location and pasting the copied data (right click and Paste or Ctrl+V) there.

There are two modes for Copying and Pasting effects: Paste by Time or Paste by Cell.

You can select, or change the mode by clicking on one of the two icons.

Paste by Time is the most common option. You do not need to have a timing track active . You copy the required section and paste at the required location. The copy works on copying effects and not copying grid locations. Therefore it will copy the first effect from with the range highlighted, and accordingly will paste that effect (and others after it that were selected) at the grid location when Paste is selected.

Paste by Cell works using timing tracks. A timing track must be active when you copy, so that the cells to be copied can be determined from the active timing track. You can use this option to copy timings/timing data (such as the phonemes used for singing faces).

Examples

1. You copy a single effect, select a target cell and hit Paste with Paste by Time mode. The result is the effect is pasted with the original duration. So if the original duration was 2 seconds , then two seconds duration will be pasted in the target irrespective of the length of the cells..

2. You copy a single effect, select a target cell and hit Paste with Paste by Cell mode. The result is the effect is pasted to fit within the target selected cell based on a %.

If it was 100% of the source cell, then the full target cell will be covered.

If it was 50% of the source cell, then 50% of the target will be selected.

You can delete an effect, by selecting the effect in the grid and pressing delete on your keyboard or pressing Ctrl+X.

Right Click Options

Model - Copy

You can copy the effects of an entire model/group and paste it to another model/group.

Highlight the model name, right click and select Model, Copy Effects to copy the entire row of the effects.

Model - Paste

Then select the model name header you want to paste the effects (in the same sequence or another sequence), right click against the model name and select Model -> Paste Effects. The data copied remains in the clipboard buffer. The Paste operation does not have to be immediately after the Copy operation.

Row - Copy

You can copy the effects of an entire row/layer and paste it to another row/layer.

Highlight the row/layer header, right click and select Row, Copy Effects to copy the entire row of the effects.

Row - Paste

You then paste the effects from the entire row/layer by right clicking on the row header and selecting Row, Paste Effects

Undo Effect

Many, but not all effect actions can be ‘Undone’ by right clicking on the Grid and selecting the Undo action i.e. Undo effect move or Undo delete.. etc

You can also use the shortcut key of Ctrl+Z. The Undo actions can be daisy changed i.e. they can be repeated one after another.

Selecting Multiple Effects

In order to select a group of effects, use the left mouse key to select the range of effects. The color of the cells change, but also, the links in the selected cells will turn to magenta.

You can only select a group of cells, when the cursor looks like a pointing hand.

If two arrows are shown, then you can’t select the cells. You may need to zoom in to be able to see and select the required effects.

Bulk Edit

After selecting multiple effects, the user can change an individual setting across all the selecting effects. Right Click on the effects setting to change and select Bulk Edit.

A separate window will appear, allowing the user to change the setting.

After Clicking OK, all the selected effects will be changed to the new setting value.

Create Random Effects

Select and highlight an area on the effects grid. Right click and select the "Create Random effects" option. Effects will be randomly selected (along with different colors and options) and created in the area highlighted, each between consecutive timing marks. If no timing marks are active, then a default time length will be used for each effect. Use the shortcut key ‘R’ to achieve the same result by highlighting one or more cells and pressing 'R' on the keyboard. The Effects used by Create Random Effects can be set in the File->Preferences Menu under the "Random Effects" Tab.

Timing Tracks

xLights 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 File, Sequence Settings, Timing menu.

Clicking on the down arrow will provide a drop down list of timing intervals to select from to create a timing track. Other than the first three, the remaining are from the VAMP plugins. If you have not installed the plugins then they will not appear in the list.

You can also import a Timing track that has been created externally. Click on the Import button instead of the New button. A window Chose Timing files(s) window will open, enabling you to browse for and select the timing file to be imported. Navigate to the .txt file containing the timing track and click OK to import it. The new timing track can be a lyric track with phrases and words broke down into phenoms.

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

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.

• You can rename a timing track , by right clicking on the timing track name and then providing a new name in the window that gets displayed.

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. This is equivalent to what is called a 'tapper' function.

You can also have xLights create fixed timing interval timing tracks by selecting the Metronome timing option and then choosing the timing interval.

Fixed Timing Tracks

When xLights created a Metronome timing it is generated as a Fixed Timing Tracks. Fixed Timing Tracks are not editable and the timing marks cannot be changed. Fixed timing tracks are colored orange in the sequence tab by default.

To edit a Fixed timing track the user must right click and select Make Timing Track Variable.

Adding/Removing Timing Track

While on the sequencer tab, you can add new timing tracks or delete an existing timing track at any time.

Right Click , with your cursor in the area of the timing track names and select Add Timing Track or Delete Timing Track.

Importing Timing Track

You can also import timing marks created externally (the most common being those created via Audacity or another xLights sequence).

This capability includes importing a Singing Face (xLights Papagayo) timing track.

In order to import a timing track, right click the Timing names area, then select Import Timing Track, navigate to the .txt ,PGO, LMS, LOR, LSP, .xml, or .xtiming file containing the timing track and click OK to import it.

The timing tracks from the specified file are imported as xLights timing tracks - the following is an example of one that has been imported from LSP.

Importing of a PGO timing track is covered elsewhere in the document.

Exporting Timing Track

Similarly to export a timing track, right click on the timing track name in the Timing names area, and save as as .xtiming file.

This capability includes exporting a singing face (xLights Papagayo) timing track.

You can export the file as a PGO file , if you wish to provide the file for use in another type of sequencer (LOR ). If you wish to use this in for another xLights sequencer , then export as an XTIMING file.

Multiple timing tracks can be exported to a single XTIMING file by selected them from the following dialog.

Import Notes

The purpose of this function is to create a timing track by importing the notes from an external source such as a MIDI file, from an externally generated source such as Audacity or from a music XML file.

Right Click on the Timing Track name and select Import Notes.

Specify a name for the Timing Track to be created , the Notes Source, and then navigate to and select the file from which the notes are to be Import.

Click OK and the Timing track will be created from the notes.

Once the timing track that has been created , it can be edited or adjusted if required.

Subsequently , when when using the Piano effect , specify the Timing Track that has been created as the Notes source.

Render All

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

Rendering order

The Data Layer order renders from the 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 from the 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.

This is important to keep in mind when you have multiple models or model groups mapped to the same channels such as whole house model group and regular models.

Changing Color Settings

From the Color window, you can change the Colors that apply to the effect, as well as the Sparkles, Brightness and Contrast values. How effects use the colors is defined by the effect. Some support just one, some support up to 8.

The 'Update' button will apply the current colors palettes to all the selected effects.

Use the Sparkles slider to increase the sparkles for the effect. If the Sparkles reflect music option is selected, then the sparkles will increase from the selected value based on the intensity of the music. The Sparkles color can be changed with the color picker on the right side.

Use the Brightness slider to increase or decrease the brightness of the effect.

You can open/close the Color Window by Clicking on the Effect Colors icon in the toolbar.

Changing Colors

To change the colors used by an effect, select the effect, and double click the color that needs to be modified.

The Color Manager Dialog allows the use to then select a different color.

The user can create custom colors by clicking "Define Custom Colors" and manually adjusting the RGB color settings.

For any effect, you can change the initial colors selected for the effect by selecting a different color or colors from the Color Window. You can use the Control key and select multiple effects.

Once you select all the effects and change the color , hit the 'Update' button in the color panel. It will modify just the colors for all selected effects.

Color Palettes

The Save button allows the user to save the current selected color for future use as a color palette. These color palette files are stored in the current show folder.

The Drop-Down allows the user to select the previously saved color palette stored in the show folder.

The update button will save any pending changes to the currently selected color palette file. Delete will delete the selected color palette file. If the user hovers over the color palette, the file name will appear.

Color Curves

This functionally enables a color to change within an effect duration I.E. where previously the same color value would have been displayed for a particular segment duration it can now be made to change within that segment duration.

As an example, drop a Bars effect against a model on the grid.

After selecting the required colors (white, red and green in this example), right click on the first color .

The Color Curves window is displayed.

The window representing the Color curve is black in color.

Double click on the mark (which turns yellow to indicate it has been selected) and from the resulting Palette window select a color (White).

Move the marker to the far left. Then click within the White Color curve window. This creates another mark , Double click on that mark and select Blue as a Color.

You now have a color effect that starts White and Turns blue over the duration of the effect.

You can adjust the markers to control where the color changes.

You can have up to 40 different color changes.

The Blend Mode can be set to Gradient or None (sharp change).

For effects that have the Platte color option (such as the Butterfly), the Palette must be selected for the colors to come into play.

You can select any one of the color curves present just below the Blend Mode attribute by clicking on it.

The color curve values will be copied into the window just above and you can then use the markers to adjust the color.

To can export a color curve by clicking on the Export button. You will be prompted to specify a name for the Color curve and a .xcc file of the specified name will be created in the location specified.

Similarly you can load a previously exported color curve file by clicking on the load button and then navigating to the location of a .xcc file and selecting it.

Types of Color Curves

Color curves can be timed based or spatial based. A timed based color curve will change color over the duration of the effect, while a spatial color curve will change over the models X/Y location. A spatial color curve has direction. The icon below the color specified what type of color curve is selected. Click the icon to change the color curve type. A clock is a time based and an arrow is used for a spatial color curve. The Direction of the arrow represents the direction of the spatial color curve.

This functionality works on most effects but not all. For example – it is not applicable to effects such as DMX, Faces, Fire, Glediator, Pictures, State and Video.

Single Channel Colors

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.

Sequencer Windows

There are several windows that are used to select different properties, setting, or views when using the sequencer tab.

To select additional Windows, click on View/Windows and select the window to have displayed. If the window is already open, selecting it will close the window.

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. The Windows are described in the View, Windows section.

Select the Dock All option to reset the Windows perspectives and dock all the windows to your current setup.

This is sometimes required if you are using an xLights_rgbeffects file that has been saved with a different default perspective e.g. two monitors and that set-up is not present in your current environment.

The Reset to Defaults options used to reset the Toolbars. This will take effect when you next start xLights.

You must Save these settings for it to take effect - you will be prompted to save when quitting xLights.

Adding an Effect

Click on the effect from the effects toolbar and drag the effect to the grid and release it between two timing marks on the row of the model you wish the effect to play on. You can then select and drag each end to stretch the duration of the effect or reduce the duration of the effect. The effect that you are working with is reflected in the (associated and open) windows to the left of the grid.

If no timing track is selected then you can drag and drop even if you have no timing marks but the effect defaults to 1 second long.

Value Curves

The Value Curves functionality effectively changes the way an “effect” or setting works over time in a nonlinear fashion, based on the type of Value Curve selected and other parameters off the curve. This is best explained via an example.

Consider the Bars effect. It has two attributes ‘Palette Rep’ and ‘Cycles’ that can be linearly adjusted using the sliders. They are currently set to 5 and 3 respectively. This means that the palette will repeat 5 times over the duration of the effect and the effect will cycle through three times. Both will be applied evenly across the duration.

However, if you click on the Value Curve icon for either of these attributes, you will be presented with options to change how these repetitions are applied.

The Flat option is the same as the default linear option. The level can be used to adjust the intensity.

The other sliders are labelled ‘N/A’ as they are not applicable to the context and type of Value Curve thats is being used.

In other scenarios, Value Curves and for other effects, different sliders are available.

Click on the drop down link and a number of options are presented.

Select the Ramp Value curve. As the image indicates, this will cause the selected attribute (say Palette Reps), to increase (ramp up) over time, starting from 20% and ending at 80%. Note that the Start level and End level sliders are now active.

Another type of Value Curve is the Sawtooth variation. The selected attribute to which this is being applied (palette reps) will increase and decrease twice (controlled by the Cycles selected) from a start level to and End level.

Custom Value Curves can also be created. Select the Custom option from the drop-down. You can then click on the waveform to add new points and drag them as necessary.

Load and Export

Value curves can be loaded and exported as a .XVC file. By default, the files will be loaded and previewed if they are in the 'valuecurves' folder automatically created in the current show folder.

Layers

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 blended with the layer below it for a combination of thousands possibilities within a single timing cell.

Layers on a model are 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 Mega Tree that look like interleaving fingers for example.

Combining two spirals in opposing directions on a mega tree 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).

Layers can also be added at the Strand level.

The Poly Line model defines each segment as a Strand and the layer functionality can then be applied separately to each strand.

To add layers at the strand level, click on the Model name in the sequencer to display the Strand names. Then right click on the strand name and choose Add Layer above or below the selected strand.

The strands blend onto the model level effects.

Layer Settings

The Layer Settings window can be opened by clicking on the Layer Settings icon from the toolbar, or via the View, Windows menu.

Reset panel when changing effects

This will reset the Layer Setting back to default every time you select or create a new effect. Checked is the recommended setting for most users.

Buffer

Render Style

This attribute controls how the buffer is laid out for a model or model group when the effect is rendered. Every model has a ‘Default’ buffer which can be view by opening the model's node layout in the Layout Tab.

For example, for Arches – the default buffer treats each arch as a single line and stacks the arches on top of eachother, for a Star model, the default is a square grid that cases effects to chase across the face of a star.

Additional options are available to change the buffer representation for the model or group. The list of values that are selectable are dynamic depending on the type of model.

For model groups, additional buffer render styles are available. The list below discrips all model render styles.

Camera

When using the "Per Preview" render style, this dropdown allows the user to select which viewpoint to use. 2D is the default.

Transformation

The transformation attributes can be used to rotate the effect clockwise, counter clockwise (90 or 180 degrees) or to flip it either horizontally or vertically.

Blur

This attribute will cause the effect to ‘blur’ i.e. the colors become less distinct (hazy) and the edges of two colors will fade into each other i.e. will not have sharp edges. The level of haziness can be increased from 0 onwards using the slider or adjusted using the Value Curve functionality by clicking on the Value Curve icon.

Sub Buffer Selection

The Sub Buffer selection can be used to limit the area that an effect is active. This basically redefines the size of the model/group (on a per effect basis). This option is different than masking, because the entire effect is rendered based on this new model size, whereas a mask covers up what you specify.

So if you only want the effect to be on the top half of the model or group, bring the bottom part of the dotted yellow line to the middle of the black box. The ‘handles’ of the yellow grid are in the corners. Double Clicking will reset the defaults to the full size.

As an example, drop the Fire effect on a Model Group covering your ‘whole house’.

Then adjust the yellow dotted lines of the box inwards and look at the effect it has on your house preview. You can limit the effect to say the left side of your house, with another similar one of a different color on the right side of the house applied on another layer.

Persistent

The Persistent option when enabled does not clear the display buffer before rendering each frame. The result is the preview frame remains until overwritten by a subsequent frame. For example, drop the balls or fan effect on a model, select the blending to “Effect 1”, then toggle Persistent on/off. You will see a huge difference. Doing the same for a “Chase” effect also results in a very different look.

The term came from high persistence scopes where each trace just kept layering on top of previous traces.

Roto-Zoom

The Roto-Zoom functionality enables the effect to be Rotated as well as have aspects of the effect Zoomed.

The Preset defines the type of rotation to be applied to the effect. The effect can be continuously rotated clockwise or counterclockwise, made to explode outwards , implode inwards , shake etc.

The Rotation attribute changes the orientation of the effect. The attribute cannot be used if a Rotation Preset has been selected.

The Pivot Point attributes work if the Rotation attribute has been used by moving the point at which the effect rotates along the other axes.

The Zoom attribute increases the size of the effect - for a Text effect - the text will be made larger. The Zoom quality increase or decreases the pixels when the zoom attribute is used. These two attributes cannot be used if a Zoom (i.e. explode or implode ) Preset has been selected.

Application Order specifies which order to apply the rotation in.

Models

Play

If the Model Preview window is open, you can play the model effects in the window by right clicking to the left of the sequencer grid and selecting Play Model. The sequencer will start playing and the effects in this window will focus on the selected window.

You can also achieve the same result by clicking on an effect against the model in the grid and then selecting Play.

Export Model / Render and Export

This function is used if you wish to export effects from your model to another sequencer, such as LOR, LSP, Vixen, HLS. It can also be used to export an eseq (effect sequence) to the Raspberry Pi Falcon Player (FPP). Effect files are .fseq format files with an .eseq extension. These special sequence files contain only the channels for a specific effect and always start at channel 1 in the sequence file. The actual starting channel offset for the Effect is specified when you run it or configure the Effect in an Event on the FPP.

Right click to the left of the sequencer grid and select Export Model or Render and Export Model.

‘Render and Export’ renders the model to a clean buffer and thus would ONLY contain the data from the effects on that model.

‘Export Model’ could include data from other sources that may affect the model such as data layers, model groups, overlapping models.

You will then be presented with a window where you can select the target sequencer type and the filename to be created. Press OK when done.

Status messages will be displayed on the last line of your sequencer as the model is exported. The file will be created in your show directory.

Model Export as Video

You can export your effects as a video avi file. It is limited to matrices, trees and custom models. It generates a low res video which can be used in the video effect or in other sequencers. Right click against the Model name on the sequencer grid, select Export Sequence and then select either Compressed video or Uncompressed video. Enter the filename and press Ok. The avi file will be created in your show directory.

Toggle Strands and Nodes

From the sequencer grid view, right click on a model name, and click on the Toggle Strands option, to display all strands for the model.

With the strands view open (i.e. displayed), right click on a strand to either toggle the strands closed or to Toggle Nodes and display the nodes for a strand.

This is often useful to see how a particular effect has been rendered down to the node level.

On the left column of the sequencer tab, Model Groups have a symbol after the name that distinguishes them from Models.

Pixel Editor (Matrix Drawing Tool)

You can use the Matrix drawing tools to amend a picture or draw your own pictures or animations. Click on the Picture effect within the sequence grid that contains your effect and then open the Effect Assist window if it is not already open. You will be presented with a window similar to the following i.e. the picture of your effect is copied to a grid.

The Matrix Drawing Tool has 8 windows, each with a color and a radio button under the color to show you which color is selected. You can change the color assigned to each window, change the saturation, hue, brightness, change the RGB setting etc.

Select the pencil tool and after selecting a color, use the left mouse button to draw and fill in the selected color or use the right mouse button to erase what has been drawn. The eraser can be used to remove colors on the grid.

New Image

Click on New Image to create a new image. The first time you use this function, you will be prompted for a directory to store the image files in. As an example, create an ‘image’ subdirectory within your show directory.

You will be presented with an empty grid and you can then draw/paint your effect within the grid. Click on Save image and name the image. The model window will display the model just drawn. (The model won’t be updated until the file is saved).

Load Image

Load Image is used to load a previously saved image or any other supported image. If the picture loaded is not as per the model scale, you won’t be able to edit it.

Save As

Save As can be used to save an effect to a new name.

Copy / Paste

Highlight the area that you wish to copy, press Ctrl C to copy to the clipboard buffer, move to the area that you wish and press Ctrl V to paste it.

File

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

Create a new sequence, either a musical or animation. See New Sequence Page for more information

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. Select the required xLights (XSQ or XML) sequence file to open. You can also select the FSEQ file and it will open the XSQ or XML file referenced within.

To open a recently used sequence, select any item from this list.

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. checked) 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 with a progress bar indicating the render progress.

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.

If you click on the green progress bar, a window opens and you can see the render progress of each model / model group.

One line is displayed for each model or Model group that is being rendered.

You can stretch and expand the window to see all the models.

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. checked) 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.

Click on Save Changes if you want to save your changes. If you click Cancel then you will be returned to the sequence. If you select and click Discard Changes, then the sequence will be closed without any sequence changes being saved.

Preferences

The Preferences Dialog allows the user to set all the global settings in xLights. These settings are stored in the system register and are persistent between show folders.

Sequence Setting

The Sequence Settings Dialog allows the user to edit all the settings for the currently open sequence. See Sequence Settings page for more information.

Key bindings

The Key bindings Dialog allows the user to manually edit the keyboards shortcuts in xLights.

Export House Preview Video

The Export House Preview Video feature will "Play" the loaded sequence and create a video file of the House Preview Window. The video resolution of the resulting file is based on House Preview size. It is recommended you make the House Preview Window as large as possible before selecting this option.

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 XML files (xlights_keybindings.xml, xlights_networks.xml and xlights_rgbeffects.xml) in your new directory.

This option will display a list of previously selected show directories. If you select any of the items listed, your show directory will be changed to the selected directory.

Backup

The Backup Menu item allows you to manually trigger a backup of the show folder.

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.

Restore Backup

The Restore Backup dialog enables the user to select the backup folder recover files stored in the backup folder. The right list display basic data about the files found in the selected backup folder.

The left list displays the available backup folders, the middle list displays the files to restore. The right list display basic data about the files found in the selected backup folder.

Alternate Backup

The Alternate Backup function enables you to specify and use a different location to back your files up, other than the default location that the F10 backup functionality provides for.

Press F11 or select this function from the File menu. The first time you use this function, you will be prompted for the location that you wish to back the files to. Navigate to the required location and select the folder. The prompts after that are similar to the Backup functions.

Subsequently, Pressing F11 will save the files to the specified location. You can change this location via the Settings, Alt Backup Location menu.

Quit

To quit xLights, 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 the Save Sequence Dialog.

Shortcuts

There are a number of shortcut keys that can be used for functionality or adding effects on the grid. These effects are stored in the xlights_keybindings.xml file and can be modified by the user. Note that you must edit this file while xLights is NOT running. Changes will be lost when xLights closes as this file is saved upon exit each time.

Views

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 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.

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.

To Create a new View , click on the Add button, enter a unique name in the window and Click OK.

To delete an existing view , highlight the view from the View window and select Delete.

New models can be added to a view by first selecting that view from the Views list on the right, then second select the Available Model on the Left and third clicking on Right Arrow Button.

Similarly models can be removed from a View by highlighting the model in the Model window on the right and clicking on Left Arrow Button..

The position that the model appears within the view can be changed by highlighting the model and clicking on Up or Down Arrow.

The Double Left and Right Arrows will Add or Remove All the Models in either list.

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.

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

User Dictionary File Location

The standard_library and extended_library are built-in dictionaries which contain information that assist xLights in converting each word into phonemes. Each word in the dictionary is listed with its associated phonemes. As xLights proceeds with the breakdown process there may occasionally be a word that it cannot find in these dictionary files. When this happens there is a simple process to add that word to the user_dictionary.

When xLights is first installed, this file is located in this folder: C:\Program Files\xLights\ This folder is the default folder that xLights is installed into. This can change if you decide to install xLights somewhere else.

To keep this file from being overwritten in future installs you should move the user_dictionary file to the folder where you store your sequences.

The user_dictionary can be moved to the Show Directory and xLights will read it from there. If you do this xLights will load the user_dictionary in the show directory and skip the user_dictionary in Program Files.

Editing the User Dictionary

The user_dictionary is a simple text file which can be edited by using a text editor such as windows notepad or any other text editor, such as Notepad++, to open this file. This is only dictionary file that you should make any additions to because the other two files will be overwritten each time xLights is installed. When you first open the user_dictionary file it will contain the information shown below.

Before continuing, create a text file containing all the words that xLights did not have an associated phoneme breakdown created. Name this something easily identifiable, such as ‘missing words.txt’ and put it in the same folder as the sequences. There is no special formatting, just a list of words, one per line, is required. One thing to note here is that if you have any hyphenated words such as ‘screa-um’ you should break the word into two words such as ‘screa’ and ‘um’’ for this list.

Then click the ‘'Choose File' button and browse to find the file you created or enter this name into the file box.

Then click the 'Compile' button.

Once the processing has completed another web page will appear similar to this:

Click the work 'link'

Another web page similar to this will appear.

Here click the file with the .dict extension such as 0548.dict, then a web page will appear with the words and their phoneme breakdown as shown below.

Before following the rest of this process, close the current sequence and exit xLights.

If your user_dictionary is not open, open it now. Highlight and copy this list and paste it into your open user_dictionary and save the newly modified file. There is a small bug in xLights at the time this document was written which you need to compensate for. After pasting in the newly added words do a search and replace with a ‘ ‘ (space) for any ‘tab’ characters in the user_dictionary. Between the "word" and the "phonemes" requires two spaces (' ') and one space(' ') is required between phonemes.

This process will work for one to how ever many words that you have. But if you just want to quickly check one word past the following link into your browser.

This is the online CMU Pronouncing Dictionary. Here you will look up each word that Papagayo did not find in its dictionaries. Let’s take the first word 'ooky'. There is a box below the title ‘Look up the pronunciation for a word or a sentence in CMUdict (v. 0.7a)’ where you will enter this word. Then click the 'Pronounce it!’ button. If a red dot appears with the phrase ‘not in dictionary; consider using the LOGIOS tool discussed above, which is able to generate missing pronunciations by rule.’ Then you need to click the ‘LOGIOS’ link which takes you to the previously discussed web page.

Now that you have updated the user dictionary you should reopen xLights and load the previously saved sequence and find the newly added dictionary words and do a right click ‘Breakdown Word’ for the missing phonemes. The image now shows the results after adding the word ‘honkey’ to the user_dictionary file.

Singing Faces

This section describes how Singing Face functionality i.e. the conversion of phrases from song lyrics or sentences spoken out aloud can be converted to work on Coro faces or Images on a matrix or Mega tree natively in xLights i.e. without using the Papagayo application.

Face Definition

In the model layout tab, select the singing face model, then click on the ellipsis (three dots) button on the Faces property.

The 'Name' dropdown specified the currently selected Face Definition. If the dropdown is empty, then no Face Definition exist for the current model.

Click 'Add' to create a new Face Definition.

'Delete' will delete the current selected Face Definition.

Click the ellipsis (three dots) to copy, rename or import a face definition.

The drop down box below the 'Name' selector is used to select the type of face definition. There are three types of face definition.

Single Node

For each phoneme, select the channels that will be turned on. Multiple selections can be selected, by holding down the CTRL key.

If force custom colors is selected, then a specific color to be turned on by default. This can be specified for each phenom/row by double clicking in the color column to bring up the color palette.

Node Ranges

If ‘Node Ranges’ is selected, then the following window will be displayed.

Type in the list of node numbers (pixel numbers) for what should be turned for each movement. Example: ("1-12,24-30"). Double click the Nodes Column or Phenom Name to bring up the Node Select Dialog.

Click and drag to select the desired nodes for the selected phenom definition.

Click Ok when done selecting the nodes for the current phenom name/row.

There is a right clicked menu that allows the user to import node numbers from a predefined submodel.

If force custom colors is selected, then a specific color to be turned on by default. This can be specified for each phenom/row by double clicking in the color column to bring up the color palette.

Matrix

If a matrix is selected, then the following window will be displayed.

Then for each mouth position, double click in the eyes open column (you may need to double click more than once) and navigate to and select the face image corresponding to that mouth position. You can specify different images for the Eyes Closed position or by default, the same image is copied across.

The 'Download Images' button will display a list of user submitted singing faces images. Select the 'Insert Face' to download the pictures files to 'DownloadedFaces' folder in the show folder. This will also populate the face definitions in the main dialog.

Then select the image placement i.e. Centered or Scaled. 'Center' with display the image in the center of the matrix. If the image resolution is greater than the matrix resolution, xLights will down scale the image to the matrix resolution. 'Scaled' will upscale the X and Y resolution of the image separately to the matrix resolution.

Timing Tracks

Next add a new Timing track. Right Click on the Row Heading and Select Add Timing Track

Select a Timing Track of type ‘Empty’ and click on OK to add it.

Right click on the name of the timing track and Select Rename Timing Track. Change it to something meaningful, such as ‘Lyrics’ or 'Main Vocals'.

If you have more than one Voice, then repeat this process for the second Voice.

Importing Phrases

Phrases/Lyrics for Voice 1

Select the Timing Track (‘Lyrics’) and for clarity deselect any others. There are two ways to add the phrases/lyrics to the Timing Track.

1. Importing the entire set of Lyrics. Obtain the lyrics from the internet or elsewhere, copy them, then Right click and select ‘Import Lyrics’.

2. Type or paste the lyrics into the Window and press OK. The words of the lyrics will be evenly distributed across the song.

Using timing marks

Play through the song at regular or reduced speed and use the ‘t’ key to add timing marks at the beginning of each phrase. Then on the timing track, between two timing marks, double click or shift double click (this is set by your preference dialog settings) and an ‘Edit label’ box will pop up. Type in, or copy and paste the words that pertain to the selected phrase (or phrases) that belong between the two timing marks. Press Ok to accept.

Repeat for as many phrases as you require or you can do one phrase at a time.

Breakdown Phrases

You can break down all the phrases into words by right clicking on the timing track to the left of the Papagayo icon and selecting the Breakdown Phrases option. This will breakdown all the phrases into words or you can do this in sections i.e. Highlight a phrase or group of phrases, right click and accept the Breakdown Phrase option.

A list of words will be generated for the phrase in a timing track, just below the phrase.

Breakdown Words

You can break down all the words into phonemes by right clicking on the Timing Track to the left of the Papagayo icon and selecting the Breakdown Words option. This will breakdown all the words into phonemes or you can do this in sections ie: highlight a group of words, right click and accept the Breakdown Word or Breakdown Selected Words option. If the Breakdown Selected Words option does not appear, ensure that your cursor is not pointing on a word, otherwise you may only see the Breakdown Word option.

A list of phonemes will be generated for the word or words phrase in a timing track, just below the word timing track.

Zoom in to see the words or phonemes more clearly. Drag the words to align them as required.

You also need to separately drag the phonemes to align them as required.

If you wish to regenerate a word or words, highlight the words, right click and select Breakdown Word or Breakdown Selected Words option.

Select and drag the Face effect to the sequence grid against the model (your Singing face model).

Using the Effects Setting window, under Mouth Movements, select the applicable Timing Track (‘Lyrics’). The face definition value will default to the one defined for the model.

You can also select ‘Show Outline’ which will activate the outline when the face effect is present and ‘Turn On/Off Eyes’, if you wish. Setting the eyes to Auto will cause the eyes to blink every few seconds when the rest phenome is on.

The timings should automatically appear against each mouth movement.

Repeat the process for the next phrase or group of phrases.

Phrases / Lyrics for Voice 2

Similarly, repeat for the next Voice by selecting another model (‘Singing Face 2’), and the next Timing Track (‘Lyrics 2’). When you drop the Face effect on the sequence grid, select the second timing track (‘Lyrics 2’) as the Timing Track on the Effects option and proceed as described for Voice.

Checking for Unknown words in the dictionary

This step will help eliminate any words that xLights may not have in its library.

As you breakdown words in xLights, occasionally you may see that there is no phonetic breakdown of the word placed in the timing track. As shown below.

As you can see there is no pink phonemes below the work ‘honkey’. This means that the word is not in the xLights work dictionary. To manually add word breakdowns, Use the User Library Dialog located in the Tools Menu.

Importing Papagayo files

This section describes how you can import a Papagayo (.PGO) file into xLights as a timing track, so as to integrate it with xLights functionality and accordingly be able to edit and adjust it.

On the sequencer tab , after creating a new musical sequence or opening an existing musical sequence, right click on the Timing name and select Import Timing Track. Browse to the location of the Papagayo pgo file and select the file.

Specify the number of frames to offset the data by. Due to a performance limitation in the Papagayo software, a sequence often had to be broken up into segments. In which case the second segment had to be offset by the number of frames of the first segment.

For the first segment being imported the offset is zero. Click on OK.

The Phrases, words and phonemes are imported and a timing track with the three components is created for each Voice contained in the PGO file. The phrases, words and phonemes can then be edited, moved and adjusted similar to one that had been created within xLights.

The following image shows a snippet of what the file contains. The 4th line contains the total number of frames and the 5th line has the number of Voices in the file, followed by the details for each voice.

Backup

Backup On Save

With this setting activated, xLights will perform an backup (similar to a user pressing F10 to manually backup) each time the sequence is saved - when the user clicks on Save or Save As.

The existing files, including the saved sequence XSQ, will be backed up to the Backup folder in your show directory prior to the render executing and FSEQ file being created.

Backup On Launch

With this setting activated, xLights will perform an backup (similar to a user pressing F10 to manually backup) each time xLights is launched. The existing files will be backed up to the Backup folder in your show directory, prior to the application launching and updating any xLights files when it is launched. The Backup sub directory created will have a suffix of ‘_OnStart’ added to the folder name.

Backup Subfolders

When selected, backups are made of all relevant files both in the show directory as well as any sub-directories (excluding the backup folder itself).

Purge Backups Older Than

This drop-down sets how long xLights will keep backup. With "Never" selected xLights will not delete any backups. 365, 90, 31, and 7 days will delete backup folder older than the selected length. This helps to clear out older files and free up space.

Backup Directory

This defines the location where the backup folder(Backup on Save/Launch or F10) will be saved. If the 'Use Show Folder' Checkbox is selected (the default) the backup files will be saved in the current show folder. If this is unchecked and a folder path is specified all the backup files will be saved to that location. If this folder doesn't exist (move computers or remove a harddrive) the backup directory will default back to the show directory.

Alternative Backup Directory

This is the location where the Alternative backups will be saved. This is manually triggered with F11 or the File Menu option. This Backup function is intended as a secondary backup location, like a external hardrive or NAS device. By default the location is not set and will prompt you if you attempt to do a Alternative Backup and no folder is set. To enable, set the desired folder or drive location.