Extracting NKI sample metadata for use in PlugInGuru Unify Guru Sampler

Preamble

UPDATE 2021-07-06: This post may be outdated, since today’s release of the new Creator Tools for Kontakt could make this a lot easier (accessing the file system from Lua is supposedly improved). I’ll need to test and validate the potentially much shorter process.

The following post only makes sense if

  • You have licensed copies of
    • PluginGuru Unify software
    • Native Instruments Kontakt 6 software (full edition, not the Kontakt player)
  • You’ve got quite a bit of experience in scripting
  • You are
    • well versed in sampling and the typical metadata required for sample playback
    • and you fully understand that grabbing the sample metadata is just a tiny part of creating a full instrument
    • reasonably familiar with what it takes to make a custom Guru Sampler library
    • reasonably familiar with native Instruments Creator Tools and the Lua scripting language

Background

The PlugInGuru.com Unify plugin (available here) is one of the more interesting music software applications appearing over the last few years. In some ways it competes with meta plugin environments like the Reason Rack and Apple MainStage. In other ways it’s on its own path.

The software is developed by Shane Dunne under the umbrella of John “Skippy” Lehmkuhl’s PlugInGuru brand.

I’ve been a long time customer of John Lehmkuhl’s sound libraries, and so I purchased Unify immediately upon its release.

While Unify depends mostly on 3rd party instruments and effects, one noteworthy exception is the Guru Sampler instrument – a (so far) bare-bones sample playback plugin.

Over the years, I’ve purchased many PlugInGuru libraries – including a couple that are designed for Native Instruments Kontakt. So I was curious, if I could extract the metadata of the samples in those libraries for use in the Unify Guru Sampler instrument. The sample files themselves don’t need any conversion, but the metadata files telling the sampler software how to play the samples are very different.

I needed to grab the metadata needed for the Guru Sampler format from the Kontakt NKI format. So I developed a script to do that, while learning just enough how to use the required tools and scripting language as I went along. Depending on the structure of a particular Kontakt library, the scripts may need modification.

I’m documenting this here in the hope that it will save someone a few hours to write their own script depending on the exact library they want to work with.

Process

I’m using Windows 10 for this. While much of this should also work on MacOS, I haven’t tried so myself. And it only makes sense with an unencrypted sample library for Kontakt.

  • Open Kontakt 6 (I used the standalone version) – and wait until it’s fully opened (it may take a while).
  • Open Creator Tools ( a separate application that ships with Kontakt 6.
  • In Kontakt:
    • Load the desired instrument
  • In Creator Tools
    • Creator Tools should now automatically show the loaded instrument.
    • Navigate to the Lua Script tab and load the extracting LUA script file
    • Run the script
    • The results of the script should now show the desired contents for the SFZ file format needed by the Guru Sampler instrument
    • Copy the contents and put them into a new sfz file – a suggested file name is given close to the bottom. You need to do this manually, because the Lua scripting in Creator Tools doesn’t have a way to write an output file – it only writes to that window. If wanting to work with a DrumKit kind of instrument, you may want to adjust how you organize the Guru Sampler folder structure and adjust the script below accordingly.

The Lua Script

-- -----------------------------------------------
-- Extract Sample Info from Kontakt 6 NKI Instrument in the format used by 
-- the Guru Sampler instrument plugin in Unify https://www.pluginguru.com/products/unify-standard/
-- File format described at https://pluginguru.net/unify/manual/doku.php?id=sampler-import
-- How to use this script described at: 
-- ------------------------------------------------



if not instrument then
    print(
        "ERROR: Kontakt Instrument not focused in Creator Tools. "..
        "Ensure an instrument is loaded in Kontakt and selected in Creator Tools"
    )
    do return end
end

print ("// Kontakt Instrument: " .. instrument.name )
suggestedFileName = instrument.name .. ".sfz"

for i,g in pairs(instrument.groups) do

    local firstZone = true
    for n,z in pairs(g.zones) do

        local sfzGroup = "<group>" .. " lokey=" .. z.keyRange.low .. " hikey=" .. z.keyRange.high .. " pitch_keycenter=" .. z.rootKey 
        print(  sfzGroup )

        local sfzRegion = "<region>" .. " lovel=" .. z.velocityRange.low .. " hivel=" .. z.velocityRange.high .. " tune=" .. g.tune -- .. " offset=" .. z.sampleStart .. " end=" .. z.sampleEnd
        if z.loops[0].mode == 0 then
        --    sfzRegion = sfzRegion .. " loop_mode=no_loop"
        else
            local loopEnd = z.loops[0].start + z.loops[0].length
            sfzRegion = sfzRegion .. " loop_mode=loop_continuous" .. " loop_start=" .. z.loops[0].start .. " loop_end=" .. loopEnd
        end
        local sampleFilePath = z.file
        local sampleFileName = filesystem.filename( sampleFilePath )
        sfzRegion = sfzRegion .. " sample=samples/" .. filesystem.filename( sampleFileName )
        if firstZone then
            suggestedFileName = sampleFileName:gsub ( "_E1.wav" , ".sfz")
            firstZone = false
        end
        print(  sfzRegion )

    end
    
end
print ( "// " .. suggestedFileName )

Bonus

Even with the above script, it’s still tedious to do many instruments. To make that quite a bit faster I ended up writing another script in PowerShell 7 (which at least in theory is also usable on MacOS).

In addition to Kontakt 6 standalone and Creator Tools, it needs Microsoft Visual Studio Code and PowerShell 7 – and Visual Studio Code has to be the default editor used by Creator Tools.

The script effectively consists of a whole bunch of keystrokes. It will need adjusting to your environment. I’m only posting it here as inspiration to write your own, not as a ready to use tool for any environment.

When doing this process for a big number of instruments, the process goes a bit like this:

  • Load target instrument in Kontakt 6
  • Execute PowerShell script (preferably via a single press keyboard shortcut (I’m using an Elgato StreamDeck, but there are other ways of achieving that)
  • repeat

PowerShell 7 Script

$targetFolder ="G:\Music SW Libraries\PlugInGuru\Unify\Libraries\PG MegaMagic Pads\Samples\MegaMagicPads"

$wsh = New-Object -ComObject Wscript.Shell
$wsh.AppActivate("Kontakt")
Start-Sleep 1
$wsh.AppActivate("Creator Tools")
Start-Sleep 1
$wsh.SendKeys("+{F3}")
Start-Sleep 1
$wsh.SendKeys("^{BACKSPACE}")
Start-Sleep 1
$wsh.SendKeys("^{r}")
Start-Sleep 1
$wsh.SendKeys("^%{c}")
Start-Sleep 1
$wsh.SendKeys("^{e}")
Start-Sleep 1
$wsh.SendKeys("^{F4}")
Start-Sleep 1
$wsh.SendKeys("^{n}")
Start-Sleep 1
$wsh.SendKeys("^{v}")
Start-Sleep 1
$wsh.SendKeys("{UP}")
$wsh.SendKeys("+{DOWN}")
$wsh.SendKeys("{DELETE}")
$wsh.SendKeys("{UP}")
$wsh.SendKeys("{DELETE}")
$wsh.SendKeys("{DELETE}")
$wsh.SendKeys("{DELETE}")
$wsh.SendKeys("+{END}")
$wsh.SendKeys("^{x}")

$targetFileName = Get-Clipboard
$targetFilePath = Join-Path $targetFolder $targetFileName

$wsh.SendKeys("^+{s}")
Start-Sleep 1
$wsh.SendKeys("{DELETE}")
$wsh.SendKeys($targetFilePath)
Start-Sleep 1
$wsh.SendKeys("{ENTER}")
Start-Sleep -Seconds 2
$wsh.SendKeys("^{F4}")
Start-Sleep 1
$wsh.AppActivate("Kontakt")

admin

,