Unify Manual

Your complete reference to PlugInGuru's creative playground!

User Tools

Site Tools


sampler-import

Manual creation of SFZ files for Guru Sampler

We DO NOT offer end-user support for what's described here.

It is our intent that a future version of Guru Sampler will include a full graphical user interface (GUI) for importing and mapping your own samples. What's described here is the complex, manual process we use now, in all its nasty glory.

If you want to try this, do so at your own risk!


Guru Sampler uses a VERY LIMITED variant of the "SFZ" format. In fact, it's better to say that Guru Sampler's format is “inspired by” the SFZ format, because our .sfz files aren't even recognized by standard SFZ players like Sforzando.

Each Guru Sampler .sfz file is a simple text file consisting of a sequence of Groups, each of which defines a region of the keyboard. Each Group contains a <group> header line, followed by one or more <region> lines, each of which maps one sample file to a specific velocity range within the key group.

Downloading the example files

Click on these links to download two SFZ examples:

  • single sample, same as PAD-Sonitarium E4 from Signs of Life: single-sample.zip
  • 11 zones, 3 velocity layers, using samples extracted from the mda-ePiano VST: mda-epiano.zip

In each case, the zip archive expands to a single SFZ file and a folder called samples containing WAV files.

Structure of the SFZ file

The following describes the basic SFZ format recognized by Guru Sampler. Make sure to read the Changes in Unify v1.3.2 section below, for some useful variations.

Let's look at the first four lines of mda-ePiano.sfz:

<group> lokey=0 hikey=39 pitch_keycenter=36
  <region> lovel = 0 hivel = 47 loop_mode=loop_sustain loop_start=4076 sample=samples/ePiano01.wav
  <region> lovel = 48 hivel = 79 loop_mode=loop_sustain loop_start=2868 sample=samples/ePiano02.wav
  <region> lovel = 80 hivel = 127 loop_mode=loop_sustain loop_start=11918 sample=samples/ePiano03.wav

The <group> line says we are mapping a group of samples to the MIDI note-number range 0 through 39 (inclusive), and that the pitch of each sample is that of MIDI note-number 36.

The three <region> lines define how three separate samples (ePiano01.wav, ePiano02.wav, ePiano03.wav) are assigned to three MIDI velocity-ranges.

  • ePiano01.wav is for note-on velocities from 0 to 47. It loops through the sustain and release periods, starting from sample-index 4076 and continuing to the end.
  • ePiano02.wav is for note-on velocities from 48 to 79. It loops through the sustain and release periods, starting from sample-index 2868 and continuing to the end.
  • ePiano03.wav is for note-on velocities from 80 to 127. It loops through the sustain and release periods, starting from sample-index 11918 and continuing to the end.

Some things to note:

  • Typically, the <group> lokey/hikey ranges will be non-overlapping and span the range 0-127, but this is neither required nor enforced by Guru Sampler.
  • Typically, the <region> lovel/hivel ranges will be non-overlapping and span the range 0-127 (technically 1-127 because velocity 0 is not used for note-on), but again, not required.
  • Anytime you have overlap, where two or more separate sample files are assigned to the same key/velocity, Guru Sampler will choose randomly among them for each note, yielding a kind of “poor man's round-robin” effect.
  • Guru Sampler is NOT a “streaming” sampler (yet). All samples are loaded fully into RAM. It is up to you to limit the RAM footprint, which will be 4/3 the size of 24-bit WAV files, or 2x the size of 16-bit WAV files, because 4 bytes/sample are used.
  • You CAN use AIFF or other standard formats; you don't have to use WAV.

Each <group> line may contain the following tags (default values in parentheses):

  • lokey (0), hikey (127) : MIDI key-number limits
  • pitch_keycenter (64) : MIDI key-number on which the sample's assumed pitch is based

Each <region> line may contain the following tags (default values in parentheses):

  • lovel (0), hivel (127) : MIDI velocity limits
  • loop_mode : the “value” is ignored; if present the sample will loop on playback
  • loop_start (0), loop_end (#samples - 1) : 0-bases indices of start/end of loop region
  • tune (0.0) : amount, in cents (decimals OK) by which the sample pitch must be raised (positive value) or lowered (negative) to exactly match the pitch_keycenter value
  • sample=<path to sample file> : identifies the sample file
    • If the path starts with a drive letter on Windows, or with the slash character (“/”) on Mac, this is an absolute path, which may reference any file on your system.
    • Otherwise, the path is relative to the folder containing the .sfz file
    • The path MAY contain embedded spaces, and ends at the end of the text line

Note you do NOT have to put new sample-sets into Samples folders under Unify's Libraries folder. You can add a folder called Samples directly in the main PlugInGuru/Unify folder, (sibling to the Libraries folder) and create sub-folders in there, containing your SFZ files (more than one if you wish) To open them in Guru Sampler, choose “<Samples Folder>” in the leftmost menu, then the name of your sub-folder in the middle menu, and finally the name of the SFZ file you want in the rightmost menu.

A simpler example

When all you need to do is map one sample across the entire keyboard, the SFZ is much simpler, requiring only one <group> line and one <region> line. Here is PAD-Sonitarium E4.sfz in its entirety:

<group> lokey=0 hikey=127 pitch_keycenter=76
<region> end=1066811 loop_mode=loop_continuous loop_start=241735 loop_end=1066810 lovel=0 hivel=127 tune=0 sample=samples/PAD-Sonitarium E4.wav

The <group> line has

  • lokey=0 hikey=127, meaning the entire MIDI key-number range. (You could actually omit these entries entirely, since these are the default values for lokey and hikey.)
  • pitch_keycenter=76. This is the really important part, which indicates that the associated sample will sound at its natural pitch (not sped up or slowed down) at MIDI note number 76 (aka E4).

The <region> line has

  • end=1066811 indicating the sample-index of the last sample. (This could have been omitted, because the sample file is exactly 1,066,812 samples long, and end defaults to the index of the last sample.)
  • loop_mode=something (The =loop_continuous could actually be anything; all that matters is that the loop_mode part is there.)
  • The loop_start and loop_end items are the important part. They indicate the sample-indices of the first and last sample of the segment which loops indefinitely while a key is held down.
  • lovel=0 hivel=127 indicates that this sample is played for the entire MIDI note-velocity range. These items could be omitted, as 0 and 127 are the defaults, but we include them here to indicate that you could also set e.g. hivel=80 to respond only to velocities 0–80.
  • tune=0 means the pitch of this sample is not adjusted up or down. To tune the sample UP by 10 cents, for example, you would say tune=-10. (Negative values push the pitch UP, positive values push it DOWN; don't ask why.)
  • sample=samples/PAD-Sonitarium E4.wav identifies the sample file. It must always be the last item on the line.

Changes in Unify v1.3.2

In Unify v1.3.2, the SFZ format rules are relaxed slightly, allowing the option to omit <group> lines entirely, and simply put all tags (lokey, hikey, etc.) onto the <region> lines.

Furthermore, Guru Sampler is able to read loop endpoints encoded in WAV files (if present), as follows:

  • If loop tags (loop_mode, loop_start, loop_end) are present in the SFZ file, these take precedence.
  • Unify will only attempt to read loop endpoints in WAV files if both of the following are true:
    • loop_mode or loop_start tags are not present in the SFZ file
    • loop_end=0 or trigger=attack are present in the SFZ file.

The trigger=attack tag has no meaning for Guru Sampler, but is found in all the Zampler Bundle SFZs, so we have co-opted it to trigger Guru Sampler to read loop endpoints, which are present in nearly all of the Zampler WAVs.

Changes in Unify v1.7

Unify v1.7 allows use of absolute paths in SFZ files, to refer to sample files anywhere on your system, including network drives, USB drives, etc.

Changes in Unify v1.8

Unify v1.7 includes two more changes, mostly aimed at improved compatibility with Bjoern's Sample Mapper, an excellent free SFZ map-creation utility from German developer Björn Bojahr.

1. default_path tag: Using full absolute paths for every sample tends to be repetitive, since all the sample files used in a given SFZ file are usually located in the same folder. You can now include a line at the top like this:

<control>
default_path=D:\PlugInGuru\Content Development\Samples\

and then use relative paths in your region lines. The <control> line is optional; it is tolerated if present, but is not required.

2. loop_mode tag is now optional: Looping will be enabled for a sample if any tag starting with loop_ is present, with the exception of the special tag loop_end=0 which causes looping to be enabled only if Guru Sampler finds loop-start and loop-end data in the sample WAV file.

Changes in Unify 1.9

The sense of the tune= tag was wrong in all versions of Unify prior to 1.9.x, but has now been corrected. If you had created any SFZ files using the tune= tag, you will need to update them.

  • E.g., tune=12 should become tune=-12 and vice versa.
  • You won't need to change any SFZ files in which you did not use the tune= tag at all.

Converting from other sampler formats

It would be wonderful if you could get a program which would magically convert key-mapped sample sets for other samplers (like ESX24 or Kontakt) to the SFZ format used by Guru Sampler. Unfortunately, there is no such thing.

The best available option is Translator by Chicken Systems. The full version costs $149, but you're only interested in converting to SFZ, you can buy the “Special Edition” for $79. It can indeed convert almost any sampler format to what it calls “Cakewalk SFZ”, BUT

  • These files require manual editing, because they're not quite the same as what Guru Sampler needs
  • In particular, the files will contain multiple redundant copies of several tag items.

Translator is no magic bullet. It's an exceptionally quirky and confusing program. If you use it, steel yourself for frustration, confusion, and regret about how much you paid for it. Its user-interface is not at all intuitive, especially the “bulk conversion” features (which can easily leave you wondering why you suddenly have multiple copies of many large WAV files on your disk).

If you have used Apple's ESX24 plug-in to create sample maps, an excellent free option is Bjoern's Sample Mapper, which is able to import .esx files and export SFZ files compatible with Guru Sampler.

Unify/Guru Sampler folder structure

All Unify's content lives in what we call the “main data folder”, which you were asked to specify when you installed Unify. If you don't remember where it is, go to Settings and look about half-way down for the line marked “Data folder”.

The full path to the main Unify data folder is on the right, and you can quickly open it in Finder/Explorer by clicking the Open… button. (Concerning the Change… button, see Moving Unify's main data folder.)

Here's a simplified view of a typical Unify data folder:

Note that there is a Samples folder at the top level (beside Libraries, Presets, etc.), and also one inside each library's folder. The one at the top level is called the “global samples folder”, and is where you should typically put your own .sfz files. Each library can also have its own Samples folder, for samples that are part of that library. (If you don't have a global Samples folder, you can create one manually.)

Guru Sampler provides a row of three pop-up menus for selecting a sample-set (i.e., an .sfz file).

From left to right:

  1. The library menu lets you choose any library, and this effectively selects that library's Samples folder. At the very top of the list, you can also choose “<Samples Folder>”, which selects the global Samples folder.
  2. The bank menu lets you select a sub-folder under the selected Samples folder.
  3. The sound menu lets you select a .sfz file within the selected sub-folder.

These three menus enforce the following simple rule about where .sfz files live in the folder hierarchy: .sfz files always live in sub-folders of a Samples folder—either the global one, or one in a library folder.

  • The left menu in Guru Sampler selects the Samples folder
  • The middle menu selects a sub-folder (aka “bank”) under that, and
  • The right menu selects a .sfz file in the sub-folder.

This expanded view of a typical global Samples folder illustrates two typical ways in which sample and .sfz files can be organized:

  • The DX7 bank has all the samples referred to by both Today EP offset.sfz and Today EP.sfz thrown together into a single folder called samples.
  • The My Samples bank is a bit more organized, with each .sfz's own samples grouped together into their own folder (whose name matches that of the .sfz file).

Note Guru Sampler only cares about where .sfz files sit in the folder structure, not where the sample files are, because each .sfz file includes all necessary information about where to find the samples.

Starting with Unify v1.8, sample files don't even have to live under any of the Samples folders; they can live anywhere, in any folder on any drive on your computer. The .sfz files, however, must all live in sub-folders of some Samples folder.

One last thing: If you explore the Samples folder of any Unify library, you'll usually see groups of large files with the file-type .gsd (Guru Sampler Data), While those libraries were being developed, the sample and .sfz files were set up as in the example. When a library is processed to prepare it for publication, each .sfz file gets replaced by a corresponding .gsd file.

sampler-import.txt · Last modified: 2023/05/08 18:59 by 127.0.0.1