edu.uiuc.cs397rhc.sound
Class MidiFilter

java.lang.Object
  edu.uiuc.cs397rhc.sound.MidiFilter

All Implemented Interfaces:

javax.sound.midi.Receiver, javax.sound.midi.Transmitter

Direct Known Subclasses:

ConditionalMidiFilter, InspectorFilter, InstrumentationFilter, VolumeFilter

public abstract class MidiFilter

extends java.lang.Object

implements javax.sound.midi.Receiver, javax.sound.midi.Transmitter

MidiFilters are used to programmatically modify MIDI events in real-time. They do this by serving as both a Receiver and a Trasnmitter, thereby allowing them to be placed between any other Receivers and Transmitters. Filters then monitor transmitted MidiMessages and their timestamps and, when these meet certain conditions, consume them and emit their own MidiMessages and timestamps instead. The result is a programmatic change to the MidiMessage stream. MidiFilters can also be concatennated to achieve even more complex effects.

Author:

Pedro DeRose

Constructor Summary

MidiFilter()
Default constructor with no Receiver.

MidiFilter(javax.sound.midi.Receiver receiver)
Default constructor for a given Receiver.

Method Summary

abstract javax.sound.midi.MidiEvent[]	applyFilter(javax.sound.midi.MidiMessage msg, long time) Returns the MidiEvents whose MidiMessages and timestamps should be sent instead of the given message and timestamp when the filter applies.
void	close()
protected long	getMicrosecondPosition() Returns the microsecond position of the associated sequencer if one has been set.
javax.sound.midi.Receiver	getReceiver()
javax.sound.midi.Sequencer	getSequencer() Gets the sequencer from which the microsecond position are taken if the send method is called with timestamps of -1.
boolean	isApplicable(javax.sound.midi.MidiMessage msg, long time) Determines whether this MidiFilter applies to the given MidiMessage and timestamp.
void	send(javax.sound.midi.MidiMessage msg, long time) This method is called by the Transmitter connected to this MidiFilter.
void	setReceiver(javax.sound.midi.Receiver receiver)
void	setSequencer(javax.sound.midi.Sequencer sequencer) Sets the sequencer from which the microsecond position are taken if the send method is called with timestamps of -1.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MidiFilter

public MidiFilter()

Default constructor with no Receiver.

MidiFilter

public MidiFilter(javax.sound.midi.Receiver receiver)

Default constructor for a given Receiver.

Parameters:

receiver - the Recever to which MidiMessages and timestamps should be sent

Method Detail

send

public void send(javax.sound.midi.MidiMessage msg,
                 long time)

This method is called by the Transmitter connected to this MidiFilter. If the given timestamp is -1, it will first retrieve the microsecond position of the associated sequencer if possible and assign that to the timestamp. It will then call isApplicable() to determine if this MidiFilter applies to this MidiMessage and timestamp. If not, the message and timestamp are passed to the receiver. Otherwise, the message and timestamp are consumed, and those returned by applyFilter are transmitted instead.

Specified by:

send in interface javax.sound.midi.Receiver

Parameters:

msg - the message

time - the timestamp

setSequencer

public void setSequencer(javax.sound.midi.Sequencer sequencer)

Sets the sequencer from which the microsecond position are taken if the send method is called with timestamps of -1.

Parameters:

sequencer - the sequencer from which microsecond positions are taken

getSequencer

public javax.sound.midi.Sequencer getSequencer()

Gets the sequencer from which the microsecond position are taken if the send method is called with timestamps of -1.

Returns:

the sequencer from which microsecond positions are taken

getMicrosecondPosition

protected long getMicrosecondPosition()

Returns the microsecond position of the associated sequencer if one has been set.

Returns:

the microsecond position of the associated sequencer if one has been set, -1 otherwise

setReceiver

public void setReceiver(javax.sound.midi.Receiver receiver)

Specified by:

setReceiver in interface javax.sound.midi.Transmitter

getReceiver

public javax.sound.midi.Receiver getReceiver()

Specified by:

getReceiver in interface javax.sound.midi.Transmitter

isApplicable

public boolean isApplicable(javax.sound.midi.MidiMessage msg,
                            long time)

Determines whether this MidiFilter applies to the given MidiMessage and timestamp. This is called by send(), with the timestamp replaced by the microsecond position of the associated sequencer if the original timestamp was -1 and a sequencer has been specified.

Parameters:

msg - the message

time - the timestamp

Returns:

true if this MidiFilter applies to the given message and timestamp, false otherwise

applyFilter

public abstract javax.sound.midi.MidiEvent[] applyFilter(javax.sound.midi.MidiMessage msg,
                                                         long time)

Returns the MidiEvents whose MidiMessages and timestamps should be sent instead of the given message and timestamp when the filter applies. When called by send(), this method will only be caleld if isApplicable() returns true.

Parameters:

msg - the message

time - the timestamp

Returns:

an array of MidiEvents whose MidiMessages and timestamps should be sent instead of the given message and timestamp

close

public void close()

Specified by:

close in interface javax.sound.midi.Receiver