The File object represents a file or directory on disk and can be used to navigate / access the file system from HISEScript.

In order to use it, call the Filesystem API class to get a folder from where you navigate to the file you want to modify / load.

Be aware that there is no possibility of writing / loading files using absolute paths (eg. C:\MyFolder ) because it is not portable across operating systems (and even computers).

Class methods


Returns the new directory created at the file location, if directory doesn't already exist

File.createDirectory(String directoryName)


Deletes the file or directory WITHOUT confirmation.



Extracts the ZIP archive if this file is a .zip file.

File.extractZipFile(var targetDirectory, bool overwriteFiles, var callback)

This method will extract a standard ZIP file (without password protection) to the given target directory (which can be either a file path String or a File object).

In order to extract to privileged locations on Windows, for example the user's VST3 folder, it is neccessary to add an extra linker flag /MANIFESTUAC:level='requireAdministrator' to your project's .jucer file.

The extraction process will be executed on the sample loading thread and you can assign a callback that is executed to track the extraction progress.

The callback expects a single parameter that will contain a JSON object with the following properties:

Property Type Description
Cancel bool Set to false . If you want to abort the extraction process, just set this flag to true.
Target String The target directory as file path.
Error String A error message if something went wrong during extracting.
Progress double the progress from 0.0 to 1.0. Be aware that this tracks only the number of files extracted vs. the total number of files, so if you have one big file inside the archive, it will not work.
NumBytesWritten int the number of bytes that have been extracted.
CurrentFile String the relative path of the file that is currently being extracted.
Status int a status flag indicating the state of the extraction: 0 at the beginning, 1 while extracting and 2 at the end.

The callback will be executed at the beginning of the extraction (with the Status flag 0 ) and at the end (with the Status flag 2 ) as well as when an error occurs.

If you extract a small archive (less than ~400 files), the callback will also be executed for each file (this limit prevents the scripting queue to be clogged with huge archives).


Returns the number of bytes free on the drive that this file lives on.



Returns a child file if this is a directory.

File.getChildFile(String childFileName)


Reads a file and generates the hash of its contents.



Returns a sibling file that doesn't exist.



Returns the number of items in the zip file.



Returns the parent directory as File.



Returns a relative path from the given other file.

File.getRelativePathFrom(var otherFile)


Returns the size of the file in bytes.



true if it's possible to create and write to this file. If the file doesn't already exist, this will check its parent directory to see if writing is allowed.



Checks if this file exists and is a directory.



Checks if this file exists and is a file.



Loads the given file as audio file.



Loads the track (zero-based) of the MIDI file. If successful, it returns an object containing the time signature and a list of all events.

File.loadAsMidiFile(int trackIndex)


Loads the given file as object.


This tries to parse the given file as JSON object and return it. If you are storing complex data, this will be the most convenient option.


Loads the given file as text.



Loads the encrypted object using the supplied RSA key pair.

File.loadEncryptedObject(String key)

This function will load a JSON object from a file that has been written with File.writeEncryptedObject()

The encryption uses Blowfish encryption, so it should be able to encrypt / decrypt pretty fast.

You can use these functions to create an authentification scheme that stores the license key in a file in order to bypass online activation.


Loads the XML file and tries to parse it as JSON object.



Renames the file.

File.rename(String newName)


Changes the execute-permissions of a file.

File.setExecutePermission(bool shouldBeExecutable)


Changes the read/write permission for the given file.

File.setReadOnly(bool shouldBeReadOnly, bool applyRecursively)


Opens a Explorer / Finder window that points to the file.

This opens a OS specific file browser that will reveal the file to the user.


Launches the file as a process.

File.startAsProcess(String parameters)


Returns a reference string with a wildcard.

File.toReferenceString(String folderType)

This function tries to parse this file as relative path string depending on the folder type. If you want to import a custom sample into a samplemap and want to make sure that it is as portable as possible you can use this:

inline function dropCallback(f)
	local samplePath = f.getReferenceString("Samples");
		"FileName": samplePath

If the file that was dropped was in the sample folder of the plugin, samplePath will be {PROJECT_FOLDER}MySample.wav (otherwise it will just be the absolute path). Having it as project reference will allow the user to port the data across systems which might be a bit more convenient.


Returns a String representation of that file.

File.toString(int formatType)

You can use this to display the filename on your UI.

The formatType argument is expected to be one of the constants supplied in the File object:

The following table will show the formatting for the file C:\MyFolder\Textfile.txt

Name Example
FullPath C:\MyFolder\Textfile.txt
NoExtension Textfile
OnlyExtension .txt
Filename Textfile.txt


Replaces the XML file with the JSON content (needs to be convertible).

File.writeAsXmlFile(var jsonDataToBeXmled, String tagName)


Writes the given data (either a Buffer or Array of Buffers) to a audio file.

File.writeAudioFile(var audioData, double sampleRate, int bitDepth)


Encrypts an JSON object using the supplied key.

File.writeEncryptedObject(var jsonData, String key)

This function will encrypt the JSON object with the given key and write it to the specified file. The key can be up to 72 characters long.

In order to read the encrypted file, use File.loadEncryptedObject() with the same key.


Writes the array of MessageHolders as MIDI file using the metadataObject to determine time signature, tempo, etc.

File.writeMidiFile(var eventList, var metadataObject)


Replaces the file content with the JSON data.

File.writeObject(var jsonData)


Replaces the file content with the given text.

File.writeString(String text)

It will return true if the file operation was completed successfully or false if there was an error during the operation.