Appendix D: Other Functions
In addition to the functions covered in Appendices B and C, there are a number of more advanced functions mainly intended for offering convenient shortcuts (i.e., providing useful/common functionality) and for building interactive musical instruments and installations. This appendix provides a reference guide to them in the order they are introduced in the book. They include:
- Mapping functions
- Image functions
- Play functions
- AudioSample functions
- MIDI Sequence functions
- Timer functions
- MIDI input/output functions
- Open Sound Control functions
- Zipf functions
- ColorGradient function
D.1 Map Functions
These functions convert a value from one range to another, maintaining the relative position within the range. They are used to expand, contract, or offset data values.
These functions are included in the music library, so in order to use them, you need the following in your program:
from music import *
|
Function |
Description |
|
mapValue(value, minValue, maxValue, minResult, maxResult) |
Takes a number within one range and returns its equivalent within another range. The arguments are: value—the number to be mapped minValue—the lowest possible number to be mapped (inclusive) maxValue—the highest possible number to be mapped (inclusive) minResult—the lowest value of the destination range (inclusive) maxResult—the highest value of the destination range (inclusive) |
|
mapScale(value, minValue, maxValue, minResult, maxResult, scale) |
Takes a number (i.e., MIDI pitch) within one range and returns its equivalent within another range, quantized to the pitch class value in scale. The arguments are: value—the number to be mapped minValue—the lowest possible number to be mapped (inclusive) maxValue—the highest possible number to be mapped (inclusive) minResult—the lowest value of the destination range (inclusive) maxResult—the highest value of the destination range (inclusive) scale—(optional) the musical scale (a list of pitch classes between 0 and 11) to be used in the destination range (see Appendix A for common scale constants) |
D.2 Image Functions
The Image class provides useful functions for displaying and manipulating jpeg and png graphic files. This class is similar to the Icon class (seen in Appendix C), except that an Icon is intended to be used as a component for an interactive (GUI) application. On the other hand, an Image:
- has its own window,
- can be manipulated at the individual pixel level, and
- can be written/saved to an external file.
The Image class is included in its own library, so you need the following in your program:
from image import *
|
Function |
Description |
|
Image(filename) |
Reads in a .jpg or .png file called filename (a string) and shows an image. It returns the image, so it should be stored in a variable, e.g., img = Image("sunset.jpg"). |
|
Image(width, height) |
Returns an empty (blank) image with provided width and height. It returns the image, so it should be stored in a variable, e.g., img = Image(200, 300). |
|
img.getWidth() |
Returns the width of image img. |
|
img.getHeight() |
Returns the height of image img. |
|
img.getPixel(col, row) |
Returns this pixel’s RGB values (a list, e.g., [255, 0, 0]), where col is the image column, and row is the image row. The image origin (0, 0) is at top left. |
|
img.setPixel(col, row, RGBlist) |
Sets this pixel’s RGB values, e.g., [255, 0, 0], where col is the image column, and row is the image row. The image origin (0, 0) is at top left. |
|
img.show() |
Displays the image img in a window. |
|
img.hide() |
Hides the image window (if any). |
|
img.write(filename) |
Writes image img to the .jpg or .png filename. |
D.3 Play Functions
Earlier in the book we used the Play.midi() function to render musical compositions stored in Note, Phrase, Part, and Score objects. The Play functions discussed below are more advanced, as they are intended for building interactive musical instruments and installations.
These functions are included in the music library, so you need the following in your program:
from music import *
|
Function |
Description |
|
Play.noteOn(pitch, volume, channel) |
Starts pitch sounding. Specifically, it sends a NOTE_ON message with pitch (0–127), at given volume (0–127—default is 100), to played on channel (0–15—default is 0) through the Java synthesizer. |
|
Continued |
|
|
Play.noteOff(pitch, channel) |
Stops pitch from sounding. Specifically, it sends a NOTE_OFF message with pitch (0–127), on given channel (0–15—default is 0) through the Java synthesizer. If the pitch is not sounding on this channel, this has no effect. |
|
Play.note(pitch, start, duration, volume, channel) |
Schedules a note with pitch (0–127) to be sounded after start milliseconds, lasting duration milliseconds, at given volume (0–127, default is 100), on channel (0–15, default is 0) through the Java synthesizer. |
|
Play.allNotesOff() |
Stops all notes from sounding on all channels. |
|
Play.setInstrument(instrument, channel) |
Sets a MIDI instrument (0–127—default is 0) for the given channel (0–15—default is 0). Any notes played through channel will sound using instrument. |
|
Play.getInstrument(channel) |
Returns the MIDI instrument (0–127) assigned to channel (0–15—default is 0). |
|
Play.setVolume(volume, channel) |
Sets the global (main) volume (0–127) for this channel (0–15). This is different from the velocity level of individual notes—see Play.noteOn(). |
|
Play.getVolume(channel) |
Returns the global (main) volume (0–127) for this channel (0–15). |
|
Play.setPanning(position, channel) |
Sets the global (main) panning position (0–127) for this channel (0–15). The default position is in the middle (64). |
|
Play.getPanning(channel) |
Returns the global (main) position (0–127) for this channel (0–15). |
|
Play.setPitchBend(bend, channel) |
Sets the pitch bend for this channel (0–15—default is 0) to the Java synthesizer object. Pitch bend ranges from −8192 (max downward bend) to 8191 (max upward bend). No pitch bend is 0 (which is the default). If you exceed these values, the outcome is undefined (it may wrap around or it may cap, depending on the system.) |
|
Play.getPitchBend(channel) |
Returns the current pitch bend for this channel (0–15—default is 0). |
|
Play.frequencyOn(frequency, volume, channel) |
Starts a note sounding at the given frequency and volume (0–127—default is 100) on channel (0–15—default is 0). |
|
Warning: You should play only one frequency per channel. (Since this uses pitch bend indirectly, it will affect the pitch of all other notes sounding on this channel.) |
|
|
Play.frequencyOff(frequency, channel) |
Stops a note sounding at the given frequency on channel (0–15—default is 0). |
|
Continued |
|
|
Warning: You should play only one frequency per channel. (Since the frequency gets translated to a pitch and a pitch bend, this will also affect notes with nearby frequencies on this channel.) |
|
|
Play.allFrequenciesOff() |
Same as Play.allNotesOff(). Stops all notes from sounding on all channels. |
D.4 AudioSample Functions
The AudioSample class includes functions related to playing audio samples in real time. An audio sample is a sound object created from an external audio file (supported formats are WAV and AIF—16-, 24-, and 32- bit PCM and 32-bit float), which can be played, looped, paused, resumed, and stopped. The functions below are intended for building interactive musical instruments and installations.
An application may have several AudioSample objects active at the same time. It is even possible to create complex timbres by loading several simple sound objects and manipulating them (e.g., changing their frequency and/or volume) in real time. AudioSample objects open endless timbral possibilities for interactive applications.
This class is included in the music library, so you need the following in your program:
from music import *
Use the following function to create an AudioSample object:
|
Function |
Description |
|
AudioSample(filename, pitch, volume) |
Creates an audio sample from the audio file specified in filename (supported formats are WAV and AIF—16-, 24-, and 32-bit PCM and 32-bit float). Parameter pitch (optional) specifies a MIDI note number to be used for playback (default is A4). Parameter volume (optional) specifies a MIDI note velocity to be used for playback (default is 127). |
Once an audio sample, a, has been created, the following functions are available:
|
Function |
Description |
|
a.play() a.play(start, size) |
Play the sample once. If start and size are provided, the sample is played from milliseconds start until milliseconds start+size (default is 0 and –1, respectively, meaning from beginning to end). |
|
Continued |
|
|
a.loop() a.loop(times, start, size) |
Repeats the sample indefinitely. Optional parameter times specifies the number of times to repeat (default is –1, indefinitely). If start and size are provided, looping occurs between milliseconds start and milliseconds start+size (default is 0 and –1, respectively, meaning from beginning to end). |
|
a.stop() |
Stops sample playback immediately. |
|
a.pause() |
Pauses sample playback (remembers current position for resume). |
|
a.resume() |
Resumes sample playback (from the paused position). |
|
a.isPlaying() |
Returns True if the sample is still playing, False otherwise. |
|
a.setPitch(pitch) |
Sets the sample pitch (0–127) through pitch shifting from sample’s base pitch. |
|
a.getPitch() |
Returns the sample’s current pitch (it may be different from the default pitch). |
|
a.setFrequency(freq) |
Sets the sample pitch frequency (in Hz). This is equivalent to setPitch(), except it provides more granularity (accuracy). For instance, pitch A4 is the same as frequency 440 Hz. |
|
a.getFrequency() |
Returns the current playback frequency. |
|
a.setVolume(volume) |
Sets the volume (amplitude) of the sample (volume ranges from 0 to 127). |
|
a.getVolume() |
Returns the current volume (amplitude) of the sample (volume ranges from 0 to 127). |
|
a.setPanning(panning) |
Sets the panning of the sample (panning ranges from 0–127). |
|
a.getPanning() |
Returns the current panning of the sample (panning ranges from 0–127). |
|
a.getFrameRate() |
Returns the sample’s recording rate (e.g., 44100.0 Hz). |
D.5 MidiSequence Functions
The MidiSequence class includes functions related to playing external MIDI files (as well as Note, Phrase, Part, and Score objects) in real time. A MIDI sequence provides playback features that are similar to the functionality described above for audio samples. Again, these functions are intended for building interactive musical instruments and installations.
This class is included in the music library, so you need the following in your program:
from music import *
Use the following function to create a MidiSequence object:
|
Function |
Description |
|
MidiSequence(material, pitch, volume) |
Creates a MIDI sequence from the MIDI material specified in material (this may be a filename of an external MIDI file or a Note, Phrase, Part, and Score object. Parameter pitch (optional) specifies a MIDI note number to be used for playback (default is A4). Parameter volume (optional) specifies a MIDI note velocity to be used for playback (default is 127). |
Once a MIDI sequence, m, has been created, the following functions are available:
|
Function |
Description |
|
m.play() |
Plays the MIDI sequence once. |
|
m.loop() |
Repeats the MIDI sequence indefinitely. |
|
m.stop() |
Stops MIDI sequence playback immediately. |
|
m.pause() |
Pauses MIDI sequence playback (remembers current position for resume). |
|
m.resume() |
Resumes MIDI sequence playback (from the paused position). |
|
m.isPlaying() |
Returns True if the MIDI sequence is still playing, False otherwise. |
|
m.setPitch(pitch) |
Sets the MIDI sequence’s playback pitch (0–127) by transposing the MIDI material. |
|
m.getPitch() |
Returns the MIDI sequence’s playback pitch (0–127). |
|
m.setTempo(tempo) |
Sets the MIDI sequence’s playback tempo in beats per minute (e.g., 60). |
|
m.getTempo() |
Returns the MIDI sequence’s playback tempo (in beats per minute). |
|
m.getDefaultTempo() |
Returns the MIDI sequence’s default tempo (in beats per minute). |
|
m.setVolume(volume) |
Returns the volume of the MIDI sequence (0–127). |
|
m.getVolume() |
Returns the current volume of the MIDI sequence (0–127). |
D.6 Timer Functions
The Timer class allows us to schedule events to happen after a precise time interval has passed and/or to be repeated at precise time intervals in the future. An event is anything that can be specified/included in the body of a Python function. In essence, a Timer object is given a function to execute in the future. This function you may include one or more sound events (such as a note or an audio sample), altering parameters of an on-going process (such as changing the frequency or volume of an audio sample, or changing the color of a graphics object on a GUI display), and many other possibilities.
Timer objects are useful building blocks for more advanced interactive musical instruments and installations. Among other things, Timer objects can be used for creating animation.
The Timer class is included in its own library, so you need the following in your program:
from timer import *
Use the following function to create a Timer object:
|
Function |
Description |
|
Timer(delay, function, parameters, repeat) |
Creates a new Timer to execute function after delay time interval (in milliseconds). The optional parameter parameters is a list of parameters to pass to the function (when called). The optional parameter repeat (boolean — default is True) determines if the timer will go on indefinitely. Note: The list of parameters is fixed at timer creation time and cannot be modified. |
Once a timer object, t, has been created, the following functions are available:
|
Function |
Description |
|
t.start() |
Starts timer t. |
|
t.stop() |
Stops timer t. |
|
t.getDelay() |
Returns the delay time interval of timer t (in milliseconds). |
|
t.setDelay(delay) |
Sets a new delay time interval for timer t (in milliseconds). This allows us to change the speed of the animation, after some event occurs. |
|
t.isRunning() |
Returns True if timer t is running (has been started), False otherwise. |
|
t.setFunction(function, parameters) |
Sets the function to execute. The optional parameter parameters is a list of parameters to pass to the function (when called). |
|
t.getRepeat() |
Returns True if timer t is set to repeat, False otherwise. |
|
t.setRepeat(flag) |
If flag is True, timer t is set to repeat (this also starts the timer, if stopped). Otherwise, if flag is False, timer t is set to not repeat (this stops the timer, if running). |
D.7 MIDI Input Output, and Functions
The MidiIn and MidiOut classes enable communication, from within your programs, to various input and output MIDI devices connected to your computer.
D.7.1 The MidiIn Class
MidiIn objects may be used in your programs to get input from MIDI devices that generate input events (e.g., a MIDI guitar, keyboard, or control surface).
The MidiIn class is included in the MIDI library, so you need the following in your program:
from midi import *
Use the following function to create a MidiIn object:
|
Function |
Description |
|
MidiIn() |
Creates a new MidiIn object to connect to an input MIDI device. When called, it presents the user with a GUI to select one from the available MIDI devices (see Figure 9.3). |
Once a MIDI input object, mInput, has been created, the following functions are available:
|
Function |
Description |
|
mInput.onNoteOn (function) |
When a NOTE_ON event happens on the mInput device (i.e., the user starts a note), the system calls the provided function. This function should expect four parameters, eventType, channel, data1, data2. For NOTE_ON events, the eventType is always 144, the channel ranges from 0 to 15, data1 is the note pitch (0–127), and data2 is the volume of the note (0–127). |
|
mInput.onNoteOff (function) |
When a NOTE_OFF event happens on the mInput device (i.e., the user ends a note), the system calls the provided function. This function should expect four parameters, eventType, channel, data1, data2. For NOTE_OFF events, the eventType is always 128, the channel ranges from 0 to 15, data1 is the note pitch (0–127), and data2 is ignored. |
|
Continued |
|
|
mInput.onSetInstrument (function) |
When a SET_INSTRUMENT (also known as CHANGE_PROGRAM) event happens on the mInput device (i.e., the user selects a different timbre), the system calls the provided function. This function should expect four parameters, eventType, channel, data1, data2. For SET_INSTRUMENT events, the eventType is always 192, the channel ranges from 0 to 15, data1 is the MIDI instrument (0–127), and data2 is ignored. |
|
mInput.onInput (eventType, function) |
Associates an incoming eventType with a callback function. When the specified eventType event happens on the mInput device, the system calls the provided function. This function should expect four parameters, eventType, channel, data1, data2. Can be used repeatedly to associate different event types (128–224) with different callback functions (one function per event type). If eventType is ALL_EVENTS, then function will be called for all incoming events that have not yet been assigned callback functions. |
D.7.2 The MidiOut Class
MidiOut objects may be used in your programs to send output to MIDI devices that accept output events (e.g., an external MIDI synthesizer).
The MidiOut class is included in the MIDI library, so you need the following in your program:
from midi import *
Use the following function to create a MidiOut object:
|
Function |
Description |
|
MidiOut() |
Creates a new MidiOut object to connect to an output MIDI device. When called, it presents the user with a GUI to select one from the available MIDI devices (see Figure 9.4). |
Once a MIDI output object, mOutput, has been created, the following functions are available:
|
Function |
Description |
|
mOutput.noteOn(pitch, velocity, channel) |
Sends a NOTE_ON message with pitch (0–127), at a given velocity (0–127—default is 100), to channel (0–15—default is 0) on the mOutput device. |
|
Continued |
|
|
mOutput.noteOff(pitch, channel) |
Sends a NOTE_OFF message with pitch (0–127), on given channel (0–15—default is 0) on the mOutput device. If the pitch is not sounding on this channel, this has no effect. |
|
mOutput.setInstrument(instrument, channel) |
Sets a MIDI instrument (0–127—default is 0) for the given channel (0–15—default is 0) on the mOutput device. Any notes played through channel will sound using instrument. |
|
mOutput.playNote(pitch, start, duration, velocity, channel) |
Schedules playing of a note with pitch at the given start time (in milliseconds from now), with duration (in milliseconds from start time), velocity (0–127—default is 100), to channel (0–15—default is 0) on the mOutput device. |
|
mOutput.play(material) |
Plays music library material (Score, Part, Phrase, Note) on the mOutput device. |
|
Note: For more information, see Chapter 9. |
|
D.8 Open Sound Control (OSC) Functions
The OscIn and OscOut classes provide functionality for open sound control (OSC) communication between programs running on your computer and other OSC devices. As opposed to MIDI input and output, where devices need to be physically connected (via wire) to your computer, OSC devices (by the nature of the OSC protocol) may be located anywhere on the Internet (in the same room, next room, or anywhere on the planet).
This Internet connectivity opens endless possibilities for developing interactive applications and installations.
D.8.1 The OscIn Class
OscIn objects (OSC servers) may be used in your programs to receive incoming OSC messages from OSC devices (clients) that send out OSC messages (e.g., an OSC-enabled smartphone or control surface).
The OscIn class is included in the OSC library, so you need the following in your program:
from osc import *
Use the following function to create an OscIn (server) object:
|
Function |
Description |
|
OscIn(port) |
Creates a new OscIn (server) object to receive incoming messages from an OSC device (such as a smartphone, or tablet) on the given port. The port number is an integer from 1024 to 65535 that is not being used by another program. |
Once an OscIn object, oscServer1, has been created, the following functions are available:
|
Function |
Description |
|
oscServer1.onInput(address, function) |
When an OSC message with the given address arrives, call function. OSC addresses look like a URL, e.g., “/first/second/third”. The function should expect one parameter, the incoming OSC message. |
D.8.2 The OscOut Class
OscOut objects (OSC clients) may be used in your programs to send OSC messages to OSC devices (servers) that listen for incoming OSC events. For instance, you could use a collection of objects to synchronize (or share data between) two different programs on the same computer or several computers used in an installation. These computers do not have to be physically connected (only to be on the Internet). Again, the possibilities are endless.
The OscOut class is included in the OSC library, so you need the following in your program:
from osc import *
Use the following function to create an OscOut (client) object:
|
Function |
Description |
|
OscOut(IPaddress, port) |
Creates a new OscOut (client) object to send messages to another OSC (server) device (such as a smartphone, or tablet) at the given IPaddress (a string, e.g., “192.168.1.223”) and port (an integer in the range 1024 to 65535). |
Once an OscOut object, oscClient1, has been created, the following functions are available:
|
Function |
Description |
|
oscClient1.sendMessage(address, arg1, arg2, ...) |
Sends an OSC message with address and 0 or more arguments to the OSC device associated with oscClient1 (when it was created). |
|
Note: For more information, see Chapter 9. |
|
D.9 Zipf Library
Zipf’s law models the scaling (fractal) properties of many phenomena in human ecology, including natural language and music (Zipf 1949). Zipf’s law is one of many related laws that describe scaling properties of phenomena studied in the physical, biological, and behavioral sciences. These include Pareto’s law, Lotka’s law, power laws, Benford’s law, Bradford’s law, Heaps’ law, etc.
The Zipf library provides functions that may be used to calculate the fractal dimension of any natural or human phenomenon, including musical pieces. To use these functions, you need the following in your program:
from zipf import *
The following functions allow you to calculate Zipf slopes and R squared (R2) values from event counts (and, potentially, event sizes) of natural and human phenomena (e.g., see Zipf 1949, p. 337).*
|
Function |
Description |
|
byRank(counts) |
Returns the Zipf slope and R2 values generated from plotting the counts (y-axis) against the ranks of the values from largest to smallest (x-axis) in log-log scale. The ranks are generated automatically. |
|
bySize(sizes, counts) |
Returns the Zipf slope and R2 values generated from plotting the counts (y-axis) against the corresponding sizes (x-axis) in log-log scale. The two lists, sizes and counts, are parallel. That is, each value of counts indicates how many fractal subdivisions of the corresponding sizes value are presented in the phenomenon (e.g., music piece) being studied. |
For more information, see Chapter 11.
D.10 ColorGradient Function
The colorGradient function returns a list of RGB colors creating a “smooth” gradient between two colors. To use this function, you need the following in your program:
from gui import *
This function may be used in conjunction with code that gives different GUI elements (such as points or circles) different colors to simulate a gradient. This may be useful in various interactive applications and installations.
|
Function |
Description |
|
colorGradient(color1, color2, steps) |
Returns a list of RGB colors creating a “smooth” gradient between color1 and color2. |
For more information, see Chapter 11.
* Through this technique, we may discern the composer, genre, and even popularity of musical pieces (Manaris et al. 2005, 2007).