REAPER | JSFX Programming Reference

back to main JSFX reference page

JSFX Programming Reference - Special Variables

Special Variables

top Special Variables

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(x) below, though splX is generally slightly faster than spl(X)
spl(channelindex) -- REAPER 2.018+
Context: @sample only
If you wish to programmatically choose which sample to access, use this function (rather than splX). This is slightly slower than splX, however has the advantage that you can do spl(variable) (enabling easily configurable channel mappings). Valid syntaxes include:
```
 
  spl(channelindex)=somevalue;
  spl(5)+=spl(3);
```
slider1, slider2, ... sliderX
Context: available everywhere
Usage: read/write
The variables slider1, slider2, ... 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.
slider(sliderindex) -- REAPER 3.11+
Context: available everywhere
If you wish to programmatically choose which slider to access, use this function (rather than sliderX). Valid syntaxes include:
```
 
  val = slider(sliderindex);
  slider(i) = 1;
```
slider_next_chg(sliderindex,nextval) -- REAPER 5.0+
Context: @block, @sample
Used for sample-accurate automation. Each call will return a sample offset, and set nextval to the value at that sample offset. Returns a non-positive value if no changes (or no more changes) are available. Notes:
- If the value of the parameter is constant for the audio block, then the all calls to slider_next_chg() will return -1.
- If the audio block is entirely a linear (or bezier) transition, slider_next_chg() will return samplesblock-1 (and set the value of the second parameter to the value at the END of the audio block).
- If the audio block contains an inflection point, e.g. a square point, or a linear point that causes the slope to change, then slider_next_chg() will return the sample-position of the first inflection point. Calling slider_next_chg() again will return the sample-position of the NEXT inflection point, and so on until returning samplesblock-1, followed by -1 (no more inflection points).
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. You can change the channel count available via in_pin:/out_pin: lines.
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).
ts_num
Context: @block, @sample
Usage: read-only The current time signature numerator, i.e. 3.0 if using 3/4 time.
ts_denom
Context: @block, @sample
Usage: read-only The current time signature denominator, i.e. 4.0 if using 3/4 time.

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. Note that in this case, srate may not be correct in @init, and the JSFX code should check for srate changes in @block or @slider.
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.
ext_tail_size -- REAPER 6.71+
Context: @init, @slider
Set to nonzero if the plug-in produces silence from silence. If positive, specifies length in samples that the plug-in should keep processing after silence (either the output tail length, or the number of samples needed for the plug-in state to settle). If set to -1, REAPER will use automatic output silence detection and let plug-in state settle. If set to -2, then REAPER will assume the plug-in has no tail and no inter-sample state.
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. regXX aliases to _global.regXX.
_global.* -- -- REAPER 4.5+
Context: available everywhere
Usage: read/write
Like regXX, _global.* are variables shared between all instances of all 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:

gfx_* and mouse_* are also defined for use in @gfx code.

MIDI Bus Support:

There are also variables defined for accessing MIDI Buses.