Reference
This page documents the methods provided by the Composer class. It assumes that you are familiar with the basic concepts introduced in the Basics page.
In the description of the methods, the following standard parameter names are used.
| Parameter | Description |
|---|---|
| patch | An integer specifying a MIDI patch number in the range 1..128 |
| fileName | A string specifying a filename (generally, to specify a soundfont file) |
| note | An integer note number: could specify a MIDI note number or a note within the current scale, depending on what method is being used |
| notes | A sequence of one or more integer note numbers |
| notesOrChords | A sequence of one or more note numbers and/or Chords |
| beat | A real number specifying a beat number within a measure (0 for first beat) |
| duration | A real number specifying a duration measured in beats |
| velocity | A strike velocity in the range 0..127 |
| strike | A single Strike |
| strikes | A sequence of 1 or more Strikes |
| n | An integer count |
| spacing | A real number specifying spacing between Strikes, measured in beats |
| octave | An integer octave shift: 1 is up one octave, -1 is down one octave, etc. |
| chord | A single Chord |
| rhythm | A Rhythm |
| rhythms | A sequence of 1 or more Rhythms |
| melody | A Melody |
| melodies | A sequence of 1 or more Melody objects |
| instr | An Instrument |
| figure | A Figure |
| figures | A sequence of one or more Figures |
| gain | A real number between 0.0 and 1.0, specifying an instrument volume |
| Method | Description |
|---|---|
| tempo(beatsPerMinute,beatsPerMeasure) | Specify the composition's beats per minute (absolute tempo) and beats per measure |
| major(note) | Use a major scale with the specified MIDI note number as the root |
| naturalMinor(note) | Use a natural minor scale with the specified MIDI note number as the root |
| harmonicMinor(note) | Use a harmonic minor scale with the specified MIDI note number as the root |
| melodicMinor(note) | Use a melodic minor scale with the specified MIDI note number as the root |
Note that if you do not choose a scale, a default E-flat major scale will be used.
Examples:
// 220 beats per minute, 8 beats per measure
tempo(220, 8);
// use E flat major scale
major(51);The variants of the instr, percussion, samplePlayer, and custom methods are used to create Instruments.
| Method | Description |
|---|---|
| instr(fileName) | Create an Instrument by loading a soundfont specified by the specified filename, using the soundfont's default instrument |
| instr(fileName,patch) | Create an Instrument by loading a soundfont specified by the given filename, using specified MIDI patch |
| percussion(fileName) | Create a percussion Instrument by loading a soundfont specified by the given filename |
| samplePlayer() | Create a sample player Instrument; see the SamplePlayer page |
| custom(n) | Create a custom instrument, where n is the custom instrument number; see the CustomInstrument page |
For the methods that load a soundfont, if the soundfont file is not found, the default Gervill instrument sounds are used.
Percussion Instruments work differently than normal Instruments: for a percussion Instrument, note numbers specify different percussion sounds rather than pitches of a single instrument. See the GM1 Percussion Keymap for details.
In general, distinct Instruments should be used for figures in the composition that will be played at the same time. The volume each instrument can be controlled individually.
Examples:
String ARACHNO =
"/home/dhovemey/SoundFonts/arachno/Arachno SoundFont - Version 1.0.sf2";
String M1 =
"/home/dhovemey/SoundFonts/m1/HS M1 Drums.sf2";
// load a soundfont, using patch 39
Instrument bass = instr(ARACHNO, 39);
// use percussion sounds from a soundfont
Instrument hihat = percussion(M1);A Rhythm is a sequence of Strikes, where each Strike indicates a start beat, duration, and velocity.
Percussive strikes are a special form of Strike that should be used with percussion instruments. They have no explicit duration, since (in general) percussion "notes" are not sustained. Each percussive strike has (by default) an implicit duration of one-quarter of a beat. Some percussion sounds, such as open hi-hat, do need to have an explicit duration, so you should use the s method to specify strikes for these sounds.
| Method | Description |
|---|---|
| s(beat,duration) | Create a Strike starting at given beat and lasting for given duration, using the maximum velocity |
| s(beat,duration,velocity) | Create a Strike starting at given beat and lasting for given duration, using a specified velocity |
| p(beat) | Create a percussive Strike at given beat using maximum velocity |
| p(beat,velocity) | Create a percussive Strike at given beat using specified velocity |
| r(strikes) | Create a Rhythm from a sequence of 1 or more Strikes |
| rr(strike,spacing,n) | Create a Rhythm by creating n exact copies of given Strike, starting at the original Strike's start beat, separated by a number of beats specified by spacing |
| gr(rhythms) | Create a single Rhythm by combining several Rhythms: this is useful for developing pieces of Rhythms individually, and then putting them together |
| sr(beat,rhythm) | Create a Rhythm by adding a specified number of beats to the start beat of all of the Strikes in an existing Rhythm: this is useful for "shifting" an existing Rhythm |
| pdur(beat) | Specify the duration in beats of percussive Strikes created by the p methods: defaults to 0.25 |
Examples:
// Create a Rhythm from a sequence of 7 Strikes
// (this was captured live from a MIDI keyboard)
Rhythm bassr = r(
s(0.000,2.365,79), s(2.1,0.709,101), s(3.5,0.7,110), s(4.45,0.184,118),
s(4.95,0.375,110), s(5.95,1.040,110), s(6.95,0.873,106));
// Create a Rhythm with 8 percussive strikes, starting
// from beat 0, separated by 1 beat, each with velocity set
// to 88
Rhythm basichihatr = rr(p(0, 88), 1, 8);A Melody is a sequence of Chords. Each Chord specifies one or more notes. The following methods are used to specify notes, Chords, and Melodies.
| Method | Description |
|---|---|
| n(notes) | Create a Chord with one or more notes chosen from the composition's scale |
| an(notes) | Create a Chord with one or more MIDI note numbers: this method is useful for specifying notes that aren't part of the composition's scale, or for representing MIDI notes captured from a live audition |
| m(notesOrChords) | Create a Melody consisting of the specified sequence of single notes or Chords; any single notes specified as integers are chosen from the composition's scale |
| xn(octave,chord) | Shift a Chord up or down by specified octave shift |
| xm(octave,melody) | Shift a Melody up or down by specified octave shift |
| gm(melodies) | Combine multiple melodies into a single Melody; the Chords in each input Melody are added to the result Melody in order |
| rm(chord,n) | Create a repeated melody by adding n instances of the specified Chord to the result Melody |
Examples:
// A Melody created from a sequence of single notes
// chosen from the composition's scale
Melody tm = m(
4, 7, 8, 9,
9, 8, 10, 9, 4, 3,
9, 7, 8, 3, 2,
6, 7
);
// A Melody that is a mixture of single notes and multiple-note Chords
// chosen from the composition's scale
Melody low = m(
-7, -6, n(-7, -5), -4, n(-5, -3), n(-6, -2), n(-6, -1), n(-5, 0)
);
// Create a Melody by shifting the "low" melody up by 1 octave
Melody mid = xm(1, low);
// A Melody whose notes are specified by absolute MIDI note numbers
// (this was captured live from a MIDI keyboard)
Melody bassm = m(
an(29), an(34), an(32), an(32), an(32), an(32), an(34)
);There are two kinds of Figures, "simple" and "group".
A "simple" Figure combines a Rhythm, Melody, and Instrument. A composition ultimately consists of simple Figures that are played at specified times.
A "group" Figure is a combination of one or more other Figures (either simple or group). Group Figures are useful for combining several Figures so that they can be scheduled to play at the same time.
The f and pf methods create new simple Figures. The gf method creates a group Figure by combining several existing Figures. The xf method shifts the octave of an existing Figure (which can be either a simple or group Figure.)
| Method | Description |
|---|---|
| f(rhythm,melody,instr) | Create a Figure from specified Rhythm, Melody, and Instrument |
| pf(rhythm,note,instr) | Create a percussion Figure by playing specified Rhythm using the percussion instrument sound chosen by the note (see GM1 Percussion Key Map) and the Instrument, which must be a percussion Instrument (created by one of the percussion methods) |
| xf(octave,figure) | Transform the melody of a Figure by shifting it up or down by some number of octaves |
| gf(figures) | Combine one or more Figures into a single group Figure |
Note that percussion Figures created by the pf method don't specify an explicit Melody, since they consist of the same percussion sound being repeated for each Strike in the Rhythm. If you want to compose a percussion part consisting of multiple percussion sounds (e.g., bass drum and hihat), it is best to create multiple Figures, and schedule them to play at the same time.
Examples:
// Assume that bassr and basichihatr are Rhythms, bassm is a Melody,
// and bass and drums are Instruments
// Create a Figure from specified Rhythm, Melody, and Instrument
Figure bassf = f(bassr, bassm, bass);
// Create a percussion Figure from specified Rhythm, note, and Instrument:
// 42 is the MIDI percussion key (note) for closed hi-hat
Figure basichihatf = pf(basichihatr, 42, drums);
// Create a Figure in which the bass and hihat are played at the same time
Figure bassandhihatf = gf(bassf, basichihatf);Figures are the building blocks of a composition. There are a number of methods that will add Figures to a composition.
One important concept is the current measure. The current measure starts out as 0, which is the first measure of the composition. All of the methods whose names begin with "add" increase the current measure. So, a series of calls to the "add" methods will result in Figures being added to the composition sequentially. In contrast, the at method schedules a figure to be played at a specific measure, without changing the current measure.
The add, addn, addseq, and addseqn methods analyze the start beats of the Strikes contained in the Rhythms within the figure. For example, if the add method is called, and the composition's tempo's number of beats per measure is 8, and the start beats of all Strikes in the added Rhythms are less than 8, then the current measure will increase by 1. However, if the add measure is called, and any of the Strikes has a start beat greater than 8, then the current measure will increase by at least 2. This is a useful property: it allows you to build the composition sequentially.
The add, addn, add1, and add1n methods add a single Figure to the composition. However, the gf method allows you to use these functions to add a group of Figures to be played at the same time. For example, if f1, f2, and f3 are all Figures, then the call
add(gf(f1, f2, f3));will add f1, f2, and f3 to the composition, to be played at the current measure.
| Method | Description |
|---|---|
| add(figure) | Add given Figure at current measure, increasing the current measure depending on the length of the added Figure |
| addn(n,figure) | Equivalent to calling add(figure) n times |
| add1(figure) | Add given Figure at current measure, increasing the current measure by exactly 1 |
| add1n(figure) | Equivalent to calling add1(figure) n times |
| addseq(figures) | Equivalent to calling the add method for each Figure in the specified sequence of Figures |
| addseqn(n,figures) | Equivalent to calling addseq(figures) n times |
| at(measure,figure) | Schedule the given Figure to be played at the specified measure, without changing the current measure |
You can change the volume of an Instrument using the v methods.
Volumes are specified as "gain" values, where 0.0 means completely quiet, and 1.0 means full volume.
| Method | Description |
|---|---|
| v(instr,gain) | Change the volume of an instrument to the specified gain, effective at the beginning of the composition |
| v(measure,instr,gain) | Change the volume of an instrument to the specified gain, effective at the beginning of the specified measure |
Examples:
// Set the volume of the bass Instrument to 0.4
// effective at the beginning of the composition
v(bass, 0.4);
// Change the volume of the bass Instrument to 0.6
// at measure 8 (which is the ninth measure, since the
// measures start at 0)
v(8, bass, 0.6);