Quick Reference Pages

• Operators
• Built-in Functions
• Common Methods
• Built-in Modules
• Turtle graphics
• Music synthesis (you are here)

Synth Reference

For producing (cheesy) synthesized sounds, we've written a synth module that can be used to build simple music out of notes and beats. The selection of instruments and their quality is extremely limited, but it allows us to make music as an alternative to drawing things with the turtle module. Using the synth module is more like programming a robot that writes sheet music than programming a robot that plays an instrument.

You can download the latest version of synth.py at this link:

synth.py

Music Concepts

To use this module you will need a basic grasp of some musical concepts, although you will not need to really be familiar with music theory or know how to play an instrument. The basic concepts you'll need are:

1. Tracks. A "track" is a series of notes that are all played together, but which can be separated from other tracks. Tracks can be saved to a '.wav' file, and if you install the extra simpleaudio module, they can be played on your speakers directly within Python. The synth module has a way to change the "current track," and any notes that you create will always be added to whichever track is current. You can use multiple tracks and later mix them together into a single track, or you can simply add all of your notes to a single track. For the most part in this class, we'll use the latter strategy, as it's simpler, and you won't have to worry too much about tracks.

2. Notes vs. beats vs. "rests". The synth module has three functions for adding music to a track: addNote, addBeat, and addRest.

   • addRest is the simplest of these functions, because a "rest" in musical terminology is a period of silence, when the musician gets to take a rest. Adding rests doesn't actually change the sound of a track, but it may extend its duration, and it can be convenient to add a rest to create a gap between notes if you want one, although it's not strictly necessary. Note that adding a rest on top of an existing note won't erase that note (and there's currently no way to erase notes you've added to a track).
   • addBeat is still pretty simple, and is used for drums and other percussion instruments which don't have a specific pitch to them. You can specify when the beat should be added, what instrument to use, and how long the beat should last.
   • addNote is the most complicated function, and is used for any instrument that has a specific pitch. You'll need to specify when in the track to add the note, the instrument to use, the pitch of the note, and its duration.

3. Pitches. A pitch (or tone, or frequency) in music refers to how high or low a sound is, and it's represented as a number. You won't have to do math with these numbers yourself (as that's quite complicated) but you will have to use the synth library's pitch modification functions to compute higher or lower pitches when you need them, and there are a few concepts to be aware of:

   • A "half-step" is the smallest unit of pitch difference that the synth module can easily create, and there are halfStepUp and halfStepDown functions for calculating higher and lower pitches. Half steps are used as part of the basis for classical music, and there are 12 half-steps in an "octave," which represents a doubling of pitch.
   • A "step" or "whole step" is a larger unit of pitch difference that is usually equivalent to two half-steps. You can use the stepUp and stepDown functions to produce pitches that are higher or lower by a step. However, steps are not as regular as half-steps, because there are 8 whole steps in an octave, not 6. Classical music is just complicated like that. You won't need to worry about this too much: just use the stepUp and/or stepDown functions and they'll take care of what the pitch should be.
   • A "leap" is not a real musical term, but synth has leapUp and leapDown functions which move between notes on what is called a pentatonic scale that uses 5 notes per octave instead of 8. Pentatonic scales are used in several non-Western music systems, and they're beginner-friendly because no matter what notes you combine, the result will always sound nice (in contrast, combining notes that are the wrong number of steps or half-steps apart can sound pretty horrible!). You don't need to worry too much about the details here, just pay attention to when we ask you to use 'leaps' vs. 'steps'.

   In addition to moving pitches up and down, you'll need to be able to talk about specific pitches, and there are two systems that synth provides. Scientific pitch notation is a classical pitch system which labels each of the eight steps in an octave using the letters "A" through "G", and then pairs those letters with a number indicating which octave the note is in. So for example, the note B3 is one octave below (i.e. 8 whole steps below, or 1/2 the frequency of) the note B4. Similarly, G4 is 3 steps above D4. The confusing thing about this system is that each octave starts on a C, not an A, so B3 is only one step below C4, which is the first note in octave 4. The synth module makes global variables named for all of the pitches C0 through B9 available. In addition to these variables, there is a set of variables named P0 through P14 which refers to successively higher notes on a pentatonic scale. These have the same values as some of the scientific pitch notation notes, they're just alternate names for them, but they can be used instead for a simpler way of naming higher and lower notes, with larger pitch differences between those notes. For reference, P5 is equal to C4, and that tone is a reasonable "middle" tone that's neither very high nor very low. If you happen to be familiar with musical notation, or if you've seen sheet music and wondered about how it works, here is an image of how these different pitch values map to sheet music notation:

   

Reference

What follows is a summary of each of the most important synth functions that you'll need to use, including a brief description of what the function does and examples of how it could be used.

Note that the simplest way to get access to these functions is to use the following import statement (assuming that synth.py is in the same directory as the file you're working on):

from synth import *

Also note that in order for synth.py to play sounds directly from within Python, you'll need to the "Manage Packages" feature in the "Tools" menu in Thonny to install the "simpleaudio" package, although you can use synth.py without this feature to produce .wav files that you can use a separate media player program to play back.

setTime(1)
addRest(2)

setDrum('kick')
setVolume(0.8)
addBeat(0.2)

setInstrument('keyboard')
setPitch(C4)
addNote(0.2)

name = pitchName(440)
# will be 'A3'

setPitch(D4)
halfStepUp()
# pitch will now be Eb4

setPitch(D4)
stepUp()
# pitch will now be E4

setPitch(E4)
leapUp()
# pitch will now be G4

addNote(0.5)
setUp(3)
rewind(0.5)
addNote(0.5)

Pitch Details

More details about pitches: in fact, the number that represents a pitch tells us how many times per second that sound vibrates the air: "higher" pitches are produced by faster vibrations (meaning more tiny pulses of high-pressure air per second) while "lower" pitches have slower vibrations. The range of frequencies that's comfortable goes from something like 20-30 pulses-per-second on the very low end, all the way up to something like 10,000-20,000 pulses-per-second on the high end, and the range is so large in part because pitch is multiplicative, not additive. In other words, when we go "up" a certain amount in terms of pitch, we're multiplying the frequency of the note, not adding to it. Going up by the same amount again and again represents successive multiplications, which is why there's such a large range of values. Pitches are stored using floating-point numbers (or rarely, integers), and you won't have to do any of the math yourself because of the functions like stepUp or leapDown that the synth module provides.