Command Line Customize Your Interactive Experience

Lightjams gives you a powerful reactive programming environment. Access it by selecting any slider and clicking the nuclear button.

Here's an overview of the different parts of the command line window. At the top, if you're lucky, you can see funny quotes from famous people. In the center is the text box to type your formula. At the bottom, there's the contextual help for the selected item in the text box.

The next sections will show you all available functions, variables and operators you can use in your formulas.

Notes: parameters inside brackets [] are optional.

Shapes Time Based Functions

These functions are the building blocks to create your effects. They all work with the master and grid sub-master speeds in a nice way.

 

sin(time)
cos(time)
triangle(time)
sawtooth(time)
square(time)
pulse(time, [duration=1 frame])
rand([min=0], [max=100])
randsquare(time, probability)
randpulse(time, probability, [duration=1 frame])

result: All functions return a value between 0% and 100%. This is the standard range in Lightjams.

time: The length of one cycle in seconds. For example, 0.5 means half a second. You can play with the master and grid sub-master speeds to gracefully slow down or speed-up the shape generation.

duration: For the pulse function, this is the length of the pulse in seconds. The default special value of 1 frame means that the pulse will last exactly 1 simulation frame which is about 1/80th second. The 1 frame duration is handy to make sure an event is triggered exactly one time per cycle and no more.

probability: From 0% to 100%. For the randsquare, this is the chance of a state change from active to inactive or the reverse. For randpulse, this is the chance of a pulse to happen.

 

Note: The cos function is mostly used with the sin function to generate circular shapes. For example, you use the sin function to compute the tilt value and the cos function to compute the pan value.

Examples

rand()

Generate random values between 0% and 100%.

randpulse(2, 80, 0.2)

Generate random pulses. Each 2 seconds, have 80% chance of generating a pulse with a duration of 0.2 second. This function makes great random strobe effects.

avg(sin(2+cos(1)/5),cos(2))

Combine multiple functions to generate more complex waves. This way you can generate shapes with a really long cycle before it repeats.

Conditional Expressions Introduce Intelligent Behaviors

Conditional expressions let you encode your very unique interactive experience logics. For example, you can react to events in an intelligent way and generate different shapes based on the current state of the experience.

 

if(condition, resultIfTrue, resultIfFalse)

condition: Boolean expression (true or false). True is any values other than 0. False is 0. You can use any logical operators to express complex conditions:

& and

| or

== equal

!= not equal

> greater than

< less than

>= greater or equal

<= less or equal

! not

 

resultIfTrue: This part is evaluated only if the condition is true (other than 0). This can be a number or another complex formula.

resultIfFalse: This part is evaluated only if the condition is false (0). This can be a number or another complex formula.

 

 

The switch function is a special case of condition of the form: if(myvalue == 1, resultIf1, if(myvalue == 2, resultIf2,...)). It tests each case for equality and returns the corresponding value.

switch(valueToMatch, case1, value1, case2, value2, ..., [defaultValue])

valueToMatch: The value to be compared for equality.

caseX: The case for which to return the corresponding valueX.

valueX: The value to be returned when the valueToMatch is equal to caseX

[defaultValue]: Optional result if no match is found. If no default value is provided, then the last result is returned.

 

The selectCondition function is a special case of condition of the form: if(myvalue < 10, result1, if(myvalue < 20, result2, if(myvalue > 50, result3...)). You can specify multiple conditions and the corresponding return values.

selectCondition(condition1, value1, condition2, value2, ..., [defaultValue])

conditionX: Boolean expression (true or false). Like the condition in the if function.

valueX: The value to be returned when the corresponding condition is true.

[defaultValue]: Optional result if no match is found. If no default value is provided, then the last result is returned.

Examples

music.1.avg < 30

Gives 100% when the music average is below 30%. Otherwise the result is 0%.

if(music.1.avg > 70 & midi.control(1,1) == 0, sin(2), 0)

If the music is loud enough and the midi control value is off then generate a sine wave otherwise shut up.

if(grid.onactivated, randInt(0,10)*10, last)

Pick a different number at random each time the grid is activated. Keep the same number until the next time the grid is reactivated. This works because the if function only evaluates the randInt function when the condition is true. This wouldn't work with the switch or latch functions for example.

switch(dmxinraw(0, 1), 0,sin(1), 1,rand(), 5,sawtooth(1))

Generates a different shape based on the dmx input. When the dmx channel is 0, generates a sinus wave. When it's 1, generates noise. When it's 5, generates a sawtooth wave.

selectCondition(dmxin(0, 1) < 10,sin(1), dmxin(0, 1) < 20,rand(), dmxin(0, 1) < 30,sawtooth(1), 0)

Generates a different shape based on the dmx input, but this time using ranges. When the dmx channel is less then 10, generates a sinus wave. When it's less than 20, generates noise. When it's less 30, generates a sawtooth wave. Otherwise, return 0% (this is the last optional parameter).

Mix and Mash

Mix multiple simple functions together to create more complex and deep moods.

loop(totalDuration, crossFadeDuration, fct1, fct2, fct3, ...)

randloop(totalDuration, crossFadeDuration, fct1, fct2, fct3, ...)

Loop through a list of functions and do a nice crossfade when switching function. The randloop version plays the functions in "shuffle" mode instead of one after another.

totalDuration: The total duration of the loop in seconds. For example, if the total duration is 15 seconds and you have 3 functions, each function will be played 5 seconds.

crossFadeDuration: The crossfade time in seconds.

fct1, fct2, fct3... : Specify any number of functions.

 

sequence(totalDuration, crossFadeDuration, resetFct, fct1, fct2, fct3, ...)

resetFct: Reset the sequence when the value is > 0.

Play each function one after another. When reaching the end of the sequence, the last function is evaluated continuously.

 

timedSequence(nbRepeats, crossfadeDuration, resetFct, time1, fct1, time2, fct2, time3, fct3, ..., [endFct])

resetFct: Reset the sequence when the value is > 0.

endFct: Optional endFct that is played when the sequence ends.

Play each function for the specified duration. Repeat the sequence nbRepeats times or indefinitely if less than 0. Crossfade when switching function.

 

select(indexPercent, fct1, fct2, fct3, ...)

indexPercent: Will select the corresponding function based on this percent value. For example, 0% is the first function and 100% is the last one.

Return the function (or value) corresponding to the specified percent index.

 

Examples

loop(9, 1, sin(1), pulse(0.2), triangle(3))

Play 3 functions, one after another, for 3 seconds each (total 9 seconds). At the end, start over playing the first function. Do a 1 second crossfade between each function.

sequence(9, 1, onbeat(midi.note(1,20)), sin(1), pulse(0.2), 0)

Play the sin and pulse functions for 3 seconds each and then fade to 0%. At any time if the midi note is pressed, the sequence resets.

select(midi.control(1,10), sin(1), rand(), 0)

Select one of the three functions with the MIDI control value. From 0% to 33%, a sinus wave will be generated. From 34% to 66%, noise will be generated and after 66%, it's a blackout.

Trigger React to Events

When something happens, may that be a user pressing a button or a value passing a threshold, the trigger function lets you react intelligently.

 

trigger(activationFct, duration, thresholdDown, thresholdUp, delay)

activationFct: The value being monitored to fire the trigger.

duration: Once activated, this gives the time in seconds that the trigger will stay active.

thresholdDown: To be re-activated, the activation value must goes below or equal to this threshold. You can disable this feature by specifying 100%.

thresholdUp: The activation value must goes over or equal to this thresold to fire the trigger.

delay: The minimum delay in seconds between two re-triggering. If less than the activation duration, allows firing while active and then resets the activation timer.

 

The trigger function returns 0% when not activated and 100% when activated.

 

The onBeat function is a simpler form of the trigger function. It fires when it detects a higher than average value.

onBeat(activationFct, [multiple], [offset])

activationFct: The value being monitored to fire the trigger.

[multiple]: Optionally specifies to not fire on every beat. For example, a multiple of 4 means we fire once and then skip 3 beats.

[offset]: Optionally fires on the 2nd, 3rd, 4th, etc. beats when using the multiple parameter. For example, if you want to fire on the first beat out of four, the multiple is 4 and the offset is 0.

 

The toggle function goes from 0% to 100% and then from 100% to 0% each time there's a beat.

toggle(activationFct)

activationFct: The value being monitored to fire the trigger.

 

The timeout function fires when there's no activity for a while. This is handy when you want to trigger something only when some other thing isn't active.

timeout(time, activationFct)

time: Time to wait before saying "timeout"!

activationFct: The value being monitored to fire the trigger.

 

The timeoutOrActive function, like the timeout function, fires when there's no activity for a while but also when some activity just happened. In the later case, the timer is reset. This is handy when you want to be sure there's a minimum of action even without user input.

timeoutOrActive(time, activationFct)

time: Time to wait before saying "timeout"!

activationFct: The value being monitored to fire the trigger.

 

The onChange function pulses when the value changes. You can optionally specify the threshold.

onChange(value, [threshold])

value: The value to watch.

[threshold]: Optionnaly specify how much the value needs to change before we pulse.

Examples

trigger(midi.note(1,40), 1, 0, 50, 1.3)

Fire for 1 second when a midi note goes over 50%. There is a 0.3 second delay between activations (1.3 second delay - 1 second activation). The note must be released and goes to 0% before firing again.

onbeat(midi.note(1,40))

Pulse when a midi note is pressed.

onbeat(midi.note(1,40), 4)

Pulse when a midi note is pressed, but only fire 1 time out of 4.

toggle(midi.note(1,40))

Each time the midi note is pressed, toggle between 0% and 100%.

timeoutOrActive(4, midi.note(1,40))

Pulse when a midi note is pressed or if nothing happens after 4 seconds.

onChange(midi.note.latest(1))

Pulse each time a different midi note is pressed on channel 1.

Operators Bread and Butter

Operators can be used anywhere in your formulas.

 

+, - Addition and substraction.

*, / Multiplication and division.

^ Exponent. Example: 2^3 is 8.

% Modulo. Return the remaning of a division. Example: 10%3 is 1.

Examples

(video.hue + 50) % 100

This gives you the complementary color by adding 50% to the hue (which is the color at the opposite position on the color wheel) and then using the modulo operator (%) to wrap the result inside 0%-100%.

Grid & Source Variables Contextual Information

When you're using multiple sources to create an effect and the formulas are really similars, you can use the source and grid variables to parametrize your formula in order to use the same for all sources, thus reducing complexity.

 

Source:

x, y Absolute source horizontal (x) and vertical (y) cell positions. The origin point (0,0) is bottom, left.

px, py Percent source horizontal (x) and vertical (y) cell positions. For example, the leftmost x is 0% and the rightmost is 100%.

last Last (or previous) result of this formula.

inactive Special value usable for the source's power meaning no power at all (not even 0%).

 

Grid:

grid.lastx, grid.lasty The position of the last horizontal and vertical cell.

grid.activation The current grid activation level in percent.

grid.onActivatedPulse when the grid has just been activated. Handy to start effects.

grid.speed The current grid sub-master speed in percent.

grid.attributeValueAt(x, y) Get the latest computed value of an attribute.

grid.backgroundAt(x,y) Get the value of the background of the grid at the specified position. The difference with the grid.powerAt function is that the powerAt includes the power of the sources of the current grid while the backgroundAt only returns the value coming from a media or another grid.

grid.bestPresetColorMatch(x, y, hue, saturation, intensity) For the attribute on the grid at position (x,y), returns the percent of the preset with the closest color. Hue, sat and int in the 0%-100% range. The color presets are defined in the fixture template. Mostly useful for color wheel attributes in order to select the color wheel position matching the desired HSL color.

grid.colorGradient(x, y, [colorIndex]) Get the percent to get the colors #index of the color palette gradient linked to the attribute at the specified position. Return the number of colors when no index is specified.

grid.colorGradient.hue(x, y, percent) Get the hue of the color gradient at the percent value linked to the attribute at the specified position.

grid.colorGradient.intensity(x, y, percent) Get the intensity of the color gradient at the percent value linked to the attribute at the specified position.

grid.colorGradient.saturation(x, y, percent) Get the saturation of the color gradient at the percent value linked to the attribute at the specified position.

grid.colorGradient.loop(x, y, goNext) Cycle through the color gradient (with last = first color) of the attribute at the specified position. Go to the next color when goNext is positive.

grid.fixturePosAt(x, y) Get the fixture patch position, as defined in the patch window, of the attribute at the specified position. Return -1 if no attribute on the grid at this position.

grid.powerAt(x, y) Get the resulting power at the specified position. Handy to share values between sources which is an alternative to using the mem and recall functions.

Examples

x*10

When using this formula for a source range, the more at the right the source is, the higher its range will be.

distance(x, y, grid.lastx/2, grid.lasty/2)*10

The farther to the grid center a source is, the higher the result is. The *10 at the end is to boost the result to achieve a good range difference between the center and the border.

if(grid.speed<50, sin(2), rand())

If the grid sub-master speed is less than half, use a smooth sine wave and when the speed is very high, generate chaotic random values.

if(grid.speed<50, inactive, rand())

If the grid sub-master speed is less than half, deactivate the source by returning the special inactive value and when the speed is very high, generate chaotic random values.

grid.powerat(0, 0)

Get the power of the bottom left cell.

grid.powerat(x-1, y)

Get the power of the cell at the left. This shows you can use relative position in your formula.

sequence(9, 1, grid.onActivated, sin(1), pulse(0.2), 0)

Play the sin and pulse functions for 3 seconds each and then fade to 0%. Reset the sequence each time the grid is activated.

Memory Functions Share Values Between Sources and Grids

When you have a really complex formula used by many sources and want to be able to change it quickly without changing all sources, use memory functions! They work like your old time calculator. You can also use the global sliders to share values between grids. Go in the view/sliders menu to see them and use the slider(index) function in your formula.

 

Local Grid Memories (private to a grid):

mem(id, value) Put a value into the memory identified by the id.

recall(id) Get the memory value identified by the id.

 

Global or Shared Grid Memories (accessible by all grids):

gmem(id, value) Put a value into the global memory identified by the id.

grecall(id) Get the global memory value identified by the id.

 

Global Sliders (accessible by all grids):

slider(index) Get the value of a global slider idendified by the index from 1 to 64. Values are always between 0 and 100.

Examples

mem(0, sin(3) + 2 * midi.note(1, 40))

Set the result of your big formula in the memory 0.

recall(0)

Get the value stored by using mem(0, ...).

gmem(0, sin(3) + 2 * midi.note(1, 40))

Set the result of your big formula in the GLOBAL memory 0. This value can be reused in any formula across your entire project.

slider(1)

Get the value of the first global slider.

General Purpose Functions Jack of All Trade

 

abs(value) Absolute value.

avg(value1, value2, value3, ...) Compute the average of a set of values. Can have any number of values.

bpmCounter(beatInput): Count the number of beats per minute in real-time. The result is in BPM, not percent.

bpmCounter.speed(beatInput): Convert the beats per minute to a percent value usable for speed parameters.

ceil(value): Rounds a number up to the nearest integer.

coalesce(v1, v2, ...): Return the first value greater than 0.

counter(from, to, incrementNow, [decrementNow], [resetFct]) Increment a counter between the from and to values only when the incrementNow value is true (other than 0). If the resetFct value is > 0, the counter resets.

noLoopCounter(from, to, incrementNow, [decrementNow], [resetFct]) Like the counter function but don't wrap around when reaching the to value.

pingCounter(from, to, incrementNow, [resetFct]) Increment a counter between the from and to values only when the incrementNow value is true (other than 0). When reaching the to value, start counting backward. If the resetFct value is > 0, the counter resets.

delay(time, value) Delay the value of the given time in seconds.

delta(value) Return the difference between the last iteration value and the current value. That's the instantaneous rate of change.

distance(x1, y1, [z1], x2, y2, [z2]) The euclidean distance between two points in 2D or optionnaly, in 3D.

floor(value): Round a number down to the nearest integer.

isBetween(value, min, max) Return 100% if the value is between min and max, inclusively.

latch(updateNow, value, [initialValue]) Store a value that is updated when the updateNow parameter is positive. Optionally provide an initial value, which is returned before the first update trigger is received.

latchDelta(updateNow, value, [min=0], [max=100]) Update the stored value by adding the delta value (difference between the current and first values when starting the update). The update starts when updateNow is > 0.

latestIndex(value0, value1, ...) Return the index of the latest received positive value.

max(value1, value2, value3, ...) Compute the largest value of a set. Can have any number of values.

min(value1, value2, value3, ...) Compute the smallest value of a set. Can have any number of values.

randInt(min, max) Return a random integer value between min and max (inclusive). Never return the same value twice in a row.

record(isRecording, value) Record the values and replay in a loop the recorded values when not recording. The isRecording triggers the start of a new recording when it is true (other than 0).

recordOnChange(isRecording, value, goNext, goBack, resetFct) Record only the changing values. Play back the values one by one following the goNext and goBack parameters. When goNext is > 0, the next value is played back. When goBack is > 0, the previous value is played back. The isRecording triggers the start of a new recording when it is true (other than 0).

restrain(value, min, max) Make sure the value is between the specified minimum and maximum values.

round(value) Round the fractional part of a number.

scale(value, toMin, toMax) Scale a percent value to fit the specified toMin and toMax range.

scale(value, min, max, toMin, toMax) Scale a value ranging from min and max to fit the specified toMin and toMax range.

seconds(hours, minutes, seconds) Compute the total number of seconds from the hours, minutes and seconds.

smooth(time, value) Average values over the specified time. This is handy when handling jittering signals like Wiimote accelerometers.

sqrt(value) Square root.

strobe(time) Generate a strobe effect in sync with the DMX output.

sum(value1, value2, value3, ...) Sum all values. Can have any number of values.

tapTempo.bpm(beatInput): Return the number of beats per minute of the detected tempo.

tapTempo.pulse(beatInput): Generate pulses based on the detected tempo.

tapTempo.sawtooth(beatInput): Generate a sawtooth wave in sync with the beat.

tapTempo.speed(beatInput): Convert the beats per minute of the tempo to a percent value usable for speed parameters.

Examples

counter(0, 10, onbeat(midi.note(1, 40)))

Count from 0 to 10. Increment the counter each time the midi note is pressed.

counter(0, 10, onbeat(midi.note(1, 40)), onbeat(midi.note(1, 41)))

Count from 0 to 10. Increment the counter each time the midi note 40 is pressed and decrement each time the midi note 41 is pressed.

latch(onbeat(midi.note(1, 40)), rand())

Take a new random value each time the midi note is pressed.

tapTempo.pulse(onbeat(midi.note(1, 40)))

Generate pulses based on the tempo made by pressing a midi note.

map.triangle(taptempo.sawtooth(midi.note(1,40)))

Generate a triangle wave in sync with the detected tempo.

tapTempo.speed(onbeat(midi.note(1, 40)))

Return a value suitable to control the speed of a grid or group based on the tempo made by pressing a midi note. If you generate a tempo of 60 BPM, the speed value will be 1x. 120 BPM will be 2x...

strobe(0.1)

Generare a 10 Hz strobe. 0.1 is the time between each pulse in seconds.

isBetween(midi.clock.time(1), seconds(0,10,0), seconds(1,10,0))

Check whether a MIDI time code is between 10 minutes and an hour and 10 minutes.

Fades Smooth Transitions

To apply nice fades to Wii, MIDI or any other interactive inputs, the fade functions are your best friends. You can also use the grid fade in and out properties if you want to apply the same fade to all sources on the grid.

 

Both Ways: Fade In and Out:

fade(time, value): Fade in and out using the exponential form.

fade.linear(time, value): Fade in and out using the linear form.

fade.exp(time, value): Fade in and out using the exponential form.

fade.log(time, value): Fade in and out using the logarithmic form.

fade.sig(time, value): Fade in and out using the sigmoid form.

 

Fade In Only

fadein(time, value): Fade in using the exponential form.

fadein.XYZ(time, value): Fade in using the linear, exponential, logarithmic or sigmoid form.

 

Fade Out Only

fadeout(time, value): Fade out using the exponential form.

fadeout.XYZ(time, value): Fade out using the linear, exponential, logarithmic or sigmoid form.

 

Different Fade In and Fade Out Times

fadein.XYZ(time, fadeout.XYZ(time, value)):You can imbricate a fade in and fade out funtions to specify different fade times.

Examples

fade.linear(1, pulse(2,1))

Use fade in and out of 1 second for a pulse function. This gives a triangle shape.

fadein.linear(0.2, fadeout.exp(1, pulse(2,1)))

A quick linear fade in and a longer exponential fade out. It is often desirable having short fade in time and longer fade out in order to be really responsive and give quick feedback.

DMX In ArtNET and sACN Inputs

You can access the whole 16 ArtNET and sACN input universes using the following formulas:

 

dmxin(universe, address)

This gives you the dmx value in percent.

universe: The universe from 0 to 15.

address: The DMX address from 1 to 512.

 

dmxinraw(universe, address)

This gives you the raw dmx value from 0 to 255.

universe: The universe from 0 to 15.

address: The DMX address from 1 to 512.

Examples

midi.control(1, dmxinraw(0, 1))

Select the proper midi control based on the raw DMX input value at universe 0 and channel 1. You can use this formula to let another lighting controller sends DMX to Lightjams and switches the midi control.

MIDI

 

midi.control(channel, control)

Get the intensity of a MIDI control in percent.

channel: The MIDI channel from 1 to 16.

control: The control index from 1 to 128.

 

midi.controlRaw(channel, control)

Get the exact intensity of a MIDI control from 0 to 127.

channel: The MIDI channel from 1 to 16.

control: The control index from 1 to 128.

 

midi.control.onReceived(channel, control)

Pulse when receiving a MIDI CC message.

channel: The MIDI channel from 1 to 16.

control: The control index from 1 to 128.

 

midi.note(channel, note)

Get the intensity of a note in percent. When the note is off, the intensity is 0.

channel: The MIDI channel from 1 to 16.

note: The note index from 1 to 128.

 

midi.noteRaw(channel, note)

Get the exact intensity of a note from 0 to 127.

channel: The MIDI channel from 1 to 16.

note: The note index from 1 to 128.

 

midi.note.latest(channel, [firstNoteIndex], [lastNoteIndex])

Get the latest pressed note index (1 to 128) of this channel. Optionnally specify a range of notes to watch for instead of the whole channel.

channel: The MIDI channel from 1 to 16.

 

midi.channel.latest(note, firstChannel, lastChannel)

Get the latest MIDI channel index having received the specified note, including only channels between the firstChannel and lastChannel parameters.

note: The note index (1 to 128) to look for.

firstChannel: The first MIDI channel (1 to 16) to look for the note.

lastChannel: The last MIDI channel (1 to 16) to look for the note.

 

midi.clock.beat(clockId)

Pulse in sync with the clock ticks.

clockId: The identifier of the clock as seen in the MIDI config panel.

 

midi.clock.bpm(clockId)

Get the detected beats per minute of the clock.

clockId: The identifier of the clock as seen in the MIDI config panel.

 

midi.clock.speed(clockId)

Convert the bpm to a usable value for speed. 60 BPM = 1x speed.

clockId: The identifier of the clock as seen in the MIDI config panel.

 

midi.clock.sawtooth(clockId)

Generate a sawtooth wave in sync with the clock. Use the map.x functions to generate other types of wave.

clockId: The identifier of the clock as seen in the MIDI config panel.

 

midi.clock.time(clockId)

Get the time code (MTC) in seconds of the clock.

clockId: The identifier of the clock as seen in the MIDI config panel.

Examples

midi.control(1,1)

Get the intensity of the first control of the first channel.

map.sin(midi.clock.sawtooth(1))

Generate a sinus wave in sync with the clock ticks.

isBetween(midi.clock.time(1), seconds(0,10,0), seconds(1,10,0))

Check whether a MIDI time code is between 10 minutes and an hour and 10 minutes.

Ableton Link

 

abletonlink.enabled(isEnabled)

Enable or disable the Ableton Link session. Must be enabled for all other ableton link functions to work. Check the firewall if you can't join the session or don't see others.

isEnabled: Enabled when different than 0.

 

abletonlink.enabled

Get whether the Ableton Link session is enabled.

 

abletonlink.peers

Get the number of peers in the Ableton Link session.

 

abletonlink.beat

Pulse each time a beat occurs.

 

abletonlink.beats

Get the number of beats that have occurred in the session.

 

abletonlink.resetBeats(resetFct)

Reset the beats counter when the resetFct parameter is > 0. This allows to align the beats with the current time.

 

abletonlink.tempo(bpm)

Set tempo for the session.

bpm: The tempo in beats per minute (BPM).

 

abletonlink.tempo

Get the tempo value in beats per minute (BPM).

 

abletonlink.phase

Get the phase value, which is the current beat position in the loop. The range is between 0 and the quantum value-1.

 

abletonlink.quantum(quantum)

Set the quantum value (number of beats) for the session.

quantum: The number of beats.

 

abletonlink.quantum

Get the quantum value in number of beats. This is the number of beats for one loop.

Examples

abletonlink.enabled(100)

Enable the session.

abletonlink.enabled(toggle(midi.note(1,30)))

Enable and disable the session each time the midi note is pressed.

floor(abletonlink.phase)

Get the beat number for the current loop.

onchange(floor(abletonlink.phase/2))

Pulse every 2 beats, in sync with the start of the loop. Using the phase variable allows to stay in sync.

trigger(onchange(floor(abletonlink.phase/2)), 0.1, 0, 100, 0)

Stay at 100% for 0.1 second every 2 beats.

Music Spectrum

 

music.X

Get the music overall instantaneous energy.

X: The sound card index from 1 to 8.

 

music.X.low

Get the music low frequencies instantaneous energy.

X: The sound card index from 1 to 8.

 

music.X.mid

Get the music mid frequencies instantaneous energy.

X: The sound card index from 1 to 8.

 

music.X.hi

Get the music high frequencies instantaneous energy.

X: The sound card index from 1 to 8.

 

music.X.avg

Get the music overall average energy.

X: The sound card index from 1 to 8.

 

music.X.low.avg

Get the music low frequencies average energy.

X: The sound card index from 1 to 8.

 

music.X.mid.avg

Get the music mid frequencies average energy.

X: The sound card index from 1 to 8.

 

music.X.hi.avg

Get the music high frequencies average energy.

X: The sound card index from 1 to 8.

 

music.X.beat

Get the music overall beat energy.

X: The sound card index from 1 to 8.

 

music.X.low.beat

Get the music low frequencies beat energy.

X: The sound card index from 1 to 8.

 

music.X.mid.beat

Get the music mid frequencies beat energy.

X: The sound card index from 1 to 8.

 

music.X.hi.beat

Get the music high frequencies beat energy.

X: The sound card index from 1 to 8.

 

music.X.band(bandIndex)

Get a music band instantaneous energy.

X: The sound card index from 1 to 8.

bandIndex: The detailed band index from 1 to 20.

 

music.X.bandAvg(bandIndex)

Get a music band average energy. It's the one second average.

X: The sound card index from 1 to 8.

bandIndex: The detailed band index from 1 to 20.

 

music.X.bandBeat(bandIndex)

Get a music band instantaneous beat energy. When over 0%, there is a beat. The louder the beat, the greater will be the value.

X: The sound card index from 1 to 8.

bandIndex: The detailed band index from 1 to 20.

 

music.X.starband

Get the music band index with the more "swing". The star! Index from 1 to 20.

X: The sound card index from 1 to 8.

 

music.X.powerband

Get the music band index with the highest average value. That's the primary frequency band. Index from 1 to 20.

X: The sound card index from 1 to 8.

 

music.volume(soundCardIndex, volume)

Change the sound card volume.

soundCardIndex: The sound card index from 1 to 8.

volume: The volume in percent.

Examples

music.1.bandBeat(0) > 0

Gives 100% as soon as there is a beat, whatever its power. Uses the first sound card.

music.1.starBand * 4

Can be used to control the hue. When the starband is a low frequency, the hue will be reddish and when the starband is a high frequency, the hue will be blueish.

tapTempo.pulse(music.1.beat)

Generate pulses based on the detected music tempo.

bpmCounter(music.1.low.beat)

Return the current number of beats per minute (BPM) of the low frequencies.

trigger(music.1.low.beat, 0.07, 10, 15, 0.15)

Better beat detection by cleaning the values a little bit. The trigger function removes the noises and avoid firing too frequently.

bpmCounter(trigger(music.1.low.beat, 0.07, 10, 15, 0.15))

Count the BPM of low frequencies using the trigger function to clean the beats.

music.volume(1, midi.control(1, 10))

Change the first sound card volume using the MIDI control value of channel 1, index 10.

Music Player

The Lightjams music player is a stand alone application used to manage your music library and able to send lots of information to Lightjams while playing music.

music.player.bpm: The detected beats per minute for the current song.

music.player.nbSongs: The number of songs in the current playlist.

music.player.playing: Whether the music is playing or paused.

music.player.playing(isPlaying): Pause when isPlaying is 0 or play when isPlaying is > 0.

music.player.playlist: The current playlist index.

music.player.playlist(index): Select a playlist.

music.player.restart(): Restart the current song.

music.player.song: The current song index.

music.player.song(index): Select a song.

music.player.songLength: The current song length in seconds.

music.player.time: The playback position in second.

music.player.volume(percent): Change the playback volume.

Examples

if(grid.onactivated, music.player.song(10) & music.player.restart(), 0)

When the grid has just been activated, start the song number 10. We use the if function to avoid continuously sending the same command to the music player.

if(onbeat(midi.note(1,40)), music.player.song(10) & music.player.restart(), 0)

When the midi note 40 is pressed, start the song number 10.

if(onbeat(midi.note(1,20)), music.player.restart(), 0)

When the midi note 20 is pressed, restart the song. We use the if function to avoid continuously sending the same command to the music player.

music.player.volume(sin(5))

Change the music player volume using a sinus wave.

xtopercent(music.player.time)

Use this as the source'x formula to make the source follow the playback time. The source will go forward one cell per second.

music.player.playing(toggle(midi.note(1,39)))

Toggle the playing or paused state by pressing a midi note.

DateTime

Everything you need to make your scheduling.

 

time.hour

The hour component of the current time. From 0 to 23, where 0 is midnight. Always expressed using a 24-hour clock.

 

time.minute

The minute component of the current time. From 0 to 59.

 

time.second

The second component of the current time. From 0 to 59.

 

time.isDark

100% when we're between the sunset and the sunrise. In other words, if it's dark and we need some light. This takes into account your position in the world (latitude & longitude).

 

time.isBetween(hour1, [minute1], hour2, [minute2])

100% when the current hour and minute (optional) are inside the specified range. Hour is always expressed using a 24-hour clock.

 

timer(resetTime, [resetFct])

Return the elapsed time in seconds. Reset when reaching the reset time (set to 0 to avoid auto reset) or when the resetFct is positive. It is synced to the computer's clock for precise timing.

 

 

 

date.year

The year component of the current date, e.g. 2013.

 

date.month

The month component of the current date. From 1 to 12, where 1 is January.

 

date.dayOfWeek

The day of the week of the current date. From 1 to 7, where 1 is Sunday and 7 is Saturday.

 

date.dayOfMonth

The day of the month of the current date. From 1 to 31.

 

date.dayOfYear

The day of the year of the current date. From 1 to 366, where 1 is January 1st. Take leap years into account.

 

date.isWeekend

100% when we're Saturday or Sunday.

Examples

time.isDark & date.isWeekend

Gives 100% when it's dark outside (between sunset and sunrise) and we're the weekend.

date.dayOfWeek == 1 | date.dayOfWeek == 2

Gives 100% when we're Sunday or Monday.

if(time.isBetween(15, 22), sin(1), 0)

When it's beween 3 PM and 10 PM, generates a sinus wave otherwise returns 0%.

timer(0, grid.onActivated)

Returns the elapsed time in seconds since the grid has been activated.

OSC

 

osc(channel)

Get a value received from OSC. The value should be between 0% and 100% depending on the minimum and maximum values used in the OSC mapping.

channel: The OSC channel from 0 to 511.

 

oscRaw(channel)

Get a raw value (unscaled), exactly as received from OSC.

channel: The OSC channel from 0 to 511.

 

osc.latest(firstChannel, lastChannel)

Get the latest channel index having received a positive value.

firstChannel, lastChannel: Channels range to be considered.

 

osc.onReceived(channel)

Pulse when a new value has been received, even if there's no value change. In other words, pulse when a osc message for the speicified channel has been received.

channel: The OSC channel from 0 to 511.

 

osc.send(channel, value1, value2, value3...)

Send OSC values (max 16) to the specified extra output channel. Configure your extra output messages in the OSC config panel. This allows you to send float values to a custom OSC address.

channel: The extra output channel from 0 to 63.

values: Float numbers to be sent.

Examples

osc(0)

Get the value of the first OSC channel (channel 0).

latch(osc.onReceived(0), rand())

Generate a random number each time a osc message is received on the first channel.

osc.send(10, rand(), sin(1))

Send two values to the extra output channel 10. The values are sent continously as they change. When there's no changes, no OSC message is sent.

TUIO

 

tuio.cursor.on(id)

Get whether a TUIO cursor is active. 0% when not active and 100% when active.

id: The cursor's id from 1 to 16.

 

tuio.cursor.x(id)

tuio.cursor.y(id)

Get a TUIO cursor x and y positions.

id: The cursor's id from 1 to 16.

 

tuio.object.on(id)

Get whether a TUIO object is active. 0% when not active and 100% when active.

id: The object's id from 1 to 128.

 

tuio.object.x(id)

tuio.object.y(id)

Get a TUIO object x and y positions.

id: The object's id from 1 to 128.

 

tuio.object.angle(id)

Get a TUIO object's angle.

id: The object's id from 1 to 128.

Examples

if(tuio.object.on(0), sin(tuio.object.angle/10), 0)

When the first object is active, generates a sine wave using the object's angle to control the sine's time.

Wii

You have acces to four wiimotes and nunchuks. All formulas begin by wii.remoteX where X is the wiimote number from 1 to 4.

 

Wii Buttons:

A, B, up, down, left, right, 1 and 2

When a button is pressed the value is 100% otherwise it's 0%.

 

Wii Axis:

X, Y, Z

The values range from 0% to 100%.

Examples

wii.remote1.x

Get the X axis value of the wiimote #1.

if(wii.remote1.b, wii.remote1.x, last)

If the B button is pressed then use the X axis value otherwise freeze. The last variable contains the last value. So when the user releases the B button, the last value will remain to this value.

record(wii.remote1.b, wii.remote1.x)

If the B button is pressed then record the X axis value. When the user releases the B button, recorded values will play in a loop. One nice thing is that the record playback speed is modulated by the grid speed.

Speech Recognition

First, you need to configure the phrases to be recognized in the configuration panel.

 

speech.recognized(phraseId)

Pulse when the corresponding phrase is recognized.

phraseId: The identifier of the phrase to be recognized from 1 to 64.

 

speech.recognized.latest([min], [max])

Latest recognized phrase id, optionally including phrases between min and max only.

min, max: Optionally specify a range of phrase ids, from 1 to 64.

Media

You can use up to 64 media, including video files, live video feeds and still images. For each media, you can get the dominant colors splitted in 9 regions.

 

media.hue(mediaId, [regionId])

Get the hue component of the dominant color of a media region or overall if not specified.

mediaId: The media id from 1 to 64.

regionId: The region id from 1 to 9.

 

media.saturation(mediaId, [regionId])

Get the saturation component of the dominant color of a media region or overall if not specified.

mediaId: The media id from 1 to 64.

regionId: The region id from 1 to 9.

 

media.intensity(mediaId, [regionId])

Get the intensity component of the dominant color of a media region or overall if not specified.

mediaId: The media id from 1 to 64.

regionId: The region id from 1 to 9.

 

media.position(mediaId)

Get the play head position of a media in percent. This way you can sync your other effects with the playback of your media

mediaId: The media id from 1 to 64.

 

media.length(mediaId)

The duration of a media in seconds.

mediaId: The media id from 1 to 64.

 

media.time(mediaId)

The current playback time of a media in seconds.

mediaId: The media id from 1 to 64.

Color Conversion

A few useful functions to convert between HSI and RGB.

hsi.hue.rgb(r, g, b): Compute the hue corresponding to the specified RGB value.

hsi.saturation.rgb(r, g, b): Compute the saturation corresponding to the specified RGB value.

hsi.intensity.rgb(r, g, b): Compute the intensity corresponding to the specified RGB value.

 

rgb.red.hsi(h, s, i): Compute the red value corresponding to the specified HSI value.

rgb.green.hsi(h, s, i): Compute the green value corresponding to the specified HSI value.

rgb.blue.hsi(h, s, i): Compute the blue value corresponding to the specified HSI value.

 

rgb.red(r, g, b, i): Compute the red value corresponding to the specified RGB and intensity (dimmer) value.

rgb.green(r, g, b, i): Compute the green value corresponding to the specified RGB and intensity (dimmer) value.

rgb.blue(r, g, b, i): Compute the blue value corresponding to the specified RGB and intensity (dimmer) value.

Examples

hsi.hue.rgb(dmxin(0, 10), dmxin(0, 11), dmxin(0, 12))

Get the hue corresponding to the RGB values specified by the DMX input values of channel 0, address 10, 11 and 12.

hsi.saturation.rgb(dmxin(0, 10), dmxin(0, 11), dmxin(0, 12))

Get the saturation corresponding to the RGB values specified by the DMX input values of channel 0, address 10, 11 and 12.

hsi.intensity.rgb(dmxin(0, 10), dmxin(0, 11), dmxin(0, 12))

Get the intensity corresponding to the RGB values specified by the DMX input values of channel 0, address 10, 11 and 12.

What's next? Try Lightjams for free!

©2009-2023 Lightjams inc. All Rights Reserved - The DMX Lighting Controller Software for Live Performances. Proudly made in Montreal, Canada.