Introduction

What does one need to know before using m.nlcode.nl?

A requirement for use of this application is some basic knowledge on the Musical Instrument Digital Interface or MIDI. You should know about MIDI messages like note on, note off and others. You should also know about MIDI ports, both in hardware and software, and how every port supports sixteen distinct MIDI channels.

Some knowledge on how to make music would also be handy.

So what is this m.nlcode.nl thing anyway?

The application m.nlcode.nl is a collection of relatively simple parts that are focussed on doing one thing with MIDI data. The basic thought behind this component strategy is to create something with a limited functional reach, but a depth and or simplicity in what it does. Every part has a narrow focus on a specific functional area. These parts can be connected to one another to chain their data through an m.nlcode.nl project. Such a part is referred to as a MidiInOut part.

sum of the parts

If you are accustomed to a unix style command prompt, then this ‘do-one-thing-but-do-it-well’ will sound familiar. A unix command line usually provides a large number of specialized little applications and commands. The output of one command can be used as the input for another command. m.nlcode.nl works in a similar fashion. Big difference compared to a unix command prompt is that it is very easy to make one MidiInOut part send to multiple other MidiInOut parts. You can also let a MidiInOut part receive data from multiple MidiInOut parts.

Graphical User Interface

The graphical user interface (or GUI) of m.nlcode.nl is made to be as simple as possible. The basic rule is (or should be) Don’t Make Me Think. All clickable items are easily identified on sight without any further action. So there is no need to ‘hover’ over a certain piece of text to see if it changes into a button of some sort.

All basic interaction is through left click only. No right-click, double-click, ctrl-alt-how-at-the-moon-while-tapdancing-right-shift-click or whatever should be needed UNLESS it is a very well known standardised action, like e.g. control-click to expand a selection with the item you clicked on.

usability

No support for the visually impaired. Sorry. If you have an idea on how to solve this AND you are (or know) someone who can do the user acceptance testing, please contact me. I cannot guarantee anything,

i18n - internationalisation

m.nlcode.nl is written in UK English. There is internal support for multiple languages however. If you need a different language AND can do the translation as well, please contact me.

Installation

Downloads

Installers (and possibly other stuff you might need, like JAR files) can be downloaded from Github. Look under ‘Assets’.

So far the easy part. Unfortunately things are almost never easy. Read on.

Supported platforms

m.nlcode.nl is written in Java with JavaFX. That means that every platform that has Java/JavaFX support should be able to run m.nlcode.nl. So having only a Java JDK is not enough; a JavaFX SDK is also needed. http://gluonhq.com provides SDKs for the most mainstream platforms.

Packaging a Java/JavaFX application to run on multiple platforms is still a bit of a challenge. Fortunately Github has multiple hardware stacks, so in theory this could privide for OS X, Windows and Linux versions.

UNVERIFIED - please let me know

Currenly I only have a Macbook Air with x86 Intel chip in it, and I can make use of one with an M1 Apple chip. And I still need to setup Docker to run Linux containers for testing. That means that at this point in time I cannot easily verify if the Linux and Windows versions actually work. That is why most distributables have UNVERIFIED in their names. If you can run them, please let me know so I can remove that UNVERIFIED text from the names of distributables that are known to work.

MONOCLE support

If you know what this is an you think you need it, please contact me.

Mac

Note that I have not yet enrolled in the Apple developer program, so I cannot at this point sign my distributables. Which means you have to take the System Settings | Privacy & Security route when you want to install or run m.nlcode.nl. High enough usage numbers of m.nlcode.nl will entice me to shell out the yearly $99 needed to be enrolled. If this unsigned bothers you, you can always clone the m.nlcode.nl repo, review the source code for bad stuff and run the release process in your clone yourself.

I have noticed that the OS X X86 version seems to run just fine on an M1. The OS X aarch64 version though ran neither on the M1, nor on my x86 Intel Macbook Air. This may be different for you. If so, please let me know. Thing is that the libraries for a x86 and a M1 machine are supposed to be different and (according to the docs) support only one of the two architectures.

Windows

I have no Windows machines. I have been able to get Windows somewhat running on my Mackbook Air under Virtualbox, but the sound was unreliable. Which explains the UNVERIFIED in the names of the distributables. I did see a completed running installation of an AMD based Windows machine.

Linux

I have not yet gotten around to setting up Docker with Linux containers on my Mac. Which explains the UNVERIFIED in the names of the distributables.

All platforms (Java SDK required, at least)

There are several options available from this point. The are described below, in order of complexity with the simplest first.

Run the JAR

1. First install a JDK version 17 or higher. E.g. ‘Temurin’ from https://adoptium.net/ .
2. Download the latest so called ‘shadow JAR’ m_nlcode_nl---all.jar from Github for your specific platform.
3. Execute the shadow JAR file: *java -jar m_nlcode_nl---all.jar

Run from source

1. Only do this if you really know what you are doing.
2. First install a JDK version 17 or higher. E.g. ‘Temurin’ from https://adoptium.net/ .
3. Clone the Github repo locally, by e.g. git clone https://github.com/leomekenkamp/m.nlcode.nl.git
4. Go into that directory and execute ./gradlew run. The first time will take a while; consecutive runs will be a lot faster.
5. Note that if you run form souce, the version of m.nlcode.nl will always be reported as 1.0.0.

Build installer from source (Java required, heavy other requirements)

1. Only do this if you really, really, really know what you are doing.
2. First install a JDK version 17 or higher. E.g. ‘Temurin’ from https://adoptium.net/ .
3. Clone the Github repo locally, by e.g. git clone https://github.com/leomekenkamp/m.nlcode.nl.git
4. Go into that directory and execute ./gradlew jpackage -PversionNumber=x.y.z.
5. Step above may fail due to missing software on your machine. If it does not fail, you can find the installer(s) in ./build/jpackage.

First project

Project

Before addressing individual MidiInOut parts, you should first understand what a project is. A project is a collection of MidiInOut parts that can:

1. be collectively persisted to disk (save)
2. be collectively restored from disk (load)
3. talk to each other

So a project is your main work space in which you work with MidiInOut parts and connect them to each other. Multiple projects can be open at the same time, but an instance of a MidiInOut part can only belong to one project. I will take for granted that you know how saving and loading works, so no example here on saving and loading a project.

but first: specify which OS MIDI devices can be used

m.nlcode.nl can work with other MIDI capable applications and drivers that are known to the operating system of your computer. But you first need to specify which ones you want to be able to work with in your projects.

• Got to the main m.nlcode.nl application window.
• Select File | Settings | system MIDI devices.
• Switch on all devices that you would like to be able to use.
• For this first project tutorial make sure you turn on Gervill, Software MIDI synthesizer - OpenJDK (receiver).

MidiInOut parts

MidiInOut parts are the building blocks for building a project that can monitor, change, filter and create MIDI data. That is basically it. A simple example will probably say more.

• Open a new project.
  • Go to the main m.nlcode.nl application window.
  • Select File | New project.
• Go to the newly created Project window, probably called noname00.m.
• Select Create | Link to MIDI device.
• Go to the newly created Link to MIDI device window, probably called Link to MIDI device 0.
• On the Link to MIDI device tab, select Gervill, Software MIDI synthesizer - OpenJDK (receiver).
• Go back to your Project window, probably called noname00.m.
• Select Create | Keyboard MIDI keyboard.
• Go to the newly created Keyboard MIDI keyboard window, probably called Keyboard MIDI keyboard 0.
• On the outputs tab, select Link to MIDI device 0.
• On the Keyboard MIDI keyboard tab, click on the D button: you should hear a sound!

If you hear no sound, check the volume. If the volume is ok but you do not hear any sound, then I am afraid you should troubleshoot further on your own. Note that a Keyboard MIDI keyboard is basically a simple test util and in no way a replacement for a proper MIDI keyboard.

Input and output

As you have seen in the above example, MidiInOut parts can be connected to send MIDI data to one another. Connections are two way in that senders obviously know to which parts they are sending, but the receiving parts also know their senders. Note that a MidiInOut part can have multiple senders as well as multiple receivers. Use the shift or control keys while clicking to select and deselect (multiple) MidiInOut names.

Example: expanding on the same example as above, do the following.

• Create a MIDI Lights MidiInOut part.
• In its inputs tab, select Keyboard MIDI Keyboard 0.
• Click (with the mouse) on A, S, D or any of the other keys of the Keyboard MIDI keyboard buttons.
• Be amazed by the sound, as well as the dazzling display of visuals in the MIDI Lights part. /s

MIDI Lights is an example of a MidiInOut without any ‘out’. It is simply something that gives a visual representation of MIDI data, but does nothing to the data it receives, not even sending it on. That also means that it has no ‘output’ tab and it cannot be selected as an input for other MidiInOut parts. Keyboard Keyboard is kind of related, in that it can only send output and not receive input.

Other MidiInOut components

There is a number of other MidiInOut components. Now that you know the basics of creating them and linking them to each other, feel free to explore. The modularity of m.nlcode.nl combined with the simplistic interface should provide for a low barrier to entry.