back to main JSFX reference page


JSFX Programming Reference - File I/O and Serialization
  • 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.

      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 RIFF WAV file, or a valid .OGG Vorbis file, this will set the first parameter to the number of channels, and the second to the samplerate.

    • 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).



  •   Home
        Company
        Reviews
        Radio
      About
        Technical
        Old Versions
        Language Packs
        ReaPlugs
        Distribution
      Developer
        Theme Development
        Custom Cursors
        JSFX Programming
        ReaScript
        Extensions SDK
        Extensions to VST SDK
        OSC
        Language Pack Template
      Resources
        User Guide
        Videos
        Stash
        Forum