From CCRMA Wiki
Jump to: navigation, search

Pendula is a single and two-player network game based on musical intervals. I (Elie Noune) wrote it for my Music, Computing and Design class (CS476A/MUSIC256A, Autumn 2010). The single player version is guessing game in which the player first hears and "sees" a target interval and tries to guess that interval by playing it back using the computer keyboard. Played musical intervals are visualized with a harmonogram, which is a plot that shows the relation between the two notes. In the two-player version, players compete against each other to find the target interval in a more challenging way: the last two notes they played are used to form the current interval, so a player should choose what note to trigger depending on what his opponent played.


Download the mac OSX version at:


The idea came when I was making my way out in the bookstore and I bumped over a book called Harmonograph, A Visual Guide to the Mathematics of Music. A Harmonograph is a mechanical device used to visualize harmony between frequencies. It used to be popular in the 19th century in London, when people used to organize parties to watch the amazing figures it could draw. The device consists of pendula (plural of pendulum), attached to a pen mounted on a piece of paper. As a single pendulum oscillates at a specific frequency, the pen moves back and forth along the direction of oscillation, call it the x-axis. Another pendulum oscillating in an orthogonal plane to the first would cause the pen to move along the orthogonal y-axis. The result is a superposition of both motions along the x and y axis, which is called a Lissajous curve. When I skimmed through the book, I was amazed at the shapes you could obtain using this device and its potential to visualize harmonies, so I thought of writing a networking application that would allow two persons to collaboratively take control over a harmonograph while simultaneously playing music, hence the name Pendula. Later, this concept evolved into a interactive game environment: the intent was to help players in becoming better at recognizing musical intervals while having fun and enjoying the beautiful shapes they would be generating.

Single Player Mode

The game starts with displaying the harmonogram of a random interval without showing its name. The player only gets to hear what this interval sounds like. He should then try to regenerate this target interval by playing notes on his computer keyboard, which lowest letter rows are mapped like in a piano keyboard (Z is C, S is C#, X is D, etc...). All intervals formed are relative to C, i.e. each note the player hits is used to form an interval with pitch class C, and that interval is compared with the target interval. The player has 15 seconds to guess the target interval, after the latter changes to a new one, with the beginning of a new round. At the end of every round, the target interval is played back irrespective of the game's outcome to remind the player of what it sounded like and help him memorizing it.


  • The player wins 5 points when he hits the target interval.
  • The player loses a point every time he misses - don't hit too many keys hoping that one of them will work!


Start a terminal, cd to pendula/src and type ./pendula

Two Player Mode

This is the coolest one! This time the target interval's name is displayed and the winner is the one who hits the target interval first, but this is no simple race! Current intervals are no more relative to C, but they are formed using the last single notes played by player 1 and 2. For example, assume the target interval is a perfect fourth. If player 1 plays a D and player played nothing, then there is no interval yet. Only when player 2 triggers a G will the current interval change to perfect fourth and the harmonogram be updated. Since the target interval was a perfect fourth, player two won because he was the one who triggered that interval! A round lasts for 15 seconds, after which the target interval is played back before a new random interval kicks in.


  • The player wins 10 points when he hits the target interval!
  • The player loses a point every time he misses -so don't guess too much!

Hint: the displayed interval should help you in guessing lower or higher. For instance, if the target is a 6th and the current interval is a 4th then you should try to play higher than your last note if your note was the lowest in pitch.


One of the players has to be the server (the one who randomly generates the intervals), the other the client. Start a terminal, cd to pendula/src and type :

./pendula -s <pierIP> for server

./pendula -c <pierIP> for client where pierIP is the IP address of your opponent

Software Design

  • Both server and client running modes are provided within the same executable
  • Virtual Midi keyboards are not required
  • Class Pendulum to model the oscillation of a pendulum: amplitude, frequency, phase, damping
  • Class Harmonograph is a class composed of "pendulum" which provides methods to tune these pendula and draw their combined output
  • Class Game is similar to a Finite State Machine that tracks the game's states
  • State S0, 3 seconds: Random Interval generated at the start of every round. Interval is played back and its harmonogram is displayed
  • State S1, 15 seconds: rock on and enjoy the harmonogram. Target interval is displayed on the right hand bottom corner
  • State S2, 3 Seconds: We've got a winner, congratulate him and play back the target interval and its harmonogram. New Round(S0)
  • State S3, 3 Seconds: Someone lost, encourage them, play back the target interval and display its harmonogram. New Round(S0)
  • Communication between two hosts using Open Sound Control
  • Messages exchanged: handshaking at start-up, target interval from server to client, round winner and score
  • Graphics using OpenGL/GLUT
  • Audio Driver: Real-time Audio