norns, a Lua and DSP sound computer you can rebuild yourself

What norns is and what it is made of

norns is many sound instruments. It connects to grids, MIDI and other objects, and it lets you define its behaviour with scripts and DSP.

The framing in the README is that it is primarily intended to run on a Pi-based sound computer designed by monome, and the homepage is monome.org. So this is not a general purpose audio library that happens to be written in Lua. It is the software for a specific piece of hardware, and the software is open so that the instrument can be rebuilt, extended and understood.

The tagline is one line: changes, travels, is open to possibilities. That sets the tone for a project whose primary commitment is to the people using and hacking on it.

The structure of the repository is the best map of the system. There are two directories named after the two core processes, matron/ for the control system and crone/ for the audio system, and a maiden-repl/ directory for the editor. There is a sc/ directory for SuperCollider-related sources, a lua/ directory for the scripting layer, and a norns/ directory for the device-level code.

Then there is the supporting cast. A watcher/ directory, a ws-wrapper/ for the network layer, an osc-test/ directory, a third-party/ directory for vendored code, an update/ directory, an image/ directory, a doc/ directory and a resources/ directory. There is an osc-test/ directory and a maiden-repl/ directory, which tells you the OSC protocol is central and that the editor can be driven remotely.

The acknowledgements section names the two systems and their creators. matron, the control system, and crone, the audio system, were created by catfact. maiden, the editor, was created by ngwese. The project was initiated, designed and variously coded by tehn of monome.

There is a companion set of repositories for the pieces that are not the software itself. The norns disk image is a Raspbian-based image, the monome Linux kernel is a custom, monome-flavored kernel, the DIY shield instructions describe the open-source hardware variant, and maiden is the editing interface with softcut, the sample-cutting editor part of matron, in a separate repository.

Building it from source

The quick reference in the README is the whole build sequence, and it is short because the project has already made the decisions:

git clone https://github.com/monome/norns.git
cd norns
git submodule update --init --recursive
./waf configure --release
./waf build --release

Two details in that sequence matter. The submodule step is required, and it is recursive, which means the project pulls in more than one nested dependency and a shallow clone of the submodules will not be enough. And the build system is waf, which is a Python-based build tool, so the configure and build steps are the waf ones rather than a conventional configure script and make.

The note on the release flag is the most important practical detail in the README. The --release flag creates builds specifically for the armv8 and cortex-a53 instruction set, meaning optimized for a Raspberry Pi 3 and compatible with a Raspberry Pi 4. It also enables aggressive compiler optimizations. Omit the flag if you need debug symbols or to build for a different architecture. And it does need to be supplied to both the configuration and build steps, which is the part people get wrong, because supplying it to configure only leaves you with an optimized configure and a debug build.

The build files are at the top level as a wscript, with a waf executable alongside it, and there is a version.mk holding the version. The build system is used to produce both the software and the disk image, with the image/ directory and the update/ directory for the release machinery, and releases.txt as the version record.

There is also a Dockerfile at the root, and its comment block is unusually informative about what the container is for. The file is based on a Raspberry Pi OS base image for the armv8 platform and the comment says the container is focused on creating an accurate build environment for continuous integration, and that it does not attempt to add any extra bits to make the container a usable way for a desktop user to interact with a running virtual norns environment in realtime. It notes that emulating armv8 can be much slower, 10 to 20 times, than running on the host architecture, and gives the build and run commands for macOS and Windows users with Docker Desktop.

The container is also published to the GitHub container registry as norns-ci, so the build step can be skipped entirely, and it can be used as a cache source with the cache-from option. The comment also notes that building the container from Linux may require additional steps around QEMU, and lists packages that were deliberately not installed because no package or no candidates were available, among them usbmount and midisport-firmware.

Running it, testing it and the surrounding tools

There are a small number of scripts for the day-to-day workflow, and their names are plain. start.sh and stop.sh handle the device lifecycle, edge.sh is there for the edge-related part of the system, clang-format.sh formats the C sources, and there is a .clang-format configuration at the top level. The .luacheckrc is the Lua equivalent, a linter configuration for the scripting layer.

The tests are split into two scripts, test.sh and test-lua.sh, with a tests/ directory and a config.ld file that looks like a linker configuration for the test harness. The separation of the C and Lua test scripts reflects the structure of the system itself, where the audio and control layers are C and the scripting layer is Lua, and each has its own test entry point.

There is a .devcontainer/ directory, which is a development container definition, and a _config.yml which is a Jekyll configuration for the documentation site, with a doc/ directory holding the source. The documentation is split across two sites in the README's link list, user docs and API docs, both under monome.org, plus a building and execution document in the repository itself as readme-setup.md, and a readme-update.md for the update path.

Discussion and help happens on a l-system link, which is the larkin mailing list and is where the community for this kind of instrument lives. The README links it as discussion and help, and for a project with a small following that is where the answers come from.

The Python dependencies are declared in requirements.txt, and the development tooling is pinned there too, with pytest bounded to a specific older version, syrupy for snapshot testing where the Python version allows it, wsproto for the WebSocket protocol work, and fastcrc plus lxml and setuptools and wheel. The pyproject.toml uses setuptools as the build backend and requires cython and setuptools 42 or newer, and the ruff configuration extends a list of ignored rules, several of them F-category rules about undefined names and unused variables, which is what you would expect when linting generated code.

The human-readable rule and the contribution guidance

The contributing section is two sentences and they are the clearest statement of intent in the README:

this codebase was written by humans and we intend to keep it maintainable and understandable by humans.

That is a design constraint rather than a sentiment, and it explains a lot of the choices visible in the repository. A project that is meant to be read by people who want to modify an instrument cannot hide its audio engine behind an opaque build, and the fact that matron and crone are separately named directories with their own histories reflects that they are meant to be understood as systems rather than consumed as a binary.

The contribution guidance itself lives in a CONTRIBUTING.md at the top level, and the README points at it rather than reproducing it. The same pattern appears elsewhere in the project, where the README is a short index and the detail lives in a document it links to, which is what keeps the front page readable.

The license is GPL-3.0, in a LICENSE.txt file. That is worth contrasting with the permissive licences that the surrounding software ecosystem usually uses, and it says something about the project. The hardware is open, the software is copyleft, and the intent is that anyone can build and change the instrument, including commercially, but that improvements to the shared software stay shared.

The community structure is visible too, in the acknowledgements. The three main systems each have a named creator, and each of them grew with contributions from a long list of people, and the project credits them individually. For a project of this size, that level of individual credit is unusual and it says the contributors are known to each other, which is what you would expect in a hobbyist instrument community that has been running for years.

The final thing worth noting is the relationship between the software and the hardware. The DIY shield instructions are in a separate repository, and the disk image and the kernel are separate too, which means you can build the software without the hardware, and you can build the hardware without buying anything from monome. That is a deliberate position, and it is the reason the build instructions in this README are complete enough to start from.

Editorial conclusion

Adopt norns if you are building or hacking on a monome-style sound computer and want the control system, audio engine and script layer as one readable codebase you can rebuild from source. Skip it if you want a general Linux audio tool, because norns is a complete instrument stack with its own kernel and image rather than a library. Verify first by building with the release flags as the README describes and confirming the target architecture is what your board needs, since the release flag is tuned for armv8 and the debug build is what you want for development.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. monome/norns on GitHub
3. Project website
4. README
5. Releases