NITools

NITools is an unofficial suite to extract, convert, and repurpose Native Instruments content, making it easy to use your kits, samples, and previews on other devices and workflows.

Created by Moai Beats Follow and stream to support me •ᴗ•

⬇️ Download

Pre-built executables for Windows and macOS are available on the Releases page.

🛠️ Usage

For a detailed user guide, including GUI screenshots and step-by-step instructions, please refer to the User Guide.

✨ Overview

NITools is an unofficial, multi-platform suite of tools designed to bulk extract, convert, and repurpose Native Instruments content for broader workflows.

The initial idea was to export Maschine groups to use them in the Roland SP 404 MK2. Since then, the project evolved to allow configurable parameters to export for other devices and to export more data.

Key Features

• GUI & CLI: Use via graphical interface or command line for maximum flexibility.
• Portable: Pre-built executables, no Python installation required.
• Cross-Platform: Supports Windows and macOS.
• Maschine Groups Exporter: Extract and process kits/samples from .mxgrp files, ignoring internal VSTs and FX.
• NKS Previews Exporter: Convert NKS audio previews to WAV for one-shot instruments on other platforms.
• Battery Kits Exporter (WIP): Early-stage tool to parse .nbkt kits for future export support.

⚠️ Compatibility Note

NITools has been tested only on Windows.
While pre-built executables are provided for macOS, some features may require adaptations (e.g., accessing the registry and other OS-specific behaviors).
Mac users should expect additional setup or adjustments. Feel free to open a PR!

Modules

Groups Exporter (Maschine)

• Scans a folder for all Maschine group files and parses sample data.
• Configurable normalization, sample rate, bit depth, and silence trimming.
• Pad reorder matrix and filtering options.
• Option to fill blank pads with a default sample.
• Option to include group preview samples.

Previews Exporter (NKS)

• Converts NKS .previews to standardized WAV files for easy browsing outside NI software.
• Configurable normalization, sample rate, bit depth, and silence trimming.
• Options to skip content from Maschine, Battery, or the large 'Native Browser Preview Library'.
• Option to find the real instrument folder names for previews.

Battery Kits Exporter (WIP)

• Planned tool for exporting Battery kits, similar in functionality to the Maschine Groups Exporter.

📦 Development

Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.13+: Required for running the scripts.
• Conda: Recommended for managing Python environments and dependencies, it is used in the build scripts.
• VS Code: Recommended IDE for development and debugging (optional, but useful for quick start configurations).
• create-dmg: For macOS executable bundling, install via Homebrew: brew install create-dmg.

Installation

1. Clone the repository:

   git clone https://github.com/joanroig/nitools.git
   cd nitools

2. Set up a Python environment (recommended):

   • Conda (recommended):

     Use the script rebuild_env.ps1, or manually execute:

     conda env create -f environment.yml
     conda activate nitools

3. Install dependencies (if not using conda):

pip install -r requirements.txt

Overview

Layer	Tool	Path	Purpose
Launcher	GUI: Launcher	src/launcher.py	Central entry point; can launch both GUIs.
GUI	Groups Exporter GUI	src/apps/groups_exporter_gui.py	Extracts and processes groups/kits (pads, instruments).
GUI	Previews Exporter GUI	src/apps/previews_exporter_gui.py	Extracts and processes audio previews (short demo sounds).
CLI	Groups Build	src/processors/groups/build_groups_json.py	Extract raw group/kit metadata into a JSON index.
CLI	Groups Process	src/processors/groups/process_groups_json.py	Process groups (trim silence, normalize, etc.).
CLI	Previews Build	src/processors/previews/build_previews_json.py	Extract raw preview metadata into a JSON index.
CLI	Previews Process	src/processors/previews/process_previews_json.py	Process preview audio (trim silence, normalize, etc.).

Quick Start (VS Code)

1. Run Launcher

   • Open Run and Debug → "GUI: Launcher"
   • Runs src/launcher.py which can start the GUI tools.

2. Run GUI Tools Independently

   • Groups Exporter GUI
     • Run config: "GUI: Groups Exporter"
     • Runs src/apps/groups_exporter_gui.py
     • Handles Maschine groups/kits (pad layouts, mappings, kit metadata).
   • Previews Exporter GUI
     • Run config: "GUI: Previews Exporter"
     • Runs src/apps/previews_exporter_gui.py
     • Handles audio previews (short WAV samples used for browsing kits).

   ⚡ These GUIs can also be launched from the Launcher, but can run independently for development/debugging.

3. Run CLI Tools

   There are 4 CLI processors that can be launched directly (the GUIs internally call these):

   • Groups Build → Builds all_groups.json from library kits.
   • Groups Process → Processes all_groups.json into individual kits.
   • Previews Build → Builds all_previews.json from audio previews.
   • Previews Process → Processes all_previews.json into individual preview files.

CLI Usage

1. build_groups_json.py

Extracts group/kit metadata and outputs a combined JSON.

python src/processors/groups/build_groups_json.py <input_folder> <output_folder> <generate_txt>

• <input_folder>: Input library folder (e.g. D:/Libraries/Native Instruments/)
• <output_folder>: Destination folder (e.g. ./out/)
• <generate_txt>: true = also generate .txt files, false = skip

Example:

python src/processors/groups/build_groups_json.py D:/Libraries/Native Instruments/ ./out/ false

2. process_groups_json.py

Processes group JSON files into cleaned/usable kits.

python src/processors/groups/process_groups_json.py <all_groups_json> <groups_output_folder> [options]

Options:

• --trim_silence → Remove silence
• --normalize → Normalize volume
• --matrix_json <path> → Optional custom reorder matrix JSON file
• --enable_matrix → Enable pad matrix reorder
• --filter_pads → Filter groups: pad 1 contains keywords for pad 1, pad 2 for pad 2, pad 3 for pad 3 (case-insensitive)
• --filter_pads_json <path> → Optional custom pad filter keywords JSON file
• --fill_blanks → Fill empty pads
• --fill_blanks_path <path> → Fill blank pads with a specified WAV file, or pick a random file from a folder of WAVs (default is a silence sample file: resources/audio/.wav)
• --sample_rate <rate> → Convert all samples to this sample rate (e.g., 48000)
• --bit_depth <depth> → Convert all samples to this bit depth (e.g., 16)
• --include_preview → Include preview samples from groups .previews
• --skip_existing → Skip processing if output file already exists

Example:

python src/processors/groups/process_groups_json.py ./out/all_groups.json ./out/groups/ --trim_silence --normalize --enable_matrix --filter_pads --fill_blanks --fill_blanks_path resources/audio/.wav --sample_rate 44100 --bit_depth 24 --include_preview --skip_existing

3. build_previews_json.py

Extracts audio preview metadata and outputs a combined JSON.

python src/processors/previews/build_previews_json.py <output_folder>

• <output_folder>: Destination folder (e.g. ./out/)

Example:

python src/processors/previews/build_previews_json.py ./out/

4. process_previews_json.py

Processes preview JSON files into cleaned/usable audio previews.

python src/processors/previews/process_previews_json.py <all_previews_json> <previews_output_folder> [options]

Options:

• --trim_silence → Remove silence
• --normalize → Normalize volume
• --sample_rate <rate> → Convert all samples to this sample rate (e.g., 48000)
• --bit_depth <depth> → Convert all samples to this bit depth (e.g., 16)
• --skip_existing → Skip processing if output file already exists
• --skip_maschine_folders → Skip folders containing .mxgrp files (Maschine groups)
• --skip_battery_kits → Skip files ending with .nbkt.ogg (Battery kits)
• --skip_native_browser_preview_library → Skip 'Native Browser Preview Library' folder
• --find_real_instrument_folder → Find real instrument folder for the Preview Library

Example:

python src/processors/previews/process_previews_json.py ./out/all_previews.json ./out/previews/ --trim_silence --normalize --sample_rate 44100 --bit_depth 24 --skip_existing --skip_maschine_folders --skip_battery_kits --skip_native_browser_preview_library

Building Executables

The project uses PyInstaller to bundle the application into standalone executables. The GitHub Actions workflow create-release.yml automates this process for releases.

• Windows: The bundle_app_windows.ps1 PowerShell script is used. For CI builds (like GitHub Actions), it's run with the --ci parameter:

  powershell -ExecutionPolicy Bypass -File .\bundle_app_windows.ps1 --ci

  To run locally, you can omit --ci or include it if you want to replicate the CI environment.

• macOS: The bundle_app_macos.sh bash script is used, which also leverages create-dmg to package the .app into a .dmg installer. For CI builds, it's run with the target architecture and the --ci parameter:

  bash ./bundle_app_macos.sh x86_64 --ci # For Intel Macs
  bash ./bundle_app_macos.sh arm64 --ci  # For Apple Silicon Macs

  To run locally, specify the desired architecture (x86_64 or arm64) and you can omit --ci. Ensure create-dmg is installed (brew install create-dmg) before running the macOS bundling script.

🤝 Contributing

Contributions welcome!

• Open an Issue
• Submit a Pull Request

The tools development was focused on extracting sample paths from binary files instead of doing proper decompiling. See the document DECISIONS.md for more insights on how the processing was built if you plan to enhance it.

⚖️ Legal Disclaimer

This project is an independent, open-source tool developed for educational and interoperability purposes.

• It is not affiliated with, endorsed by, or connected to Native Instruments GmbH, Roland Corporation, or any other company.
• All product names, trademarks, and brands mentioned (e.g. Native Instruments, Roland, Maschine, Battery, etc) are the property of their respective owners and are used strictly for identification and compatibility purposes.
• This project does not contain any proprietary source code, file formats, or assets from Native Instruments or Roland.

The software is intended to be used only with legitimately purchased content and exclusively for personal use. Users are responsible for ensuring compliance with the license terms of their software and content libraries.

The authors do not encourage, condone, or accept responsibility for:

• Any unauthorized distribution or misuse of copyrighted material,
• Any violation of third-party license agreements or terms of service,
• Any data loss or damage arising from the use of this tool.

This software is provided “as is”, without warranty of any kind.

📜 License

This project is licensed under the GPL-3.0 License.