REAPER JSFX SDK

https://www.reaper.fm/sdk/js/
Admin
REAPER JSFX SDK is a comprehensive reference guide and documentation for programming custom audio...
Tokens:17,638
Snippets:229
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Pattern Matching with Wildcards

Source: https://www.reaper.fm/sdk/js/strings.php

Examples of using the match function with wildcard characters to search for substrings.

```text
    match("*blah*", "this string has the word blah in it") == 1
    match("*blah", "this string ends with the word blah") == 1
```

--------------------------------

### Defining Compile-time JSFX Configuration

Source: https://www.reaper.fm/sdk/js/preproc.php

Example of defining a configuration item in a JSFX plugin that appears in the user interface.

```EEL2
config: nch "Channels" 8 1 2 4 8="8 (namesake)" 12 16 24 32 48
```

--------------------------------

### mem_insert_shuffle(buf, len, value)

Source: https://www.reaper.fm/sdk/js/advfunc.php

Shuffles a buffer to the right by one element, inserting a new value at the start.

```APIDOC
## mem_insert_shuffle(buf, len, value)

### Description
Shuffles buf to the right by one element, inserting value as buf[0], and returning the previous buf[len-1].

### Parameters
- **buf** (buffer) - The buffer to shuffle.
- **len** (number) - The length of the buffer.
- **value** (number) - The value to insert.
```

--------------------------------

### Looping with loop()

Source: https://www.reaper.fm/sdk/js/basiccode.php

Executes a block of code a fixed number of times. The loop count is evaluated only once at the start.

```JSFX
      loop(32, 
         r += b;
         b = var * 1.5;
      );
```

--------------------------------

### Define External Files

Source: https://www.reaper.fm/sdk/js/index.php

Registers files for use within the effect. Indices must be sequential starting from 0.

```JSFX
filename:0 ,filename.wav
```

--------------------------------

### Dynamic State Initialization with Preprocessor

Source: https://www.reaper.fm/sdk/js/preproc.php

Using the preprocessor loop and printf to generate repetitive initialization code.

```EEL2
  <? x_size = 16; /* near the start of file, perhaps */ ?>

  ...

  <?
     // x_size will still be set
     loop(i=0;x_size, printf("x%02d=0;\n", i); i += 1);
  ?>
```

--------------------------------

### Perform FFT and permutation on a memory buffer

Source: https://www.reaper.fm/sdk/js/advfunc.php

Demonstrates the sequence of FFT, permutation, modification, inverse permutation, and IFFT. Note that outputs must be scaled by 1/size.

```JSFX
      buffer=0;
      fft(buffer, 512);
      fft_permute(buffer, 512);
      buffer[32]=0;
      fft_ipermute(buffer, 512);
      ifft(buffer, 512);
      // need to scale output by 1/512.0, too.
```

--------------------------------

### Manual State Initialization

Source: https://www.reaper.fm/sdk/js/preproc.php

Standard manual approach to initializing a state of 16 variables.

```EEL2
  x00=0; x01=0; x02=0; x03=0; x04=0; x05=0; x06=0; x07=0;
  x08=0; x09=0; x10=0; x11=0; x12=0; x13=0; x14=0; x15=0;
```

--------------------------------

### Blitting with gfx_blitext

Source: https://www.reaper.fm/sdk/js/gfx.php

Configures a memory buffer with 10 parameters to define source, destination, and rotation offsets before calling gfx_blitext.

```eel
  coordinatelist=1000; // use memory slots 1000-1009
  coordinatelist[0]=source_x;
  coordinatelist[1]=source_y;
  coordinatelist[2]=source_w;
  coordinatelist[3]=source_h;
  coordinatelist[4]=dest_x;
  coordinatelist[5]=dest_y;
  coordinatelist[6]=dest_w;
  coordinatelist[7]=dest_h;
  coordinatelist[8]=rotation_x_offset; // only used if rotation is set, represents offset from center of image
  coordinatelist[9]=rotation_y_offset; // only used if rotation is set, represents offset from center of image
  gfx_blitext(img,coordinatelist,angle);
```

--------------------------------

### gfx_getchar

Source: https://www.reaper.fm/sdk/js/gfx.php

Retrieves keyboard input or window information.

```APIDOC
## gfx_getchar([char, unicodechar])

### Description
If no parameter or zero is passed, returns a character from the plug-in window's keyboard queue. If char is passed and nonzero, returns whether that key is currently down.
```

--------------------------------

### fft(start_index, size) / ifft(start_index, size)

Source: https://www.reaper.fm/sdk/js/advfunc.php

Performs a Fast Fourier Transform or inverse FFT on data in the local memory buffer.

```APIDOC
## fft(start_index, size) / ifft(start_index, size)

### Description
Performs a FFT or inverse FFT on the data in the local memory buffer. Requires real/imaginary input pairs.

### Parameters
- **start_index** (number) - The offset in the local memory buffer.
- **size** (number) - The size of the FFT. Must be 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, or 32768.
```

--------------------------------

### gfx_printf

Source: https://www.reaper.fm/sdk/js/gfx.php

Formats and draws a string.

```APIDOC
## gfx_printf(str, ...)

### Description
Formats and draws a string at the current cursor position.
```

--------------------------------

### export_buffer_to_project

Source: https://www.reaper.fm/sdk/js/advfunc.php

Writes audio contents from a buffer to an audio file and inserts it into the project. Must be called from the @gfx section.

```APIDOC
## export_buffer_to_project(buffer, length_samples, nch, srate, track_index[, flags, tempo, planar_pitch])

### Description
Writes the audio contents of buffer(s) to an audio file and inserts into project. This may only be called from the @gfx section.

### Parameters
- **buffer** (pointer) - Required - Pointer to the first sample of the first channel of audio data
- **length_samples** (number) - Required - Number of samples to write
- **nch** (number) - Required - Number of channels to write
- **srate** (number) - Required - Samplerate to write
- **track_index** (number) - Required - Track index to insert media
- **flags** (bitmask) - Optional - Bitmask for stretch/loop/tempo matching options
- **tempo** (number) - Optional - Sets project tempo if 0x20000 flag is set
- **planar_pitch** (number) - Optional - If nonzero, specifies channel separation in buffer
```

--------------------------------

### Open a file handle

Source: https://www.reaper.fm/sdk/js/file.php

Opens a file for reading using different input methods such as filename lists, sliders, or strings.

```JSFX
      filename:0,myfile.wav
      handle = file_open(0);
```

```JSFX
      slider1:/mydata:mydef.wav:WAV File
      handle = file_open(slider1);
```

```JSFX
      handle = file_open(string);
```

--------------------------------

### Accessing samples programmatically with spl()

Source: https://www.reaper.fm/sdk/js/vars.php

Use the spl() function to access audio channels dynamically using an index variable.

```JSFX
  spl(channelindex)=somevalue;
  spl(5)+=spl(3);
```

--------------------------------

### file_open(index or slider or string)

Source: https://www.reaper.fm/sdk/js/file.php

Opens a file from the effect filename list, a file slider, or an absolute path string. Returns a file handle or < 0 on failure.

```APIDOC
## file_open(index or slider or string)

### Description
Opens a file for reading. The search path depends on the input method, generally checking the current effect path and the JS Data/ directory.

### Parameters
- **index/slider/string** (mixed) - Required - The file identifier, slider reference, or absolute file path.
```

--------------------------------

### gfx_showmenu(str)

Source: https://www.reaper.fm/sdk/js/gfx.php

Displays a popup menu at the current gfx_x, gfx_y coordinates. The string parameter defines menu items separated by '|', with special prefixes for formatting and submenus.

```APIDOC
## gfx_showmenu(str)

### Description
Shows a popup menu at gfx_x, gfx_y. The input string contains fields separated by '|'. Special characters at the start of fields define item behavior: '#' (grayed), '!' (checked), '>' (submenu start), '<' (submenu end).

### Parameters
- **str** (string) - Required - A pipe-separated list of menu items.

### Returns
- **integer** - Returns 0 if nothing is selected, or the 1-based index of the selected item.
```

--------------------------------

### Implement Namespace Pseudo-Objects

Source: https://www.reaper.fm/sdk/js/userfunc.php

Use 'instance' or 'this' to access relative namespaces for object-style programming.

```JSFX
  function set_foo(x) instance(foo)
  (
    foo = x;
  );
  // or
  function set_foo(x)
  (
    this.foo = x;
  );

  whatever.set_foo(32); // whatever.foo = 32;
  set_foo(32); // set_foo.foo = 32;

  function test2()
  (
    this.set_foo(32);
  );
  whatever.test2(); // whatever.foo = 32
```

--------------------------------

### __memtop()

Source: https://www.reaper.fm/sdk/js/advfunc.php

Returns the total number of memory slots available to the plug-in.

```APIDOC
## __memtop()

### Description
Returns the total number of memory slots available to the plug-in.
```

--------------------------------

### Pass Namespaces as Parameters

Source: https://www.reaper.fm/sdk/js/userfunc.php

Use the '*' suffix on parameter names to accept and combine namespaces.

```JSFX
  function copy_from(src*, src2*, scale)
  (
    this.value = src2.value * src.value * scale;
  );
  obj1.copy_from(obj2, obj3, 1.0);
```

--------------------------------

### gfx_blit

Source: https://www.reaper.fm/sdk/js/gfx.php

Copies a bitmap to the screen.

```APIDOC
## gfx_blit(source, scale, rotation[, srcx, srcy, srcw, srch, destx, desty, destw, desth, rotxoffs, rotyoffs])

### Description
Copies a source bitmap to the screen with optional scaling, rotation, and coordinate mapping.
```

--------------------------------

### Set Plugin Options

Source: https://www.reaper.fm/sdk/js/index.php

Configures various plugin behaviors such as memory allocation, keyboard input, and UI/gfx processing.

```JSFX
options:gmem=someUniquelyNamedSpace
```

```JSFX
options:want_all_kb
```

```JSFX
options:maxmem=XYZ
```

```JSFX
options:prealloc=XYZ
```

```JSFX
options:no_meter
```

```JSFX
options:gfx_idle
```

```JSFX
options:gfx_idle_only
```

```JSFX
options:gfx_hz=60
```

--------------------------------

### get_host_placement

Source: https://www.reaper.fm/sdk/js/advfunc.php

Retrieves information about the host placement of the FX.

```APIDOC
## get_host_placement([chain_pos, flags])

### Description
Returns track index, or -1 for master track, or -2 for hardware output FX. Populates chain_pos and flags with placement details.
```

--------------------------------

### Navigate Namespace Hierarchy

Source: https://www.reaper.fm/sdk/js/userfunc.php

Use the 'this..' prefix to access parent namespaces.

```JSFX
  function set_par_foo(x) 
  (
    this..foo = x;
  );
  a.set_par_foo(1); // sets foo (global) to 1
  a.b.set_par_foo(1); // sets  a.foo to 1
```

--------------------------------

### gfx_transformblit

Source: https://www.reaper.fm/sdk/js/gfx.php

Blits to destination using a transformation table.

```APIDOC
## gfx_transformblit(srcimg, destx, desty, destw, desth, div_w, div_h, table)

### Description
Blits to destination at (destx,desty), size (destw,desth). Each pair in the table represents a S,T coordinate in the source image, and the table is treated as a left-right, top-bottom list of texture coordinates.
```

--------------------------------

### gfx_blitext(source, coordinatelist, rotation)

Source: https://www.reaper.fm/sdk/js/gfx.php

Blits an image or framebuffer to the screen using parameters stored in a memory buffer.

```APIDOC
## gfx_blitext(source, coordinatelist, rotation)

### Description
This function is a version of gfx_blit that accepts parameters via a memory buffer. It is used to blit images or the main framebuffer with support for rotation.

### Parameters
- **source** (number) - Required - The source image index (0-127) or -1 to use the main framebuffer.
- **coordinatelist** (number) - Required - An index to memory where a list of 10 parameters (source_x, source_y, source_w, source_h, dest_x, dest_y, dest_w, dest_h, rotation_x_offset, rotation_y_offset) are stored.
- **rotation** (number) - Required - The rotation angle to apply.
```

--------------------------------

### Load Image

Source: https://www.reaper.fm/sdk/js/gfx.php

Loads an image from a filename into a specified slot. Returns the image index on success or -1 on failure.

```text
gfx_loadimg(image, filename)
```

--------------------------------

### Match strings with format tags

Source: https://www.reaper.fm/sdk/js/strings.php

Demonstrates extracting values using format tags and assigning them to variables either as function arguments or global variables.

```ReaScript
match("*%4d*","some four digit value is 8000, I say",blah)==1 && blah == 8000
match("*%4{blah}d*","some four digit value is 8000, I say")==1 && blah == 8000
```

--------------------------------

### memcpy(dest, source, length)

Source: https://www.reaper.fm/sdk/js/advfunc.php

Quickly copies regions of the local memory buffer.

```APIDOC
## memcpy(dest, source, length)

### Description
Provides the ability to quickly copy regions of the local memory buffer.

### Parameters
- **dest** (number) - Destination offset.
- **source** (number) - Source offset.
- **length** (number) - Number of items to copy.
```

--------------------------------

### file_avail(handle)

Source: https://www.reaper.fm/sdk/js/file.php

Checks the number of items remaining in the file.

```APIDOC
## file_avail(handle)

### Description
Returns the number of items remaining in read mode, or < 0 in write mode. For text files, returns 0 at EOF and 1 otherwise.

### Parameters
- **handle** (number) - Required - The file handle.
```

--------------------------------

### gfx_loadimg

Source: https://www.reaper.fm/sdk/js/gfx.php

Loads an image from a file into a specific slot.

```APIDOC
## gfx_loadimg(image, filename)

### Description
Load image from filename into slot 0..127 specified by image. Returns the image index if success, otherwise -1 if failure. The image will be resized to the dimensions of the image file.
```

--------------------------------

### Grouping Statements with Parentheses

Source: https://www.reaper.fm/sdk/js/basiccode.php

Shows how to enclose multiple statements in parentheses where the final expression value is returned.

```text
z = (
       a = 5; 
       b = 3; 
       a+b;
     ); // z will be set to 8, for example
```

--------------------------------

### mdct(start_index, size) / imdct(start_index, size)

Source: https://www.reaper.fm/sdk/js/advfunc.php

Performs a modified DCT or inverse MDCT on data in the local memory buffer.

```APIDOC
## mdct(start_index, size) / imdct(start_index, size)

### Description
Performs a modified DCT (or inverse in the case of imdct()) on the data in the local memory buffer at the offset specified by the first parameter. The MDCT takes the number of inputs provided and replaces the first half with results, while the IMDCT takes size/2 inputs and gives size results.

### Parameters
- **start_index** (number) - The offset in the local memory buffer.
- **size** (number) - The size of the MDCT/IMDCT. Must be one of: 64, 128, 256, 512, 1024, 2048, or 4096.
```

--------------------------------

### gfx_rectto

Source: https://www.reaper.fm/sdk/js/gfx.php

Fills a rectangle from the current cursor position to the specified coordinates.

```APIDOC
## gfx_rectto(x,y)

### Description
Fills a rectangle from gfx_x, gfx_y to x, y and updates the cursor position to x, y.
```

--------------------------------

### match(pattern, string, [variable])

Source: https://www.reaper.fm/sdk/js/strings.php

The match function compares a string against a pattern. It supports format specifiers like %d and allows capturing values into variables.

```APIDOC
## match(pattern, string, [variable])

### Description
Matches a string against a pattern. Supports format specifiers and optional variable assignment for captured values.

### Parameters
- **pattern** (string) - The pattern to match against, supporting format specifiers like %d.
- **string** (string) - The input string to be evaluated.
- **variable** (variable) - Optional. A variable to store the matched value.

### Usage Example
```
match("*%4d*","some four digit value is 8000, I say",blah)==1 && blah == 8000
match("*%4{blah}d*","some four digit value is 8000, I say")==1 && blah == 8000
```
```

--------------------------------

### spl(channelindex)

Source: https://www.reaper.fm/sdk/js/vars.php

Accesses audio samples programmatically by channel index. This is useful for dynamic channel mapping.

```APIDOC
## spl(channelindex)

### Description
Accesses the audio sample for a specific channel index. This function is used when the channel index is determined dynamically at runtime.

### Context
@sample only

### Syntax
`spl(channelindex) = somevalue;`
`spl(5) += spl(3);`
```

--------------------------------

### Looping Constructs

Source: https://www.reaper.fm/sdk/js/basiccode.php

Control flow functions for repeating code blocks in JSFX.

```APIDOC
## loop(count, code)

### Description
Evaluates the provided code block a specified number of times. The count is evaluated only once at the start.

### Parameters
- **count** (number): The number of iterations.
- **code** (expression): The code block to execute.

## while(code)

### Description
Evaluates the code block repeatedly until the last statement in the block evaluates to zero.

### Parameters
- **code** (expression): The code block to execute until the condition is met.
```

--------------------------------

### Define and Call JSFX Functions

Source: https://www.reaper.fm/sdk/js/userfunc.php

Syntax for declaring functions with parameters and calling them from other code blocks.

```JSFX
     function getSampleRate()
     (
       srate; // return srate
     );

     function mySine(x)
     (
       // taylor approximation
       x - (x^3)/(3*2) + (x^5)/(5*4*3*2) - (x^7)/(7*6*5*4*3*2) + (x^9)/(9*8*7*6*5*4*3*2);
     );

     function calculateSomething(x y)
     (
       x += mySine(y);
       x/y;
     );
```

```JSFX
     y = mySine($pi * 18000 / getSampleRate());
     z = calculateSomething(1,2);
```

--------------------------------

### Define Plugin Pins

Source: https://www.reaper.fm/sdk/js/index.php

Exports names for audio/MIDI pins for display in the connector dialog. Specifying 'none' enables processing optimizations for MIDI-only effects.

```JSFX
in_pin:name_1
in_pin:name_2
out_pin:none
```

--------------------------------

### gfx_setfont

Source: https://www.reaper.fm/sdk/js/gfx.php

Configures the current font.

```APIDOC
## gfx_setfont(idx[,fontface, sz, flags])

### Description
Selects and configures a font. idx 0 is default, 1-16 are configurable.
```

--------------------------------

### Conditional Branching with Parentheses

Source: https://www.reaper.fm/sdk/js/basiccode.php

Demonstrates using parentheses to group multiple statements within a conditional expression.

```text
x % 5 ? (
        f += 1;
        x *= 1.5;
      ) : (
        f=max(3,f);
        x=0;
      );
```

--------------------------------

### Using temporary string instances

Source: https://www.reaper.fm/sdk/js/strings.php

Use the # operator to allocate a temporary string instance with limited and unpredictable scope.

```JSFX
   x = #;
   strcpy(x, "hello ");
   strcat(x, "world");
   gfx_drawstr(x);
```

--------------------------------

### gfx_getfont

Source: https://www.reaper.fm/sdk/js/gfx.php

Returns the current font index.

```APIDOC
## gfx_getfont()

### Description
Returns the index of the currently active font.
```

--------------------------------

### Display a popup menu

Source: https://www.reaper.fm/sdk/js/gfx.php

Shows a popup menu at the current gfx_x and gfx_y coordinates. The string argument defines menu items, separators, and submenus using specific control characters.

```jsfx
gfx_showmenu("first item, followed by separator||!second item, checked|>third item which spawns a submenu|#first item in submenu, grayed out|<second and last item in submenu|fourth item in top menu")
```

--------------------------------

### Accessing Local Memory with Brackets

Source: https://www.reaper.fm/sdk/js/basiccode.php

Use brackets to read from or write to the effect's local memory space.

```EEL2
z=x[y]; 
x[y]=z;
```

--------------------------------

### gfx_circle

Source: https://www.reaper.fm/sdk/js/gfx.php

Draws a circle.

```APIDOC
## gfx_circle(x, y, r[, fill, antialias])

### Description
Draws a circle, optionally filling/antialiasing.
```

--------------------------------

### file_rewind(handle)

Source: https://www.reaper.fm/sdk/js/file.php

Resets the file pointer to the beginning of the file.

```APIDOC
## file_rewind(handle)

### Description
Rewinds the current file to the beginning to allow re-reading.

### Parameters
- **handle** (number) - Required - The file handle.
```

--------------------------------

### memset(dest, value, length)

Source: https://www.reaper.fm/sdk/js/advfunc.php

Quickly sets a region of the local memory buffer to a specific value.

```APIDOC
## memset(dest, value, length)

### Description
Provides the ability to quickly set a region of the local memory buffer to a particular value.

### Parameters
- **dest** (number) - Destination offset.
- **value** (number) - The value to set.
- **length** (number) - Number of items to set.
```

--------------------------------

### Send MIDI messages using midisend

Source: https://www.reaper.fm/sdk/js/midi.php

Sends 2 or 3 byte MIDI messages. The old syntax uses a single parameter for the second and third bytes, while the new syntax accepts them as separate arguments.

```JSFX
     midisend(0, $x90, 69, 127); // send note 69 to channel 0 at velocity 127 (new syntax)
     midisend(0, $x90, 69+(127*256)); // send note 69 to channel 0 at velocity 127 (old synatx)
     midisend(10,$xD4,50); // set channel pressure on channel 4 to 50, at 10 samples into current block
```

--------------------------------

### Check file availability

Source: https://www.reaper.fm/sdk/js/file.php

Returns the number of items remaining in the file or status information.

```JSFX
       len=file_avail(handle);
```

--------------------------------

### Pattern Matching

Source: https://www.reaper.fm/sdk/js/strings.php

Functions for searching strings using simplified regex-style wildcards.

```APIDOC
## Pattern Matching

- **match(needle, haystack, ...)**: Search for needle in haystack.
- **matchi(needle, haystack, ...)**: Search for needle in haystack (case insensitive).

Wildcards: * (0+ chars), + (1+ chars), ? (1 char). Supports format specifiers for matching specific data types.
```

--------------------------------

### file_mem(handle, offset, length)

Source: https://www.reaper.fm/sdk/js/file.php

Reads or writes a block of local memory to/from the file.

```APIDOC
## file_mem(handle, offset, length)

### Description
Reads or writes a block of local memory. Returns the actual number of items processed.

### Parameters
- **handle** (number) - Required - The file handle.
- **offset** (number) - Required - Memory offset.
- **length** (number) - Required - Number of items to process.
```

--------------------------------

### Pin Mapper Functions

Source: https://www.reaper.fm/sdk/js/advfunc.php

Functions for interacting with REAPER's pin mapper.

```APIDOC
## Pin Mapper Functions

### get_host_numchan()
Get the number of track or media item take channels.

### set_host_numchan(numchan)
Set the number of track or media item take channels. Only valid in @gfx section.

### get_pin_mapping(inout, pin, startchan, chanmask)
Get a bitfield (maximum 32 bits) representing the channel mappings for this pin.

### set_pin_mapping(inout, pin, startchan, chanmask, mapping)
Set the channel mappings for this pin/startchan/chanmask. Only valid in @gfx section.

### get_pinmapper_flags()
Get the pinmapper flags for this fx.

### set_pinmapper_flags(flags)
Set the pinmapper flags for this fx. Only valid in @gfx section.
```

--------------------------------

### midirecv(offset, msg1, msg23)

Source: https://www.reaper.fm/sdk/js/midi.php

Receives a MIDI message from the input stream.

```APIDOC
## midirecv(offset, msg1, msg23)

### Description
Receives a MIDI message. If only three parameters are passed, the third parameter receives both the second and third bytes of the MIDI message.

### Parameters
- **offset** (number) - Variable to store the sample offset.
- **msg1** (number) - Variable to store the first byte.
- **msg23** (number) - Variable to store the second and third bytes.
```

--------------------------------

### Stack Operations

Source: https://www.reaper.fm/sdk/js/advfunc.php

Functions for managing a small user stack within the code.

```APIDOC
## stack_push(value)
- Pushes value onto the user stack, returns a reference to the value.

## stack_pop(value)
- Pops a value from the user stack into value, or into a temporary buffer if value is not specified, and returns a reference to where the stack was popped.

## stack_peek(index)
- Returns a reference to the item on the top of the stack (if index is 0), or to the Nth item on the stack if index is greater than 0.

## stack_exch(value)
- Exchanges a value with the top of the stack, and returns a reference to the parameter.
```

--------------------------------

### Keyboard Input Handling

Source: https://www.reaper.fm/sdk/js/gfx.php

Retrieves keyboard input or checks key states. Calling this function ensures mouse_cap reflects keyboard modifiers.

```text
gfx_getchar([char, unicodechar])
```

```text
options:want_all_kb
```

--------------------------------

### Execute while loop in JSFX

Source: https://www.reaper.fm/sdk/js/basiccode.php

Implements a C-style while loop with a hard-coded safety limit of 1,000,000 iterations to prevent runtime hangs.

```JSFX
while ( a < 1000 ) (
         a += b;
         b *= 1.5;
       );
```

--------------------------------

### gfx_set

Source: https://www.reaper.fm/sdk/js/gfx.php

Sets the current graphics state variables including color, alpha, mode, and destination.

```APIDOC
## gfx_set(r[g,b,a,mode,dest,a2])

### Description
Sets gfx_r, gfx_g, and gfx_b to the provided r, g, b values. If not specified, gfx_a defaults to 1, gfx_mode defaults to 0, and gfx_a2 defaults to 1.0.
```

--------------------------------

### midisend_buf(offset, buf, len)

Source: https://www.reaper.fm/sdk/js/midi.php

Sends a variable length MIDI message from a buffer, suitable for standard MIDI or SysEx messages.

```APIDOC
## midisend_buf(offset, buf, len)

### Description
Sends a variable length MIDI message from a buffer. Returns the length sent, or 0 on error.

### Parameters
- **offset** (number) - Sample offset within the current block.
- **buf** (number) - Memory address of the buffer containing the MIDI data.
- **len** (number) - Length of the data to send.
```

--------------------------------

### Draw strings sequentially

Source: https://www.reaper.fm/sdk/js/gfx.php

Demonstrates how sequential calls to gfx_drawstr update the cursor position similarly to a single call.

```JSFX
 gfx_drawstr("a"); gfx_drawstr("b");
```

```JSFX
 gfx_drawstr("ab");
```

--------------------------------

### ext_midi_bus

Source: https://www.reaper.fm/sdk/js/midi.php

A variable used to enable support for multiple MIDI buses in JSFX plugins.

```APIDOC
## ext_midi_bus

### Description
Set this variable to 1.0 in the @init block to enable support for MIDI buses. By default, buses other than bus 0 are passed through.
```

--------------------------------

### Send SysEx messages (Deprecated)

Source: https://www.reaper.fm/sdk/js/midi.php

Demonstrates sending a SysEx message using the deprecated midisyx function.

```JSFX
buf[0] = $x01;
     buf[1] = $x02;
     midisyx(offset,buf,2);  // send sysex: f0 01 02 f7
```

--------------------------------

### file_riff(handle, nch, samplerate)

Source: https://www.reaper.fm/sdk/js/file.php

Parses media file headers for channel count and samplerate.

```APIDOC
## file_riff(handle, nch, samplerate)

### Description
Sets the provided parameters to the number of channels and samplerate of a media file.

### Parameters
- **handle** (number) - Required - The file handle.
- **nch** (number) - Required - Variable to store channel count.
- **samplerate** (number) - Required - Variable to store samplerate.
```

--------------------------------

### Looping with while()

Source: https://www.reaper.fm/sdk/js/basiccode.php

Executes a block of code repeatedly until the last statement evaluates to zero.

```JSFX
       while(
         a += b;
         b *= 1.5;
         a < 1000; // as long as a is below 1000, we go again.
       );
```

--------------------------------

### gfx_drawstr

Source: https://www.reaper.fm/sdk/js/gfx.php

Draws a string of text.

```APIDOC
## gfx_drawstr(str[,flags,right,bottom])

### Description
Draws a string at gfx_x, gfx_y. Optional flags and boundaries can be used for alignment and clipping.
```

--------------------------------

### midirecv_buf(offset, buf, maxlen)

Source: https://www.reaper.fm/sdk/js/midi.php

Receives a MIDI message into a buffer. Returns the length of the message, or 0 if no more messages are available.

```APIDOC
## midirecv_buf(offset, buf, maxlen)

### Description
Receives a MIDI message to a buffer, including any SysEx messages whose length is not more than maxlen. If maxlen is smaller than the length of the MIDI message, the message is automatically passed through.

### Parameters
- **offset** (number) - The time offset of the event.
- **buf** (number) - The memory address of the buffer.
- **maxlen** (number) - The maximum length of the message to receive.
```

--------------------------------

### slider_next_chg(sliderindex, nextval)

Source: https://www.reaper.fm/sdk/js/vars.php

Retrieves sample-accurate automation changes for a slider.

```APIDOC
## slider_next_chg(sliderindex, nextval)

### Description
Used for sample-accurate automation. Returns the sample offset of the next automation change and updates the nextval parameter with the value at that offset.

### Context
@block, @sample

### Parameters
- **sliderindex** (number) - The index of the slider to check.
- **nextval** (variable) - The variable to store the value at the returned sample offset.

### Returns
- **offset** (number) - The sample offset of the change, or a non-positive value if no more changes exist.
```

--------------------------------

### midirecv_str(offset, string)

Source: https://www.reaper.fm/sdk/js/midi.php

Receives a MIDI or SysEx message into a string variable. Returns the length of the message on success, or 0 on failure.

```APIDOC
## midirecv_str(offset, string)

### Description
Receives a MIDI or SysEx message to a string. On failure (no more messages), the value of the string is undefined.

### Parameters
- **offset** (number) - The time offset of the event.
- **string** (string) - The string variable to store the message.
```

--------------------------------

### Send variable length MIDI messages with midisend_buf

Source: https://www.reaper.fm/sdk/js/midi.php

Sends variable length MIDI or SysEx messages from a buffer. Automatically handles leading 0xf0 and trailing 0xf7 bytes for SysEx if necessary.

```JSFX
     buf = 100000;
     buf[0] = $x90;
     buf[1] = 69;
     buf[2] = 127;
     midisend_buf(10,buf,3); // send (at sample offset 10) note-on channel 0, note 69, velocity 127

     buf[0] = $xf0;
     buf[1] = $x01;
     ...
     buf[n] = $xf7;
     midisend_buf(0,buf,n+1); // send sysex f0 01 .. f7
```

--------------------------------

### midi_bus

Source: https://www.reaper.fm/sdk/js/midi.php

A variable representing the current MIDI bus index (0-15).

```APIDOC
## midi_bus

### Description
If ext_midi_bus is enabled, this variable is set by midirecv() to the MIDI bus of the event and is used by midisend() to route the event accordingly.
```

--------------------------------

### gfx_arc

Source: https://www.reaper.fm/sdk/js/gfx.php

Draws an arc of a circle.

```APIDOC
## gfx_arc(x, y, r, ang1, ang2[, antialias])

### Description
Draws an arc of the circle centered at x,y, with ang1/ang2 being specified in radians.
```

--------------------------------

### file_var(handle, variable)

Source: https://www.reaper.fm/sdk/js/file.php

Reads or writes a variable to/from the file.

```APIDOC
## file_var(handle, variable)

### Description
Reads or writes a variable depending on the current file mode (e.g., @serialize mode).

### Parameters
- **handle** (number) - Required - The file handle.
- **variable** (variable) - Required - The variable to read or write.
```

--------------------------------

### gfx_triangle

Source: https://www.reaper.fm/sdk/js/gfx.php

Fills a triangle or convex polygon.

```APIDOC
## gfx_triangle(x1, y1, x2, y2, x3, y3[, x4, y4, ...])

### Description
Fills a triangle (or a convex polygon if more than 3 pairs of coordinates are specified).
```

--------------------------------

### gfx_lineto

Source: https://www.reaper.fm/sdk/js/gfx.php

Draws a line from the current cursor position to the specified coordinates.

```APIDOC
## gfx_lineto(x,y,aa)

### Description
Draws a line from gfx_x, gfx_y to x, y. Updates gfx_x and gfx_y to the new coordinates. If aa is 0.5 or greater, antialiasing is applied.
```

--------------------------------

### file_string(handle, str)

Source: https://www.reaper.fm/sdk/js/file.php

Reads or writes a string from or to a file handle. Behavior varies based on whether the operation is on a normal file or within @serialize.

```APIDOC
## file_string(handle, str)

### Description
Reads or writes a string from/to the file handle. If operating on a normal file, the string will be a line of text. If in @serialize, the string is encoded as a binary-safe blob with length.

### Parameters
- **handle** (handle) - Required - The file handle to read from or write to.
- **str** (string) - Required - The string to write to the file handle.
```

--------------------------------

### time([v])

Source: https://www.reaper.fm/sdk/js/basiccode.php

Returns the current time as seconds since January 1, 1970 with 1 second granularity.

```APIDOC
## time([v])

### Description
Returns the current time as seconds since January 1, 1970. 1 second granularity. If a parameter is specified, it will be set to the timestamp.
```

--------------------------------

### midisend(offset, msg1, msg2, [msg3])

Source: https://www.reaper.fm/sdk/js/midi.php

Sends a 2 or 3 byte MIDI message. If only three parameters are specified, the second lowest byte of the third parameter is used as the third byte.

```APIDOC
## midisend(offset, msg1, msg2, [msg3])

### Description
Sends a 2 or 3 byte MIDI message. Returns 0 on failure, otherwise returns msg1.

### Parameters
- **offset** (number) - Sample offset within the current block.
- **msg1** (number) - First byte of the MIDI message.
- **msg2** (number) - Second byte of the MIDI message.
- **msg3** (number) - Optional third byte of the MIDI message (or combined second and third bytes).
```

--------------------------------

### while(condition) ( code )

Source: https://www.reaper.fm/sdk/js/basiccode.php

Evaluates the condition and executes the code block repeatedly as long as the condition is non-zero. Includes a safety limit of 1,000,000 iterations to prevent runtime hangs.

```APIDOC
## while(condition) ( code )

### Description
Evaluates the parameter, and if nonzero, evaluates the following code block, and repeats. This is similar to a C style while() construct.

### Note
In the interest of avoiding common runtime hangs, the repeat count will be limited to approximately 1,000,000.
```

--------------------------------

### Receive MIDI messages into a buffer

Source: https://www.reaper.fm/sdk/js/midi.php

Uses midirecv_buf to process MIDI events, filtering note-on messages while passing others through.

```JSFX
@block
    buf = 10000;
    maxlen = 65536;
    while ((recvlen = midirecv_buf(offset,buf,maxlen)) > 0) (
       recvlen <= 3 && buf[0] == $x90 && buf[2] !=0 ? (
         noteon_cnt+=1; // count note-ons
       ) : (
         midisend_buf(offset,buf,recvlen); // passthrough other events
       )
    );
```

--------------------------------

### Configure Delay Compensation Channels

Source: https://www.reaper.fm/sdk/js/vars.php

Sets the range of channels to be affected by the pdc_delay variable.

```text
    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.
```

--------------------------------

### midisend_str(offset, string)

Source: https://www.reaper.fm/sdk/js/midi.php

Sends a variable length MIDI message from a string.

```APIDOC
## midisend_str(offset, string)

### Description
Sends a variable length MIDI message from a string. Returns the length sent, or 0 on error.

### Parameters
- **offset** (number) - Sample offset within the current block.
- **string** (string) - String containing the MIDI message bytes.
```

--------------------------------

### Defining Global Memory Namespaces

Source: https://www.reaper.fm/sdk/js/basiccode.php

Specify a unique namespace for gmem to isolate shared memory between specific plug-ins.

```EEL2
options:gmem=someUniquelyNamedSpace
```

--------------------------------

### gfx_deltablit

Source: https://www.reaper.fm/sdk/js/gfx.php

Performs a delta blit operation from a source image to a destination.

```APIDOC
## gfx_deltablit(srcimg, srcx, srcy, srcw, srch, destx, desty, destw, desth, dsdx, dtdx, dsdy, dtdy, dsdxdy, dtdxdy[, usecliprect=1])

### Description
Blits from srcimg(srcx,srcy,srcw,srch) to destination (destx,desty,destw,desth). Source texture coordinates are s/t, dsdx represents the change in s coordinate for each x pixel, dtdy represents the change in t coordinate for each y pixel, etc.
```

--------------------------------

### gfx_gradrect

Source: https://www.reaper.fm/sdk/js/gfx.php

Fills a gradient rectangle with specified color and alpha.

```APIDOC
## gfx_gradrect(x, y, w, h, r, g, b, a[, drdx, dgdx, dbdx, dadx, drdy, dgdy, dbdy, dady])

### Description
Fills a gradient rectangle with the color and alpha specified. Parameters drdx-dadx reflect the adjustment (per-pixel) applied for each pixel moved to the right, drdy-dady are the adjustment applied for each pixel moved toward the bottom.
```

--------------------------------

### Resize Image

Source: https://www.reaper.fm/sdk/js/gfx.php

Resizes an image referenced by index 0-127. The contents become undefined after resizing.

```text
gfx_setimgdim(image, w,h)
```

--------------------------------

### Receive and filter MIDI events with midirecv

Source: https://www.reaper.fm/sdk/js/midi.php

Processes incoming MIDI events in a loop. If a function is called, all events must be retrieved and those not processed must be passed through.

```JSFX
  @block
    while (midirecv(offset,msg1,msg2,msg3)) ( // REAPER 4.59+ syntax while()
       msg1==$x90 && msg3!=0 ? (
         noteon_cnt+=1; // count note-ons
       ) : (
         midisend(offset,msg1,msg2,msg3); // passthrough other events
       )
    );
```

--------------------------------

### Import External Files

Source: https://www.reaper.fm/sdk/js/index.php

Imports functions and sections from another JSFX file. Files intended for import should use the .jsfx-inc extension.

```JSFX
import filename
```

--------------------------------

### gfx_setimgdim

Source: https://www.reaper.fm/sdk/js/gfx.php

Resizes an image referenced by index.

```APIDOC
## gfx_setimgdim(image, w, h)

### Description
Resize image referenced by index 0..127, width and height must be 0-2048. The contents of the image will be undefined after the resize.
```

--------------------------------

### Send MIDI messages from a string using midisend_str

Source: https://www.reaper.fm/sdk/js/midi.php

Sends variable length MIDI or SysEx messages defined as a string.

```JSFX
     midisend_str(10,"
\x90\x11\x7f"); // send at sample offset 10, note-on, note 17, velocity 127
```

--------------------------------

### gfx_setcursor(resource_id[, "custom cursor name"])

Source: https://www.reaper.fm/sdk/js/gfx.php

Sets the mouse cursor to a specified resource ID or a custom cursor name.

```APIDOC
## gfx_setcursor(resource_id[, "custom cursor name"])

### Description
Sets the mouse cursor. resource_id is a numeric identifier (e.g., 32512 for arrow). If provided, the custom cursor name string overrides the resource_id if available.

### Parameters
- **resource_id** (integer) - Required - The numeric ID of the cursor.
- **custom_cursor_name** (string) - Optional - A string description to override the resource_id.
```

--------------------------------

### Formatted String Generation

Source: https://www.reaper.fm/sdk/js/strings.php

Function for creating formatted strings using C-style printf modifiers.

```APIDOC
## sprintf(str, format, ...)

Copies format to str, converting format strings. Supports standard C printf modifiers and custom specifiers like %s, %d, %f, %x, etc.
```

--------------------------------

### Rewind a file

Source: https://www.reaper.fm/sdk/js/file.php

Resets the file pointer to the beginning of the file.

```JSFX
       file_rewind(handle);
```

--------------------------------

### gfx_blurto

Source: https://www.reaper.fm/sdk/js/gfx.php

Applies a blur effect to a region.

```APIDOC
## gfx_blurto(x,y)

### Description
Blurs the screen region between the current cursor and the specified coordinates.
```

--------------------------------

### file_text(handle, istext)

Source: https://www.reaper.fm/sdk/js/file.php

Checks if the file is a text file.

```APIDOC
## file_text(handle, istext)

### Description
Returns 1 if the file is a text file. Used to determine if text-specific parsing logic is required.

### Parameters
- **handle** (number) - Required - The file handle.
```

--------------------------------

### Parse RIFF media files

Source: https://www.reaper.fm/sdk/js/file.php

Extracts channel count and sample rate from media files like WAV or OGG.

```JSFX
      file_riff(handle,nch,samplrate);
      nch ? file_mem(handle,0,file_avail(0));
```

--------------------------------

### Draw Circle

Source: https://www.reaper.fm/sdk/js/gfx.php

Draws a circle with optional fill and antialiasing.

```text
gfx_circle(x,y,r[,fill,antialias])
```

--------------------------------

### Read or write a variable

Source: https://www.reaper.fm/sdk/js/file.php

Reads or writes a variable to the file depending on the current mode.

```JSFX
       file_var(handle,myVar);
```

--------------------------------

### gfx_rect

Source: https://www.reaper.fm/sdk/js/gfx.php

Fills a rectangle at a specific location with given dimensions.

```APIDOC
## gfx_rect(x,y,w,h)

### Description
Fills a rectangle starting at x, y with width w and height h.
```

--------------------------------

### Check text file mode

Source: https://www.reaper.fm/sdk/js/file.php

Determines if the opened file is a text file.

```JSFX
      istext=file_text(handle);
      istext ? use_diff_avail syntax;
```

--------------------------------

### Configure Slider Shaping

Source: https://www.reaper.fm/sdk/js/index.php

Appends log or polynomial shaping to slider increments. Use the ! suffix to preserve automation compatibility when changing shaping types.

```JSFX
slider1 :5 <0 ,10 ,0.1 :log>slider description
```

```JSFX
slider1 :5 <0 ,10 ,0.1 :log=2>slider description
```

```JSFX
slider1 :5 <0 ,10 ,0.1 :sqr>slider description
```

```JSFX
slider1 :5 <0 ,10 ,0.1 :sqr=3>slider description
```

```JSFX
slider1 :5 <0 ,10 ,0.1 :log!>slider description
```

--------------------------------

### gfx_muladdrect

Source: https://www.reaper.fm/sdk/js/gfx.php

Multiplies and adds values to pixels in a rectangle.

```APIDOC
## gfx_muladdrect(x, y, w, h, mul_r, mul_g, mul_b[, mul_a, add_r, add_g, add_b, add_a])

### Description
Multiplies each pixel by mul_* and adds add_*, and updates in-place. Useful for changing brightness/contrast, or other effects.
```

--------------------------------

### Using named string variables

Source: https://www.reaper.fm/sdk/js/strings.php

Use named strings for persistent variables that maintain their state throughout the script's lifecycle.

```JSFX
  x = #myString;
  strcpy(x, "hello world");
```

```JSFX
  #myString = "hello ";  // same as strcpy(#myString, "hello ");
  #myString += "world"; // same as strcat(#myString, "world");
```

--------------------------------

### Math Functions

Source: https://www.reaper.fm/sdk/js/basiccode.php

A collection of mathematical functions for performing calculations within JSFX scripts.

```APIDOC
## Math Functions

### Description
Provides standard mathematical operations including trigonometry, powers, logarithms, and rounding.

### Functions
- **sin(angle)**: Returns the Sine of the angle (radians).
- **cos(angle)**: Returns the Cosine of the angle (radians).
- **tan(angle)**: Returns the Tangent of the angle (radians).
- **asin(x)**: Returns the Arc Sine of the value (radians).
- **acos(x)**: Returns the Arc Cosine of the value (radians).
- **atan(x)**: Returns the Arc Tangent of the value (radians).
- **atan2(x,y)**: Returns the Arc Tangent of x divided by y (radians).
- **sqr(x)**: Returns the square of the parameter.
- **sqrt(x)**: Returns the square root of the parameter.
- **pow(x,y)**: Returns x raised to the power of y.
- **exp(x)**: Returns e raised to the power of x.
- **log(x)**: Returns the natural logarithm of the parameter.
- **log10(x)**: Returns the base 10 logarithm of the parameter.
- **abs(x)**: Returns the absolute value of the parameter.
- **min(x,y)**: Returns the minimum of two values.
- **max(x,y)**: Returns the maximum of two values.
- **sign(x)**: Returns the sign of the parameter (-1, 0, or 1).
- **rand(x)**: Returns a pseudorandom number between 0 and x.
- **floor(x)**: Rounds down to the lowest integer.
- **ceil(x)**: Rounds up to the highest integer.
- **invsqrt(x)**: Returns a fast inverse square root approximation.
```

--------------------------------

### Accessing Global Shared Memory

Source: https://www.reaper.fm/sdk/js/basiccode.php

Use the gmem keyword to access the shared global buffer accessible by all JSFX instances.

```EEL2
z=gmem[y]; 
gmem[y]=z;
```

--------------------------------

### Receive MIDI messages into a string

Source: https://www.reaper.fm/sdk/js/midi.php

Uses midirecv_str to process MIDI events, filtering note-on messages while passing others through.

```JSFX
@block
    while (midirecv_str(offset,#str)) (
       strlen(#str) <= 3 && str_getchar(#str,0) == $x90 && str_getchar(#str,2) != 0 ? (
         noteon_cnt+=1; // count note-ons
       ) : (
         midisend_str(offset,#str);
       )
    );
```
Tokens:
Raw