org.jfugue
Class Player

java.lang.Object
  extended by org.jfugue.Player

public class Player
extends java.lang.Object

Prepares a pattern to be turned into music by the Renderer. This class also handles saving the sequence derived from a pattern as a MIDI file.

Version:
2.0
Author:
David Koelle
See Also:
MidiRenderer, Pattern

Constructor Summary
Player()
          Instantiates a new Player object, which is used for playing music.
Player(boolean connected)
          Instantiates a new Player object, which is used for playing music.
Player(javax.sound.midi.Sequencer sequencer)
          Creates a new Player instance using a Sequencer that you have provided.
Player(javax.sound.midi.Synthesizer synth)
          Creates a new Player instance using a Sequencer obtained from the Synthesizer that you have provided.
 
Method Summary
static void allNotesOff()
           
static void allNotesOff(javax.sound.midi.Synthesizer synth)
          Stops all notes from playing on all MIDI channels.
 void close()
          Closes MIDI resources - be sure to call this after play() has returned.
 javax.sound.midi.Sequence getSequence(Pattern pattern)
          Returns the sequence containing the MIDI data from the given pattern.
 long getSequenceLength(javax.sound.midi.Sequence sequence)
           
 long getSequencePosition()
           
 javax.sound.midi.Sequencer getSequencer()
          Returns the sequencer containing the MIDI data from a pattern that has been parsed.
static javax.sound.midi.Sequencer getSequencerConnectedToSynthesizer(javax.sound.midi.Synthesizer synth)
          Returns an instance of a Sequencer that uses the provided Synthesizer as its receiver.
 boolean isFinished()
           
 boolean isPaused()
           
 boolean isPlaying()
           
 boolean isStarted()
           
 void jumpTo(long microseconds)
           
 Pattern loadMidi(java.io.File file)
          Parses a MIDI file and returns a Pattern.
 void pause()
           
 void play(Anticipator anticipator, Pattern pattern, long offset)
           
 void play(Anticipator anticipator, javax.sound.midi.Sequence sequence, javax.sound.midi.Sequence sequence2, long offset)
           
 void play(Pattern pattern)
          Plays a pattern by setting up a Renderer and feeding the pattern to it.
 void play(Rhythm rhythm)
          Plays a pattern by setting up a Renderer and feeding the pattern to it.
 void play(java.lang.String musicString)
          Plays a string of music.
 void playMidiDirectly(java.io.File file)
          Plays a MIDI file, without doing any conversions to MusicStrings.
 void playMidiDirectly(java.net.URL url)
          Plays a URL that contains a MIDI sequence.
 void resume()
           
 void saveMidi(Pattern pattern, java.io.File file)
          Saves the MIDI data from a pattern into a file.
 void saveMidi(java.lang.String musicString, java.io.File file)
          Saves the MIDI data from a MusicString into a file.
 void stop()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Player

public Player()
Instantiates a new Player object, which is used for playing music.


Player

public Player(boolean connected)
Instantiates a new Player object, which is used for playing music. The connected parameter is passed directly to MidiSystem.getSequencer. Pass false when you do not want to copy a live synthesizer - for example, if your Player is on a server, and you don't want to create new synthesizers every time the constructor is called.


Player

public Player(javax.sound.midi.Sequencer sequencer)
Creates a new Player instance using a Sequencer that you have provided.

Parameters:
sequencer - The Sequencer to send the MIDI events

Player

public Player(javax.sound.midi.Synthesizer synth)
       throws javax.sound.midi.MidiUnavailableException
Creates a new Player instance using a Sequencer obtained from the Synthesizer that you have provided.

Parameters:
synth - The Synthesizer you want to use for this Player.
Throws:
javax.sound.midi.MidiUnavailableException
Method Detail

play

public void play(Pattern pattern)
Plays a pattern by setting up a Renderer and feeding the pattern to it.

Parameters:
pattern - the pattern to play
See Also:
MidiRenderer

play

public void play(Rhythm rhythm)
Plays a pattern by setting up a Renderer and feeding the pattern to it.

Parameters:
pattern - the pattern to play
See Also:
MidiRenderer

play

public void play(java.lang.String musicString)
Plays a string of music. Be sure to call player.close() after play() has returned.

Parameters:
musicString - the MusicString (JFugue-formatted string) to play

playMidiDirectly

public void playMidiDirectly(java.io.File file)
                      throws java.io.IOException,
                             javax.sound.midi.InvalidMidiDataException
Plays a MIDI file, without doing any conversions to MusicStrings. Be sure to call player.close() after play() has returned.

Parameters:
file - the MIDI file to play
Throws:
java.io.IOException
javax.sound.midi.InvalidMidiDataException

playMidiDirectly

public void playMidiDirectly(java.net.URL url)
                      throws java.io.IOException,
                             javax.sound.midi.InvalidMidiDataException
Plays a URL that contains a MIDI sequence. Be sure to call player.close() after play() has returned.

Parameters:
url - the URL to play
Throws:
java.io.IOException
javax.sound.midi.InvalidMidiDataException

play

public void play(Anticipator anticipator,
                 Pattern pattern,
                 long offset)

play

public void play(Anticipator anticipator,
                 javax.sound.midi.Sequence sequence,
                 javax.sound.midi.Sequence sequence2,
                 long offset)

close

public void close()
Closes MIDI resources - be sure to call this after play() has returned.


isStarted

public boolean isStarted()

isFinished

public boolean isFinished()

isPlaying

public boolean isPlaying()

isPaused

public boolean isPaused()

pause

public void pause()

resume

public void resume()

stop

public void stop()

jumpTo

public void jumpTo(long microseconds)

getSequenceLength

public long getSequenceLength(javax.sound.midi.Sequence sequence)

getSequencePosition

public long getSequencePosition()

saveMidi

public void saveMidi(Pattern pattern,
                     java.io.File file)
              throws java.io.IOException
Saves the MIDI data from a pattern into a file.

Parameters:
pattern - the pattern to save
file - the File to save the pattern to. Should include file extension, such as .mid
Throws:
java.io.IOException

saveMidi

public void saveMidi(java.lang.String musicString,
                     java.io.File file)
              throws java.io.IOException
Saves the MIDI data from a MusicString into a file.

Parameters:
musicString - the MusicString to save
file - the File to save the MusicString to. Should include file extension, such as .mid
Throws:
java.io.IOException

loadMidi

public Pattern loadMidi(java.io.File file)
                 throws java.io.IOException,
                        javax.sound.midi.InvalidMidiDataException
Parses a MIDI file and returns a Pattern. This is an excellent example of JFugue's Parser-Renderer architecture:
  MidiParser parser = new MidiParser();
  MusicStringRenderer renderer = new MusicStringRenderer();
  parser.addParserListener(renderer);
  parser.parse(sequence);
 

Parameters:
filename - The name of the MIDI file
Returns:
a Pattern containing the MusicString representing the MIDI music
Throws:
java.io.IOException - If there is a problem opening the MIDI file
javax.sound.midi.InvalidMidiDataException - If there is a problem obtaining MIDI resources

allNotesOff

public static void allNotesOff()

allNotesOff

public static void allNotesOff(javax.sound.midi.Synthesizer synth)
Stops all notes from playing on all MIDI channels.


getSequencer

public javax.sound.midi.Sequencer getSequencer()
Returns the sequencer containing the MIDI data from a pattern that has been parsed.

Returns:
the Sequencer from the pattern that was recently parsed

getSequence

public javax.sound.midi.Sequence getSequence(Pattern pattern)
Returns the sequence containing the MIDI data from the given pattern.

Returns:
the Sequence from the given pattern

getSequencerConnectedToSynthesizer

public static javax.sound.midi.Sequencer getSequencerConnectedToSynthesizer(javax.sound.midi.Synthesizer synth)
                                                                     throws javax.sound.midi.MidiUnavailableException
Returns an instance of a Sequencer that uses the provided Synthesizer as its receiver. This is useful when you have made changes to a specific Synthesizer--for example, you've loaded in new patches--that you want the Sequencer to use. You can then pass the Sequencer to the Player constructor.

Parameters:
synth - The Synthesizer to use as the receiver for the returned Sequencer
Returns:
a Sequencer with the provided Synthesizer as its receiver
Throws:
javax.sound.midi.MidiUnavailableException