Skip to content

Home

Jump to bottom
David Anderson edited this page Aug 10, 2024 · 85 revisions

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. 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 algorithmic composition.

The output of a Numula program is a MIDI file that you can play with a software synthesizer such as Pianoteq. Numula has additional 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 type 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):

Describing nuance

With Numula, you can:

  • Define fluctuations 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 - e.g. to accentuate a particular fugue voice, or to define right-hand rubato.

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 if you don't already have it. Features involving random numbers require numpy:

pip3 install numpy

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

Installing Numula

To install Numula:

pip3 install numula

Alternatively you can clone this repository. This will create this 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.

To run the programs in examples and test, you need to connect them to the modules in numula and comp. There are two ways to do this:

  • Make a symbolic link examples/numula pointing to the numula/numula directory, and a link examples/comp pointing to numula/comp. Do this in test as well. Note: on Windows you need to create a 'junction' in a command (cmd) window using
mklink /J

A shortcut doesn't cut it.

  • Add comp and the (inner) numula directory to your PYTHONPATH environment variable.

There may be an easier to organize Python code into directories; I don't know what it is.

Bugs and feature requests

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.

Notes

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.

Home

Clone this wiki locally