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)
            handle = file_open(0);
            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)
      Closes a file opened with file_open().

    • file_rewind(handle)
      Use this to rewind the current file to the beginning, to re-read the file etc.

    • file_var(handle,variable)
      This reads (or writes if in a @serialize write) the variable from(to) the current file.

    • file_mem(handle,offset, length)
      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)
      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)
            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)
            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
        Old Versions
        Language Packs
        Theme Development
        Custom Cursors
        JSFX Programming
        Extensions SDK
        Extensions to VST SDK
        Language Pack Template
        User Guide