REAPER | JSFX Programming Reference - File I/O and Serialization

JSFX Programming Reference - File I/O and Serialization

top File I/O and Serialization

The following functions can be used in the @serialize section or in other sections.

Using with @serialize:
Pass 0 as a handle to various file_*() functions, but do not call file_open() or file_close(). Simple @serialize code will often appear the same for read and write, as file_var(0,x) will read/write x depending on the mode. If you want to have different logic per mode, you can check file_avail(0)>=0 to determine if it is in read mode.

Using in other sections:
file_open() and file_close() can be used to open files for reading in any section.

file_open(index or slider)
Example:
```
 
      filename:0,myfile.wav
      handle = file_open(0);
```
Example:
```
 
      slider1:/mydata:mydef.wav:WAV File
      handle = file_open(slider1);
    
```
Example ( REAPER 4.59+):
```
 
      handle = file_open(string);
    
```
Opens a file from either the effect filename list or from a file slider, or from a string (REAPER 4.59+). Once open, you may use all of the file functions available. Be sure to close the file handle when done with it, using file_close(). The search path for finding files depends on the method used, but generally speaking in 4.59+ it will look in the same path as the current effect, then in the JS Data/ directory.

REAPER v6.17+: string can be an absolute path to a file.

If file_open() fails, it will return < 0 (usually -1).
file_close(handle)
Example:
```
 
      file_close(handle);
    
```
Closes a file opened with file_open().
file_rewind(handle)
Example:
```
 
       file_rewind(handle);
    
```
Use this to rewind the current file to the beginning, to re-read the file etc.
file_var(handle,variable)
Example:
```
 
       file_var(handle,myVar);
     
```
This reads (or writes if in a @serialize write) the variable from(to) the current file.
file_mem(handle,offset, length)
Example:
```
 
       amt=file_mem(handle,offset,len);
    
```
This reads (or writes) the block of local memory from(to) the current file. Returns the actual number of items read (or written).
file_avail(handle)
Example:
```
 
       len=file_avail(handle);
    
```
Returns the number of items remaining in the file, if it is in read mode. Returns < 0 if in write mode. If the file is in text mode (file_text(handle) returns TRUE), then the return value is simply 0 if EOF, 1 if not EOF.
file_riff(handle,nch,samplrate)
Example:
```
 
      file_riff(handle,nch,samplrate);
      nch ? file_mem(handle,0,file_avail(0));
    
```
If the file was a media file (.wav, .ogg, etc), this will set the first parameter to the number of channels, and the second to the samplerate.

REAPER 6.29+: if the caller sets nch to 'rqsr' and samplerate to a valid samplerate, the file will be resampled to the desired samplerate (this must ONLY be called before any file_var() or file_mem() calls and will change the value returned by file_avail())
file_text(handle,istext)
Example:
```
 
      istext=file_text(handle);
      istext ? use_diff_avail syntax;
    
```
If the file was a text file (and ended in .txt), this will return 1. If you need to use different file_avail() logic for text files (you often will), you can query it this way.

Text file notes
Note that if in an extended file-slider code section, and the extension of the file is .txt, it will read one line at a time, ignoring non-number lines. Note that file_avail() should be called to check for EOF after each read, and if it returns 0, the last file_var() should be ignored.

You can also use file_mem(offs,bignum) and it will read the maximum available.

The format of each line in the text file can be either a floating point number, a binary number beginning with 'b', i.e. b0101010111, or a hexadecimal number beginning with 'x', i.e. xDEADF000.

Additionally text files can create their own symbolic constants (using =), and combine them using basic +, -, |, & etc operators.
file_string(handle,str) -- REAPER 4.59+
Reads or writes a string from/to the file handle. If operating on a normal file, the string will be a line of text (possibly including newline or other characters). If in @serialize, the string will be encoded as a blob with length, which means that it is binary-safe (you can include NUL characters within the string etc).