Skip to content

Variable Text Formatting

Use the following formatting expressions with the appropriate Variable Text mode to have LightBurn replace the expressions with alternate data when you output a project to your laser.

In order for each type of formatting expression to be replaced with alternate data, you must also select the corresponding mode from the dropdown menu in the Text Options Toolbar.

Variable Text Dropdown menu

Tip

Use the Test button to verify that you have entered the formatting expressions correctly, before sending a project to your laser.

Date/Time

When using the Date/Time formatting, LightBurn will automatically substitute special combinations of characters with values for the current local date and time, as determined by your system's clock.

Date/Time Example

Use the following expressions for dates:

Output Expression
The day as number without a leading zero (1 to 31) d
The day as number with a leading zero (01 to 31) dd
The abbreviated localized day name (e.g. "Mon" to "Sun"). Uses the system locale to localize the name. ddd
The long localized day name (e.g. "Monday" to "Sunday"). Uses the system locale to localize the name. dddd
The month as number without a leading zero (1-12) M
The month as number with a leading zero (01-12) MM
the abbreviated localized month name (e.g. "Jan" to "Dec"). Uses the system locale to localize the name. MMM
the long localized month name (e.g. "January" to "December"). Uses the system locale to localize the name. MMMM
the year as two digit number (00-99) yy
the year as four digit number yyyy

Use the following expressions for time:

Expression Output
h The hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)
hh The hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)
H The hour without a leading zero (0 to 23, even with AM/PM display)
HH The hour with a leading zero (00 to 23, even with AM/PM display)
m The minute without a leading zero (0 to 59)
mm The minute with a leading zero (00 to 59)
s The whole second without a leading zero (0 to 59)
ss The whole second with a leading zero where applicable (00 to 59)
z The fractional part of the second, to go after a decimal point, without trailing zeroes (0 to 999). Thus "s.z" reports the seconds to full available (millisecond) precision without trailing zeroes.
zzz The fractional part of the second, to millisecond precision, including trailing zeroes where applicable (000 to 999).
AP or A Use AM/PM display. A/AP will be replaced by either "AM" or "PM".
ap or a Use am/pm display. a/ap will be replaced by either "am" or "pm".
t The time zone (e.g. "CEST")

Additional Notes

  • Any sequence of characters enclosed in single quotes will be included verbatim in the output string (stripped of the quotes), even if it contains formatting characters.

  • Two consecutive single quotes ('') are replaced by a single quote in the output.

  • All other non-formatting characters in the input string are included verbatim in the output.

Variable Text formatting using single quotes

Tip

Formats without separators (e.g. "ddMM") are supported but must be used with care, as the resulting strings aren't always reliably readable (e.g. if "dM" produces "212" it could mean either the 2nd of December or the 21st of February).

Serial Number

When using the Serial Number formatting, LightBurn will automatically substitute special combinations of characters with the Current serial number value.

Serial Number example

Use the following expressions for serial numbers:

Output Expression
The serial number as a decimal value d
The serial number as a hexadecimal value, lower case h
The serial number as a hexadecimal value, upper case H
Tells LightBurn to pad the number with leading zeros 0

The number of characters controls how many digits will output. If the Current serial number is larger than the number of digits allowed, as many digits as will fit from the end of the number will be displayed. For example, if your Current serial number is 1234, the table below shows how that number would be formatted for each of the displayed formatting inputs:

Input Output Input Output
d 4 0d 4
dd 34 0dd 34
ddd 234 0ddd 234
dddd 1234 0dddd 1234
ddddd 1234 0ddddd 01234
dddddd 1234 0dddddd 001234

Additional Notes

  • Any sequence of characters enclosed in single quotes will be included verbatim in the output string (stripped of the quotes), even if it contains formatting characters.

  • All other non-formatting characters in the input string are included verbatim in the output.

  • Use the Offset field in the Text Options Toolbar to enter multiple indentical formatting strings that output a different serial number.

  • You cannot mix decimal and hexadecimal formatting in the same text entry.

  • You cannot split a serial number with other characters. For example, because of the hyphen between the two groups of format characters, this string is not valid: ddd-ddd.

  • Invalid strings will output as "bad serial format".

Bad Format example

Merge/CSV

When using the Merge/CSV formatting, LightBurn will automatically substitute special combinations of characters with an entry from a CSV file.

Merge/CSV example

A CSV file is a Comma Separated Values file — a very simple text format that uses a line in a file as the row, and commas to separate columns. You can create a CSV file using a plain text editor, or by exporting from most common spreadsheet software.

In a Merge/CSV entry in LightBurn, the text you enter uses the percent sign followed by a number to look up a column in the current row of the CSV file.

  • Columns and rows are numbered starting from 0.

  • Refer to the first column in a CSV using the formatting "%0", the second using "%1", the third using "%2", and so on.

  • A Current value of 0 refers to the first row, 1 to the second, 2 to the third, and so on.

For example, using a CSV file with the following content:

LightBurn,80,10
Corel,300,20

And entering this formatting:

"​I'm thinking of buying %0, it costs $%1."

Would output:

"​I'm thinking of buying LightBurn, it costs $80."

Additional Notes

  • Use the Offset field in the Text Options Toolbar to enter multiple indentical formatting strings that output a different row from a CSV.

Cut Setting

When using Cut Setting formatting, LightBurn will automatically substitute certain characters with values from the Cut Settings applied to the text, or another specified layer.

Cut Setting example

Use the following expressions for Cut Settings:

Expression Output
C Followed by a number, pulls settings from the numbered cut layer (e.g. C03) for the remainder of this string
s Speed, as a number in the current speed units
S Speed, including the current units (like mm/sec)
p Max Power, as a percentage
P Max Power, including the percent sign
m Min Power, as a percentage
M Min Power , including the percent sign
d / D DPI, as a number, always dots per inch
i Interval, in the current distance units
I Interval, including the current distance units (like mm)
L Displays the name of the laser. Can optionally be followed by a character index to start displaying from, and optionally, a comma and a 2nd number for the number of characters to display. For example, if L displayed "Ruida 6442G", L6 would display "6442G", and L6,4 would display "6442" (without the quotes)
z Z Offset for the current layer, in the current distance units
Z Z Offset for the current layer including the units (eg, mm)
q Q-Pulse width
Q Q-Pulse width, followed by "ns" to indicate the units
k Frequency in kHz
K Frequency in kHz, followed by "kHz" to indicate the units

Additional Notes

  • Any sequence of characters enclosed in single quotes will be included verbatim in the output string (stripped of the quotes), even if it contains formatting characters.

  • All other non-formatting characters in the input string are included verbatim in the output.

For more help using LightBurn, please visit our forum to talk with LightBurn staff and users, or email support.