To turn signals coming from a Wiimote into MIDI events.
In more concrete terms: to play real MIDI instruments with the Guitar Hero drumkit. Or to control stage effects (lighting and so on) with your Wiimote buttons. Or to control software sound effects with a hacked Wiimote. Or simply to use your Wiimote as a remote control for your media player.
- Handles all the standard buttons on a Wiimote, plus those on the “nunchuck” (including the directional stick), the Guitar Hero World Tour drum contoller (including the actual drum pads, the stick and the extra buttons), the Guitar Hero guitar controller (colored frets, “touch” frets, strum bar, buttons, stick and the whammy bar). The ”classic controller” is only partially supported (sticks and a few buttons); I don't have one at hand to test.
- Each event can be mapped to a specific MIDI signal (note or program-change or any arbitrary MIDI message).
- …or to a LED status change.
- …or to LED animations!
- …ot to set the default channel for future events.
- …or to several such actions (MIDI signals, LED stuff, channel change).
- …or even cycle across a list of events, so a button/pad can act as a toggle.
- Buttons generate two separately-mappable events for press and release.
- Drum pads are sensitive to the force of the hit, which is mapped to a MIDI velocity. Also, the MIDI event can differ based on the strength of the hit, which allows things like open/closed hi-hat sounds on the same pad.
- Directional sticks can be used as an “analog” control (with values across the given range of the stick); they are also mapped to four virtual buttons that generate press/release events if that's enough.
.ini-style configuration file.
- Multiple configurations can be defined in the configuration file, and one chosen at runtime.
- The configuration includes what MIDI device to send the events too.
- A sample Hydrogen “song file” is provided, since it can be tricky to set up a kit appropriately in Hydrogen.
- A sample Wiimidi kit is also included in the configuration file, which should work with the order of the instruments in the default GMkit provided by Hydrogen.
- A sample script is also included, demonstrating how to run arbitrary commands on receiving MIDI events. The commands shown in the sample script control the Rhythmbox music player, which you can therefore control with your Wiimote or something attached to it.
- Free Software: licensed under the GNU General Public License, version 2 or later.
The current version of Wiimidi is arbitrarily numbered 0.8, and can be downloaded at wiimidi-0.8.tar.gz.
Wiimidi is developed with Bazaar, and the public branch is at
http://alioth.debian.org/~lolando/bzr/wiimidi/trunk/ (may also work
in https). So, to grab a copy:
bzr checkout http://alioth.debian.org/~lolando/bzr/wiimidi/trunk/
You'll need a few Python modules, namely
(PortMidi) and of course
python-cwiid for accessing the Wiimote
data. They're all packaged in major Linux distributions. Wiimidi
itself could easily be made available in Debian if there's enough
demand (the Bazaar branch actually already contains the packaging).
wiimidi --verbose --config=./wiimidi.conf --kit=general_midi
--config option allows specifying a config file (on top of the
--kit allows choosing which of the
configurations in the config file to use. After launching the script,
press the 1+2 buttons simultaneously on the Wiimote to establish the
Bluetooth peering. Oh, yes, you'll need a Bluetooth adapter if it's
not built-in, of course.
wiimidi.conf file to fit your needs. (Or copy it to
/etc/wiimidi/wiimidi.conf or to your
~/.config/wiimidi/wiimidi.conf.) It's sort of self-documented, and I
tried to pick meaningful names for the sections and the variables, as
well as providing usable default values, but your use case may be
different. The configuration syntax is described below.
Each section describes a “kit”, or set of settings. The
section is special, and its values are inherited by other kits. It
also has a
default_kit setting, which is used if no kit is
explicitly specified on the command line.
midi_out describes the MIDI port to which events should be sent. It
can be a purely software port (Midi Through Port-0 for instance, or
Hydrogen Midi-In) or a hardware adapter (my Roland USB adapter
describes itself as UM-1G MIDI 1).
on_startup is a list of actions to be executed on startup. You can
send initialization messages to MIDI, or provide some visual feedback
using the LEDs on the Wiimote.
map_* values describe the mappings from Wiimote events to actions.
The simplest mappings concern the buttons and the cross-pad:
map_wiimote_button_left and so on. You can
also trigger events when the button is released, with mappings such as
When the Wiimote is plugged into an additional controller that
provides buttons, these can be mapped too; for instance, the nunchuck
map_nunchuck_button_c (and the
When the additional controller provides a directional stick, four new
virtual buttons appear for up/down/right/left; hence possible mappings
map_guitar_stick_left (and of course
map_nunchuck_stick_right_release for the release action). The exact
value of each axis (mapped to the 0-127 range used in MIDI) can also
be used for MIDI “control change” events (see
cc below) with
map_nunchuck_stick_y. The classic controller provides two such
sticks, leading to
map_classiccontroller_leftstick_up and so on.
The classic controller has a cross-pad and a handful of buttons, used
the usual way. The standard classic controller also provides two
r, which can be mapped to a control
change using the
map_classiccontroller_trigger_l mapping (and ditto
_r of course). This comes in addition to the
mappings, so you can use the triggers both as a continuous source of
events or as a button. Note that the “classic controller pro“ only
provides buttons where these triggers are in the standard one, so the
_trigger_l/r mappings will not be particularly useful since they'll
only send one of two distinct values.
The drum pads (
map_drum_pad_kick, and so on) are
sensitive to velocity (on a range from 1 to 7), and can have a
different mapping based on whether the hit is stronger than a
threshold. To have the red pad send a “cross-stick” action instead of
the standard snare drum action on soft hits, set
drum_split_threshold_red to a value such as 2, and set the
map_drum_pad_red_soft value to the cross-stick action.
The guitar controller provides five fret buttons (from
map_guitar_fret_orange). The Guitar Hero
World Tour guitar controller also provides five buttons for the
sensitive part of the guitar neck, which are accessible with
map_guitar_touchfret_5; note that these
touch-frets they're not quite independent: at most two touch-frets can
be active at a time, and that requires them to be contiguous. If you
finger several touch-frets in a split way, only the highest one is
taken into account (or possibly the highest two, if they're
The guitar controller also provides a whammy bar, which can be mapped
to a control change action with
Note that the various controls provided by the guitar generate independent MIDI events; there's no mechanism to only trigger the event when you strum, for instance. This is partly because I have no clue about guitars (I'm a drummer myself), partly because that would probably mean a combinatory explosion in the required mappings, and partly because I feel it goes beyond what Wiimidi should do: Wiimidi is meant as a gateway from the Wii world to the MIDI world. The actual smarts of what to do can (and should) be implemented further down the MIDI pipe, possibly with tools such as Mididings or others.
The syntax for actions is
command/parameter/parameter if several parameters are possible.
Commands can be grouped in several categories. First, MIDI events:
note-on: mandatory parameter is the number of the note; an optional second parameter can override the default channel to send the note on.
noteis a shortcut, and sends the note-on and the note-off events in a row.
- Another shortcut: if the action is only a number, then
pc: program change. The program number is expected as first argument; an optional second argument can specify an explicit channel.
cc: control change. The control number is expected as first argument; an optional second argument can specify an explicit channel. The value of the controller is taken from the input trigger when relevant.
raw: send raw MIDI events. Useful for SysEx events, or those events that don't have a dedicated command here. No validation is made on the bytes, so be careful what you send.
- Not exactly a MIDI event, but
set-channelsets the default channel for further actions.
Then, LED control:
led-on: switch a Wiimote LED (number expected as parameter) on.
led-animate: start a LED animation (see below). Parameter is the name of the animation.
- Several actions can be described in one mapping, using
+as separator. The actions are executed in a row, with no arbitrary delay. For instance,
pc/2 + led-on/2 + led-off/1could be used to send a program change and adjust the LEDs accordingly.
cycle: run the next action in the cycle named in the parameter, see below.
cycle_foo directive describes a cycle named
foo. It's described
as a sequence of actions (possibly compound actions) separated with
;. The number of semicolon-separated components is the length of
the cycle. Each time the cycle is called (with an action such as
cycle/foo, the actions in the corresponding step are called, and the
step is pushed forward by one, unless the end of the cycle has been
reached and we loop back to the beginning.
A two-step cycle can be used as a toggle/flip-flop: a possible use
cycle_playpause = pc/10 + led-on/2 ; pc/11 + led-off/2
(note compound steps). The first time the cycle is called, a
program-change/10 event is sent, and the second LED is switched on.
The next time, program-change/11 and the LED is switched off.
A one-step cycle can be used as a macro: for readability, you may want
to define a
cycle_ledsoff = led-off/1 + led-off/2 + led-off/3 +
ledanimation_foo directive describes a LED animation that can be
triggered to give visual feedback on some actions. The syntax is a
simple semicolon-separated list of the set of LEDs that should be on
at a particular step. Flashing all LEDs twice would be
ledanimation_flashtwice = 1234;0;1234;0 (the zeroes are optional and
only mentioned for readability). A sweep would be defined as
ledanimation_sweep = 1;12;123;1234;234;34;4;0, and would be invoked
by an action with
Note that LED animations are asynchronous, and further actions do not wait for the animation to complete. As a consequence, if two animations overlap in time because the second one was started before the first one was finished, then you'll see interesting flashing things.
Tell me about it
Patches welcome, of course! Also, I'll be interested to hear about your applications. I use it alternately to add extra pads to my electronic drumkit and to control my music player when practicing. I've already been told about a Wiimote-powered foot controller. If you do a Wiimote-controlled robot dinosaur (with lasers), please tell me!
Possible improvements to Wiimidi include:
- Some kind of GUI to help with customisation/configuration.
- Handling of the accelerometers in the Wiimote and nunchuck, probably mapped to Control Change messages (to act as an expression pedal, or a pitch-bend wheel).
- More comprehensive handling of attached devices, such as the “Taiko no Tatsujin” taiko drum controller, or the “balance board” for more convenient expression pedals. This may take some time, because I don't have the necessary hardware at hand (hint, hint).