Editing and Js programming: Difference between pages

From Reaper Accessibility Wiki
(Difference between pages)
Jump to navigation Jump to search
VisualWikitext
(initial page migration)
 
 
Line 1: Line 1:
==Inserting Silence==
=js Programming=
===I want to insert silence at the start of my project===
The following steps insert silence at the start of the project moving all existing items to the right.
* In the main track view go to the start of the project with control home.
* Press left bracket, [, to start a time selection.
* Move to the right by the amount of silence you want to insert.  For example, you can move right four bars by pressing Page Down four times.
* Press right bracket, ], to end the time selection.
* Bring up the context menu.  In Windows this is the application key.
* Arrow down to the menu item Insert Empty Space in Selection.


All existing items will be moved right by the size of the time selection. All tracks are affected and happens regardless of the current ripple mode.
== 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.


You can carry out the insertion of empty space by running the action from the action list (F4) which is by default bound to control + alt + Insert (you have to double tap the Insert key).
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.


It is a good idea to clear the time selection by pressing Escape before playing as typically the play cursor is at the start of the time selection which is now all silence.
== 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.


===Inserting Silence In the Middle Of A Project===
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.
Inserting silence in the middle of a project works in just the same way as inserting silence at the beginning.
* Start a time selection at the point you want to insert silence.
* Move right by the amount of silence you want to insert and end the time selection.
* Use either the Insert Empty Space  in Selection menu item in the context menu, run the action or use the keyboard shortcut to add the silence.
* If needed, items will be split in order to move content to the right.  Default fade out and fade ins will be applied to split items.
===Silencing a Time Selection without Moving Proceeding Content===
Let's say you're trying to mute a section with a major noise presence, but you've no reason to change the timing of anything else.
* Start a time selection at the beginning of the section you want muted.
* Go to the end of the offending section, then end your time selection.
* now, ensure you're focused on the track, or tracks, where the offending section takes place. You are able to use your shift+up or down arrow to select multiple tracks contiguously, or your shift+space for noncontiguous selection if necessary.
* Now, press Alt+SHIFT+A, Option+Shift+A on mac, to select all items on selected track or tracks within time selection.
* Finally, press CTRL+Windows+Delete, command+CTRL+FN+Backspace on Mac, to remove selected area of items. This will mute your entire time selection without affecting the surrounding contents.


==Selecting Tracks and Items and Reporting What Is Selected==
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.


===Single Track Selection and Reporting===
In NVDA, the verbosity can be cycled with NVDA+P.


To select a single track use the up and down arrow keys to move through the tracks.  OSARA reports the track name as you go.
== 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.


You can also select a track with reaConsole.  Start reaCConsole with alt + C and then type a capital S followed by the track number.  Or a capital S followed by the track name or start of the track name.  For example, typing S3 will go to track 3.  Typing Str will go to a track called "trumpet".  If there are two tracks starting with "tr" however no selection is made. To make the selection either press enter or press control enter which closes the console dialogue at the same time otherwise it remains open.


After moving between tracks, press control + shift + space to have OSARA report the currently selected track.
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.


===Selecting An Item and reporting===


When on a track containing items press control + left arrow or control + right arrow. Reaper moves to the next item to the left or right of the current edit cursor position.  OSARA will announce the item name and its position.
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.


If you are to the left of all items and press control + left arrow then nothing will get selected.  Similarly, if you are to the right of all items and press control + right then nothing will get selected.


After changing the selected item, press control + shift + space to have OSARA report the currently selected item.
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.


===Unselecting Tracks and Items===


As you press up and down arrow keys to move through the tracks only one track is selected at a time. Similarly, moving through items with control + left and right arrows selects just one item at a time.  Any previous track or item selection is removed.
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.


However, track and item selection are independent.  If you have an item selected on a track and then move down the track list then the selected track changes but the selected item remains unchanged. 


This can be a source of great confusion for beginners and is worth getting familiar with.
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.


Note that control + shift + space reports on the latest object so it reports the current track if you last changed the track selection and reports on items if the last change was to change item.


To clear all track and item selection press shift + escape.
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.


===Multiple continuous selections===


Holding down the shift key whilst moving between tracks or moving between items will select multiple tracks or items. Using this method will select continuous, or adjacent tracks or items.  You can, for example, select tracks 2, 3 and 4.
The @gfx block is used to draw graphics and process keyboard input.  I'm not sure when it is run.


Once you have made your selection pressing control + shift + space will report all the selected items.
== 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.


If you have multiple tracks selected and then press just up arrow or down arrow then all the previously selected tracks are unselected and only one track will remain selected.  There is similar behaviour for items.


Remember that selected items are not unselected when selecting multiple tracks and viceversa.
Desc: My first audio plugin


===Discontiguous Selection===


OSARA allows you to make a selection of any items and any tracks in your project by entering discontiguous selection mode.  For example, you can have tracks 1 and 3 selected and items 5 and 7 from track 2 selected.
slider:100<0,100,1>Volume


Press shift + space to enter discontiguous selection mode.  Keep the shift key pressed whilst pressing the up and down arrow keys to move through the track list.  As you move nothing is selected.  OSARA is just reporting your location but does not change the current selection.  Similarly, keeping shift held down whilst pressing control + left and right arrows moves through the items reporting your position but does not change the selection as you go.


To add a track or item that is currently unselected, press shift + space.  To unselect a selected track or item, press shift + space.  That is, shift + space toggles whether the track or item is selected.
@slider


One way to help understand this is to imagine that going into con tiguous selection mode lets you hover above the tracks and items.  You can hover freely over the top of them without changing their selection state.  Pressing shift + space then stamps down on your location changing the selection state of whatever is there.
scaler = slider1/100;


To report the currently selected tracks hold shift and move either up or down to get OSARA into reporting tracks and then press control + shift + space. 


To report the currently selected items hold shift and move  item with control left or right to get OSARA into reporting items.  Then press control + shift + space.
@sample


Pressing shift + escape clears all track and item selections.
spl0 *= scaler;


To leave discontiguous slection mode just release the shift key and then change either track or item. This is quite easily done by mistake when you are learning to use discontiguous selection. Undo, with control + Z, reverts the selection back as long as the default options in the General section of Preferences (control + P) have undo points for track and item selection changes ticked.
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 [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. 

Retrieved from "https://www.reaperaccessibility.com/index.php?title=Editing&oldid=618"