Core Overview

maelzel.core provides a set of classes to define notes, chords, lines, sequences, voices or entire scores. Any of these objects can be played in real time, recorded and displayed as notation. When converting to notation, objects are quantized following a score structure.

maelzel.core’s main purpose is to represent musical ideas, reason about aspects of pitch, rhythms, etc., and be of help while composing, analyzing or preparing a performance.

Notation as display vs engraving

The objects defined in maelzel.core can have many attributes within the realm of notation which do not have a well defined acoustic translation: articulations, text labels, size. Although such symbolic attributes are very important for composing or analyzing maelzel.core does not seek to provide the level of customization needed to produce a finished engraved score. The notation produced is to be understood as a means of visualization of musical and / or acoustic processes.

Key Concepts

MObj

All classes defined in maelzel.core inherit from MObj (Maelzel Object, or Music Object). A MObj exists in time (it has a duration and a time offset), it can be displayed as notation (show()) and played as audio (play())

Explicit / Implicit Time

A MObj always has an explicit duration (the dur attribute). The offset can be undetermined (None), meaning that it is not explicitely set and depends on the context. A Note without an explicit offset will be stacked left to the previous event.

Absolute Time / Relative Time

The time attributes (offset, dur, end) of a MObj refer to a relative time, measured in quarternotes. To map from relative time to absolute time (measured in seconds) a score structure (ScoreStruct) is needed (see below)

Workspace

At any moment there is an active Workspace (an instance of Workspace). It contains the current configuration (config, an instance of CoreConfig, see below Configuration) and the default score structure (scorestruct, a ScoreStruct, see below Score Structure)

Configuration

The active configuration (an instance of CoreConfig, see Configuration) controls multiple aspects of maelzel.core and enables the user to customize the rendering process, quantization, playback, etc. The active config can be accessed via getConfig() or

Score Structure

A Score Structure (ScoreStruct) is a timeline built from a sequence of measure definitions. Each measure defines a time signature and tempo. A ScoreStruct does not contain any material itself: it is only the “skeleton” of a score. At any moment there is always an active score structure (getScoreStruct(), setScoreStruct()), the default being an endless score with a 4/4 time-signature and a tempo of 60 bpm.

Playback

For playback maelzel uses csound as an audio engine embedded in python (see csoundengine). When the play() method is called, a MObj generates a list of SynthEvent, which tell csound how to play a Note, Chord, or an entire Score. Using csound it is possible to define instrumental presets using any kind of synthesis or by simply loading a set of samples or a soundfont (see also the maelzel.core.playback module)

Class Structure

_images/classstruct.svg

In general, there are two kinds of MObj: events (Note, Chord, Clip) and containers (Chain, Voice, Score).

Events: Note, Chord, Clip

Events are all subclasses of MEvent and represent individual events in time: Notes, Chords, media Clips.

Horizontal Containers: Chain, Voice

A Chain is a sequence of events. Within a chain any number of events can be juxtaposed to build more intricate horizontal structures. For example, a sequence of notes can be tied or linked together with glissandi to generate a line of any desired complexity. A Chain can also contain other Chains

A Voice is a special case of a Chain with an offset forced to be 0.

Vertical Container: Score

The last node in the class structure is the Score: this is simply a list of Voices <maelel.core.chain.Voice with some extra attributes which are exclusive to a score (for example a Score can have an attached score structure <maelzel.scorestruct.ScoreStruct)

Core: Reference