REAPER | JS Programming - Variable Reference

Audio Production Without Limits

About : Download : Purchase : Manual : Forum : Resources : REAPER Radio!

REAPER/JS Programming Variable Reference

[Back to the main JS programming reference]

JS uses numerous variables for special purposes, in the following categories:

Basic functionality, Audio system, Extended functionality, Delay Compensation, and Graphics/Mouse.

Basic Functionality:

spl0, spl1 ... spl63
Context: @sample only
Usage: read/write
The variables spl0 and spl1 represent the current left and right samples in @sample code .

The normal +0dB range is -1.0 .. 1.0, but overs are allowed (and will eventually be clipped if not reduced by a later effect).

On a very basic level, these values represent the speaker position at the point in time, but if you need more information you should do more research on PCM audio.

If the effect is operating on a track that has more than 2 channels, then spl2..splN will be set with those channels values as well. If you do not modify a splX variable, it will be passed through unmodified.

See also spl() (though spl0 etc are slightly faster than spl()).
slider1, slider2, ... slider16
Context: available everywhere
Usage: read/write
The variables slider1, slider2, ... slider16 allow interaction between the user and the effect, allowing the effects parameters to be adjusted by the user and likewise allow the effect to modify the parameters shown to the user (if you modify sliderX in a context other than @slider then you should call sliderchange(sliderX) to notify JS to refresh the control).

The values of these sliders are purely effect-defined, and will be shown to the user, as well as tweaked by the user.
trigger
Context: @block, @sample
Usage: read/write
The trigger variable provides a facility for triggering effects.

If this variable is used in an effect, the UI will show 10 trigger buttons, which when checked will result in the appropriate bit being set in this variable.

For example, to check for trigger 5 (triggered also by the key '5' on the keyboard):
```
      isourtrig = trigger & (2^5);
```
Conversely, to set trigger 5:
```
      trigger |= 2^5;
```
Or, to clear trigger 5:
```
      trigger & (2^5) ? trigger -= 2^5;
```
It is recommended that you use this variable in @block, but only sparingly in @sample.

Audio and transport state:

srate
Context: available everywhere
Usage: read-only
The srate variable is set by the system to whatever the current sampling frequency is set to (usually 44100 to 192000). Generally speaking your @init code section will be called when this changes, though it's probably a good idea not to depend too much on that.
num_ch
Context: most contexts (see comments)
Usage: read-only
Specifies the number of channels available (usually 2). Note however splXX are still available even if this count is less, their inputs/outputs are just ignored.
samplesblock
Context: most contexts (see comments)
Usage: read-only
The samplesblock variable can be used within @block code to see how many samples will come before the next @block call. It may also be valid in other contexts (though your code should handle invalid values in other contexts with grace).
tempo
Context: @block, @sample
Usage: read-only
The current project tempo, in "bpm". An example value would be 120.0.
play_state
Context: @block, @sample
Usage: read-only
The current playback state of REAPER (0=stopped, <0=error, 1=playing, 2=paused, 5=recording, 6=record paused).
play_position
Context: @block, @sample
Usage: read-only
The current playback position in REAPER (as of last @block), in seconds.
beat_position
Context: @block, @sample
Usage: read-only The current playback position (as of last @block) in REAPER, in beats (beats = quarternotes in /4 time signatures).

Extended Functionality:

ext_noinit
Context: @init only
Set this variable to 1.0 in your @init section if you do not wish for @init to be called (and variables/RAM to be possibly cleared) on every transport start.
ext_nodenorm
Context: @init only
Set this variable to 1.0 in your @init section if you do not wish to have anti-denormal noise added to input.
reg00-reg99
Context: available everywhere
Usage: read/write
The 100 variables reg00, reg01, reg02, .. reg99 are shared across all effects and can be used for inter-effect communication. Their use should be documented in the effect descriptions to avoid collisions with other effects.

Delay Compensation (PDC):

pdc_delay
Context: @block, @slider
Usage: read-write
The current delay added by the plug-in, in samples. Note that you shouldnt change this too often. This specifies the amount of the delay that should be compensated, however you need to set the pdc_bot_ch and pdc_top_ch below to tell JS which channels should be compensated.
pdc_bot_ch, pdc_top_ch
Context: @block, @slider
Usage: read-write
The channels that are delayed by pdc_delay. For example:
```
    pdc_bot_ch=0; pdc_top_ch=2; // delays the first two channels (spl0/spl1).
    pdc_bot_ch=2; pdc_top_ch=5; // delays channels spl2,spl3, and spl4.
    
```
(this is provided so that channels you dont delay can be properly synchronized by the host).
pdc_midi
Context: @block, @slider
Usage: read-write
If set to 1.0, this will delay compensate MIDI as well as any specified audio channels.

Graphics and Mouse:
Note: these should all only be accessed from within the @gfx code section:

gfx_r, gfx_g, gfx_b, gfx_a
These represent the current red, green, blue, and alpha components used by drawing operations (0.0..1.0).
gfx_w, gfx_h
These are set to the current width and height of the framebuffer you will be drawing to.
gfx_x, gfx_y
These set the "current" graphics position in x,y. You can set these yourselves, and many of the drawing functions update them as well.
gfx_mode
Set to 0 for default options. Add 1.0 for additive blend mode (if you wish to do subtractive, set gfx_a to negative and use gfx_mode as additive). Add 2.0 to disable source alpha for gfx_blit(). Add 4.0 to disable filtering for gfx_blit().
gfx_clear
If set to a value of >= 0.0, this will result in the framebuffer being cleared to that color. the color for this one is packed RGB (0..255), i.e. red+green*256+blue*65536. The default is 0. Or you could just clear manually using lice_rectto.
gfx_texth
Read-only, set to the height of text rendering. Eventually this may be read/write but for now it's readonly, and usually 8.
mouse_x, mouse_y, mouse_cap
mouse_x and mouse_y are set to the coordinates of the mouse. If the user is clicking and dragging the mouse within the UI/graphics area, mouse_cap is set to nonzero (1 if left mouse down, 2 if right - 4,8,16 will be set for control,shift, alt).