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.

      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)
      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 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)
            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 a series of tokens (see below) delimited by newlines or commas. Comments can be specified with a ; or # which makes the rest of the line ignored.

      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 newline or comma delimited record can be:
      • a floating point number
      • a binary number beginning with 'b', i.e. b0101010111
      • a hexadecimal number beginning with 'x', i.e. xDEADF000.
      • a combination of numbers or symbolic values using basic +. -, |, & and parentheses.
      • an assignment (e.g. NAME = 1.0) to create a symbolic constants (this does not count as a record and is otherwise ignored)

    • 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