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.

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.

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

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.

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

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.

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

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"

Saving the Sequence

Click on the Save or Save As icon to save the sequence.

Since this is the first time that the sequence is being saved, the Save As dialogue box opens for a file name to be provided. If saving an audio sequence the filename field will be prepopulated with the Audio file name as the sequence name.

Provide a name and then click Save.

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.

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.

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.