Skip to content

napframework/nap

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation


Description

NAP is an open source, low overhead, real-time control & visualization plaform. Create fast, modular and responsive applications to interact with the world around you. NAP is built to scale up to a large number of input and output devices: many displays, many lights, many speakers, many sensors, many servos.

Features

NAP Framework ships with many useful modules, including: a Vulkan 2D/3D render engine, a Vulkan Compute module, a multi-channel audio engine for music playback, recording and analysis, a sequencer to control parameters in real-time, an editor to author application content, a web-portal to control and monitor NAP applications in a browser, a system for creating and loading presets, a video player powered by FFmpeg and a Python programming interface.

NAP also has built in support for many common protocols and standards, including: WebSocket, MIDI, OSC, Artnet, Serial, EtherCAT, OpenCV and SQLite. NAP has been battle tested in production for years. For more information about NAP, how it is commonly used and what it can do for you, visit the nap-framework.tech website.


Philosophy

NAP is completely data driven and heavily influenced by modern game engine design, with one exception: it does not dictate any sort of pipeline. This allows NAP to run on any type of device: from low-power, energy efficient ARM computers such as the Raspberry Pi to industrial PCs and x86 gaming rigs.

NAP applications are lean and mean: only package and ship what you actually use. On top of that NAP is easy to extend: build you own modules, resources, devices and components. NAP wants you to be safe and validates data for you on initialization. Applications are also responsive: hot-load content changes directly in to the running application. On top of that NAP is completely cross-platform and supports all modern desktop environments.

Documentation

NAP documentation can be found online at docs.nap-framework.tech. Take note that the installation instructions on that website apply to the binary (compiled) NAP package only. Follow the instructions in this document to build and work against NAP Framework from source.

Gallery

Visit nap-labs.tech for more examples

Between Mind and Matter, Nick Verstand Between Mind and Matter by Nick Verstand, Marcel Smit and 4DSOUND Habitat, Heleen Blanken Habitat by Heleen Blanken, Naivi and Stijn van Beek Shylight, Studio Drift Shylight by Studio Drift 4DSound System 4DSound System NAP Framework NAP Framework editor & demo

Where to Start

System Compatibility

Currently, whether working with the packaged framework release or against the framework source, we support the following architectures and operating systems:

x86

x86-64: Windows (10 & 11), Visual Studio 2019 - MSVC
x86-64: Ubuntu Linux LTS (v22.04 & v24.04) - GCC

ARM

arm64: Raspberry Pi OS (v12 Bookworm) - GCC

Binary Packages

Pre-compiled packages of official NAP releases are made available for download on Github for all supported platforms. Follow the framework installation instructions to get started. Continue reading below to compile, package and work with NAP from source.

Raspberry Pi

Only the Raspberry Pi 4 & 5 running Debian Bookworm (v12, arm64) is 'fully' supported. Headless applications and services without graphics should run on older models, although this has not been tested. The editor (napkin) only works on the Raspberry Pi 4 and higher.

Compilation

Dependencies

The editor Napkin depends on open source Qt.

Download

Download and extract the pre-compiled binaries for your target platform:

Alternatively

  • Go to qt.io for open source users
  • Download the Qt online installer
  • During installation select Custom installation
  • Filter on the LTS category to download and install Qt6 for your target platform
  • NAP uses Qt 6.7.2, although other versions are known to work.

Note that only only the desktop binaries (MSVC 2019 64-bit or gcc 64-bit) are required, other content is optional.

Setup

Create an environment variable called QT_DIR and point it to the directory that contains the QT libraries, for example: C:\qt\6.7.2\msvc2019_64. The build system uses this environment variable to locate QT. Note that only the editor (Napkin) depends on Qt, NAP distributable applications do not have a dependency on Qt.

Create the Solution

Run:

check_build_environment to ensure your build environment is up to date.

On success, run:

generate_solution.bat to generate a Visual Studio Solution (Windows)
generate_solution.sh to generate make files (Linux)

The solution allows you to build every target and inspect the code of the demos, editor, modules, core etc. NAP uses a pre-bundled version of CMake in third-party to ensure compatibility for all platforms. The default build configuration is Release. Alternatively you can use CLion.

Run a Demo

Open the generated solution in Visual Studio, select a build configuration (Debugor Release) and a demo as target. Compile and run the demo. You can also use the build script to compile one or more projects using the command line, for example: ./build.sh helloworld.


Work Against Source

Allows you to step into the NAP Framework source code and make changes if required.

Create Application

Run tools/create_app to create a new application:

./create_app.sh myApp

This creates a new application called myApp in the apps directory. It also adds myApp to solution_info.json in the root and regenerates the solution. Run the build script inside the application directory to compile it:

./build.sh

Create Module

Run tools/create_module to create a new user module:

./create_app.sh myModule

This creates a new module called napmyModule in the modules directory. It also adds napmyModule to solution_info.json in the root and regenerates the solution. You can inlcude this module by adding it to the RequiredModules property in app.json or module.json files.

Note that when you make manual changes to the build system (by editing CMake or JSON) you must run generate_solution to update the solution.

Download Module

A list of publicly available user modules can be found at modules.nap-framework.tech. These modules are created, maintained and shared by NAP users, independent of NAP Framework.

Share Your Module

You can share your module with other NAP users by making it available on modules.nap-framework.tech. Follow the instructions here to register it.


Build Distributable NAP Package

A packaged version of NAP will include all of the following:

compiled object code (headers & binaries)

  • core engine
  • system modules
  • editor

source code (not compiled)

  • demos
  • user modules
  • apps

After packaging a new zip or folder is created, with the naming convention NAP-*Version*-*Platform*-*Timestamp* (Timestamp may be optionally omitted).

Package

Run package to package NAP:

./package.sh

Alternatively, you can use the -sna flag to build a package that includes only one app, e.g.:

./package.sh -sna myApp

Some other useful flags:

  • -nt: remove the timestamp
  • -nz: do not create a zip file from the release
  • -ds: include debug symbols. On Windows .pdb files are also packaged.

More options for packaging can be queried by adding the flag --help when running the script.

Contributing

We welcome contributions and potential bug fixes. But before you submit any code for review make sure to read and follow our C++ styleguide. Also take into consideration that reviewing code takes time: Be as thorough and explicit as possible.

Use the github issues page for bug reports and well defined feature requests. Use the Github discussions page for general questions and help.

New modules are not considered unless useful, vital or important enough to have as part of the core release. If you feel a module is missing we would like to hear from you. If a module depends on a third-party library, linkage should be dynamic and not violate the NAP license policy. Static linkage is discouraged unless recommended by the library or when a NAP application, that uses the module, doesn't require the library to link and run. In that case all third-party code is compiled into the module when NAP is packaged. Third-party dependencies must work cross-platform and must be compiled using

MSVC, Platform Toolset v142 on Windows 10
GCC <= 11 on Ubuntu LTS 22.04

License

NAP Framework is open source software, licensed under the Mozilla Public License Version 2.0. You can use the NAP source code and NAP distributable package to create both commercial and non-commercial derivate works, as long as the MPL 2.0 license is not violated.

This means that you must make your changes to the NAP source code available under MPL. You can combine NAP source code with proprietary code, as long as you keep the NAP source code in separate files. Version 2.0 is, by default, compatible with LGPL and GPL version 2 or greater. You can also distribute binaries under a proprietary license, as long as you make the NAP source code available under MPL.

In short: You are allowed to use and modify the NAP source code, for both commercial and non commercial purposes. However: if you make changes to the NAP source code, you have to make those changes available for others to use. We encourage people to share their ideas with the community. Keeping knowledge to yourself is not what NAP Framework is about.