Reaper Preferences General/es and Js programming: Difference between pages

From Reaper Accessibility Wiki
(Difference between pages)
Jump to navigation Jump to search
(Created page with "A continuación se presentan algunas de las opciones en el diálogo de preferencias (control + P) que comúnmente se cambian a partir de sus valores predeterminados. Útil para repasar cuando se está aprendiendo a usar Reaper o después de un reinicio a los valores predeterminados del programa.")
 
 
Line 1: Line 1:
<span id="Preferences"></span>
=js Programming=
= Preferencias =


A continuación se presentan algunas de las opciones en el diálogo de preferencias (control + P) que comúnmente se cambian a partir de sus valores predeterminados. Útil para repasar cuando se está aprendiendo a usar Reaper o después de un reinicio a los valores predeterminados del programa.
== Introduction ==
js plugins are Reaper's own plugin format similar in many ways to VST plugins.  A js plugin can process and generate audio and midi data and expose parameters to the user which can be automated.


<div lang="en" dir="ltr" class="mw-content-ltr">
js plugins have a number of advantages such as easy to start writing, all parameters are exposed and these parameters are easy to interact with via a keyboard either directly in the user interface or by the OSARA parameter dialogue.  They also support graphics making them good for sighted users and it is also possible to add keyboard support though this is almost vanishingly rare.  Disadvantages are around limited to non-existent file handling.
Note that changes to preferences are sticky from one load of Reaper to another.  There are other options in Reaper, such as metronome settings, which are part of the default project settings and only persist once the Save As Default button is used in project settings (alt _+ enter).
</div>


== View and existing js plugin ==
js plugins are written in plain text files and there are plenty to take a look at.  From the Reaper Help Options menu select Resource path.  In here is a folder called "Effects" in which are all the js plugins that come with Reaper.


Typically a js plugin either has no file extension or an extension of jsfx.  Use your favourite plain text editor to open up any of the files to see what they look like.


<div lang="en" dir="ltr" class="mw-content-ltr">
It is useful to turn the vebosity of your screen reader so it speaks all characters.  It is important to capture all the code when programming.  For example, a semicolon is required at the end of each command and most people dont set their screen reader to announce these.
*General
 
** There are tick boxes for what creates an undo item.  Untick to shorten the undo history.
In NVDA, the verbosity can be cycled with NVDA+P.
** Option to preserve undo history when saving a project.
 
** Several options on how Reaper behaves when starting up such as load last project, start a new project or prompt.  Also can check for new versions of Reaper and an option to allow multiple instances of Reaper to be run.
== Structure of a plugin ==
*Paths
A js plugin is made up of a header and then a series of sections which have a predefined named and purpose.
** Option to set a specific folder to store peak files (reapeaks).  Can then clear this folder out from time to time.
 
*Keyboard / multitouch
 
** Recommend ticking Allow space key  to be used for navigation in various windows
The header can be as short as a declaration of the name of the plugin but can also hold much more information such as the author, date, version, release notes, instructions on usage and other information that helps with reaPack integration.
*Projects
 
** Option to define a default project template
 
** Prompt to save on new project. Tick this if you want to be forced to define a path for all your projects which means you know where your media is going.
The header is followed by definition of the plugin parameters which is done by defining a slider for each parameter.  A slider has a min value, a max value, an increment value and a default value.  These are seen by the user in the plugin user interface as a slider and edit box for each parameter.
** Options to autosave project backups into a defined subfolder.  Suggestion is to store to a subfolder called Backups every 10 or 15 minutes. Backup files are generally small.
 
** Option to save the undo history.
 
*Media Item defaults
The @init block is run when the plugin first starts which is typically when it is first loaded onto an FX chain and when play starts. It is used to initialise variables to default values.  Note that the js plugin language does not require variables to be declared before they are used so this section does not need to include initialisation of all variables if this is done elsewhere.  Also, the default initialisation of a variable is to set it to zero.
** Default fade in and fade out time is 10ms.  Can reduce to 3ms to be less obtrusive. Is If looping and splitting samples may want to reduce this to zero to avoid dips in volume between samples. Alternatively, can raise these values to get modulation effects when splitting an item at grid lines.
 
*Audio
 
** Recommended to turn off tiny fade in and fade out on start and stop.
The @slider block is run whenever a parameter is changed either through automation or by the user.  For example, a parameter might be presented to the user as a percentage from 0 to 100 but the code needs this rescaling from -1 to 1.
*Devices and MIDI
 
** Fundamental section specific to equipment set up for input and output of audio and MIDI
 
*Buffering
The @block code is run as a new block of samples arrives.  The block size as defined in Reaper preferences in the devices section dictates how many sampless.  This is an area of code commonly used to process MIDI as all the MIDI notes and events coming up in the next block of samples can be processed and action taken accordingly.  Also, MIDI notes and events can be inserted so they are played once the block enters Reaper's play buffer.
** Can reduce Default Media Buffer size from 1200 to around 100 for more responsivness on playback.
 
*Playback
 
**  Recommend ticking Stop playback at end of loop if repeat is disabled. This links with other settings in Edditing.
The@sample block is run every sample.  So yes, many thousands of times a second.  Commonly used to process audio as there is easy access to the value of the audio in each channel.
*Recording
 
**  Recommend disabling Show preview of recording items while recording
 
** Options to prompt to save or discard newly recorded material on stop.  Often easier to disable this and use control + Z to undo recorded media if new material isn't wanted.
The @gfx block is used to draw graphics and process keyboard input.  I'm not sure when it is run.
** Option to define the name given to newly recorded items
 
*Rendering
== First Audio Plugin ==
** Option to override the default buffer size when rendering which can speed up render times e.g. Can set to 1024.
Let's dive in with a very simple js plugin that includes a volume control for audio.  Open up a plain text editor and copy and paste the following code into it.
** Options to set a tail duration  and when it is applied to capture effects like reverb.
 
*Editting
 
** Can set Move edit cursor to start of time selection on time selection change.  So when ending a time selection with right bracket edit cursor moves to the start of the time selection.
Desc: My first audio plugin
** Option to set moving edit cursor to end of item when pasting. Useful if pasting multiple copies of an item one after another. Can also cause confusion though as means have to rewind to hear newly pasted content.
 
** Link loop points to time selection. Set this to on so that option in Playback section  works effectively. Can unlink loop points and time selection in the options menu if needed for a particular workflow.
 
*Envelope display
slider:100<0,100,1>Volume
** Options here to change the range of volume and pitch envelopes.
 
*Media
 
** Option on copying  media to project directory
@slider
** Options for rendering tails on item FX. Defaults are quite short. Values of 5000 to 10,000 more useful.
 
** Can untick Show status window when generating peaks as this is just annoying.
scaler = slider1/100;
*MIDI
 
** Some default options for how to treat MIDI files being imported
 
*Plugins
@sample
** Numerous options on how to display FX windows.  Typically do want to auto-resize, uncheck auto-float newly created windows, don't want to dock, and tick display only one window at a time but this last doesn't really work very well.
 
*Compatibility
spl0 *= scaler;
** Options in here on how to treat 32-bit plugins by default but can also do this each plugin at a time using the context menu when highlighting a plugin in the FX search dialogue.
 
*VST
spl1 *= scaler;
** Fundamental option to define the paths that Reaper uses when searching for and loading VST's.
 
*External editors
 
** Define the path of external editors
Save this in the Reaper resources Effects folder, ideally in a new subfolder to contain all your plugins.  Start up Reaper and it should do a rescan and make your new js plugin available to use.
</div>
 
 
Create a track and add some audio to it for example recording yourself speaking, by inserting an audio file or selecting something from media explorer.  Hit F on the track to bring up the FX chain dialogue and use the Add button to add your plugin.  Type in "first" as this is text included in the first line of the code copied into the plugin and is the name given to the plugin.  Arrow down and you should find the plugin.  Hit enter and it will get loaded onto the FX chain for the track.  Press tab to work your way through the plugin and you will come to the slider and edit controls for the volume parameter.
 
 
Press space to play the audio and then adjust the volume with either the slider or entering a new value in the edit field.  The volume changes.  Your first plugin.
 
== First MIDI Plugin ==
Here is a simple plugin that has a slider to change the pitch of any incoming MIDI notes.  The minimum code for MIDI is a little more than for audio.
 
 
Desc: My first MIDI js plugin
 
 
slider:0<-24,24,1>Semitone shift
 
 
@slider
 
shift = slider1;
 
 
@block
 
while( midirecv( offset, msg1, msg2, msg3 ) )
 
(
 
  msg1 & 0xF0 = 0x90 ?
 
  (
 
   midisend( offset, msg1, msg2 + shift, msg3 );
 
  )
 
  :
 
  (
 
   midisend( offset, msg1, msg2, msg3 );
 
  );
 
);
 
 
In the same way as with the audio plugin, copy this code into a plain text file and save it in the Effects subfolder in the Reaper resource path ideally in your own subfolder holding all your plugins. Start up Reaper so it does a rescan and then insert reaSynth onto a track as as a VSTi.  Test you can play notes.  Now add your first MIDI plugin onto this track as well.  Before it has any effect thugh yu need to move reaSynth so it is below your first MIDI plugin since the plugin needs to update the MIDI data between it being played and it arriving at reaSynth.  Do this by either cutting and pasting reaSynth so it is second in the chain, or using the action bound to control-shift alt page down (Windows).
 
 
Tab to the Semitone shift slider in your new plugin. Play a note and then change the slider.  The pitch of notes is shifted.
 
== Tools to help write plugins ==
The most basic tool is your plain text editor of choice.  Reaper does have an inbult editor but it is not easily accessible.  So writing code in a plain text editor is the next best thing.  If you make a change to your code and save it though, you will need to return to Reaper and the FX chain , press contrl R on your plugin and replace the plugin with a new instance of itself to for the changes take effect.
 
 
It is possible to view all the variables used in a plugin along with their values.  This can be done with NVDA object navigation by tabbing to the edit button in the FX dialogue, hitting enter , and uing object navigation to move right until a list control is reached.  Gone down and you can then review each variable.
 
 
Debugging is difficult though in js plugins.  There is no option to display a message box or output diagnostic info to a file. And some variables will change their value with every sample or every block making them impossible to track.  You cannot step through the code one line at a time reviewing variable values like you can in more complex IDE's.
 
==Resources ==
 
There are not a whole bunch of great resources for writing js plugins.  Probably the most comprehensive source of information are all the plugins that come with Reaper and found in the Effects folder.  But these can be complex and difficult to work out how they work.
 
There is a good tutorial made by [https://www.admiralbumblebee.com/music/2018/02/08/Write-a-Reaper-MIDI-JSFX-from-scratch.html Admiral Bumblebeee] which goes through a modestly complex project to write a MIDI plugin.  There is also other useful content on this web site.
 
[https://www.reaper.fm/sdk/js/basiccode.php#js_basic The JSFX Programming Reference - Language Essentials] is on Reaper's web site.  It is a reference manual though and not a tutorial but if you get into JSFX programming you will come to appreciate this resource.
 
The Reaper community are a helpful bunch.  [https://forum.cockos.com/forumdisplay.php?f=3 The JSFX forum]. Use the search feature or search with something like Google putting reaper jsfx forum in as part of your search.  Sign up to post a question. 

Revision as of 19:45, 7 November 2023

js Programming

Introduction

js plugins are Reaper's own plugin format similar in many ways to VST plugins.  A js plugin can process and generate audio and midi data and expose parameters to the user which can be automated.

js plugins have a number of advantages such as easy to start writing, all parameters are exposed and these parameters are easy to interact with via a keyboard either directly in the user interface or by the OSARA parameter dialogue.  They also support graphics making them good for sighted users and it is also possible to add keyboard support though this is almost vanishingly rare.  Disadvantages are around limited to non-existent file handling.

View and existing js plugin

js plugins are written in plain text files and there are plenty to take a look at.  From the Reaper Help Options menu select Resource path.  In here is a folder called "Effects" in which are all the js plugins that come with Reaper.

Typically a js plugin either has no file extension or an extension of jsfx.  Use your favourite plain text editor to open up any of the files to see what they look like.

It is useful to turn the vebosity of your screen reader so it speaks all characters.  It is important to capture all the code when programming.  For example, a semicolon is required at the end of each command and most people dont set their screen reader to announce these.

In NVDA, the verbosity can be cycled with NVDA+P.

Structure of a plugin

A js plugin is made up of a header and then a series of sections which have a predefined named and purpose.


The header can be as short as a declaration of the name of the plugin but can also hold much more information such as the author, date, version, release notes, instructions on usage and other information that helps with reaPack integration.


The header is followed by definition of the plugin parameters which is done by defining a slider for each parameter.  A slider has a min value, a max value, an increment value and a default value.  These are seen by the user in the plugin user interface as a slider and edit box for each parameter.


The @init block is run when the plugin first starts which is typically when it is first loaded onto an FX chain and when play starts. It is used to initialise variables to default values.  Note that the js plugin language does not require variables to be declared before they are used so this section does not need to include initialisation of all variables if this is done elsewhere.  Also, the default initialisation of a variable is to set it to zero.


The @slider block is run whenever a parameter is changed either through automation or by the user.  For example, a parameter might be presented to the user as a percentage from 0 to 100 but the code needs this rescaling from -1 to 1.


The @block code is run as a new block of samples arrives.  The block size as defined in Reaper preferences in the devices section dictates how many sampless.  This is an area of code commonly used to process MIDI as all the MIDI notes and events coming up in the next block of samples can be processed and action taken accordingly.  Also, MIDI notes and events can be inserted so they are played once the block enters Reaper's play buffer.


The@sample block is run every sample.  So yes, many thousands of times a second.  Commonly used to process audio as there is easy access to the value of the audio in each channel.


The @gfx block is used to draw graphics and process keyboard input.  I'm not sure when it is run.

First Audio Plugin

Let's dive in with a very simple js plugin that includes a volume control for audio.  Open up a plain text editor and copy and paste the following code into it.


Desc: My first audio plugin


slider:100<0,100,1>Volume


@slider

scaler = slider1/100;


@sample

spl0 *= scaler;

spl1 *= scaler;


Save this in the Reaper resources Effects folder, ideally in a new subfolder to contain all your plugins.  Start up Reaper and it should do a rescan and make your new js plugin available to use.


Create a track and add some audio to it for example recording yourself speaking, by inserting an audio file or selecting something from media explorer.  Hit F on the track to bring up the FX chain dialogue and use the Add button to add your plugin.  Type in "first" as this is text included in the first line of the code copied into the plugin and is the name given to the plugin.  Arrow down and you should find the plugin.  Hit enter and it will get loaded onto the FX chain for the track.  Press tab to work your way through the plugin and you will come to the slider and edit controls for the volume parameter.


Press space to play the audio and then adjust the volume with either the slider or entering a new value in the edit field.  The volume changes.  Your first plugin.

First MIDI Plugin

Here is a simple plugin that has a slider to change the pitch of any incoming MIDI notes.  The minimum code for MIDI is a little more than for audio.


Desc: My first MIDI js plugin


slider:0<-24,24,1>Semitone shift


@slider

shift = slider1;


@block

while( midirecv( offset, msg1, msg2, msg3 ) )

(

  msg1 & 0xF0 = 0x90 ?

  (

   midisend( offset, msg1, msg2 + shift, msg3 );

  )

  :

  (

   midisend( offset, msg1, msg2, msg3 );

  );

);


In the same way as with the audio plugin, copy this code into a plain text file and save it in the Effects subfolder in the Reaper resource path ideally in your own subfolder holding all your plugins. Start up Reaper so it does a rescan and then insert reaSynth onto a track as as a VSTi.  Test you can play notes.  Now add your first MIDI plugin onto this track as well.  Before it has any effect thugh yu need to move reaSynth so it is below your first MIDI plugin since the plugin needs to update the MIDI data between it being played and it arriving at reaSynth.  Do this by either cutting and pasting reaSynth so it is second in the chain, or using the action bound to control-shift alt page down (Windows).


Tab to the Semitone shift slider in your new plugin. Play a note and then change the slider.  The pitch of notes is shifted.

Tools to help write plugins

The most basic tool is your plain text editor of choice.  Reaper does have an inbult editor but it is not easily accessible.  So writing code in a plain text editor is the next best thing.  If you make a change to your code and save it though, you will need to return to Reaper and the FX chain , press contrl R on your plugin and replace the plugin with a new instance of itself to for the changes take effect.


It is possible to view all the variables used in a plugin along with their values.  This can be done with NVDA object navigation by tabbing to the edit button in the FX dialogue, hitting enter , and uing object navigation to move right until a list control is reached.  Gone down and you can then review each variable.


Debugging is difficult though in js plugins.  There is no option to display a message box or output diagnostic info to a file. And some variables will change their value with every sample or every block making them impossible to track.  You cannot step through the code one line at a time reviewing variable values like you can in more complex IDE's.

Resources

There are not a whole bunch of great resources for writing js plugins.  Probably the most comprehensive source of information are all the plugins that come with Reaper and found in the Effects folder.  But these can be complex and difficult to work out how they work.

There is a good tutorial made by Admiral Bumblebeee which goes through a modestly complex project to write a MIDI plugin.  There is also other useful content on this web site.

The JSFX Programming Reference - Language Essentials is on Reaper's web site.  It is a reference manual though and not a tutorial but if you get into JSFX programming you will come to appreciate this resource.

The Reaper community are a helpful bunch.  The JSFX forum. Use the search feature or search with something like Google putting reaper jsfx forum in as part of your search. Sign up to post a question.