From CCRMA Wiki
Revision as of 13:48, 9 December 2010 by Noune (Talk | contribs)

Jump to: navigation, search

Pendula is a single and two-player network game based on musical intervals. 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.


Dowload 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 would move back and forth along the direction of oscillation, say along the x-axis. Another pendulum oscillating in an orthogonal plane to the first would cause the pen to move along the orthogonal axis, the y-axis. So what you obtain 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 game environment: the intent was to help players to become better at recognizing musical intervals while having fun and enjoying the beautiful shapes they would be generating.

Single Player

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 the note 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 how 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 -so don't guess too much!


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

Two Player

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 note played by player 1 and the last note played by player 2. For example, assume the target interval is a perfect fourth. If player 1 plays a D and player has played nothing yet, there is no interval yet. Only when player 2 triggers a G will the current interval change to perfect fourth and the harmonogram updated. Since the target interval was a perfect fourth, then 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 being updated.


  • 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 compared to the other player's note, and vice versa.


One of the player has to be a server (the one who randomly generates the intervals), the other a 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 functionalities 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 classed 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: play notes and watch 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 interval and its harmonograph. New Round(S0)
  • State S3, 3 Seconds: Someone lost, encourage them, playback interval and display harmonograph. New Round (S0)
  • Communication between two hosts using Open Sound Control
  • Messages exchanged: handshaking at startup, target interval from server to client, round winner and score
  • Graphics using OpenGL/GLUT
  • Audio Driver: Real-time Audio