Project Management

[Christoph Hart]

Until now, HISE didn't really had a nice way to handle different projects. Every preset was stored into the global preset directory and absolute file names were used for every file reference.

This was changed when the project management system was introduced. It should meet these requirements:

• Have one project folder with subfolders for different files
  Everything related to one project should be collected in one place.

• Use the project folder as root folder for file references (relative)
  This simplifies collaboration because there are no more absolute file paths involved.

• Allow cross platform file handling (even on the same machine using Bootcamp)
  Even with relative files, it is quite easy to mess up the references when switching between OSX / Windows

• Allow redirecting of the sample folder to another location
  Since samples can be quite large, it should be possible to store them at another location.

• Quickly change between projects
  By using a recent project list as well as a list of every preset in the project it speeds up switching between projects.

• XML Backup possibility
  The binary preset format is quicker and smaller than its human readable counterpart, but for some reasons, the XML file format should be preferred.

• Compatibility with version control systems
  SVN or GIT are great ways to jump between different development branches / states so the project management is designed with the usage of these tools in mind.

• Store project related settings in a XML file
  Things like the plugin name, version and the RSA keys for the licence file can be stored in a XML file in the root directory.

• Abstraction of the file handling between the backend system and a compiled plugin
  When compiling a plugin, it will embed certain data directly into the binary without having to change the references. When using an external file in a script, the wildcard {PROJECT_FOLDER} can be used to obtain the file (you don't need to supply the subdirectory, because it assumes that all images are within the Images subfolder).

• One click compile to plugin (not yet implemented)
  When correctly set up, there will be a one-click compile option that creates the plugin files directly in the project folder. It will still use the system compilers (XCode on OSX and VisualStudio on Windows)

What is a project?

Depending on your deploying target, a project can be one of these two things:

1. A compiled VST / AU plugin
2. A library in the HISE Player

There are export tools for both deploymend targets, but the workflow during development will be the same for both options. The only difference is that a HISE Player library can contain multiple presets while a plugin consists only of one preset.

How to use

You can create a new project via the file menu (File->Create new Project). Select an empty folder and the required subdirectories will be created for you. You can then open, close and switch between recent projects using the File menu.

As soon as a project is active, HISE will use the root folder of the project for all references. You can create new patches, use the wildcard {PROJECT_FOLDER} whenever you need to access external files and build your instrument.

The Folder Structure

When creating a new project, these subdirectories will be created which store different types of data:

/AudioFiles/
/Binaries/
/Images/
/Presets/
/Samples/
/Scripts/
/UserPresets/
/XmlPresetBackups/

The AudioFiles Folder

Every audio file that is referenced by a module can be stored here. This would be impulse responses or audio loops that are loaded in a Looper.

Samples are not treated as AudioFiles, but are stored in their own subdirectory

On compilation, all files within these folder will be embedded in the plugin.

Binaries

This subdirectory stores compiled plugins and all project files for the compilers (using the Introjucer)

Images

Every image (background image or filmstrip image for interface widgets) will be stored here.

On compilation, all files within these folder will be embedded in the plugin.

Presets

This directory contains all preset files (= instrument files) of this project.

You can store different versions of a project as presets (if you don't want to use a version control system)

Samples

The samples subfolder contains either all samples or a redirect file that points to a folder where the samples are stored.

If you want to redirect the sample folder, you can do this either via Tools->Redirect Sample Folder or by manually creating a file in the sample folder with this name (without extension):

OSX: LinkOSX
Windows: LinkWindows

The file must be a simple text file that contain a valid path for the OS.

You can't mix both modes: As soon as there is a redirect file in the folder, HISE will stop looking for actual samples in that folder (to speed up loading times).

The samples will not be embedded in the plugin (because they must be available as streamable audio file).

Scripts

You can use external Javascript files and include them in a script using include("fileName.js")

On compilation, all files within these folder will be embedded in the plugin.

User Presets

This folder contains all user presets for this instrument. A user preset is a collection of values of your user interface and can be used to restore different states of your instrument.
Those files will be embedded into the binary (starting from HISE 1.1.0) and will be extracted to the AppData subfolder UserPresets at first launch (or if you manually delete the UserPresets folder in order to reset them).

XML Preset Backups

You can store human readable files in this directory (instead of the binary .hip files from the Preset directory). This can be done via File->Load XML Backup and File->Save XML Backup.

Version Control

Using a version control system heavily simplifies the handling of different development versions. I would recommend only putting these directories under version control:

/Scripts/
/Images/
/XmlPresetBackups/
/UserPresets/
/SampleMaps/

because these are the only places that contain human readable files (the other files won't benefit from version control features like "Compare to last version" etc.). This also means that using the XML file format should be preferred over the binary format during developing (you'll have slightly longer loading times.)

The best workflow to setup a version controlled project is by following these steps (I assume basic knowledge of version control systems):

1. Create a folder manually
2. Check out the repository you want to use (it should be empty or use an empty subfolder)
3. Create the project or copy an existing project into this folder.
4. Add this subfolders to the ignore list: Binaries, Presets, Samples
5. Commit the working copy

I assume that files like the impulse responses and the image files won't change during developing of the instrument, otherwise you can of course include these directories.