[WUSUM] - [W]hy [U]se [S]amples, [U]se [M]IDI !

[ W.U.S.U.M. ]

WUSUM is a Java library designed for the Processing environment.

It allows for real-time MIDI communication.

[W]hy [U]se [S]amples, [U]se [M]IDI !

Introduction

Projects using WUSUM

WUSUM helps you use the MIDI features of Java in simple and effective way.

The current implementation only supports ShortMessage MIDI messages, allowing you
for some freedom, but inhibiting some interesting functions.

The main idea is that with this library you can use the GeneralMidi synthesizer
that is built in yur soundcard, and/or send MIDI messages to other devices you have
connected to your PC (MIDI controllers, keyboards, VJ devices, for example: anything
that accepts a MIDI control signal).

This library is designed for the Processing Environment (http://www.processing.org).
With minor modifications it can be used in any Java environment.

The code is free, available and, well, here it is, inckuded in the ZIP.
Sorry for my bad undercover coding, bad variable names, awful constructs, CPU-hungry
loops and threads... well, sorry for anything you don't find useful :)

Bug reports, ideas on how to fix them and help in upgrading/updating/fixing this
library are MORE than welcome!

See the included MAIN method in the source for non-Processing usage, and the html
Reference for detailed documentation and software usage examples.

For all other info: http://www.artisopensource.net/wusum
For questions, rants and chats: salvatore.iaconesi@artisopensource.net

For everyting else: http://www.artisopensource.net/

Oo.[ [ concertoPer16Automi ]
Oo.[ [ GoM ]

Download & Installation

[ WUSUM_dist_0.1.zip ]

Unzips to a folder.
Take the directory [WUSUM] and place it in your Processing [libraries] directory.
Restart Processing.

Reference

public class WUSUM

It is the class through which you handle the MIDI system.
You construct it like this:

>>public WUSUM(PApplet parent, int howManyChannels)

In the constructor you specify the Processing applet hosting WUSUM (you will use this in most cases) and the number of WUSUM channels to be used.

Each WUSUM channel is a thread handling a queue of events. Each queue can handle several MIDI channels. You can see WUSUM channels as a way to handle correctly parallel sources of MIDI events.

These are the fields usable from the WUSUM class:

>>PApplet parent;
The Processing applet hosting us

>>public SoundThread[] soundThreads;
WUSUM uses threads to handle realtime MIDi communication.
When you setup WUSUM you state how many threads you wish to use

>>public TreeSet[] soundTrees;
These cumbersome Structures are used to hold the MIDI data queues

>>public javax.sound.midi.Synthesizer synth;
The Java MIDI synthesizer

>>public Receiver synthReceiver;
The Java MIDI Receiver, used to handle MIDI communication

>>public int howManyChannels;
This tells you how many channels you're using
It's the same size as the soudThreads array

These are the methods usable from the WUSUM class:

>>public WUSUM(PApplet parent, int howManyChannels)
Constructor
param parent is the link to the hosting Processing applet
param howManyChannels tells how many channels you would like to use

>>public void dispose()
function called by Processing toclean everything up when shutting down

>>public void stop()
can be called to shut down MIDI system programmatically

>>public void addEvent(WUSUM.SoundEvent se, int ch )
method used to add MIDI events to a specified WUSUM channel
It is interesting to note that WUSUM channels are a different from MIDI channels
WUSUM channels represent the threads used for MIDI communication
while a MIDI channel is a physical channel on which this communication happens.
You can think of WUSUM channels as a way to perform tasks simultaneously, as
concurrent queues that you can use to perform MIDI task.
The SoundEvents in a single WUSUM channel can concern several different MIDI channels
@param ch is the WUSUM channel this event is going to be put into
@param se is the event

>>public WUSUM.SoundEvent getPANEvent(int midiChannel, int value, long tStamp, long waitAfter )
Generate a PAN event
@param midiChannel is the MIDI channel where the event will take place
@param value is the pan value [0..127]
@parm tStamp is the timestamp: it is not necessarily a REAL timestamp, as it is used to order events
@parm waitAfter is the time to wait on the WUSUM channel hosting the event, after this event has been fired

>>public WUSUM.SoundEvent getINSTRUMENT_CHANGEEvent(int midiChannel, int instrument, long tStamp, long waitAfter )
Generate a POGRAM_CHANGE event, to change instrument
@param midiChannel is the MIDI channel where the event will take place
@param instrument is the instrument number [0..127] [TODO: supports only bank 1. include support for other MIDI banks]
@parm tStamp is the timestamp: it is not necessarily a REAL timestamp, as it is used to order events
@parm waitAfter is the time to wait on the WUSUM channel hosting the event, after this event has been fired

>>public WUSUM.SoundEvent getNOTE_ONEvent(int midiChannel, int note, int velocity, long tStamp, long waitAfter )
Generate a NOTE_ON event
@param midiChannel is the MIDI channel where the event will take place
@param note is the note to be played [0..127]
@param velocity is the velocity at which the note shall be played [0..127]
@parm tStamp is the timestamp: it is not necessarily a REAL timestamp, as it is used to order events
@parm waitAfter is the time to wait on the WUSUM channel hosting the event, after this event has been fired

>>public WUSUM.SoundEvent getNOTE_OFFEvent(int midiChannel, int note, int velocity, long tStamp, long waitAfter )
Generate a NOTE_OFF event
@param midiChannel is the MIDI channel where the event will take place
@param note not used [0..127]
@param velocity not used [0..127]
@parm tStamp is the timestamp: it is not necessarily a REAL timestamp, as it is used to order events
@parm waitAfter is the time to wait on the WUSUM channel hosting the event, after this event has been fired

public class SoundThread extends Thread

The SoundThread is an extended Thread taking care of handling the MIDI communication
Threaded technology has been chosen to provide for an asynchronous MIDI communication
which is fundamental for realtime
The threads are constructed automtically at WUSUM startup.

These are the fields usable from the SoundThread class:

>>public int channel;
This is the WUSUM channel

>>public WUSUM parent;
This is the WUSUM host

>>public boolean alive;
This tells if the WUSUM channel is alive

These are the methods usable from the SoundThread class:

>>public SoundThread(int ch,WUSUM parent)
Constructor
@param ch is the WUSUM channel number
@param WUSUM is the WUSUM host

>>public void run()
This is the main thread cycle

public class SoundEvent implements Comparable

This is a WUSUM sound event

These are the fields usable from the SoundThread class:

>>public ShortMessage message;
is the MIDI message to be sent

>>public long timeStamp;
A timestamp. Not necessarily a real timestamp, as the system will use it to order the events.

>>public long waitAfter;
is the milliseconds to wait, on the WUSUM channel, after this event has been fired

>>public double calmness;
I had an idea about this, but it is currently not used :)

These are the methods usable from the SoundThread class:

>>public SoundEvent(ShortMessage msg , long t, long w, double c)
Constructor
@param msg is the MIDI message to be sent
@param t is the timestamp. It needs not be a REAL timestamp, as it is used only to order events
@param w is the milliseconds to wait, on the WUSUM channel, after this event has been fired
@param calmness I had an idea about this, but it is currently not used :)

>>public boolean equals(Object obj)
Used for the Java Comparator interface

>>public int compareTo(Object o)
Used for the Java Comparator interface

StepByStep example :)

Here we will go through some lines of code :)

Let's say you want to play some notes on the internal MIDI synthesizer.

You first setup WUSUM for 1 channel from inside your Processing sketch:

WUSUM wusum = new WUSUM(this, 1);

Then you prepare the values which you'll use for the note to be played:

// try 9 as a midi channel to use the percussions
int midiChannel = 0;

// enter pan
int pan = 64;

//beginning of time
long timestamp = 0;

// 100 msec long
long waitAfter = 100;

// use intrument 120 (I DON't know what it is)
int instrument = 120;

// note 50: lookup these and other values at http://www.midi.org
int note = 50;

// high velocity
int velocity = 100;

Then prepare the events:

SoundEvent se = wusum.getPANEvent(midiCh, pan, timestamp, waitAfter );
wusum.addEvent(se,0);

timestamp++;
se = wusum.getINSTRUMENT_CHANGEEvent(midiCh, instrument, timestamp, waitAfter );
wusum.addEvent(se,0);

timestamp++;
se = wusum.getNOTE_ONEvent(midiCh, note, velocity, timestamp, waitAfter );
wusum.addEvent(se,0);

timestamp++;
se = wusum.getNOTE_OFFEvent(midiCh, note, velocity, timestamp, waitAfter );
wusum.addEvent(se,0);

Just repeat commands to perform other notes.
Make sure to have a NOTE_OFF event for each NOTE_ON you issue, otherwise you'll have hanging notes.
That might be a desirable effect, too.

[<< back to AOS]