---
title: The ConvertWithMoss Manual
author: 
    - Jürgen Moßgraber
header-includes:
    - \usepackage{fancyhdr}
    - \pagestyle{fancy}
geometry: margin=2.5cm
papersize: a4paper
date: \today
...

<div style="page-break-after: always; visibility: hidden"> 
\pagebreak 
</div>

# Introduction & Installation

This tool converts multisamples in a [specific source format to a different destination format](README-FORMATS.md#). Furthermore, it can create multisample files from plain sample files like AIFF and WAV.

Additionally, the conversion process reads and writes metadata (name, category, creator, description and keywords) as well as envelopes and filter settings, if supported by the format. If the source format does not support metadata a guessing algorithm is applied based on the samples names.

Details about the specific converted parameters can be found in a [spreadsheet][1].

## Reporting bugs and asking questions

If you run into an error or you are stuck somewhere, feel free to get in touch. But make sure that you have read this manual and also have a look at the tutorial videos on my Youtube channel. To report bugs and/or ask questions write either to the ConvertWithMoss thread on KVR or create an issue in the ConvertWithMoss GitHub projects. All links can be found on the ConvertWithMoss [Download][2] page.

## Installation

[Download][2] and run the matching installer for your operating system.
After that you can start the application ConvertWithMoss.

### macOS issues

Since the build depends on the GitHub build infrastructure, you need a recent macOS version.
This is currently macOS 13 for Intel and macOS 14 for ARM based Macs. It might work down to macOS 11 but I cannot test that.

After installation macos will complain about different things when you try to run the application, which vary depending on your macOS version:

1. The application is unsafe to run since it is downloaded from the internet.
2. The application is unsafe to run since it is not signed by Apple.
3. The application files are corrupted.

To fix this, do the following:

* Run the application again and click away the error.
* Open the system settings and go to *Privacy & Security Settings*.
* Scroll to the very end, there should now be a message saying something like 'publisher of ConvertWithMoss could not be identified'.
* Click on the allow anyway button
* When you start ConvertWithMoss again you need to confirm again that you want to run the application.

If this did not work for any reason, try this:

Open the Terminal app and enter the application folder:

```sh
cd /Applications/ConvertWithMoss.app
```

Then remove the evil flag (Requires your administrator password):

```sh
sudo xattr -rc .
```

Since this seems not to work for everybody, there is another solution:

Temporarily, disable the Gatekeeper with

```sh
sudo spctl --master-disable
```

Open the application (should work now). Close it and enable Gatekeeper again to feel safe...

```sh
sudo spctl --master-enable
```

The application should now run also with Gatekeeper enabled.

Finally, have fun.

## Build from sources

Ensure to have the required `JDK` and latest `Maven` software installed and set the `JAVA_HOME` environment variable to specify which Java version to use; the minimum required version is `25`. Then use `mvn install` command to start the build.

See also the various build scripts in this directory as references on how to build the documentation and/or the application source files.

For Linux (BSD not tested) there is also a `Makefile` for build and install with the usual `make` and `make install` commands.

# Usage via the user interface

1. Select the source format on the left.
2. Now the source file(s) need to be selected. There are 2 conversion modes: 1) Convert several source files (batch mode) or 2) one single source file. Select either "Folder" for batch mode or "File" for single file conversion with the choice box in front of the source text field.
3. Select the source folder/file with the *Select* button (or type/copy it into the text field). In the default batch mode, the files can also be located in sub-folders.
   * In single file mode, *Select* opens a file dialog whose filter box lists every source format with its file endings, the current one preselected. Afterwards the source format is set from the picked file: a filter which you switched in the dialog wins, otherwise the file ending decides, and a disk image goes to the generic ISO/IMG format, which hands it to whichever sampler format can read it.
   * Each mode keeps a path history of its own, which is exchanged along with the entered path when you use the toggle. You can also simply type the path of a file into the field, which converts that file alone whatever the toggle says.
4. Select the destination format on the right.
5. Select the output folder where you want to create the multisamples. You can add a non-existing folder to the name, which then is automatically created. E.g. you could select the Desktop and then add a folder *Conversions*.
6. Choose the type of the created output format: either single presets, a preset library which contains all found source files, a performance which contains several presets with settings or finally a library of performances. Only some destination formats support libraries and performances, all others are greyed out.
7. Press the *Convert* button to start the conversion. The progress is shown with notification messages in the log area, which you should check for potential errors like defect source files, skipped folder, etc. This log is also written to a file in the output folder.

Alternatively, press *Analyse* to analyse all potential source files but do not to write any file(s). Use this to quickly check for errors before finally running the slower conversion process.

## Picking specific source presets (Contents...)

Every source format has a *Contents...* button. It reads the source without writing anything and shows all presets it found as a tree of their folders, of their file - if the file contains more than the one preset - and of the containers inside of that file (e.g. image, bank, preset). Each entry shows its number of zones, its key range and its category, which is useful to explore a bank or a preset folder you do not know yet. Tick the presets you want and only those are converted; the number of them is shown below the source path and *Clear* discards the selection again.

This works for a format where one file simply is one preset as well, e.g. a folder of Elektron Tonverk or Synthstrom Deluge presets. The tree then lists the presets themselves - under the folder they are in and with the name which is stored inside of the file, which is not necessarily the name of that file. The name of the file is added to a preset which is named differently. Only the files of the ticked presets are read again by the conversion, so narrowing a large folder down also makes the conversion much quicker.

Highlighting a preset and pressing *Play* - or double-clicking it - plays one note of it. The note is rendered from the preset as it was read, with its amplitude and filter envelopes, its filter and its LFOs applied, so you hear what the conversion produces and can pick the presets by ear instead of by name. The preset is read from its file again for this, which takes about a tenth of a second even inside a large disk image. Pressing *Play* again stops the note, as does closing the dialog.

## Processing

Clicking the *Process* button open a dialog to configure processing options which will be executed for each sample during the conversion process.

* **Enable**: Use this to activate or deactivate all processing features below.
* **Normalize**: Normalizes all samples. The algorithm normalizes across all samples of a multi-sample and not each sample individually.
* **Make Mono**: Combines all stereo (incl. mono-split) samples to mono samples.
* **Trim sample start/end**: If there is an unused area of the sample before the start or after the end, it will be removed.
* **Maximum number of samples**: Reduces the number of samples in a multi-sample to this number (clear the field to ignore). The algorithm tries to keep the distribution of samples over thes key- and velocity range.
* **Reduce bit-depth**: If the source sample has a higher bit-depth, it will be reduced to this setting.
* **Reduce sample frequency**: Reduces the sample frequency of all samples to the given value. If the sample frequency is smaller than the selected value the sample is not modified.
* **Always re-sample**: Does as well up-sampling to the set sample frequency and bit depth, if enabled.
* **Set fixed loop-crossfade**: Sets all loop cross-fades (if supported by the destination format) to this percentage value. For a destination whose sound engine cannot cross-fade at playback (e.g. Roland ZEN-Core), the cross-fade is instead baked into the written sample audio; a loop that already wraps cleanly is left untouched.
* **Snap loops to zero-crossings**: Moves the start and end of forward loops to a nearby zero-crossing, which removes the click that some sample libraries have at the loop point (e.g. auto-sampled instruments whose loop was not designed to be click-free). The adjustment is conservative: single-cycle loops are left untouched and a boundary is only moved when it actually reduces the discontinuity at the loop wrap. Enabled with `-Zs` on the command line.
* **Transpose (semitones)**: Transposes playback by the given number of semitones (-24 to 24) by moving the root notes of all samples. The key ranges are not changed, so each key still plays the same sample - only higher or lower. Useful for libraries whose presets are mapped an octave off (some commercial SoundFonts carry root keys one octave above the samples' true pitch and therefore sound an octave lower than played). Set with `-Zp` on the command line.

## Options

* **Create folder structure**: If enabled, sub-folders from the source folder are created as well in the output folder. For example, if I select my whole "Sounds" folder, there are sub-folders like `Sounds/07 Synth/Lead/01W Emerson'70 Samples`. In that case the output folder would contain e.g. `07 Synth/Lead/01W Emerson'70.multisample` if Bitwig multisample is selected as the destination format.
* **Add new files**: Starts the conversion even if the output folder is not empty. Duplicates will get unique names by adding numbers.
* **Dark Mode**: Toggles the user interface between a light and dark layout.

[1]: https://github.com/git-moss/ConvertWithMoss/blob/main/documentation/SupportedFeaturesSampleFormats.ods
[2]: https://mossgrabers.de/Software/ConvertWithMoss/ConvertWithMoss.html

# Usage via the command line interface (CLI)

Locate the ConvertWithMoss executable on your system. On **Windows** use the application ConvertWithMossCLI.exe which is in the same folder as ConvertWithMoss.exe.
Open a console window. As soon as you add attributes after the application it will run in CLI mode instead of opening the ConvertWithMoss application window.

First display all of the available attributes by typing:

```./ConvertWithMoss -h```

The following output is displayed (the processing parameters are omitted):

```
Usage: ConvertWithMoss [-afhPV] -d=DESTINATION [-l=LIBRARY]
                       -s=SOURCE [-t=TYPE] [-p[=KEY=VALUE...]]...
                       SOURCE... DESTINATION_FOLDER
      SOURCE... DESTINATION_FOLDER
                           The source folder to process or, instead, one or
                             more source files to convert only these (e.g. by
                             using a wildcard), followed by the destination
                             folder to write to.
  -a, --analyze            If present, only analyzes the potential source files.
  -d, --destination=DESTINATION
                           The destination format.
  -f, --flat               If present, the folder structure is not recreated in
                             the output folder.
  -h, --help               Show this help message and exit.
  -l, --library=LIBRARY    Name for the library. Set to create a library.
  -p=[KEY=VALUE...]        Key-value pairs in the form -pkey1=value1,
                             key2=value2,...
  -P, --machine-progress   If present, the progress of the conversion is
                             additionally written to the error output in a
                             machine-readable form ('CWM_PROGRESS pct=<0..100>
                             phase=<token> detail=<text>'), which allows a
                             hosting application to display it. Can also be
                             requested by setting the environment variable
                             CWM_MACHINE_PROGRESS to 1.
  -s, --source=SOURCE      The source format.
  -t, --type=TYPE          Set to either 'preset' (the default if absent) or
                             'performance' (without the quotes).
  -V, --version            Print version information and exit.
```

The parameters should be easy to understand since they are identical to what you can do with the user interface.
Here is an example for a conversion from Kontakt NKI files to 1010music format:

```./ConvertWithMoss -s nki -d 1010music D:\MySampler\Kontakt C:\ConversionOutput```

If you do not want to convert all files of a folder, give the files to convert instead of the folder, which is most useful with a wildcard. This converts only the two named programs and only the EXS files which start with 'Piano':

```./ConvertWithMoss -s exs24 -d 1010music "My Rhodes.exs" "My Wurli.exs" C:\ConversionOutput```

```./ConvertWithMoss -s exs24 -d 1010music D:\MySampler\Piano*.exs C:\ConversionOutput```

Note that sub-folders are not searched in this case, since the given files already state exactly what to convert. Each of the files is converted on its own, exactly like it would be as part of a full folder conversion.

To get a list of the available detectors simply set a non-existing one like this (same for the creators):

```./ConvertWithMoss -s whatever -d 1010music D:\MySampler\Kontakt C:\ConversionOutput```

All configuration settings for the detector and the creator are available as well. These settings are can be applied with the -p attribute and then adding a list of key/value pairs. To get a list of the available settings for the selected detector and creator simply add an illegel one like this:

```./ConvertWithMoss -s nki -d 1010music -pKey=Value D:\MySampler\Kontakt C:\ConversionOutput```

You will get the following output:

```
Unknown parameter: 'key'.
Accepted source parameters: [NkiPreferFolderName, NkiDefaultCreator, NkiCreators]
Accepted destination parameters: [1010musicWriteBroadcastAudioChunk, 1010musicWriteInstrumentChunk, 1010musicWriteSampleChunk, 1010musicRemoveJunkChunk, 1010musicInterpolationQuality, 1010musicResampleTo2448, 1010musicTrimStartToEnd]
```

The names of the parameters should be easy to match when looking at the ConvertWithMoss user interface. Checkboxes are boolean value which can be set with 0 and 1, for example:

```./ConvertWithMoss -s nki -d 1010music -p1010musicResampleTo2448=1 D:\MySampler\Kontakt C:\ConversionOutput```

Multiple settings are concatenated by using a comma:

```./ConvertWithMoss -s nki -d 1010music -pNkiDefaultCreator="Klaus Meier",1010musicResampleTo2448=1 D:\MySampler\Kontakt C:\ConversionOutput```

Finally, an example for creating a library of performances:

```./ConvertWithMoss -s nki -d ysfc -l Pads -t performance D:\MySampler\Kontakt C:\ConversionOutput```

A destination format which cannot hold what was asked for - a library of several presets, or performances at all - is reported as an error and nothing is converted. The user interface only offers the output types which the chosen destination supports; the command line accepts '-l' and '-t performance' for every destination, so they are checked before the detection starts.

Additionally, there are several parameters for processing the samples as well. They use 2 letters and always start with a 'Z'. Note that processing needs to be enabled by adding '-Ze'.

## Machine-readable progress

The output of a conversion is written for a human: the progress of a file is a row of dots. An application which runs ConvertWithMoss as a child process - e.g. to offer the conversion from inside of its own user interface - cannot derive a percentage from those dots. Adding '-P' therefore additionally writes the progress to the **error output** in a form which is easy to parse. The normal output is not changed by this, so both can be used at the same time. If the hosting application cannot add options to the command line, the environment variable `CWM_MACHINE_PROGRESS` can be set to '1' or 'true' instead, which has the same effect.

Each event is one line which is terminated with a line separator and flushed immediately:

```
CWM_PROGRESS pct=<0..100> phase=<token> detail=<text>
```

* **pct**: the percentage which is reached, 0 to 100.
* **phase**: one of `start` (the run begins), `convert` (a source file was started or finished), `sample` (a sample file of the current source file was loaded) and `done` (the run ended - if it was cancelled the percentage is the one which was reached and not 100).
* **detail**: the rest of the line, which may contain spaces since it is a file name or a path. It is reduced to printable ASCII characters, so that both processes do not need to agree on a character encoding; all other characters are replaced by a question mark.

Any line which is not understood should be ignored, which keeps the protocol open for further phases. Here is a shortened example of a conversion of two Kontakt instruments:

```
CWM_PROGRESS pct=0 phase=start detail=D:\MySampler\Kontakt
CWM_PROGRESS pct=0 phase=convert detail=Enigma.nki
CWM_PROGRESS pct=2 phase=sample detail=Kick_01.wav
CWM_PROGRESS pct=4 phase=sample detail=Snare_02.wav
CWM_PROGRESS pct=50 phase=convert detail=Enigma.nki
CWM_PROGRESS pct=50 phase=convert detail=Prophecy.nki
CWM_PROGRESS pct=52 phase=sample detail=Pad_C2.wav
CWM_PROGRESS pct=100 phase=convert detail=Prophecy.nki
CWM_PROGRESS pct=100 phase=done detail=
```

The percentage range is split into one slice per source file, which is why a finished file reports the start of the next one. How many samples a source file contains is only known once it was read, therefore the progress inside of a slice approaches the end of the slice with every loaded sample but only reaches it when the file is finished. This keeps a single large instrument - a Kontakt library often is one file with several hundred samples - moving instead of standing at the same percentage for minutes. Formats which do not read their samples from separate files, e.g. the disk images of the hardware samplers, only report the `convert` events.
