paulscode.sound

Class MidiChannel

java.lang.Object

paulscode.sound.MidiChannel

All Implemented Interfaces:

EventListener, MetaEventListener

public class MidiChannel
extends Object
implements MetaEventListener

The MidiChannel class provides an interface for playing MIDI files, using the JavaSound API. For more information about the JavaSound API, visit http://java.sun.com/products/java-media/sound/

SoundSystem License:

You are free to use this library for any purpose, commercial or otherwise. You may modify this library or source code, and distribute it any way you like, provided the following conditions are met:
1) You may not falsely claim to be the author of this library or any unmodified portion of it.
2) You may not copyright this library or a modified version of it and then sue me for copyright infringement.
3) If you modify the source code, you must clearly document the changes made before redistributing the modified source code, so other users know it is not the original code.
4) You are not required to give me credit for this library in any derived work, but if you do, you must also mention my website: http://www.paulscode.com
5) I the author will not be responsible for any damages (physical, financial, or otherwise) caused by the use if this library or any part of it.
6) I the author do not guarantee, warrant, or make any representations, either expressed or implied, regarding the use of this library or any part of it.

Author: Paul Lamb
http://www.paulscode.com

Field Summary

Fields

Modifier and Type	Field and Description
protected float	fadeInGain Specifies the gain factor used for the fade-in effect, or 1 when playback is not currently fading in.
protected long	fadeInMilis Specifies the number of miliseconds it should take to fade in.
protected float	fadeOutGain Specifies the gain factor used for the fade-out effect, or -1 when playback is not currently fading out.
protected long	fadeOutMilis Specifies the number of miliseconds it should take to fade out.
protected long	lastFadeCheck System time in miliseconds when the last fade in/out volume check occurred.

Constructor Summary

Constructors

Constructor and Description
MidiChannel(boolean toLoop, String sourcename, FilenameURL midiFilenameURL) Constructor: Defines the basic source information.
MidiChannel(boolean toLoop, String sourcename, String filename) Constructor: Defines the basic source information.
MidiChannel(boolean toLoop, String sourcename, URL midiFile, String identifier) Constructor: Defines the basic source information.

Method Summary

Modifier and Type	Method and Description
void	cleanup() Shuts the channel down and removes references to all instantiated objects.
void	dequeueSound(String filename) Removes the first occurrence of the specified filename/identifier from the list of MIDI sequences to play when the previous sequence ends.
protected boolean	errorCheck(boolean error, String message) Prints the specified message if error is true.
protected void	errorMessage(String message) Prints an error message.
void	fadeOut(FilenameURL filenameURL, long milis) Fades out the volume of whatever sequence is currently playing, then begins playing the specified MIDI file at the previously assigned volume level.
void	fadeOutIn(FilenameURL filenameURL, long milisOut, long milisIn) Fades out the volume of whatever sequence is currently playing, then fades the volume back in playing the specified MIDI file.
String	getFilename() Returns the filename/identifier of the MIDI file being played.
FilenameURL	getFilenameURL() Returns the MIDI file being played.
boolean	getLooping() Returns the value of boolean 'toLoop'.
String	getSourcename() Returns the unique identifier for this source.
float	getVolume() Returns the current volume for the MIDI source.
protected void	importantMessage(String message) Prints an important message.
boolean	loading() Check if a MIDI file is in the process of loading.
protected void	message(String message) Prints a message.
void	meta(MetaMessage message) Called when MIDI events occur.
void	pause() Temporarily stops playback without rewinding.
void	play() Plays the MIDI file from the beginning, or from where it left off if it was paused.
protected void	printStackTrace(Exception e) Prints an exception's error message followed by the stack trace.
void	queueSound(FilenameURL filenameURL) Queues up the next MIDI sequence to play when the previous sequence ends.
void	resetGain() Resets playback volume to the correct level.
void	rewind() Returns playback to the beginning.
void	setFilenameURL(FilenameURL value) Defines which MIDI file to play.
void	setLooping(boolean value) Sets the value of boolean 'toLoop'.
void	setSourcename(String value) Defines the unique identifier for this source
void	setVolume(float value) Changes the volume of MIDI playback.
void	stop() Stops playback and rewinds to the beginning.
void	switchSource(boolean toLoop, String sourcename, FilenameURL filenameURL) Changes the basic information about the MIDI source.
void	switchSource(boolean toLoop, String sourcename, String filename) Changes the basic information about the MIDI source.
void	switchSource(boolean toLoop, String sourcename, URL midiFile, String identifier) Changes the basic information about the MIDI source.

Methods inherited from class java.lang.Object

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

Field Detail

fadeOutGain

protected float fadeOutGain

Specifies the gain factor used for the fade-out effect, or -1 when playback is not currently fading out.

fadeInGain

protected float fadeInGain

Specifies the gain factor used for the fade-in effect, or 1 when playback is not currently fading in.

fadeOutMilis

protected long fadeOutMilis

Specifies the number of miliseconds it should take to fade out.

fadeInMilis

protected long fadeInMilis

Specifies the number of miliseconds it should take to fade in.

lastFadeCheck

protected long lastFadeCheck

System time in miliseconds when the last fade in/out volume check occurred.

Constructor Detail

MidiChannel

public MidiChannel(boolean toLoop,
                   String sourcename,
                   String filename)

Constructor: Defines the basic source information.

Parameters:

toLoop - Should playback loop or play only once?

sourcename - Unique identifier for this source.

filename - Name of the MIDI file to play.

MidiChannel

public MidiChannel(boolean toLoop,
                   String sourcename,
                   URL midiFile,
                   String identifier)

Constructor: Defines the basic source information. The fourth parameter, 'identifier' should look like a filename, and it must have the correct extension (.mid or .midi).

Parameters:

toLoop - Should playback loop or play only once?

sourcename - Unique identifier for this source.

midiFile - URL to the MIDI file to play.

identifier - Filename/identifier for the MIDI file.

MidiChannel

public MidiChannel(boolean toLoop,
                   String sourcename,
                   FilenameURL midiFilenameURL)

Constructor: Defines the basic source information.

Parameters:

toLoop - Should playback loop or play only once?

sourcename - Unique identifier for this source.

midiFilenameURL - Filename/URL to the MIDI file to play.

Method Detail

cleanup

public void cleanup()

Shuts the channel down and removes references to all instantiated objects.

queueSound

public void queueSound(FilenameURL filenameURL)

Queues up the next MIDI sequence to play when the previous sequence ends.

Parameters:

filenameURL - MIDI sequence to play next.

dequeueSound

public void dequeueSound(String filename)

Removes the first occurrence of the specified filename/identifier from the list of MIDI sequences to play when the previous sequence ends.

Parameters:

filename - Filename or identifier of a MIDI sequence to remove from the queue.

fadeOut

public void fadeOut(FilenameURL filenameURL,
                    long milis)

Fades out the volume of whatever sequence is currently playing, then begins playing the specified MIDI file at the previously assigned volume level. If the filenameURL parameter is null or empty, playback will simply fade out and stop. The miliseconds parameter must be non-negative or zero. This method will remove anything that is currently in the list of queued MIDI sequences that would have played next when current playback finished.

Parameters:

filenameURL - MIDI file to play next, or null for none.

milis - Number of miliseconds the fadeout should take.

fadeOutIn

public void fadeOutIn(FilenameURL filenameURL,
                      long milisOut,
                      long milisIn)

Fades out the volume of whatever sequence is currently playing, then fades the volume back in playing the specified MIDI file. Final volume after fade-in completes will be equal to the previously assigned volume level. The filenameURL parameter may not be null or empty. The miliseconds parameters must be non-negative or zero. This method will remove anything that is currently in the list of queued MIDI sequences that would have played next when current playback finished.

Parameters:

filenameURL - MIDI file to play next, or null for none.

milisOut - Number of miliseconds the fadeout should take.

milisIn - Number of miliseconds the fadein should take.

play

public void play()

Plays the MIDI file from the beginning, or from where it left off if it was paused.

stop

public void stop()

Stops playback and rewinds to the beginning.

pause

public void pause()

Temporarily stops playback without rewinding.

rewind

public void rewind()

Returns playback to the beginning.

setVolume

public void setVolume(float value)

Changes the volume of MIDI playback.

Parameters:

value - Float value (0.0f - 1.0f).

getVolume

public float getVolume()

Returns the current volume for the MIDI source.

Returns:

Float value (0.0f - 1.0f).

switchSource

public void switchSource(boolean toLoop,
                         String sourcename,
                         String filename)

Changes the basic information about the MIDI source. This method removes any queued filenames/URLs from the list of MIDI sequences that would have played after the current sequence ended.

Parameters:

toLoop - Should playback loop or play only once?

sourcename - Unique identifier for this source.

filename - Name of the MIDI file to play.

switchSource

public void switchSource(boolean toLoop,
                         String sourcename,
                         URL midiFile,
                         String identifier)

Changes the basic information about the MIDI source. This method removes any queued filenames/URLs from the list of MIDI sequences that would have played after the current sequence ended. The fourth parameter, 'identifier' should look like a filename, and it must have the correct extension (.mid or .midi).

Parameters:

toLoop - Should playback loop or play only once?

sourcename - Unique identifier for this source.

midiFile - URL to the MIDI file to play.

identifier - Filename/identifier for the MIDI file.

switchSource

public void switchSource(boolean toLoop,
                         String sourcename,
                         FilenameURL filenameURL)

Changes the basic information about the MIDI source. This method removes any queued filenames/URLs from the list of MIDI sequences that would have played after the current sequence ended.

Parameters:

toLoop - Should playback loop or play only once?

sourcename - Unique identifier for this source.

filenameURL - Filename/URL of the MIDI file to play.

setLooping

public void setLooping(boolean value)

Sets the value of boolean 'toLoop'.

Parameters:

value - True or False.

getLooping

public boolean getLooping()

Returns the value of boolean 'toLoop'.

Returns:

True while looping.

loading

public boolean loading()

Check if a MIDI file is in the process of loading.

setSourcename

public void setSourcename(String value)

Defines the unique identifier for this source

Parameters:

value - New source name.

getSourcename

public String getSourcename()

Returns the unique identifier for this source.

Returns:

The source's name.

setFilenameURL

public void setFilenameURL(FilenameURL value)

Defines which MIDI file to play.

Parameters:

value - Path to the MIDI file.

getFilename

public String getFilename()

Returns the filename/identifier of the MIDI file being played.

Returns:

Filename of identifier of the MIDI file.

getFilenameURL

public FilenameURL getFilenameURL()

Returns the MIDI file being played.

Returns:

Filename/URL of the MIDI file.

meta

public void meta(MetaMessage message)

Called when MIDI events occur.

Specified by:

meta in interface MetaEventListener

Parameters:

message - Meta mssage describing the MIDI event.

resetGain

public void resetGain()

Resets playback volume to the correct level.

message

protected void message(String message)

Prints a message.

Parameters:

message - Message to print.

importantMessage

protected void importantMessage(String message)

Prints an important message.

Parameters:

message - Message to print.

errorCheck

protected boolean errorCheck(boolean error,
                             String message)

Prints the specified message if error is true.

Parameters:

error - True or False.

message - Message to print if error is true.

Returns:

True if error is true.

errorMessage

protected void errorMessage(String message)

Prints an error message.

Parameters:

message - Message to print.

printStackTrace

protected void printStackTrace(Exception e)

Prints an exception's error message followed by the stack trace.

Parameters:

e - Exception containing the information to print.