Unify Manual

Your complete reference to PlugInGuru's creative playground!

User Tools

Site Tools


sampler-import

This is an old revision of the document!


Importing your own samples into 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
    • 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.

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).

Are you SURE you want to try this?

Seriously, unless you're a bit of a masochist, save yourself the money, time, and trouble, and wait until we can add all the easy, drag-and-drop, graphical-editing loveliness Unify users have asked for.

And remember what we said at the start: WE DO NOT PROVIDE SUPPORT FOR THESE PROCEDURES. You're on your own.

sampler-import.1636568524.txt.gz · Last modified: 2023/05/08 18:59 (external edit)