REAPER | JSFX Programming Reference

JSFX Programming Reference - MIDI

top MIDI Functions

It is highly recommended that any MIDI event processing take place in @block, but sending MIDI events can also take place in @sample.

midisend(offset,msg1,msg2)
midisend(offset,msg1,msg2 + (msg3 * 256))
midisend(offset,msg1,msg2,msg3) -- REAPER 4.60+
```
    
     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
```
Sends a 2 or 3 byte MIDI message. If only three parameters are specified, the second lowest byte of the third parameter will be used as a third byte in the MIDI message. Returns 0 on failure, otherwise msg1.
midisend_buf(offset,buf, len) -- REAPER 4.60+
```
    
     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
```
Sends a variable length MIDI message. Can be used to send normal MIDI messages, or SysEx messages. When sending SysEx, logic is used to automatically add leading 0xf0 and trailing 0xf7 bytes, if necessary, but if you are sending sysEx and in doubt you should include those bytes (particularly if sending very short SysEx messages). Returns the length sent, or 0 on error.

This function is very similar to midisyx, but preferable in that it can be used to send non-SysEx messages and has no restrcitions relating to the alignment of the buffer being sent.
midisend_str(offset,string) -- REAPER 4.60+
```
    
     midisend_str(10,"\x90\x11\x7f"); // send at sample offset 10, note-on, note 17, velocity 127
```
Sends a variable length MIDI message from a string. Can be used to send normal MIDI messages, or SysEx messages. When sending SysEx, logic is used to automatically add leading 0xf0 and trailing 0xf7 bytes, if necessary, but if you are sending sysEx and in doubt you should include those bytes (particularly if sending very short SysEx messages). Returns the length sent, or 0 on error.
midirecv(offset,msg1,msg23)
midirecv(offset,msg1,msg2,msg3) -- REAPER 4.60+
```
 
  @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
       )
    );
    
```
The above example will filter all noteons on channel 0, passing through other events. The construct above is commonly used -- if any of the midirecv*() functions are called, one must always get all events and send any events desired to be passed through.

If only three parameters are passed to midirecv, the third parameter will receive both the second and third bytes of a MIDI message (second byte + (third byte * 256)).

Calling midirecv() will automatically passthrough any SysEx events encountered; if you wish to process SysEx events, please use midirecv_buf() instead.
midirecv_buf(offset,buf, maxlen) -- REAPER 4.60+

Receives a message to a buffer, including any SysEx messages whose length is not more than maxlen.
```
 
  @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
       )
    );
 
```
The above example will filter all noteons on channel 0, passing through other events. The construct above is commonly used -- if any of the midirecv*() functions, one must always get all events and send any events desired to be passed through.

If maxlen is smaller than the length of the MIDI message, the MIDI message will automatically be passed through.

For one and two byte MIDI messages (such as channel pressure), the length returned may or may not be 2 or 3.
midirecv_str(offset, string) -- REAPER 4.60+

Receives a MIDI or SysEx message to a string.
```
 
  @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);
       )
    );
 
```
The above example will filter all noteons on channel 0, passing through other events. The construct above is commonly used -- if any of the midirecv*() functions, one must always get all events and send any events desired to be passed through.

midirecv_str() will return the length of the message on success, or 0 on failure. On failure (no more messages), the value of the string passed in is undefined. strlen(#str) may be 1,2 or 3 for one or two byte MIDI messages.
midisyx(offset,msgptr,len) -- deprecated in REAPER 4.60+
```
 
     buf[0] = $x01;
     buf[1] = $x02;
     midisyx(offset,buf,2);  // send sysex: f0 01 02 f7 
    
```
Sends a SysEx message -- if the message does not begin with F0 and end with F7, these will be automatically added. If the message crosses any 64k boundaries, it will be sent as multiple messages. This function is deprecated, midisend_buf() should probably be used instead.

top MIDI Bus Support

REAPER supports multiple MIDI buses, JSFX plug-ins can (but do not by default) access all 16 buses.

ext_midi_bus -- REAPER 4.16+
Set to 1.0 in @init to enable support for MIDI buses (by default buses other than bus 0 will be passed through).
midi_bus -- REAPER 4.16+
If ext_midi_bus is set, this will be set by midirecv() to the MIDI bus of the event, and will be used by midisend() et al to route the MIDI event accordingly. Valid values are 0..15.