files
type: Specification
name: LV2 Files
maintainer: David Robillard
comment: This extension provides a mechanism for plugins to create new files for storing arbitrary data (e.g. waveforms), which can be persisted using the LV2 Persist extension. This allows plugins to work with potentially very large data via files, and save/restore these files. The motivating idea behind this extension is that all details of file management must be handled by the host in whatever way is most appropriate for that host. Plugins MUST NOT make any assumption about filesystem locations beyond what is explicitly guaranteed by this extension. To create a new file, plugins request a filename from the host. This way, the host is aware of files used by the plugin and can use an appropriate location for them that the plugin alone could not know (e.g. using an appropriate disk volume for recording). Plugins may also use pre-existing files from elsewhere on the filesystem. Using the LV2 Persist extension, the host can save both these types of files in an appropriate way (by e.g. storing a link, or copying the file to export or archive a project).

Support for plugin-created files
type: Feature
comment: This feature allows plugins to use pre-existing or newly created files, and files them (e.g. across project saves and restores). If a host supports this feature it passes a LV2_Files_FileSupport structure to the plugins instantiate method as a feature (with URI http://lv2plug.in/ns/ext/files#FileSupport). This structure provides a function the plugin can use to create new file names. If and only if the host supports this feature, the plugin MAY files and restore values of type LV2_FILES_FILENAME. A plugin SHOULD use this facility to create any new files it may need (e.g. samples, waveforms for recording). Plugins MUST NOT expect their state to be correctly restored if they do not use this mechanism to create new files.

File Path
type: AtomType
comment: The full path to a file on the local filesystem. The format of a files:filePath is a C string (escaped or otherwise restricted in whatever way necessary for the system). This URI (http://lv2plug.in/ns/ext/files#FilePath), mapped to an integer, should be used as the type parameter with the LV2 Persist extension to persist a file. When persisting a files:FilePath, the plugin MUST NOT assume that the same path will be restored (i.e. the host MAY choose to store the file elsewhere). The plugin may, of course, assume that the actual contents of the file are equivalent when restored.