# NKS - Details

{% hint style="info" %}
This page contains technical details of the Native Kontrol Standard. As a legal disclaimer, I do not have access to the specification from Native Instruments and all the information is based on my own research.
{% endhint %}

## What is NKS?

I assume you already know about NKS, the Native Kontrol Standard. If not, I recommend you look at a brief overview on the [Native Instruments Website.](https://www.native-instruments.com/en/specials/komplete/this-is-nks/)

## Details about NKS

NKS consists of several parts:

* A preset file (.nksf for Instruments, .nksfx for Effects)
* A directory structure where the preset files and metadata information are stored
* Several metadata files
* A central database where favourites are stored and preset names/banks are cached

## NKS Preset Files

NKS preset files are [RIFF](https://en.wikipedia.org/wiki/Resource_Interchange_File_Format) files with 4 sections:

* A Summary Information Section, which contains data like the preset author, comments, bank information, types, modes and vendor name
* A Controller Assignments Section, where the controller pages are stored
* A Plugin ID section, where the plugin ID is stored to the software can load the correct plugin
* A Plugin Chunk section, where the plugin specific preset information is stored

All sections except the plugin chunk section are encoded using [MessagePack](https://msgpack.org).

## Directory Structure

The user content directory contains sub-directories which specify the plugin name. Each plugin directory has one sub-directory per bank. Finally, in each bank directory, the NKS files are stored.

Apparently it's possible to nest banks in sub-directories, however, the actual bank hierarchy is extracted from the NKS files, so sub-directories is just an organizing aid on the filesystem and not within Maschine/KK.

If the bank contains instruments, it might contain audio previews in an additional sub-directory named `.previews`. Audio Previews are stored in the `.ogg` format, consisting of the full NKS filename appended with `.ogg`.

To my knowledge, audio previews are not possible for Effects.

## Cached Colors

From NI Forum user Baer:

> I have some additional information for you: When an individual plugin is loaded the background color for the right screen of a Mk2 keyboard gets retrieved from dist\_database\plugin name\color.json. The background color is only loaded when the plugin image for the left screen was found before. If the plugin image for the left screen is not found or if dist\_database\plugin name\color.json is not found then the background color for the right screen is black. Now comes the interesting part: When the background color for the right screen has been loaded successfully for the first time KK stores the color somewhere in its own database. You can find this out by removing the color.json file or even the entire folder. KK will still remember the background color. This even goes so far that if you change color.json after the first successful load the color does not change anymore!

## Metadata Files

Metadata files are plugin specific and contain information about the Plugin name displayed on the NI Hardware, image files and color settings.

These metadata files are usually stored in the public documents folder, typically found in `C:\Users\Public\Documents\NI Resources`.

| Folder or File                                                                                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \_DatabaseResources\color\color.db                                                                                        | <p>A SQLite Database containing entries for all plugin colors used for Maschine and the Visual Browser. This database is managed by Maschine / Komplete Kontrol and should left untouched.</p><p></p><p><strong>MST\_bgcolor</strong><br>Maschine Studio Background Color (probably also for MK3)</p><p><strong>VB\_bgcolor</strong></p><p>Visual Browser Background Color (= in Maschine and KK software)</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| \_DatabaseResources\shortname\shortname.db                                                                                | <p>A SQLite Database containing name variations of the plugin. This database is managed by Maschine / Komplete Kontrol and should left untouched.</p><p></p><p><strong>MKII\_shortname</strong></p><p>The name displayed on Maschine MK2 (and maybe MK1 as well?</p><p></p><p><strong>MST\_shortname</strong></p><p>The name displayed on Maschine Studio and MK3</p><p><br><strong>MIKRO\_shortname</strong><br>The name displayed on Maschine Mikro<br></p><p><strong>VB\_shortname</strong></p><p>The name displayed in the visual browser</p>                                                                                                                                                                                                                                                                                                                                                                     |
| database\pal\categories.db                                                                                                | <p>A SQLite Database containing categories, information about plugins and groups.</p><p></p><p>Currently it is not known for what purpose it is used, as the actual data about presets, plugins, groups and categories is stored in <code>AppData\Local\Native Instruments\Maschine 2\komplete.db3</code> for Maschine and <code>AppData\Local\Native Instruments\Komplete Kontrol\komplete.db3</code> for Komplete Kontrol.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| <p>dist\_database\&#x3C;vendor name>\&#x3C;plugin name>\ <em>or</em> dist\_database\&#x3C;plugin name>\</p><p></p><p></p> | <p><strong>categories.json</strong></p><p>Contains information about the plugin categories</p><p></p><p><strong>color.json</strong></p><p>Contains the background color for the visual browser, not sure if it can also contain the background color for Maschine Studio</p><p></p><p><strong>shortname.json</strong></p><p>The shortnames for different hardware (see above)</p><p></p><p><strong>\<pluginname>.meta</strong></p><p>A metadata file containing vendor and product name </p>                                                                                                                                                                                                                                                                                                                                                                                                                          |
| <p>image\&#x3C;vendor name>\&#x3C;plugin name>\</p><p><em>or</em> image\&#x3C;plugin name>\</p>                           | <p><strong>\<pluginname>.meta</strong></p><p>A metadata file containing vendor and product name<br> </p><p><strong>MST\_artwork.png</strong></p><p>A 134x66 pixel PNG image containing the artwork displayed when using the Maschine Studio/MK3 plugin browser<br><br><strong>MST\_logo.png</strong><br>A 240x96 pixel PNG image containing the logo displayed in the Maschine Studio/MK3 preset browser.<br><br><strong>MST\_plugin.png</strong><br>A 190x75 pixel PNG image displayed when viewing the plugin chain on the Maschine Studio/MK3 hardware<br><br><strong>OSO\_logo.png</strong></p><p>A 417x64 pixel PNG image. Currently unknown where this is used.</p><p><br><strong>VB\_artwork.png</strong><br>A 96x47 pixel PNG image displayed in the visual browser.<br><br><strong>VB\_logo.png</strong><br>A 279x47 pixel PNG image displayed as bank header when browsing a plugin for presets.</p><p></p> |

## Additional Information for images / dist\_database

{% hint style="warning" %}
This information is most likely not complete. I don't know why NI decided to do it that way, but that's what I found out so far.
{% endhint %}

Maschine and KK use two different mechanisms to decide from which directory to load images.

### Information stored within the NKS files

When showing information before a plugin is loaded (for example, in the preset browser), Maschine/KK use the plugin and vendor name embedded within the NKS file itself. For example, if the plugin name is `Schorsch` and the vendor name is `Kluney`, the bank header image would be loaded from `image\schorsch\kluney\VB_logo.png`.

{% hint style="info" %}
PresetMagician currently makes the vendor and plugin name lower-case. I'm not sure if this is necessary, but from what I remember Maschine/KK does it the same way.
{% endhint %}

{% hint style="warning" %}
If the vendor name (and most likely the plugin name, too) contain special characters, please read the next section regarding MD5 hashing.
{% endhint %}

### Information of the plugin itself

When a plugin is loaded, Maschine/KK takes the plugin's **DLL filename** to decide from which directory to load the data. No vendor information is used, unless it's registered in Maschine/KK's databases somehow (currently unknown how).

If the DLL filename doesn't contain special characters, Maschine/KK simply use the plugin's DLL lower-case filename without the .dll extension. For example, if the plugin's DLL filename is `SuperPlugin.dll`, the resulting image directory would be `images\superplugin\`

If the plugin contains special characters, things get complicated. At first, all special characters are removed and converted to lower-case without the extension. Then a [MD5 hash](https://en.wikipedia.org/wiki/MD5) is applied over the whole DLL filename without the extension and appended to the plugin name after an underscore.. You can use an online [MD5 generator](https://www.md5hashgenerator.com/) to generate an MD5 hash.

Example for u-he's Diva plugin: The DLL filename is `Diva(x64).dll`. The first step is to remove all special characters and lower-case the result, which would be `divax64`. Now, the MD5 hash is calculated over `Diva(x64)`, which is `6cd2cc7f3b48dc8cba1e1855d61c0c67`. Then the MD5 hash is appended to the processed plugin filename, the resulting directory would be `divax64_6cd2cc7f3b48dc8cba1e1855d61c0c67`. Note that the meta file must be named the same as the directory.