NKS - Details

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.

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.

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

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	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. MST_bgcolor Maschine Studio Background Color (probably also for MK3) VB_bgcolor Visual Browser Background Color (= in Maschine and KK software)
_DatabaseResources\shortname\shortname.db	A SQLite Database containing name variations of the plugin. This database is managed by Maschine / Komplete Kontrol and should left untouched. MKII_shortname The name displayed on Maschine MK2 (and maybe MK1 as well? MST_shortname The name displayed on Maschine Studio and MK3 MIKRO_shortname The name displayed on Maschine Mikro VB_shortname The name displayed in the visual browser
database\pal\categories.db	A SQLite Database containing categories, information about plugins and groups. Currently it is not known for what purpose it is used, as the actual data about presets, plugins, groups and categories is stored in AppData\Local\Native Instruments\Maschine 2\komplete.db3 for Maschine and AppData\Local\Native Instruments\Komplete Kontrol\komplete.db3 for Komplete Kontrol.
dist_database\<vendor name>\<plugin name>\ or dist_database\<plugin name>\	categories.json Contains information about the plugin categories color.json Contains the background color for the visual browser, not sure if it can also contain the background color for Maschine Studio shortname.json The shortnames for different hardware (see above) <pluginname>.meta A metadata file containing vendor and product name
image\<vendor name>\<plugin name>\ or image\<plugin name>\	<pluginname>.meta A metadata file containing vendor and product name MST_artwork.png A 134x66 pixel PNG image containing the artwork displayed when using the Maschine Studio/MK3 plugin browser MST_logo.png A 240x96 pixel PNG image containing the logo displayed in the Maschine Studio/MK3 preset browser. MST_plugin.png A 190x75 pixel PNG image displayed when viewing the plugin chain on the Maschine Studio/MK3 hardware OSO_logo.png A 417x64 pixel PNG image. Currently unknown where this is used. VB_artwork.png A 96x47 pixel PNG image displayed in the visual browser. VB_logo.png A 279x47 pixel PNG image displayed as bank header when browsing a plugin for presets.

Additional Information for images / dist_database

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.

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.

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.

If the vendor name (and most likely the plugin name, too) contain special characters, please read the next section regarding MD5 hashing.

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