Package org.jjazz.musiccontrol.api

Class MusicController

java.lang.Object
org.jjazz.musiccontrol.api.MusicController
All Implemented Interfaces:
PropertyChangeListener, EventListener, MetaEventListener
public class MusicController extends Object implements PropertyChangeListener, MetaEventListener
Control the music playback of a PlaybackSession.

The PlaybackSession provides the Sequence to be played and various related data which impact how the MusicController manage the Sequence.

Property changes are fired for:
- start/pause/stop/disabled state changes

Use NoteListener to get notified of note ON/OFF events. Use PlaybackListener to get notified of other events (e.g. bar/beat changes) during playback. Note that listeners will be notified out of the Swing EDT.
The current output synth latency is taken into account to fire events to NoteListeners and PlaybackListeners.

Use acquireSequencer()/releaseSequencer() if you want to use the Java system sequencer independently.

  • Field Details

  • Method Details

    • getInstance

      public static MusicController getInstance()

    • acquireSequencer

      public Sequencer acquireSequencer(Object lockHolder)
      Try to temporarily acquire the java sequencer opened and connected to the default Midi out device.

      You can acquire the sequencer only if MusicController is in the STOPPED state. If acquisition is successful the MusicController is put in DISABLED state since it can't use the sequencer anymore. When the caller is done with the sequencer, he must call releaseSequencer(lockHolder) so that the MusicController can use it again.

      Parameters:
      lockHolder - Must be non-null
      Returns:
      Null if sequencer has already a different lock or if MusicController is in the PLAYING state.

    • releaseSequencer

      public void releaseSequencer(Object lockHolder)
      Release the external sequencer lock.

      Once released, MusicController becomes able to take the Sequencer lock when playing music.

      Parameters:
      lockHolder -
      Throws:
      IllegalArgumentException - If lockHolder does not match

    • setPlaybackSession

      public void setPlaybackSession(PlaybackSession session, boolean silent) throws MusicGenerationException
      Set the current playback session and try to generate the sequence if required.

      If MusicController is paused then current playback is stopped.

      Parameters:
      session - Can be null. If not null, must be in NEW or GENERATED state, and can't be dirty.
      silent - If false and session needs to be generated, a progress dialog is shown while generating music
      Throws:
      MusicGenerationException - E.g. if song is already playing, missing start section chord, etc.
      IllegalStateException - If session is dirty or is CLOSED.
      See Also:

    • play

      public void play(int fromBarIndex) throws MusicGenerationException
      Play the current playback session from the specified bar.

      Do nothing if no playback session set.

      Parameters:
      fromBarIndex -
      Throws:
      MusicGenerationException - If a problem occurred which prevents song playing: no Midi out, rhythm music generation problem, MusicController state is not PAUSED nor STOPPED, etc.
      IllegalStateException - If current session is not in the GENERATED state, or if fromBarIndex is invalid

    • resume

      public void resume() throws MusicGenerationException
      Resume playback from the pause state.

      If state is not PAUSED, nothing is done.

      Throws:
      MusicGenerationException - For example if state==DISABLED
      IllegalStateException - If current playback session is not in the GENERATED state.

    • stop

      public void stop()
      Stop the playback of the sequence if it was playing, and reset the position to the beginning of the sequence.

    • pause

      public void pause()
      Stop the playback of the sequence and leave the position unchanged.

      If state is not PLAYING, do nothing. If session is dirty, use stop() instead.

    • changePausedBar

      public void changePausedBar(int barIndex)
      Change the current bar when in PAUSED state.

      Do nothing if not in PAUSED state.

      Parameters:
      barIndex -
      Throws:
      IllegalArgumentException - If bar index is not valid for the current PlaybackSession.

    • getCurrentBeatPosition

      public Position getCurrentBeatPosition()
      The current playback position updated at every natural beat (eg 0, 1, 2, 3 in 4/4).

      Note: value is meaningful only for PlaybackSessions which are also ControlTrackProviders. Otherwise returned value is always bar=0, beat=0.

      Returns:
      See Also:

    • getCurrentChordSymbol

      public CLI_ChordSymbol getCurrentChordSymbol()
      The current CLI_ChordSymbol being played.

      Note: value is meaningful only when playback is on or paused, and for PlaybackSessions which are also ControlTrackProviders. Otherwise return value is null.

      Returns:
      Can be null.
      See Also:

    • getCurrentSongPart

      public SongPart getCurrentSongPart()
      The current SongPart being played.

      Note: value is meaningful only when playback is on or paused, and for PlaybackSessions which are also ControlTrackProviders and SongContextProviders. Otherwise return value is null.

      Returns:
      Can be null.
      See Also:

    • getState

      public MusicController.State getState()

    • getPlaybackSession

      public PlaybackSession getPlaybackSession()
      Get the current playback session.
      Returns:
      Can be null if no song has ever been played.

    • isArrangerPlaying

      public boolean isArrangerPlaying()
      True if the current playing session is a special arranger session.
      Returns:

    • setDebugPlayedSequence

      public void setDebugPlayedSequence(boolean b)

    • isDebugPlayedSequence

      public boolean isDebugPlayedSequence()

    • addNoteListener

      public void addNoteListener(NoteListener listener)
      Add a listener of note ON/OFF events.

      Listeners will be called out of the Swing EDT (Event Dispatch Thread).

      Parameters:
      listener -

    • removeNoteListener

      public void removeNoteListener(NoteListener listener)

    • addPlaybackListener

      public void addPlaybackListener(PlaybackListener listener)
      Add a listener to be notified of playback bar/beat changes events etc.

      Listeners will be called out of the Swing EDT (Event Dispatch Thread).

      Parameters:
      listener -

    • removePlaybackListener

      public void removePlaybackListener(PlaybackListener listener)

    • addPropertyChangeListener

      public void addPropertyChangeListener(PropertyChangeListener listener)

    • removePropertyChangeListener

      public void removePropertyChangeListener(PropertyChangeListener listener)

    • meta

      public void meta(MetaMessage meta)
      Specified by:
      meta in interface MetaEventListener

    • propertyChange

      public void propertyChange(PropertyChangeEvent e)
      Specified by:
      propertyChange in interface PropertyChangeListener