Getting started
Getting started
grafer is a visual node graph for algorithmic composition. You build musical structures by placing nodes on a canvas, connecting their ports, and letting data flow from source to output. Every connection carries typed musical data — pitches, rhythms, curves, dynamics — and updates in real time as you change parameters.
The Canvas
The canvas is your workspace. Right-click or use the node palette to add nodes. Drag from an output port to an input port to create a connection. Pan by dragging empty space; zoom with the scroll wheel. Nodes can be freely repositioned, grouped, and labeled. Every change triggers an immediate recalculation of downstream nodes so you always hear and see the current state of your composition.
Port Types
Each node has typed input and output ports. The main types you will encounter are:
| Type | Description |
|---|---|
| midicents | Pitch values in midicents (integer, 100 per semitone). 6000 = middle C (C4), 6100 = C#4, 7200 = C5. |
| rhythm-tree | Nested proportional rhythm structure. A tree of lists where each sub-list divides its parent beat proportionally. |
| bpf | Break-point function — a piecewise-linear curve defined by (x, y) coordinate pairs. Used for envelopes, contours, and control signals. |
| chord | A vertical sonority: a list of midicents values with an associated velocity. |
| voice | A complete musical line combining a rhythm-tree with a sequence of chords. This is what gets exported to MusicXML. |
| number | A single numeric value (integer or float). |
| list | An ordered sequence of numbers or pitch-classes. |
| pc-set | A pitch-class set — integers 0–11 representing the twelve chromatic pitch classes. |
| velocity | Dynamic values in MIDI velocity range (0–127). |
| articulation | A named articulation marking (staccato, tenuto, accent, etc.). |
Basic Workflow
A typical composition chain flows left to right through three stages:
Source nodes generate raw material — pitch collections, rhythmic structures, harmonic series, stochastic sequences. Transform nodes modify that material — transposing, inverting, filtering, quantizing, morphing. The Voice node combines a rhythm-tree with a sequence of chords to produce a playable musical line. The output can be previewed with MIDI playback or exported as MusicXML for notation in Dorico, Sibelius, Finale, or MuseScore.
Cells, Moments, Movements
A score is built in three layers. A cell is one independent piece of material with its own graph; whatever its Voice nodes emit is the cell's music. A moment groups cells that play at the same time: every cell in a moment starts on the same bar, each on a staff of its own. A movement is an ordered list of moments, and the moments follow each other in time, so a score reads left to right through the moments of each movement.
| You want | Do this |
|---|---|
| Two cells in parallel | Keep them in the same moment. Each one becomes a staff. |
| Two cells in sequence | Put them in separate moments. In the browser, drag a cell onto another moment's header, or press + Moment and drag the cell there. A moment lasts as long as its longest cell; shorter cells rest until the next moment begins. |
| One instrument through the whole piece | Give the Voice nodes the same Name in every moment. Voices with the same name continue on one staff, with rests where the instrument is silent. An unnamed voice takes its cell's name. |
| Change the order | Drag a moment header above or below another moment. Dragging cells within a moment changes the order of their staves. |
Playback follows the same layout: the transport plays the cells of a moment together and the moments one after another, in Score, Movement or Cell scope. The Score view prints the moment names as rehearsal marks above the top staff once a score has more than one moment. Live mode is the exception: there the rhizome edges decide which cell comes next.
Understanding Midicents
Midicents are the pitch representation used throughout grafer, inherited from the IRCAM tradition. One midicent equals one hundredth of a MIDI semitone. This gives you cent-level microtonal precision while staying compatible with MIDI note numbers (multiply by 100).
| Midicents | Note | Explanation |
|---|---|---|
| 6000 | C4 (middle C) | MIDI note 60 × 100 |
| 6050 | C4 + quarter-tone | 50 midicents = 50 cents above C4 |
| 6100 | C#4 / Db4 | One semitone above C4 |
| 6900 | A4 (440 Hz) | MIDI note 69 × 100 |
| 7200 | C5 | One octave above middle C |
| 4800 | C3 | One octave below middle C |
Quick reference: each semitone is 100 midicents. Each octave is 1200. A quarter-tone is 50. To convert a MIDI note number to midicents, multiply by 100.
Try it on your own material.
Create a free account14 days of Composer Pro, no card needed. Every account opens with the Examples folder.