Package org.jjazz.songstructure.api

Interface SongStructure

public interface SongStructure
A SongStructure manages SongParts.

Implementation must fire the relevant SgsChangeEvents when a method mutates the song structure. If a RhythmParameter uses a value class which is mutable (implements MutableRpValue), the SongStructure will listen to value changes and propagate the change event via SgsChangeEvents.

  • Method Details

    • getUniqueRhythms

      default List<Rhythm> getUniqueRhythms(boolean excludeAdaptedRhythms, boolean excludeImplicitSourceRhythms)
      Return the list of unique rhythms used in this SongStructure.

      Parameters can be used to exclude from the return list AdaptedRhythm and "implicit source rhythm" instances.

      An "implicit source rhythm" is the source rhythm of an AdaptedRhythm in a song which does not directly use the source rhythm. For example if song contains only spt1=bossa[3/4], then bossa(4/4) is the implicit source rhythm of the AdaptedRhythm bossa[3/4]. If song contains spt1=bossa and spt2=bossa[3/4], then bossa(4/4) is a source rhythm but is not an "implicit source rhythm".

      If both excludeAdaptedRhythms and excludeImplicitSourceRhythms parameters are false and there is an implicit source rhythm, then the return list will contain the AdaptedRhythm instance juste before the implicit rhythm instance.

      Parameters:
      excludeAdaptedRhythms - If true, don't return AdaptedRhythm instances
      excludeImplicitSourceRhythms - If true don't return "implicit source rhythms" instances
      Returns:
      The list of rhythms, in the order they are used in the song.

    • getUniqueAdaptedRhythms

      default List<AdaptedRhythm> getUniqueAdaptedRhythms()
      Return the list of unique AdaptedRhythms used in this SongStructure.
      Returns:
      Can be empty. List is ordered by SongPart order.

    • getUniqueRhythmVoices

      default List<RhythmVoice> getUniqueRhythmVoices(boolean excludeAdaptedRhythms, boolean excludeImplicitRhythms)
      Get all the unique RhythmVoices used by this SongStructure.

      Parameters are used to exclude RhythmVoice instances from AdaptedRhythms or "implicit source rhythms" (see getUniqueRhythms()).

      Parameters:
      excludeAdaptedRhythms - If true exclude the RhythmVoiceDelegate instances of AdaptedRhythms
      excludeImplicitRhythms - If true exclude the RhythmVoice instances of the "implicit source rhythms"
      Returns:
      See Also:

    • getUniqueTimeSignatures

      default List<TimeSignature> getUniqueTimeSignatures()
      Get the list of unique TimeSignatures used in the SongStructure.
      Returns:
      List is ordered by SongPart order.

    • getParentChordLeadSheet

      ChordLeadSheet getParentChordLeadSheet()
      An optional parent ChordLeadSheet.

      The SongStructure might listen to ChordLeadSheet changes to update itself accordingly.

      Returns:
      Can be null.

    • createSongPart

      SongPart createSongPart(Rhythm r, String name, int startBarIndex, int nbBars, CLI_Section parentSection, boolean reusePrevParamValues)
      Create a new SongPart instance whose container is this object.

      Use default rhythm parameters values, unless reusePrevParamValues is true and there is a previous song part.

      Parameters:
      r -
      name - The name of the created SongPart.
      startBarIndex -
      nbBars -
      parentSection - Can be null
      reusePrevParamValues -
      Returns:

    • getSongParts

      List<SongPart> getSongParts()
      Returns:
      A copy of the list of SongParts ordered according to their getStartBarIndex().

    • getSongParts

      List<SongPart> getSongParts(Predicate<SongPart> tester)
      Get the SongParts which match the tester.
      Parameters:
      tester -
      Returns:

    • getSongPart

      SongPart getSongPart(int absoluteBarIndex)
      Get the SongPart which contains a specific bar.
      Parameters:
      absoluteBarIndex -
      Returns:
      Can be null

    • getSizeInBars

      int getSizeInBars()
      Get the size in bars of the song.
      Returns:

    • getBarRange

      default IntRange getBarRange()
      The bar range corresponding to this song structure.
      Returns:
      [0;getSizeInBars()-1]
      See Also:

    • toBeatRange

      FloatRange toBeatRange(IntRange barRange)
      Converts the specified bar range into a natural beat range.

      The method must take into account SongParts with possibly different time signatures.

      Parameters:
      barRange - If null use the whole song structure.
      Returns:
      Can be an empty range if barRange is not contained in the song structure.

    • toPositionInNaturalBeats

      float toPositionInNaturalBeats(int absoluteBarIndex)
      Converts the position of the specified bar in natural beats: take into account the possible different time signatures before specified bar.
      Parameters:
      absoluteBarIndex - A value in the range [0; getSizeInBars()].
      Returns:

    • toPositionInNaturalBeats

      default float toPositionInNaturalBeats(Position pos)
      Converts the specified position in natural beats: take into account the possible different time signatures before specified bar.
      Parameters:
      pos -
      Returns:

    • toClsPosition

      default Position toClsPosition(Position pos)
      Converts a song structure position into a chord leadsheet position.
      Parameters:
      pos -
      Returns:
      null if pos is beyond the end of the song

    • toPosition

      Position toPosition(float posInBeats)
      Converts a natural beats position into a bar/beats Position.

      Take into account the possible different time signatures of the song.

      Parameters:
      posInBeats -
      Returns:
      Null if posInBeats is beyond the end of the song.

    • getSptItemPosition

      Position getSptItemPosition(SongPart spt, ChordLeadSheetItem<?> clsItem)
      Get the absolute position in the song structure of a chordleadsheet item referred to by the specified song part.
      Parameters:
      spt -
      clsItem -
      Returns:
      A position within spt range
      Throws:
      IllegalArgumentException - If clsItem does not belong to spt's parent Section.
      IllegalStateException - If getParentChordLeadSheet() returns null.

    • authorizeAddSongParts

      void authorizeAddSongParts(List<SongPart> spts) throws UnsupportedEditException
      Check if add operation is doable.

      Operation is not doable if a new rhythm could not be accepted by listeners.

      Parameters:
      spts -
      Throws:
      UnsupportedEditException

    • addSongParts

      void addSongParts(List<SongPart> spts) throws UnsupportedEditException
      Add one by one a list of SongParts.

      Each SongPart's startBarIndex must be a valid barIndex, either:
      - equals to the startBarIndex of an existing SongPart
      - the last barIndex+1
      The startBarIndex of the trailing SongParts is shifted accordingly. The SongPart container will be set to this object.

      Parameters:
      spts -
      Throws:
      UnsupportedEditException - Exception is thrown before any change is done. See authorizeAddSongParts().

    • authorizeRemoveSongParts

      void authorizeRemoveSongParts(List<SongPart> spts) throws UnsupportedEditException
      Check if remove operation is doable.

      Parameters:
      spts -
      Throws:
      UnsupportedEditException

    • removeSongParts

      void removeSongParts(List<SongPart> spts) throws UnsupportedEditException
      Remove some SongParts.

      The startBarIndex of the trailing SongParts are updated.

      Parameters:
      spts - A List of SongParts.
      Throws:
      UnsupportedEditException - Exception is thrown before any change is done. See authorizeRemoveSongParts()

    • resizeSongParts

      void resizeSongParts(Map<SongPart,Integer> mapSptSize)
      Change the size in bars of SongParts.

      The startBarIndex of the trailing SongParts are updated.

      Parameters:
      mapSptSize - A map which associates a SongPart and the new desired size.

    • authorizeReplaceSongParts

      void authorizeReplaceSongParts(List<SongPart> oldSpts, List<SongPart> newSpts) throws UnsupportedEditException
      Check if replace operation is doable.

      UnsupportedEditException is thrown if replacement is impossible, because :
      - not enough Midi channels for a new rhythm

      Parameters:
      oldSpts -
      newSpts -
      Throws:
      UnsupportedEditException

    • replaceSongParts

      void replaceSongParts(List<SongPart> oldSpts, List<SongPart> newSpts) throws UnsupportedEditException
      Replace SongParts by other SongParts.

      Typically used to changed rhythm. The size and startBarIndex of new SongParts must be the same than the replaced ones. The container of newSpt will be set to this object.

      Parameters:
      oldSpts -
      newSpts - size must match oldSpts
      Throws:
      UnsupportedEditException - Exception is thrown before any change is done. See authorizeReplaceSongParts()

    • setSongPartsName

      void setSongPartsName(List<SongPart> spts, String name)
      Change the name of one or more SongParts.
      Parameters:
      spts -
      name - The name of the SongParts.

    • setRhythmParameterValue

      <T> void setRhythmParameterValue(SongPart spt, RhythmParameter<T> rp, T value)
      Change the value of a specific RhythmParameter.
      Type Parameters:
      T -
      Parameters:
      spt - The SongPart rp belongs to.
      rp - The RhythmParameter.
      value - The new value to apply for rp.

    • getLastUsedRhythm

      Rhythm getLastUsedRhythm(TimeSignature ts)
      Returns the last rhythm used in this songStructure for this TimeSignature.

      Parameters:
      ts -
      Returns:
      Can be null if the specified time signature has never been used by this SongStructure.

    • getRecommendedRhythm

      Rhythm getRecommendedRhythm(TimeSignature ts, int sptStartBarIndex)
      Get the recommended rhythm to use for a new SongPart.

      If possible use getLastUsedRhythm(). If not possible then :
      - return an AdaptedRhythm of the current rhythm at sptStartBarIndex,
      - otherwise return the RhythmDatabase default rhythm for the time signature.

      Parameters:
      ts - The TimeSignature of the rhythm
      sptStartBarIndex - The start bar index of the new song part, can be on an existing song part, or right after the last song part.
      Returns:
      Can't be null

    • addSgsChangeListener

      void addSgsChangeListener(SgsChangeListener l)
      Add a listener to changes of this object.
      Parameters:
      l -

    • removeSgsChangeListener

      void removeSgsChangeListener(SgsChangeListener l)
      Remove a listener to this object's changes.
      Parameters:
      l -

    • addUndoableEditListener

      void addUndoableEditListener(UndoableEditListener l)
      Add a listener to undoable edits.
      Parameters:
      l -

    • removeUndoableEditListener

      void removeUndoableEditListener(UndoableEditListener l)
      Remove a listener to undoable edits.
      Parameters:
      l -