Unify Manual

Your complete reference to PlugInGuru's creative playground!

User Tools

Site Tools


sample-mapper

SampleMapper utility

This page describes a very early “alpha” version of SampleMapper. You are welcome to try it, but please note we are working on a new and far more capable SampleMapper program which will be available soon as a paid product.

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, but that is still not available. Prior to November, 2021, we had no user-accessible tools for importing samples. Today, we have one simple utility app called SampleMapper, which can at least handle some basic cases. Bringing your own samples into Guru Sampler is still not a simple process, so we don't provide full support, but we hope the new SampleMapper tool will prove useful to at least some of you.

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. For details, see the Manual creation of SFZ files for Guru Sampler.

SampleMapper is a simple program for creating these SFZ files, intended to handle two basic cases:

  1. “Drum” Maps: A series of samples must be mapped to a contiguous range of notes on the keyboard, starting at a selected note, and increasing by one for each sample.
    • This isn't exclusive to drums, of course. We're just using “drum maps” as a convenient shorthand.
  2. “Note” Maps: A program such as Keymap Pro by Redmatica has been used to prepare a collection of pitched musical samples, and the sample file names all incorporate either note-names (e.g. C3, F#5, Ab2, etc.) or the equivalent MIDI note-numbers (e.g. 60 = middle C).
    • “Note” samples prepared in this way will almost always have gaps, and so a major distinction from the “drum map” case is that SampleMapper will automatically map the samples to appropriate contiguous note-groups, where adjacent note-groups don't overlap, nor are there any gaps or “dead zones” between them.

Downloading and installing SampleMapper

Download links:

In both cases, simply unzip the downloaded file to obtain the executable:

  • Windows: SampleMapper.zip
  • Macintosh: SampleMapper.app (you may not see the .app part)

Put the executable wherever you wish on your system. Double-click to run it.

Before you start: Important concepts

To use SampleMapper, you use the GUI controls to define aspects of the map(s) you want to create, then drag/drop groups of sample files, or folders containing sample files, into the GUI.

Note Some Windows systems may not allow drag/drop operations, if your user-account does not have Administrator privileges. The only solution is to run the app as Administrator, by right-clicking the app icon and choosing “Run as Administrator”. A User Account Control (UAC) dialog will pop up, and you will have to enter a valid Administrator password for your system.

SampleMapper automatically remembers how you set up all of its controls, and will restore the last-used settings each time you run it. To understand how it does so, see under “Settings file” below.

The Settings tab

Middle-C Octave Number

The numbering of octaves in note-names such as C3, F#6, etc. is not fully standardized. Yamaha instruments usually designate middle C (MIDI note 60) as “C3”; this is also the default for Logic Pro and Unify. Roland instruments designate middle C as “C4”, and BlueARP even allows using “C5” (because this avoids the need for negative numbers entirely; MIDI note 0 is then designated “C0”).

When working with note-names, either encoded in file-names, or typed into the program yourself, you need to be aware of which octave-numbering convention you are using, and ensure that it is selected in the Settings tab.

SFZ Folder Path

Before actually saving any SFZ files with SampleMapper, you must choose a folder on your system for them to be saved into. This will typically be a new sub-folder of the Samples folder directly under the main Unify data folder, or, if you are creating a new Unify library, it will be a sub-folder of the Samples folder for that library.

The reason why you should always create a sub-folder inside the Samples folder is because this is what Guru Sampler expects.

Making Drum maps

Percussive samples such as drums are usually mapped one per note, to a sequence of consecutive notes, and are usually played back at their natural pitch. To create a drum map, you need only specify the starting MIDI note-number, and then drag/drop your a group of sample files into the SampleMapper GUI. The sample files will be assigned to MIDI notes in alphabetical (alpha-numeric) ordering of the sample-file names. Click Save… to actually save SFZ file(s).

Starting MIDI note number or name

In the box labeled Starting MIDI note number or name, you can either enter a MIDI note-number, or a note-name like “C3”, “F#5”, or “Db4”. Note names will be interpreted according to the middle-C octave number setting on the Settings tab; the interpretation (which may be an error message) will be displayed just to the right of the edit box.

Dragging in sample files/folders

You specify which sample files (or folders full of sample files) to use in creating new SFZ file(s) by dragging them into the GUI.

If you drag/drop a group of sample files, the program will prepare to create a single SFZ file. The table in the middle of the GUI will show a list of the files, indicating the note-numbers to which they will be assigned. You can drag files in individually, and they will be added to the end of the list. If you drag in several files at once, they will be added to the table in alphabetical order of the file names. There is presently no facility to edit the table; this may come in a future update. Click Clear and start again if you get the order wrong.

You can resize the SampleMapper window, and also resize individual columns by dragging the dividing-lines between them, to ensure you can see all of the data.

If you have several folders full of sample-files, you can also drag/drop the folders into the SampleMapper GUI. SampleMapper will then create one SFZ file for each folder. The table is automatically cleared when you drag in one or more folders.

You must drag in only files, or only folders; the program will not accept a mix of files and folders.

Clear and Save... buttons

After dragging in your files/folders, check the table display to ensure that samples are assigned to notes in the way you intend. If not, you can click the Clear button to clear the table, and you may need to rename some or all of the sample files (manually, using Explorer/Finder) before trying again.

When you are ready to create SFZ file(s), click the Save… button. If the current SFZ folder you specified in Settings does not exist (e.g., if you moved, renamed, or deleted it in Explorer/Finder), SampleMapper will prompt to ask if you want to create it. If you click Cancel, nothing will be done: neither the folder nor any SFZs will be created. If you click Save, you will be presented with a file-save dialog as described below.

For each SFZ to be created, SampleMapper will present a standard file-save dialog, with the save-location set according to the “SFZ folder” setting on the Settings tab, and the SFZ file name already set based on the enclosing folder for each group of samples. If this is what you want, just click Save; if not, you can choose a different filename and/or target location.

Making Pitched Note maps

Preparing sample maps for pitched musical samples is considerably more complex than for drum samples. Pitched samples are usually saved with note-names or MIDI note-numbers (corresponding to each sample's natural pitch) encoded somewhere in each sample's file-name, but there are really no standard file-naming schemes. SampleMapper's Notes tab allows you to specify enough details for it to be able to pick out (“parse”) the note-name or -number from the sample-file names, and provides a table showing the results, which you can use to assess whether your specifications are correct.

Dragging in sample files/folders

You specify which sample files (or folders full of sample files) to use in creating new SFZ file(s) by dragging them into the GUI.

If you drag/drop a group of sample files, the program will prepare to create a single SFZ file. The table in the middle of the GUI will show a list of the files, indicating the note-numbers to which they will be assigned. Files will be assigned to note-numbers in alphabetical order of the file names. There is presently no facility to edit the list; this may come in a future version of SampleMapper.

You can resize the SampleMapper window, and also resize individual columns by dragging the dividing-lines between them, to ensure you can see all of the data.

If you have several folders full of sample-files, you can also drag/drop the folders into the SampleMapper GUI. SampleMapper will then create one SFZ file for each folder.

You must drag in only files, or only folders; the program will not accept a mix of files and folders.

Include tags to tell Guru Sampler...

If your samples are WAV files, and you have prepared them using looping software which embeds the loop-endpoints in RIFF tags in each WAV file, check the Include tags to tell Guru Sampler to look in WAV files for loop endpoints box. The generated SFZ file will include the special tag loop_end = 0 for each sample (see Manual creation of SFZ files for Guru Sampler).

Parse note NAMES/NUMBERS...

The first pop-up menu allows you to specify whether your sample filenames contain MIDI note-numbers or note-names like “C4”, “F#5”, “Db3”, etc. Note that note-names are interpreted according to the middle-C octave number setting on the Settings tab.

File-name parsing controls

Most sample-preparation programs put note-names (or numbers) at the end of each sample-file name, just before the “extension” (e.g. .wav, .aif, etc.). SampleMapper only looks at the main part of the file name, up to but not including the period which begins the extension. The beginning part of the file name will typically be something related to the instrument sampled, and very commonly, this will be separated from the part containing the note name (or number) by a special character (e.g. hyphen) or sequence of characters (e.g. space-hyphen-space). Type this “separator sequence” into the After the last occurrence of box, and SampleMapper will simply skip over the beginning part entirely.

Let's begin with a simple example, with file names like:

  • Guitartronik_E1.wav
  • Guitartronik_E2.wav
  • Guitartronik_E3.wav
  • Guitartronik_E4.wav
  • … and so on

For these files, the separator sequence is a single underscore character (_), there are no extra characters after the underscore that must be skipped, and everything after the underscore is a valid note-name. This is a particularly simple case. (See below for a more complicated example.)

When you drag/drop a group of WAV files (OR a group of folders containing sample files) into the GUI, SampleMapper will attempt to parse the file names according to the specifications you have set, and will report its results in the table at the bottom. For example, dragging the four “Guitartronik” files in the example above will result in a display similar to that shown in the screenshot above.

  • The Folder column shows the name of each file's enclosing folder (which will later be used to define the SFZ file name)
  • The File Name (without extension) column shows the file names (with extension removed) that the program attempts to parse (analyze) to find note-names or -numbers.
  • The Substring column shows the sub-string which is left after skipping over the separator (and optionally some number of additional characters)
  • The Match column shows the part of the sub-string which actually matched the regular expression. These should all be valid note-names. If not, you will need to adjust your settings.
  • The Note# column shows the MIDI note-number that SampleMapper chooses, based on the contents of the Match column. This may be meaningless if the Match column does not contain valid data.

Clear and Save... buttons

After dragging in your files/folders, check the table display to ensure that samples are assigned to notes in the way you intend. If not, you can click the Clear button to clear the table, and you may need to rename some or all of the sample files (manually, using Explorer/Finder) before trying again.

When you are ready to create SFZ file(s), click the Save… button. If the current SFZ folder you specified in Settings does not exist (e.g., if you moved, renamed, or deleted it in Explorer/Finder), SampleMapper will prompt to ask if you want to create it. If you click Cancel, nothing will be done: neither the folder nor any SFZs will be created. If you click Save, you will be presented with a file-save dialog as described below.

For each SFZ to be created, SampleMapper will present a standard file-save dialog, with the save-location set according to the “SFZ folder” setting on the Settings tab, and the SFZ file name already set based on the enclosing folder for each group of samples. If this is what you want, just click Save; if not, you can choose a different filename and/or target location.

A more complex example

Occasionally, a sample-preparation program may put some variable content (such as a sequence number, to ensure files are sorted in the correct order in the Finder/Explorer) after the “separator sequence”. For example, the file names might look something like:

  • D50_DawningPad-01C2.wav
  • D50_DawningPad-02F2.wav
  • D50_DawningPad-03B2.wav
  • D50_DawningPad-04E2.wav
  • … and so on

For these files, the separator sequence is a single hyphen, and you could optionally select “2 characters” in the Skip over menu, so SampleMapper simply skips past them, but we won't do this for this example. The final characters of each file name is a note-name, so you would select “Note Name” from the Then match menu. This automatically populates the text-box at the bottom * [A-G]: Every note-name begins with a single capital letter between A and G

  • [#b]?: This can optionally be followed by either a sharp (“#”) or flat (lower-case “b”)
  • -?: There may optionally be a minus sign before the octave number (see below).
  • [0-9] The note-name ends in a single digit indicating the octave-number.

The following image shows the result of setting up the controls this way and dropping in the “DawningPad” files:

If this file set actually included a file with a minus-sign before the octave number, e.g. D50_DawningPad-00C-2.wav, the results would be incorrect, e.g.:

Look carefully at the results in the last three columns. What has happened here is that SampleMapper skipped to the last occurrence of the separator-sequence - (single hyphen), and since the hyphen and minus-sign are the same character, it skipped all the way to the minus-sign. Solutions to this kind of problem will always be case-specific. In this case, the problem could be solved by changing the separator sequence to d-, giving this result:

It's VERY important to check your results in this way, before trusting that the SFZ file(s) produced by SampleMapper will work correctly in Guru Sampler.

Testing sample maps using Guru Sampler

To test your sample maps using Guru Sampler, locate the Samples folder under the main Unify data folder, and create a new sub-folder inside it, e.g. My Sample Maps. Put your SFZ file(s) inside this sub-folder, along with the sample files they refer to, making sure to keep the structural relationship intact. If your SFZ and sample files are in the same folder (i.e., what you get when you drag the sample files into SampleMapper), put them into your test folder that way, i.e., all the sample files and the SFZ file all together. If your samples are collected into a folder, and your SFZ file is beside (sibling to) that folder, put the SFZ and the sample-folder into the Unify Samples folder. This is very important, because the SFZ files contain the path to each sample file relative to the folder containing the SFZ file.

Start Unify and add a new instance of Guru Sampler. Select <Samples Folder> in the left menu, the name of the new sub-folder you created (e.g. “My Sample Maps”) in the middle menu, and the name of your SFZ file in the right menu. If you click the sample-select menu (as shown below), you should see the note-names and -numbers of all the mapped samples. If you do not, either something is incorrect about your SFZ files, or you may not have kept the right structural relationship between the SFZ file and sample files.

You may find it useful to put all your samples into your working sub-folder under the Unify Samples folder, and drag them from there into SampleMapper, so the SFZs are created there. This can be particularly helpful when you need to repeatedly re-create your SFZs, either due to mistakes, or because you are editing the SFZs to add detail (see Manual creation of SFZ files for Guru Sampler).

After making any change, you don't need to quit Unify, but you may need to either switch to a different SFZ using the rightmost menu, then back again (if the name of the SFZ file has not changed), OR swap in a fresh instance of Guru Sampler (if it has) for the changes to take effect.

Creating samples for a new Unify library

If you are creating a new library for Unify, and you want your samples and SFZs to be specific to that library, simply create a Samples folder inside that library's folder (e.g., next to the Patches folder that Unify itself creates when you save the first patch for your new library). Then basically follow the instructions in the previous section, substituting the library-specific Samples folder for the global Unify Samples folder.

When preparing a new Unify library which is to include its own samples, it's particularly important to make sure all your sample files (.wav, .aif, etc.) are already located wherever you want them to live under the library's own Samples folder before creating your SFZs. This will ensure that the file-paths that SampleMapper creates in the SFZs are relative paths, and hence will still work no matter where the eventual users of your library have decided to store the main Unify data folder.

Settings file

SampleMapper uses an XML file called SampleMapper.settings to keep track of how you last set all the controls, and this is also where the pre-defined search-pattern names and associated regular expressions are stored. If you're technically inclined, you may wish to edit this file to add more pattern definitions of your own.

Make sure to close all instances of SampleMapper before attempting to edit the settings file.

To locate the file on Windows, open an Explorer window and type %appdata%\PlugInGuru into the address bar, then press ENTER. On Mac, open a Finder window and type ~/Library/Application Support/PlugInGuru into the address bar and press ENTER. The file contents look like this:

<?xml version="1.0" encoding="UTF-8"?>
 
<PROPERTIES>
  <VALUE name="middleCOctaveNumber" val="3"/>
  <VALUE name="includeLoopTags" val="1"/>
  <VALUE name="useNoteNames" val="1"/>
  <VALUE name="drumsStartingNote" val="36"/>
  <VALUE name="fileNamePrefix" val="d-"/>
  <VALUE name="skipCharCount" val="0"/>
  <VALUE name="patternIndex" val="0"/>
  <VALUE name="regex" val="[A-G][#b]?-?[0-9]"/>
  <VALUE name="patternDefinitions">
    <PatternDefs>
      <Pattern description="Note Name" regex="[A-G][#b]?-?[0-9]"/>
      <Pattern description="A number" regex="[0-9]*"/>
      <Pattern description="All remaining characters" regex=".*"/>
    </PatternDefs>
  </VALUE>
</PROPERTIES>

To add more pattern definitions, duplicate one of the <Pattern> lines and edit the description and regex strings, taking care not to mess up the quotation marks or tag-endings. (This is a VERY advanced technique, included here strictly for completeness. DON'T attempt this unless you know what you're doing. If you do attempt it, and run into trouble, simply delete the settings file. SampleMapper will create a new, valid one the next time you run it.)

sample-mapper.txt · Last modified: 2022/02/04 15:10 (external edit)