About WiiMotion

WiiMotion is a system for connecting a Nintendo Wii Remote to a Bluetooth-equipped Macintosh in order to analyze the motion data from the Wii Remote. For fun, this example shows how to recognize gestures and use them to control iTunes on the Mac.

Download (Mac only)

Download the WiiMotion zip file. It contains a program for connecting to the Wii Remote, a script for interpreting the data and this set of instructions.

WiiMotion.zip 168k


First, launch the "Wiimote Connect" program to interface with the Wii Remote. Sync the Wii Remote by pressing the 1 + 2 buttons simultaneously.

Graph from Wiimote Connect Program

A graph should appear once the Wii Remote is synced.

Next, open a Terminal window and navigate to the WiiMotion scripts directory.

1. Type cd then a space.
2. Drag the scripts folder onto the Terminal window.
3. Hit return.

Your Terminal should look something like this:

macbooks-computer:~/Desktop/WiiMotion/scripts macbook$

Once you've changed the directory, copy and paste the following command into the Terminal:

tail -f /tmp/wiipipe | python wiitunes.py

. . .

The Terminal window should display a readout of numbers from the Wii Remote.

Hold the B button while moving the Wii Remote to execute a gesture. When a gesture command is recognized, its name appears in the Terminal.

If iTunes is running, you should be able to control it now.

. . .

Hit ctrl-c to exit the Terminal readout and stop using Wii motion data.


A - Play/Pause
B - Hold while executing gestures

1 - Turn off/on motion capture
2 - Turn off/on motion capture

The direction pad, home, plus and minus buttons have no function for this script (though they certainly could).

Basic Gestures

Roll: Twist the remote on its longest axis
Pitch: Tilt the remote up or down
Yaw: Swing the remote from side to side

To Control iTunes

Roll left/right for previous/next track
Pitch up/down to raise/lower volume
Yaw left/right to select previous/next playlist

Remember: Hold down the B button while executing a gesture to let WiiMotion know to expect a command. Without this safeguard, the Wii Remote goes a little crazy whenever you set it down.

What Does the Readout Mean?

The terminal window displays three sets of numbers for each gesture. They should look something like this:

r: -2 14 18 -3 . 5
p: 2 -5 -5 -7 -2 .
y: . -7 -9 -8 . 5

Each time a new set of numbers appears, it means that the Wii Remote has detected a change in its orientation. This is a gesture.

A series of six numbers are displayed for Roll, Pitch and Yaw movements. These numbers represent the change in position during the gesture. A dot (.) reflects no change.

Watch the readout as you execute different gestures to develop an understanding of how the numbers reflect the movement. The numbers vary in patterns. The amplitude of the change, its axis, whether it represents a rising or falling pattern, and the overall consistency can be used to programmatically interpret the gesture.

More complex pattern matching could detect longer gestures (these are only about one second each) across multiple axes and could detect subtleties such as the attack (staccato vs legato) or patterns of decay or sustain.


This system is based on several pieces of software:

AMSTracker by Amit Singh

BumpTunes by Timo Arnall

DarwiinRemote by Hiroaki Kimura

RoombaWii by Christopher Hughes

I've modified DarwiinRemote to output readings in a format similar to that generated by AMSTracker software, on which BumpTunes originally depended. Like RoombaWii, the Wii Remote outputs to a temporary named pipe on the Mac, the contents of which are fed into a Python script via the Terminal, much like BumpTunes, which then controls iTunes through Applescript.

WiiMotion pattern matching is much different from BumpTunes, which only needed to measure whether or not a Powerbook was being tilted and the direction of the tilt (three states). I wanted to work with taps rather than tilts on my Macbook and so needed a higher resolution to decipher the complex wobbles that occur when you tap on your computer. The 18 measured increments that I'm using are an artifact of that early experimentation, though a Wii Remote could obviously benefit from many more datapoints.

More sophisticated pattern matching scripts could be written to work with the data that the Wiimote Connect program outputs. The Applescript in the wiitunes.py file could also be modified to control other programs besides iTunes. If you create any experiments based off these ideas I'd love to see them. Contact me at jeff at howardesign dot com

// jeff

February 2007
Updated August 2007