You bought a sequence because you liked how it looked. Now the job is to make those effects work on your display. Your house, prop arrangement and pixel counts can be different from the vendor's preview, so a good import needs a little planning.
We recommend starting with one song, keeping a working backup and mapping the important parts first. Get a solid result, then refine it. You do not need to make every unfamiliar effect land perfectly on the first attempt.
Check what came with the sequence
Read the vendor's requirements and use the intended version of the music with permission for your use. A radio edit, live recording or different introduction can change the timing. Keep the supplied sequence, model information and required images or other assets together in their own folder.
Know which file does what. A .xmodel describes a model. An .xsq contains editable sequence work. An .fseq contains rendered playback data. Downloading a prop model does not also download a song's effects. The xLights glossary explains the file types.
Check the selected audio in Sequence Settings before adjusting timing. Solve a wrong-media problem at the media selection first.
Protect your working layout
Save the current show and back it up, including media and other required assets. Review the backup preferences so you know which folders are included.
Keep the vendor's files separate from your live configuration. If you open the vendor layout to study its preview, turn output to lights off and use a separate show folder. Return to your own show folder before importing or uploading anything. The File menu documentation covers switching folders.
The vendor's controller IP addresses and port assignments describe the vendor's setup. Do not upload them to your controllers just to make an import look complete.
Make your destination models accurate
Start with the correct model for each physical prop. Use our CoroWorks model downloads when building your Mattos layout, then check the pixel path, orientation and controller assignment.
A whole-prop effect on a CoroWorks Santa has a different canvas from an arch or matrix. The import can move effects between models, but the shape and render settings still affect what you see. If the prop is filled with EVO pixels, that hardware choice still needs its own power and controller setup; it does not decide which vendor model belongs on Santa.
Plan the mapping by visual job
Watch the source preview and identify the jobs you want to preserve: outlines sweeping across the house, a repeated beat on smaller props, or a featured character. Then choose destinations that can perform those jobs in your yard.
| Source element | Possible destination | Check before accepting it |
|---|---|---|
| Roofline or window outlines | Your corresponding outline models | Left-to-right order and effect direction. |
| A repeated group of small props | A suitable group in your display | Group membership, spacing and rendering style. |
| Whole-prop color effects | A chosen coro character or other prop | Whether movement still reads clearly on that shape. |
| Singing-face effects | A model with the required face definitions | Face configuration, timing tracks and supported features. |
Leave room for a deliberate choice when you do not own an equivalent prop. A simpler effect that suits your display is more useful than forcing every source element onto an unrelated shape.
Import into your sequence and save the map
In your own show folder, create or open the destination sequence and choose a view containing the models and groups you want to use. Select Import > Import Effects, choose the source sequence or supported package, and review the mapping window.
Match source models or groups from the Available list to the intended rows in your layout. Select the timing tracks you need. Save the mapping as an .xmap before completing the import so it can be reused and reviewed for later sequences from that source layout. Follow the official Import Effects guide for your version's controls.
Render, watch and fix one problem at a time
Run Render All and watch the destination preview. If a group effect looks compressed or appears on the wrong props, inspect group membership and layout settings. If effects unexpectedly cover one another, inspect the render order and relevant layers.
Run Check Sequence, resolve errors and review warnings. Then test a short section on the actual lights. Save the finished sequence, render the current playback file and use our FPP transfer checklist if that is your player.
If you want help with this part, we offer xLights Sequence Input Mapping. Review the service details and send your layout, sequence information and the problem you want solved. The goal is a sequence that makes sense on your display.
Keep learning in the Mattos Designs Learning Center, with guides for your next project and troubleshooting help when you need it.
Reviewed October 29, 2026.
A practical example: their four arches, your two arches
Imagine the purchased preview has four arches, six snowflakes and a large tree. Your display has two arches, a window group and a CoroWorks Snowman. Make a small mapping plan before importing:
Scroll sideways to see all columns.
| Source job | Your planned destination | Decision to review |
|---|---|---|
| An all-arches group doing a sweep | Your group containing the left and right arches | Check group order and the effect's rendering across the pair. |
| Four separately sequenced arch rows | Choose the two rows that best preserve the movement | Leave the others intentionally unmapped, then inspect the musical phrase for missing beats. |
| All snowflakes flashing on a beat | A suitable window or whole-prop group | Check whether the simplified accent reads well on the new shapes. |
| Detailed singing-face effects | The correct face-capable Snowman model | Match face definitions and timing; inspect the exact model's supported features first. |
These are artistic mapping choices, not automatic equivalences between shapes. Avoid assigning several independent source rows to one destination without understanding the resulting layers and overlaps. Review a short phrase, then deliberately add or simplify effects that lost their purpose in the smaller layout.
Save the map with the source layout's name. A reusable mapping file is useful only while the relevant source and destination names still match. When you add a new prop later, update the map and check existing songs rather than assuming every import will include it.
Five checks before accepting the import
- The song is the intended version and its first cue aligns.
- Every destination you expect to light receives an effect somewhere in the test section.
- Direction and group order match the yard.
- Whole-house and individual-prop layers do not unintentionally hide one another.
- The final rendered playback file reflects your own layout and controller assignments.
Use our CoroWorks submodel and singing-face lesson for the detailed model work, then refine color and timing.
