xLights Text Effect: Display Custom Messages in Your Light Show

The Text effect in xLights lets you display words, numbers, and symbols on matrices, MegaTrees, singing faces, and other props that support text rendering. It is commonly used for song titles, artist, greetings, countdowns, announcements, and lyric displays.

Unlike many effects that animate pixels directly, the Text effect generates text using installed fonts and then applies optional animations.

Basic Settings

Text

Enter the message you want to display. Examples:

  • Merry Christmas!
  • Happy Halloween!
  • Tune To 88.5 FM
  • Welcome!

If you need to insert a line break, simply put \n (backslash and a small n) inline with your text — it will force the text after the \n to the next row on the matrix.

Font

Choose the font used to draw the text . Different fonts can dramatically change readability. General recommendations:

  • Sans-serif fonts work best on low-resolution matrices.
  • Bold fonts are easier to read.
  • Avoid highly decorative fonts unless your matrix has a high pixel density.

Font Size

Controls the size of the text.

  • Larger text is easier to read.
  • Smaller text allows longer messages.
  • Extremely large fonts may be clipped if they exceed the matrix dimensions.

Text Color

Choose one or more colors.

When multiple colors are selected, xLights can create color transitions depending on the selected palette.

Inserting Song Titles, Artist Or Other Metadata

  1. Ensure that your sequence metadata contains the correct information (title, artist, etc) that you plan to display. To do this, in xLights with your sequence open, go to file, sequence settings and click on the metadata tab where you can check the accuracy and make updates if needed.
  2. In the “text” box, you can enter ${XYZ} where XYZ is the metadata element you want displayed — it must be upper case to work! Options include:
    • ${SONG} or ${TITLE} = song title
    • ${ARTIST} = artist
    • ${ALBUM} = album
    • ${COMMENT} = comment
    • There are several other less common metadata elements that can be found in the xLights manual here: xLight Text Effect (scroll to bottom)

Inserting Song Lyrics

  1. Ensure that your sequence contains song lyrics in a lyrics track. See our xLights sequencing tips & tricks article on inserting lyrics.
  2. In the “from lyrics” box, you can select the appropriate lyrics track and it will be displayed on your matrix / MegaTree
  3. You can combine lyrics with different movement options like wavy, up, down, etc for some interesting effects

Position Options

Horizontal Alignment:

Determines where the text starts. Can be left, center or right.

Vertical Alignment

Controls vertical placement. Can be top, middle or bottom.

Offset

Fine-tunes the text position by moving it horizontally or vertically. Useful when aligning text with other effects.

Animation Options

The Text effect supports several movement styles.

Static

The text remains fixed on the screen. Best for greetings, titles, credits, etc. if you have enough room on your matrix.

Scroll Left

Text moves from right to left. Most commonly used for:

  • Marquee signs
  • Long announcements
  • Song lyrics

Scroll Right

Moves left to right. Less common but useful for certain visual effects.

Scroll Up

Text moves upward through the matrix. Often used for:

  • Credits
  • Countdown lists
  • Names

Scroll Down

Moves downward across the display. Useful for transitions or dramatic reveals.

Bounce

The text reverses direction when reaching the edge of the model. Good for keeping a short message visible without restarting.

Timing Controls

Speed

Controls how fast animated text moves.

  • Lower values produce slower movement.
  • Higher values increase scrolling speed.

Match the speed to your music so viewers can comfortably read the message.

Repeat

Controls whether the animation repeats during the effect duration. Long effects often benefit from repeating animations.

Rotation

Text can be rotated to match the orientation of your prop.

Common options include:

  • 0°
  • 90°
  • 180°
  • 270°

This is especially useful for vertical matrices or props mounted sideways.

Transparency and Layering

The Text effect works well when layered with other effects.

Examples include:

  • Snow falling behind text
  • Sparkles over text
  • Color washes beneath text
  • Fire effects behind Halloween messages

Use Layer Blending modes when combining multiple effects on the same model.

Tips for Readable Text

For the best results:

  • Keep messages short.
  • Use bold, simple fonts.
  • Use high-contrast colors.
  • Slow the scroll speed enough for viewers to read.
  • Test your message on the actual matrix before sequencing an entire song.

Common Uses

The Text effect is frequently used for:

  • Welcome messages
  • Merry Christmas greetings
  • Happy Halloween displays
  • Tune-to radio frequency announcements
  • Song titles
  • Lyric displays
  • Sponsor acknowledgements
  • Countdown timers
  • Show credits

Common Mistakes

Avoid these common issues:

  • Fonts that are too small for the matrix resolution.
  • Scrolling text too quickly to read.
  • Long paragraphs instead of short phrases.
  • Low-contrast color combinations.
  • Trying to display too much information at once.

Sequencing Tips & Tricks
About MegaTrees
Prop Types
Buyer’s Guide

Scroll to Top