Numula* is a Python library for making computer-rendered music with nuance: complex variations in dynamics, timing, articulation and pedaling, as are typical in human performance. Numula is designed to create music like you hear in concert halls, not in video games.

Numula can be used in several ways:

• To render existing compositions (known as virtual performance). You can specify the scores using a powerful textual notation.
• To add nuance to existing MIDI files.
• To create compositions that are partly or entirely algorithmic.

The output of a Numula program is a MIDI file that you can play with a software synthesizer such as Pianoteq. Numula has features that let you process the resulting .WAV files, positioning and moving voices independently in the stereo soundfield.

Numula is oriented towards keyboard music: it controls the timing and volume of notes, but not (for example) the attack parameters or variation within a note. It doesn't currently handle multiple instruments or MIDI channels (if you want this, let me know).

Examples (piano pieces rendered with Numula, using Pianoteq to generate the audio):

• Beethoven: Opus 57 mvt. 3 (Appassionata): Listen | Source | Notes
• Luciano Berio: "wasserklavier": Listen | Source |Notes
• Robert Helps:
  • Hommage a Faure: Listen | Source
  • Hommage a Rachmaninoff: Listen | Source
  • Hommage a Ravel: Listen | Source

With Numula, you can:

• Define variations in tempo and dynamics using linear and exponential primitives.
• Insert pauses and shift notes forward or backwards in time.
• Emphasize and de-emphasize notes.
• Vary articulation.
• Add random jitter to the timing or volume of notes.
• Layer these adjustments to an arbitrary depth.

... and so on. Each adjustment can affect all notes or subsets of notes selected on the basis of time, pitch, chord position, offset within a measure, or "tags" that you can associate with notes. For example, you can accentuate a particular fugue voice, or to define a rubato that's applied only to the right hand.

The adjustments are specified separately from the score (analogous to CSS and HTML). They can be expressed either in Python or in a compact textual shorthand. Numula's nuance features are based on a model called MNS.

Install Python 3.10 or later. Install a couple of modules:

pip install requests
pip install numpy
pip install scipy

Many of the examples assume you have Pianoteq, but you can also generate MIDI files and play them by other means.

Clone this repository. This will create a directory structure:

numula/
   numula/
      (basic modules: score specification, nuance)
      nscore.py etc.
   comp/
      (modules for algorithmic composition)
      pitch.py etc.
   examples/
      (pieces, both scored and algorithmic)
      wasserklavier.py etc.
   test/
      (tests programs)
      test.py etc.

There is also a Numula package on PyPi, which you can install with

pip install numula

But don't do this; it's an old version, and I don't maintain the package.

If you find a bug in Numula please create an issue in this repo.

I've found that each time I make a new piece with Numula, I need new features. You'll probably find this too. If so, please create an issue explaining what you need, and I'll try to provide it.

Numula could be implemented on top of Music21, and this might be worth doing at some point, since Music21 provides many ways of importing scores. However, Music21 is gigantic, and for our purposes only a small part of it is needed. Numula implements this part in a clean and simple way.

Numula uses the MIDIUtil module to write MIDI files. For simplicity this file is included with Numula.

* NOOM-yoo-luh. The name stands for Nuance Music Language, and also refers to FORMULA, a Forth-based music language from which Numula borrows some ideas.