Unify Manual

Your complete reference to PlugInGuru's creative playground!

User Tools

Site Tools


guru-files

This is an old revision of the document!


About .guru files

.guru files provide a convenient way to package, distribute, and install batches of related files in Unify, e.g., patch libraries, sample collections, etc.

A .guru file is simply a renamed .zip file, whose contents (files and folders) are set up to unzip into Unify's main data folder. Getting the folder structure right is the trickiest part of making your own .guru files.

Example .guru file

The following example .guru file was created in support of a new video about the Patch Variations feature in Unify v1.6.0:

unify_step_curves.zip

Click the link above to download this .guru file, and note that it has been re-zipped, i.e., you will have to unzip it after downloading. The software powering this online manual does not support the .guru file type, so it was necessary to zip it again before uploading. This is a common limitation of online file-hosting tools.

This particular .guru file has the following folder structure:

  • file: Unify Step Curves.guru
    • folder: Libraries
      • folder: User Library
        • folder: Media
          • file: Intro_Verse_Chorus.txt
        • folder: Patches
          • file: 3 Parts Song Switcher.unify
    • folder: Presets
      • folder: Macro Link Curves
        • 18 .curve files

When this .guru file is dropped into the Unify GUI, Unify will unzip its contents into the main data folder. Hence, everything inside the Libraries folder in the .guru file will go into the Libraries folder in the main Unify data folder, and everything inside the Presets folder will go into Presets.

What happens is exactly the same as if you put the .guru file itself into the main Unify data folder, and unzipped its contents using the “extract here” option. (Different systems may use different wording to describe this, but the effect is the same, as described in the next section.)

How Unify unzips the .guru file

Any folders present in the .guru file, which don't yet exist in the corresponding locations under the main Unify data folder, will get created automatically. This is why it is VERY important to get the folders inside your .guru files just right, or files and folders will go into the wrong places, and anyone to whom you send your .guru file will end up with a mess to clean up.

Individual Files present in the .guru file will be created if they don't already exist, but if a file by the same name does exist in that location, it will be overwritten with the new file. This is another reason to be very careful when setting up .guru files.

If the .guru file contains any patch files (i.e., files which go into the Patches sub-folder of any Library folder), Unify will take note of the library name (i.e., the name of the parent folder of the Patches folder containing the patch file) and trigger the patch database to rebuild only for that library (or libraries, if more than one are present).

Limitations of .guru files

When Unify unzips the contents of a .guru file, it can only add or overwrite files (and folders as required). It cannot delete files. Some capability to do this may be added to Unify in the future, but there is none at the moment.

Creating a .guru file (the safe way)

Suppose you have created a new library called My Awesome Library in Unify, and you'd like to make a .guru file to help others install it quickly. Here are the steps:

  1. Start by creating an empty “working folder” somewhere, preferably not under the main Unify data folder.
  2. Open your working folder, and also the main Unify data folder, in Windows Explorer or Mac Finder.
    • To quickly open the main Unify data folder, click the “gear” icon to go to the Settings view, and click the “Open…” button there.
  3. In the window representing your working folder:
    • Create an empty Libraries folder, and open it
  4. In the main Unify data folder window:
    • Navigate into the Libraries folder
    • Locate the folder for your library (in this case My Awesome Library)
  5. Copy the entire My Awesome Library folder to the empty Libraries sub-folder of your working folder
  6. In your working-folder window, navigate back up to where you started (where you see the Libraries folder you made at step 3).
  7. Select the Libraries folder, and zip it, using whatever mechanism your computer provides to make .zip files, e.g.:
    • On a Mac, right-click the Libraries folder and choose “compress”
    • On a Windows PC with 7-zip installed, right-click the Libraries folder and choose “add to … .zip” (the name will be the name of your working folder).
  8. Rename the resulting .zip file to whatever you want, and change the extension from .zip to .guru.
    • Your operating system will pop up some kind of message asking you to confirm that you really want to change the extension to .guru.
    • Click “OK” or respond in whatever is the appropriate way, to confirm that you want to change the extension.

At this point, assuming you followed the above steps precisely, you will have a valid .guru file, which others can now use to install My Awesome Library quickly.

If you want to upload your .guru file to some kind of file-sharing service, attach to an email, etc., it's usually best to re-zip the .guru file, and share/attach the resulting .zip file. Advise recipients that they must unzip it, then drag/drop the resulting .guru file into the Unify GUI, or use the Select .guru file… button in the Settings view and select it that way.

Creating a .guru file (the risky way)

If you know what you're doing, you can use these steps instead:

  1. Open the main Unify data folder, and navigate into Libraries
  2. Create a new empty Libraries folder (inside the Libraries folder)
  3. Drag (i.e., move) your own library folder into this new Libraries folder
  4. Compress the new Libraries folder to a .zip file (e.g. Libraries.zip), then rename using the .guru extension, and confirm as described above.
  5. Make sure to move your library folder back out into the main Libraries folder, then delete the dummy Libraries sub-folder you created.

Creating a .guru file (more generic)

The above instructions described how to make a .guru file for a single patch library, but .guru files can contain multiple libraries, or no libraries (i.e., no top-level Libraries folder at all), and anything else that belongs under the main Unify data folder, e.g., you may have a top-level Presets folder as in the example, or MIDI Bank Files, MIDI Controller Files, etc. In such cases, it's strongly advisable to use a working folder.

Whatever you do, just make sure that the folder structure of your .guru file exactly corresponds to where all of your own files need to go.

Testing your .guru files

It's a very good idea to test dragging your .guru file into Unify, to make sure everything goes into the right places. The best way to do this is to create a second “main Unify data folder” somewhere on your disk, and select in Unify using the “Change…” button in the Settings view. That way, there will be no risk of messing up your actual Unify data folder contents, and you can switch back after you're finished testing.

To create a second Unify data folder:

  1. Create an empty folder in a suitable location on your disk, then create empty Libraries and Presets folders inside it.
    • If you do not create these sub-folders, Unify will not allow you to select the folder as your main Unify data folder.
  2. In Unify, go to the Settings view, click the “Change…” button, and choose your new folder.
  3. IMPORTANT: Quit Unify immediately.
    • This step ensures that your patch database will not be damaged.
  4. Optionally, copy over any other content you may want (patch libraries, presets, etc.) from your real Unify data folder to your testing folder.
    • Be very careful that to COPY (not MOVE) files/folders to your test data folder
  5. Re-start Unify
    • Unify will automatically create an empty database file presets.db in your test Libraries folder.
    • If you copied over any libraries, click the lightning-bolt icon at the top of the patch browser, to update this newly-created database to include entries for whatever patches you copied.
  6. Optional, but recommended: Quit Unify again, and zip up your entire test folder.
    • This will allow you to delete and re-create it quickly, for future tests.
  7. Drag/drop your .guru file, and verify that Unify responds as you would wish.
  8. Examine the contents of your test data folder carefully, and verify that all files/folders went into the right places.
guru-files.1630705633.txt.gz · Last modified: 2023/05/08 18:59 (external edit)