Package eu.bandm.music.entities

Class MetricConsumer

java.lang.Object
eu.bandm.music.entities.MetricConsumer
public class MetricConsumer extends Object
Consumes a prefix of a list of QualifiedRational by using a MSplitter, returns its result and additionally information about the remaining sequence. The MSplitter can change with every analysis step, i.e. after the prefix corresponding to one complete measure has been acceped. This can realize changes in the metrum of a score.
Usage in detail:

  • Field Details

    • metricSplitter

      protected MSplitter metricSplitter
      The currently valid MetricSplitter, representing the currently valid metrum. May be ==null only in intialization.

    • measureLength

      protected Rational measureLength
      The currently valid duration of a measure, defined by the metric tree spec underlying the current metricSplitter. Is only a cache. May be ==null only in intialization.

    • lastQRinMeasure

      protected QualifiedRational lastQRinMeasure
      The startpoint of any measure's successor, relative to its own startpoint, when hat measure is in the currently set meter. This corresponds always to the current meter's duration. For convenience only.
      See Also:

    • input

      protected final List<QualifiedRational> input
      The list of events to split, derived from the input data to the constructor.

    • inputsize

      protected final int inputsize
      The number of time points in input. One larger than the number of events. Set in the constructor for convenience only.

    • lastTp

      protected final Rational lastTp
      The last time point data in the input = the end time point of the last event. Set in the constructor For convenience only.

    • metricSplitterResult

      protected MSplitter.Result metricSplitterResult
      The result of the most recent invocation of metric split. Reflects the analysis of the most recently accepted prefix of the input data, which is the current measure.

    • resultIndex

      protected int resultIndex
      Index of the input time point which corresponds to the start point of the first event in the current measure.

    • measureStart

      protected Rational measureStart
      Running cursor of the time of the start of the current measure relative to the input data.

    • firstIsOverlap

      protected boolean firstIsOverlap
      Whether the first event in the current measure is overlapping from the preceding measure.

    • lastOverlapDuration

      protected Rational lastOverlapDuration
      If not zero, this is the part of the last processed event (=nextIndex), which overlaps into the next measure.

    • isIncomplete

      protected boolean isIncomplete
      Whether the input data is exhausted and could not fill the most recently recognized measure completely.

    • tailDiscarded

      protected boolean tailDiscarded
      Local flag that any synthetic very last event shall not be processed by the write-out visitor.

    • nextIndex

      protected int nextIndex
      Index of the next event to process on the next call to getNext(). (In case of overlap, this is equal to the index of the last event in the current measure.)

    • nextMeasureStart

      protected Rational nextMeasureStart
      The start time point of the next measure, calculated by adding its length to the start of the current measure.

  • Method Details

    • byStartPoints

      public static MetricConsumer byStartPoints(@Opt MSplitter metricSplitter, List<QualifiedRational> input)
      Service point: Factory method.
      Parameters:
      metricSplitter - is the initial one. It can be changed between two invocations of hasNext() by changeMetrum(MSplitter). May initially be null, but must be set non-null before using this instance.
      input - a sorted list of relative time points (event start positions). The very first time point defines the start time of the very first measure. The very last time point is not an event, but the end of the event beginning at the next-to-last time point.

    • byStartPoints

      public static MetricConsumer byStartPoints(@Opt MSplitter metricSplitter, List<Rational> input, boolean soundNotPause)
      Service point: Factory method. For details see byStartPoints(MSplitter, List).
      Parameters:
      soundNotPause - how all start points in input must be interpreted.

    • byDurations

      public static MetricConsumer byDurations(@Opt MSplitter metricSplitter, List<QualifiedRational> input)
      Service point: Factory method.
      Parameters:
      metricSplitter - is the initial one. It can be changed between two invocations of hasNext() by changeMetrum(MSplitter). May initially be null, but must be set non-null before using this instance.
      input - a list of durations. A sequence of all-pause events is constructed for all operations. The very first time point will be mapped to "0/1" of the very first measure. 
          input index   0      1     2                     3
       duration   dt0    dt1   dt2                   dt3
    input to MetricSplitter
       index      0      1     2        3            4
       startpoint 0.0    dt0   dt0+dt1  dt0+dt1+dt2  dt0+dt1+dt2+dt3
       duration     dt0     dt1   dt2       dt3

    • byDurations

      public static MetricConsumer byDurations(@Opt MSplitter metricSplitter, List<Rational> input, boolean soundNotPause)
      Service point: Factory method. For details see byDurations(MSplitter, List).
      Parameters:
      soundNotPause - how all durations in "input" must be interpreted.

    • changeMetrum

      public void changeMetrum(MSplitter newms)
      Change the metric splitter and thus the meter to be used for all subsequent splitting operations.
      Parameters:
      newms - must be fully instantiated with an MTreeSpec and all parameters.

    • hasNext

      public boolean hasNext()
      Whether there are unconsumed events, or at least one partially unconsumed event. Attention: the very last timepoint in inputs is not an event, but the end of the very last event.

    • hasCompleteNext

      public boolean hasCompleteNext()
      Whether there are unconsumed events, or at least one partially unconsumed event, which fill at least one complete measure, according to the currently set meter.

    • getResult

      public MSplitter.Result getResult()
      Returns the result of the last getNext() call to the metric splitter. For details see MSplitter.Result. But better use
      this.new WriteOut().process(), see MetricConsumer.WriteOut. Only this treats all cross-measure-bar situations correctly.

    • getResultIndex

      public int getResultIndex()
      The index of the first event in the current result measure, may be a trailing overlap from the last event in the preceding measure.

    • getMeasureStart

      public Rational getMeasureStart()
      Get the start of the most recently accepted measure. In case that durations are the input, a start with 0/1 is assumed. Otherwise the first measure starts with the first event, and the current time point corresponds to the input time points.

    • getMeasureLength

      public Rational getMeasureLength()
      /

    • firstIsOverlap

      public boolean firstIsOverlap()
      Whether the first node in the current result (=event getResultIndex) is an overlap from the last measure.

    • getLastOverlap

      public Rational getLastOverlap()
      The length of the part of the last event of the current result which will overlap into the next measure.

    • isIncomplete

      public boolean isIncomplete()
      Whether the current measure is the very last, and its last event has been synthesized to fill it up.

    • discardSyntheticTail

      public void discardSyntheticTail()
      Discard the last event, which was only synthesized for completing the measure.

    • getRestDuration

      public Rational getRestDuration()
      The total of all events which have not yet been consumed. May be negative iff measure is the very last and incomplete.

    • getNextIndex

      public int getNextIndex()
      The index of the event which will be the first in the next measure, after calling getNext(). (This may be the trailing rest of the last event of the current measure.)

    • getNextMeasureStart

      public Rational getNextMeasureStart()
      Get the end point of the current measure, ie. the start of the next measure after calling getNext(). In case that durations are the input, a start of the whole sequence at point 0/1 is assumed. Otherwise the first measure starts with the first event, and all returned timepoint values are relative to that input data.

    • getNext

      public void getNext()
      This method performs the metric analysis of a prefix of the input data. This is done according to the currently selected metrum (see changeMetrum(MSplitter) and consumes as much as possible to fill one complete measure. After this call, the recognized prefix is called the current measure, and all inquiry methods are related to this situation.

      This method prepares the time point data for a call to MSplitter. The input to that (prepared in "Accu.Tps") must start with 0/1 and end exactly with the measure length. The very last measure is possibly extended to meet this criterion. The MSplitter WriteOut-Visitor is wrapped into the own MetricConsumer.WriteOut visitor, which treats the cross-measure-bar situations correctly.

      Throws:
      IllegalStateException - if the input is exhausted, ie. a call to hasNext() would return false.
      NullPointerException - if no metrum has previously been selected (see changeMetrum(MSplitter)