Numula: a Python library for nuanced computer music

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. It lets you 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 spatialization features that let you use Pianoteq to create .WAV files, then process these files position and move 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):

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

Describing nuance

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.

Prerequisites

Install Python 3.12 or later.

Install some modules:

pip install requests
pip install numpy
pip install scipy
pip install readchar

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

Installing Numula

Clone this repository. This creates a directory structure:

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

Note: there's a Numula package on PyPi, but don't use it; it's not maintained.

Running the examples

Works on Windows; should work on other platforms.

• Install Numula as described above.
• Install the current version of Pianoteq.
• Run Idle (the Python GUI).
• In Idle, open 'numula/examples/pianoteq_server.py' and run it by pressing Fn-F5. A Pianoteq window should open.
• Open one of the examples, say 'numula/examples/wasserklavier.py' and run it using Fn-F5. It should play.

Bugs and feature requests

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

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.

Notes

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

Numula uses Python type hints in its API, but not internally. For the most part, Numula passes static type checking with MyPy.

Numula could be implemented on top of Music21, and this might be worth doing at some point, since Music21 (for example) 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.

---

* 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.