Expressions

Expressions in urmusic

These are all expressions. They are used to specify a value.

There are 2 types of expressions in urmusic:

Constant value

This is the simplest way. You just have to directly type the value that you want.

Examples:

64
-2
0.8
-43.86

Variable value

This is the more advanced way. Here, the value isn't directly typed. You have to type an expression using built-in variables and functions that will determine the value used on each frame:

Examples:

time
2 * pi
rand() * 8
16 + 8
0.02 * (rand() * 2 - 1) * clamp((maxlowval + 70) / 50, 0, 1)

Yeah, 16 + 8 is considered as an expression, a constant expression. This kind of expression aren't recommended, because urmusic will re-evaluate it each frame, even if it won't change. You should directly type 24 for performance reasons.

Reference

Here's a list of all the built-in variables and functions available in urmusic:

variable/function	description
rand()	generates a random number in the range [0.0; 1.0[.
smoothrand(i)	returns a number picked in an array of constant random numbers. i is the index of this array, and the random numbers are at integer indices. If i isn't an integer, then the value is sinusoidally interpolated.
max(a, b)	returns the largest number between a and b.
min(a, b)	returns the smallest number between a and b.
clamp(x, a, b)	returns the value of x constrained to the range a to b. The returned value is computed as max(min(x, b), a).
floor(x)	returns a value equal to the nearest integer that is less than or equal to x.
ceil(x)	returns a value equal to the nearest integer that is greater than or equal to x.
cos(x)	returns the trigonometric cosine of x (in radians).
sin(x)	returns the trigonometric sine of x (in radians).
tan(x)	returns the trigonometric tangent of x (in radians).
acos(x)	returns the angle whose trigonometric cosine is x.
asin(x)	returns the angle whose trigonometric sine is x.
atan(x)	returns the angle whose trigonometric tangent is x.
pow(x, a)	returns x raised to the a power.
pi	returns the constant π, the ratio of the circumference of a circle to its diameter. It's approximately 3.14159.
maxval	returns the largest frequency value in decibels urmusic processed for the current frame.
minval	returns the smallest frequency value in decibels urmusic processed for the current frame.
time	returns the current time of the track in seconds.
duration	returns the duration of the track in seconds.
maxlowval	returns the same as maxval, but applying a low-pass filter. The filter's frequency is defined in the advanced settings.
minlowval	returns the same as minval, but applying a low-pass filter. The filter's frequency is defined in the advanced settings.
maxhighval	returns the same as maxval, but applying a high-pass filter. The filter's frequency is defined in the advanced settings.
minhighval	returns the same as minval, but applying a high-pass filter. The filter's frequency is defined in the advanced settings.
csize	returns the size in pixels of the smallest side of the canvas. This is the value of 1 unit in most of the distance/position expressions (e.g. posX, posY, height, lineWidth...).
imgw	returns the width of the image in pixels. Only works for the expressions of an IMAGE type section.
imgh	returns the height of the image in pixels. Only works for the expressions of an IMAGE type section.
imgr	returns the aspect ratio of the image (width/height). Only works for the expressions of an IMAGE type section.
songtitle	returns the title of the current track. For a file, it's the file name without the extension.
prettytime	returns the current time of the track, formatted as (hh:)mm:ss.
prettyduration	returns the duration of the track, formatted as (hh:)mm:ss.

You can use all of these variables and functions in your expression. It's then parsed as JavaScript, so you can also use parentheses.

Examples

Let's get back to our examples and manually interpret them:

time = whatever, let's say 8 seconds = 8
2 * pi = approximately 6.28318
rand() * 8 = a random number in the range [0.0; 8.0[ = let's say 4.183 = 4.183
16 + 8 = 24

Then, the big one:

0.02 * (rand() * 2 - 1) * clamp((maxlowval + 70) / 50, 0, 1)

Let's call it E, and simulate the functions and variables such as rand() and maxlowval:

E = 0.02 * (rand() * 2 - 1) * clamp((maxlowval + 70) / 50, 0, 1) // Start point
E = 0.02 * (0.5384 * 2 - 1) * clamp((-15 + 70) / 50, 0, 1) // rand() returned 0.5384, and maxlowval is -15 decibels!
E = 0.02 * (1.0768 - 1) * clamp(55 / 50, 0, 1) // 0.5384 * 2 = 1.0768 and -15 + 70 = 55
E = 0.02 * 0.0768 * clamp(1.1, 0, 1) // 1.0768 - 1 = 0.0768 and 55 / 50 = 1.1
E = 0.02 * 0.0768 * 1.0 // clamp(1.1, 0, 1) will returns 1.0, because 1.1 is larger than 1.0
E = 0.001536 // 0.02 * 0.0768 * 1.0 = 0.001536

Then, in this case, the expression will return E = 0.001536. Now, what does this expression do finally? Well, it's used in some presets to make everything "shake" with the bass! The first constant 0.02 is the shaking amount, rand() * 2 - 1 returns a random number in the range [-1.0; 1.0[, and clamp((maxlowval + 70) / 50, 0, 1) returns a number in the range [0.0; 1.0] which is the bass "volume".

Strings

Direct string

If the expression is a string, then you should put it inside quotes or double-quotes: 'Just like this', "Or like this".

Advanced string

Since an expression is parsed as JavaScript, you can use concatenations. It can be useful to customize your visualizer even more, or simply to debug:

"Song title: " + songtitle
"Progression: " + prettytime + " / " + prettyduration
"Value of csize: " + csize + "px"