Unify Manual

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Loading and playing patches in Unify ======
Loading and playing patches in Unify //should// be as simple as clicking on the patch name in the patch browser. This page also covers how this might go wrong, and how to recover.

===== I don't see ANY patches! =====
If you open the patch browser (see next section) and don't see any patches, one of three things may be wrong:
  - You haven't installed the Unify Standard Library yet: [[installing#install_the_unify_standard_library|check these instructions]]
  - The path to the Unify data folder on the Settings page might be incorrect: [[installing#install_the_unify_standard_library|check these instructions]]
  - You need to rebuild the patch database: click the "gear" icon at bottom right to open the Settings page, and click the "Rebuild Now..." button.

If you see some patches, but fewer than you expect, you almost certainly need to rebuild the patch database.


===== Using the Patch Browser (sidebar) =====
Unify's //patch browser// view lives in the [[gui-overview|sidebar]] extension on the right-hand side of the GUI, which may not always be visible. Click the **browse button** to open and close it:

{{::browser-1.png?600|}}

The patch browser consists of two main sections:
  - The top section (outlined in red in the picture above) is called the //Selector//, and contains controls to allow you to narrow down the available choices in the bottom section.
  - The bottom section (also outlined in red) is called the //Chooser//; it contains a list of patch names in alphabetical order. Click once on any patch name to load that patch.

In addition to these two main sections are three less-obvious things you need to know about:
  - Between the Selector and Chooser is a grey "split bar" which you can drag to adjust the relative heights of the two main sections.
  - To the left of the sidebar itself is another split bar (like the first one, it lights up bright blue when you roll the mouse pointer over it), which you can drag to adjust the width of the sidebar.
  - To the left of the **browse button** are two buttons with up- and down-pointing green chevrons (see below)
    * Click the downward-pointing chevron button to load the //next// patch listed in the Chooser
    * Click the upward-pointing chevron button load the //previous// patch

{{::browser-2.png|}}


===== Using the Patch Selector =====
When you first open the patch browser, the Chooser (bottom part) will show //all patches on your system//, which may run to many hundreds once you have more than a few libraries installed.

**Starting in Unify v1.7**, there is a "..." button to the right of the library-selector menu; see [[#using_the_library_selector|Using the Library Selector]] below.

**Starting in Unify v1.8**, there is a second "..." button to the right of the library-selector menu. Clicking this pops up a small menu which allows you to choose which fields (items) in the database are searched:

{{::browser-2a.png|}}

  * Choices are //ALL//, //Name//, //Category//, //Tags//, //Author//, and //Comment//.
  * Check-marks indicate which fields are currently selected for search.
  * Default selection is //ALL//, i.e., all five fields are searched.
  * Select any individual field to //select that one, and de-select all others//.

If you CTRL-click or right-click the "..." button, the //ALL// item changes to //MULTI//, indicating that you can select any combination of fields.
  * The //MULTI// item itself is just a label; you can select it, but nothing will change.
  * Select any individual item to //toggle// it (if it's checked, it will be un-checked, and vice versa).
  * Note if only one field is checked, you will not be able to un-check it; check another field first.
  * Click the "..." button again to verify the selection, if you need to.

The controls in the Selector (top part of the sidebar) allow you to narrow down the set of patches in the Chooser, to help you find what you want quickly:

{{::browser-3.png?800|}}

**In Unify v1.8**:
  * The "Genre" list has been removed.
  * The items in each list will update automatically, to include only items which are relevant to the current library (or library-subset).
  * Each list will now display a "Clear" button, whenever at least one item in the list is selected.
  * Clicking the Clear button de-selects all items in that list only.

The icons at the top-left and top-right are as follows:
  * Click the "heart" icon to toggle showing only patches you have marked as "favorites" (by clicking the heart icon next to the patch name in the Chooser section).
  * The "lightning bolt" icon icon; click this to rebuild the patch database.
  * Click the "X" icon at the right-hand side of the search box (as of v1.1.x) to clear the search box text.

The various scrolling lists in the patch browser (not the pop-up menu of libraries) are //multi-selection lists//, i.e. you can select (highlight) one or more items, by using various modifier keys while clicking:
  * **Click** (no modifiers) to select an item, and simultaneously de-select all others
  * **CTRL + Click** (**CMD + Click** on Mac) to toggle an item's selection
  * **SHIFT + Click** to select a //range// of items (click 1st item, Shift+click last in the range)

===== Using the Patch Chooser =====
  * **Left-click** any patch-name in the chooser to **load the patch, replacing any previously loaded patch**.
  * **Right-click** any patch-name to pop up a menu with additional options as follows:
    * **Load patch:** This is the same as left-clicking the patch name
    * **Add  all layers to current patch:** Attempts to load the patch's layers as additional layers into the currently-loaded patch. This allows you to create a composite patch from partial layer-groups you have saved as patches previously.
      * Unify will load as many of the patch's layers as possible, but may not be able to load all AUX layers.
      * The patch's MASTER EFFECTS layer will NOT be loaded.
      * Unify will attempt to maintain connections between MIDI, INST, and AUX layers.
    * **Add INST1 layer to current patch** Loads only the patch's first INST layer as a new layer in the current patch.
    * **Load into new Unify layer:** Creates a single new INST layer, using //an instance of Unify itself// as the instrument plug-in, and loads the selected patch into that. See [[embedded-unify|Using Unify itself as an Instrument plug-in in Unify]]
    * **Unify/drum (No Pitch Shift):** As above, but modifies certain [[midibox|MIDIBox]] settings.
    * **Copy patch name to clipboard**: Does what it says, without having to load the patch.
    * **Reveal in Windows Explorer** (**Reveal in Finder** on Mac): allows you to locate the patch file.
**As of Unify v1.4**, after loading a new Unify layer, if you decide you only need the first INST layer (very common for "unified" patch libraries having only one INST layer per patch), you can click on the layer's operations menu (concentric circles menu at right end of layer) and choose "Replace with embedded INST1".

==== Setting favorite patches, advance to next/previous patch ====

After you have loaded one patch by clicking on its name, you can advance to the next one by clicking on the downward-pointing chevron button beside the browse/init/revert/save buttons at the top of the GUI, or simply pressing the cursor-down key on your computer's keyboard. You can go back to the previous patch using the upward-pointing chevron button, or the cursor-up key.

You can toggle the "heart" icon beside any patch name (which indicates if that patch is marked as a favorite) by clicking directly on the icon. You can do this for //any// patch, not just the currently-loaded one. Once you have loaded a patch, you can quickly toggle its "heart" icon by pressing the F key on your computer keyboard.

==== Patch count and load-options menu ====

**As of Unify v1.7**, a small "footer" may appear at the bottom of the Chooser area (depending on your settings; see [[settings|Using the Settings view]]). This was revised somewhat in Unify v1.8, as shown:

{{::browser-4.png|}}

The **Count** simply displays the number of patches currently listed in the Chooser.

The **Patch-load options menu** (labeled "Mode") allows you to choose what happens when you left-click on the name of a patch in the Chooser OR the [[gui-overview#random-patch_button_dice_icon|random-patch button]] (dice icon) in the Header. The options are:
  * **Normal**: selected patch is loaded, replacing any existing patch
  * **INST1 only**: the INST1 layer from the selected patch is added to the current patch
  * **Unify layer**: same as right-clicking patch and choosing "Load into new Unify layer"
  * **Unify/drum**: same as right-clicking patch and choosing "Unify/drum (No Pitch Shift)"

**Notes**
  - If you hide the patch-load options menu in [[settings|Settings]], left-clicking on patch names automatically reverts to the default load/replace behavior
  - Right-clicking on patch names will still open the full pop-up menu, whether the patch-load options menu is shown or hidden.

===== Loading individual patch files =====

Unify v1.7 added the ability to load an individual patch file (//.unify// or //.upf// file) from anywhere on your system, i.e., one which has not yet been added to your patch database. This is particularly useful for files shared on //Dropbox// in a YouTube livestream, or patch files shared by another user.

All you need to do is //drag the .unify (or .upf) file into the layer-stack view//. (If your system does not permit drag/drop operations, there's also a "Load Patch file..." button in the [[settings|Settings view]].) Unify will load the patch as though you had just created it yourself, starting from an INIT patch. It will NOT automatically add the patch to your patch database; if you want to do that, simply [[first-patch#save_your_new_patch|save the patch in the usual way]].

**Note** random shared patch files might not load perfectly on your system, as they may require additional files such as samples. Unify's [[guru-files|.guru files]] mechanism is a better method for sharing groups of related files or entire libraries. Unify will try to load the patch as best it can, and if you choose to save it, you may need to update some aspects, such as the library name, to match the library folders on your system.

You can then make any changes you like and save it to (typically) your User Library.

===== OOPS, I clicked a patch and lost all my work! =====
In versions of Unify before v1.5, it was all too easy to lose work by clicking on a patch in the Chooser.
Unify v1.5 introduced two new [[safety-features|Safety Features]] to help (click link for details).

**If you load a new patch by accident, and need to get back what you were working on before**, click the **Revert** button at the top right corner, to bring up a menu like this:

{{::revert-recall.png|}}

**Click the first saved patch below the horizontal line** (indicated by the purple outline above) to get back what you had before.

===== Using the Library Selector =====
Starting with Unify v1.7, you will see a "..." button to the right of the library-selector menu:

{{::browser-5.png|}}

Clicking the "..." button opens the new **Library Subset view**, which allows you to select a //subset of the libraries on your system//, rather than having to see all of them, in order to de-clutter the library-selector menu. Having defined a library subset, you can save it as a named //Library-Subset Preset// for later reuse.
  * **Power-user shortcut**: Right-click the "..." button (or hold down CTRL while left-clicking) to pop up a menu of available //library-subset presets// (explained below).

{{::browser-6.png|}}

The Library Subset view includes the following controls, listed from top to bottom:
  * The **Close button** returns the sidebar to the usual patch-browser view.
  * The **current preset name** is shown next to "Preset:".
  * The **All Libraries**, **Load**, and **Save...** buttons are described in detail below.
  * The large **library list** at the bottom shows ALL libraries in Unify's patch database, and allows you to select which subset of them you would like to work with.

==== Defining a library subset ====

The library list will scroll if necessary. It's a [[shortcuts#multi-selection_lists|multi-selection list]], like others in the Unify GUI, and works as follows:
  * **Click** (no modifiers) to select an item, and simultaneously de-select all others
  * **CTRL + Click** (**CMD + Click** on Mac) to toggle an item's selection
  * **SHIFT + Click** to select a //range// of items (click 1st item, Shift+click last in the range)

If NO libraries are selected, then they are ALL effectively selected. Clicking the **All Libs** button will de-select all list items and return to this condition. If ANY libraries are selected, the set of selected libraries defines the //current libraries preset//.

If you select one or more libraries, the current preset name will change to "Unsaved Library Subset", indicating that you have changed the current subset, but haven't yet saved this subset as a preset. This unsaved subset is entirely usable; if you click the **Close** button, the first item in the main library-selector menu will change to "All: Unsaved Library Subset", and when you click it, you will see that this is followed by only the libraries you selected, like this:

{{::browser-7.png|}}

(In this case, exactly four libraries had been selected.) Note that clicking the **Reset** button at the top of the patch browser will now revert to showing //only the libraries in the current preset//. If you want to **go back to seeing ALL libraries**, click the "..." button, then the "All Libraries" button, then "Close".

==== Saving and re-loading library-subset presets ====

Having defined a subset, you can save it as a named preset by clicking the **Save...** button.
  * A standard file-save dialog will appear, and should already be prepared to save the preset file (as a ''.txt'' file) in the //Presets/Library Subsets// sub-folder inside the main Unify data folder.
  * Navigate down into any sub-folder if you wish.
  * Type a name for your preset as the new file name; Unify will add the ''.txt'' extension automatically.
  * Click the **Save** button.

Once you have saved your preset, its name will be displayed above the row of three buttons, and will also be shown instead of "Unsaved Library Subset" when you click **Close** to return to the main view.

**Unify will remember the last library preset you saved/loaded, and will automatically load that the next time you run it.** Remember, to revert to all libraries: Click "...", then "All Libraries", then "Close".
  * If the last library subset you were using before closing Unify was //unsaved//, Unify will NOT remember this; it will open next time with all libraries selected.

To re-load one of your saved library-subset presets, click the **Load** button. This will pop up a menu of all ''.txt' files under the //Presets/Library Subsets// folder, with sub-menus for any sub-folders you may have created, like this:

{{::browser-8.png|}}

To load a preset, roll your mouse until the preset you want is highlighted, and then release the mouse button. The current preset name will be updated, and of course also the libraries menu in the main view.

===== About the Patch Database =====
All the controls in the Patch Selector make use of Unify's //patch database//, which is basically an index to all the patches on your system.
  * To see the how the database is structured, open the [[settings|Settings view]] by clicking on the "gear" icon at the bottom right, and click the "View Database..." button.
  * For every patch, the database keeps track of the patch name, the file name (which //need not be the same// as the patch name), what folder it is in, which library it's part of (which //need not be the same// as the name of the folder it's in), and lots of other details.
  * Whenever you add patches or libraries to your system, Unify needs to //rebuild// the patch database by re-scanning the patch files. This happens automatically each time you add new content using a //.guru// file, and you can force a rebuild at any time by clicking the "Rebuild Now..." button in Settings view.

Unify can only work with patch files (types //.upf//, //.unify//) in sub-folders of the main //Libraries// folder (i.e., the //Libraries// folder inside whatever folder you designated as the main Unify data folder; you can check the path to this in the Settings view).

Because scanning all these files repeatedly would be slow, Unify creates a list or index of them, which we call the "patch database". The patch browser lists the entries in the database, not the actual files. Any time you create, delete, or move patch files outside of Unify, the patch database will no longer correspond to the files; that's why we have a "rebuild database" button.

When you click the rebuild database button, Unify scans all sub-folders of the main //Libraries// folder, looking for //.upf// and //.unify// files. It opens and reads every single one, to extract the "patch metadata" (patch name, library name, authors, tags, categories, comments, etc.), and puts all this into the database.

==== Incremental vs Full rebuild ====

As of Unify v1.2.0, Unify can rebuild the patch database in either of two ways: //Incremental// and //Full//.

When you click the "lightning bolt" icon, Unify performs an //incremental rebuild//. It scans all folders under the main //Libraries// folder, looking for //.upf// or //.unify// files, and checks their "last modification" date/time against the database. If the file is newer, Unify will open it and update the database record. If it does not appear to have changed, it will ignore it and skip ahead. It will also add new records for any files which are not yet in the database, and delete records which no longer have an associated file.

**As of Unify 1.10.x**, incremental rebuild has been further optimized as follows:
  * If all libraries are selected, and no library-subset is active, works as described above.
  * If a library-subset is active, and no specific one is selected, only the libraries in the subset are scanned.
  * If a library is selected, only the selected library folder is scanned.

This incremental rebuild method, which can be very quick if few or no files have changed, will be all you need in most cases. If you ever suspect that the database may have errors, you can perform a //full rebuild// by holding down the Option/Alt key while clicking the lightning bolt. Unify will perform the following steps:

  - Create a temporary file favorites.xml in the Libraries folder, listing the names of all patches you had marked as "favorites" (heart icon).
  - Delete the old database file (//presets.db//).
  - Scan through the //.upf// and //.unify// files and create a new //presets.db// from the patch metadata, as described above.
  - Read the temporary //favorites.xml// file again, to re-mark the indicated patches as favorites.
  - Update the displayed patch browser.

==== Patch names vs File names, and some tips ====

As mentioned in the section above, each patch file's metadata includes the //patch name// and the //library name//. This makes each patch file entirely self-contained, but it can lead to some confusion. You would expect the patch name to match the file name, and the library name to match the name of the containing folder, but //this is absolutely NOT required//.

Based on these details, here are some specific tips for patch management:

  * Avoid manipulating patch files manually (in the Finder/Explorer) as much as possible.
    * Whenever you do manipulate files manually, click the "rebuild database" button in Unify when you are done.
  * Never click the "rebuild database" button in one Unify instance, while another instance is still rebuilding.
    * (Normally the buttons will be deactivated, making this impossible, but in a few unusual cases they might not be.)
  * If you want to make backup copies of patches you have created, put them //anywhere except// under the main //Libraries// folder. This will ensure they won't be found when rebuilding the database.
  * If you want to work with a reduced set of libraries for some reason, you can move entire library folders into a new temporary location (e.g., make a folder //beside// the main //Libraries// folder, call it something like "Inactive Libraries", and move some library folders in there) and rebuild the database.
  * Manually changing a patch's //file name// will not change the displayed patch name, even after rebuilding.
    * To change a patch's //name//, you must re-save the patch, and change the name in the save dialog.
  * Manually moving a patch file from one library folder to another will //not// make it part of the new library.
    * To change a patch's associated //library name//, you must re-save the patch, and select the new library name in the save dialog.
    * It is //strongly recommended// (but NOT required) to save the patch into the library folder for the new library. Unify will automatically select the correct folder when saving, but will not stop you from saving the file somewhere else.