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 rest 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 nominally last time point in a measure, relative to the measure. This is identical with the measure's duration. Set in the constructor For convenience only.

    • input

      protected final List<QualifiedRational> input
      The list of input data, either strictly ascending time points of duration values.

    • inputsize

      protected final int inputsize
      The number of time points in input. One large 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

      @Opt protected MSplitter.Result metricSplitterResult
      The result of the last call to metric split, reflects the analysis of the accepted prefix of the input data.

    • resultIndex

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

    • measureStart

      protected Rational measureStart
      Running cursor of the time of the measure start 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 !=0/1, 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 currently 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 == 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 last accepted measure.

  • Method Details

    • byStartPoints

      public static MetricConsumer byStartPoints(@Opt @Opt MSplitter metricSplitter, List<QualifiedRational> input)
      Parameters:
      metricSplitter - is the initial one, can be changed between to "hasNext()" accesses by changeMetrum(MSplitter).
      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 @Opt MSplitter metricSplitter, List<Rational> input, boolean soundNotPause)
      Factory method for a user. For details see byStartPoints(MSplitter, List).
      Parameters:
      soundNotPause - how all start points in "input" must be interpreted.

    • byDurations

      public static MetricConsumer byDurations(@Opt @Opt MSplitter metricSplitter, List<QualifiedRational> input)
      Factory method for a user.
      Parameters:
      metricSplitter - is the initial one, can be changed between to "hasNext()" accesses by changeMetrum(MSplitter). (Maybe == null initially, but must be set != null before the first split request.)
      input - a list of durations. 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 @Opt MSplitter metricSplitter, List<Rational> input, boolean soundNotPause)
      Factory method for a user. 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 the next 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 Metrum.

    • 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 current getResult 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.

    • 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, i.e. 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 the current getResult 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 the current time point corresponds to the input time points.

    • getNext

      public void getNext()
      This method performs the metric analysis of a prefix of the input data, 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 the "current measure", and all inquiry methods are related to this situation.

      This method prepares the time point data for a call to MSplitter. Its input (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)