Package org.jjazz.musiccontrol.api.playbacksession

Class UpdateProviderSongSession

java.lang.Object
org.jjazz.musiccontrol.api.playbacksession.BaseSongSession
org.jjazz.musiccontrol.api.playbacksession.UpdateProviderSongSession
All Implemented Interfaces:
PropertyChangeListener, EventListener, ControlTrackProvider, EndOfPlaybackActionProvider, PlaybackSession, SongContextProvider, UpdatableSongSession.UpdateProvider
public class UpdateProviderSongSession extends BaseSongSession implements UpdatableSongSession.UpdateProvider
A session to be used as a BaseSongSession for an UpdatableSongSession.

The session provides on-the-fly UpdatableSongSession.Updates for:
- chord symbol changes (add/remove/change/moveAll)
- rhythm parameter value changes
- existing user phrase content changes (but not for add/remove user phrase events)
- PlaybackSettings playback transposition changes
- MidiMix instrument transposition/velocity changes, plus drum keymap and drum rerouting changes

If change can't be handled as an update (eg a song part tempo factor change or a click setting), session is marked dirty (ie needs regeneration). If session is dirty, editors can still show the playback point using the control track but the "dirty" changes are not heard.

A more serious change like a structural change of the song context will make the session dirty, plus it disables the control track and any future update. So editors should stop showing the playback point, and any further change will not be heard (until a new session is generated).

  • Field Details

  • Method Details

    • getSession

      public static UpdateProviderSongSession getSession(SongContext sgContext, boolean enablePlaybackTransposition, boolean includeClickTrack, boolean includePrecountTrack, boolean includeControlTrack, boolean enableUpdateControl, int loopCount, ActionListener endOfPlaybackAction)
      Create or reuse a session for the specified parameters.

      Sessions are cached: if a non-dirty session in the NEW or GENERATED state already exists for the same parameters then return it, otherwise a new session is created.

      Parameters:
      sgContext -
      enablePlaybackTransposition - If true apply the playback transposition
      includeClickTrack - If true add the click track, and its muted/unmuted state will depend on the PlaybackSettings
      includePrecountTrack - If true add the precount track, and loopStartTick will depend on the PlaybackSettings
      includeControlTrack - if true add a control track (beat positions + chord symbol markers)
      enableUpdateControl - If true updates are authorized depending on the PlaybackSettings AutoUpdateEnabled value.
      loopCount - See Sequencer.setLoopCount(). Use PLAYBACK_SETTINGS_LOOP_COUNT to rely on the PlaybackSettings instance value.
      endOfPlaybackAction - Action executed when playback is stopped. Can be null.
      Returns:
      A session in the NEW or GENERATED state.

    • getSession

      public static UpdateProviderSongSession getSession(SongContext sgContext)
      Same as getSession(sgContext, true, true, true, true, true, PLAYBACK_SETTINGS_LOOP_COUNT, null);

      Parameters:
      sgContext -
      Returns:
      A targetSession in the NEW or GENERATED state.

    • getFreshCopy

      public UpdateProviderSongSession getFreshCopy(SongContext sgContext)
      Description copied from interface: PlaybackSession
      Get a copy of this session in the NEW state for the specified context.
      Specified by:
      getFreshCopy in interface PlaybackSession
      Overrides:
      getFreshCopy in class BaseSongSession
      Parameters:
      sgContext - If null use a copy of this session'SongContext
      Returns:

    • generate

      public void generate(boolean silent) throws MusicGenerationException
      Generate the initial music then listen for song changes to be ready to generate updates.
      Specified by:
      generate in interface PlaybackSession
      Overrides:
      generate in class BaseSongSession
      Parameters:
      silent -
      Throws:
      MusicGenerationException

    • close

      public void close()
      Description copied from interface: PlaybackSession
      Put session in the CLOSED state and release used resources, so that session can be disposed.
      Specified by:
      close in interface PlaybackSession
      Overrides:
      close in class BaseSongSession
      See Also:

    • isUpdateControlEnabled

      public boolean isUpdateControlEnabled()
      True if updates are authorized/blocked depending on the PlaybackSettings auto update value.
      Returns:

    • getPreUpdateBufferTimeMs

      public int getPreUpdateBufferTimeMs()
      Wait time before starting the music generation to provide an update.
      Returns:
      See Also:

    • setPreUpdateBufferTimeMs

      public void setPreUpdateBufferTimeMs(int preUpdateBufferTimeMs)
      Calls to this method are ignored if state is not NEW.
      Parameters:
      preUpdateBufferTimeMs -

    • getPostUpdateSleepTimeMs

      public int getPostUpdateSleepTimeMs()
      Wait time after having generated an update.
      Returns:
      See Also:

    • setPostUpdateSleepTimeMs

      public void setPostUpdateSleepTimeMs(int postUpdateSleepTimeMs)
      Calls to this method are ignored if state is not NEW.
      Parameters:
      postUpdateSleepTimeMs -

    • setUserErrorExceptionHandler

      public void setUserErrorExceptionHandler(Consumer<UserErrorGenerationException> handler)
      The handler for exception during music generation due to user error.

      By default the handler displays the exception error message using StatusDisplayer.

      Parameters:
      handler - If null errors will be ignored

    • propertyChange

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

    • getLastUpdate

      public UpdatableSongSession.Update getLastUpdate()
      Description copied from interface: UpdatableSongSession.UpdateProvider
      Get the last available update after the PROP_UPDATE_AVAILABLE property change event was fired.
      Specified by:
      getLastUpdate in interface UpdatableSongSession.UpdateProvider
      Returns:
      Can be null if PROP_UPDATE_AVAILABLE change event was never fired.

    • isUpdateProvisionEnabled

      public boolean isUpdateProvisionEnabled()
      Description copied from interface: UpdatableSongSession.UpdateProvider
      Check if this UpdateProvider can still provide updates.
      Specified by:
      isUpdateProvisionEnabled in interface UpdatableSongSession.UpdateProvider
      Returns:
      True upon this object's creation, but might become false if UpdateProvider is "too" dirty and not able anymore to provide updates.
      See Also:

    • getControlTrack

      public ControlTrack getControlTrack()
      Description copied from interface: ControlTrackProvider
      get the control track.
      Specified by:
      getControlTrack in interface ControlTrackProvider
      Overrides:
      getControlTrack in class BaseSongSession
      Returns:
      Null if no contral track available.