Package heronarts.lx

Class Tempo

java.lang.Object
heronarts.lx.LXComponent
heronarts.lx.LXModulatorComponent
heronarts.lx.Tempo
All Implemented Interfaces:
LXLoopTask, LXPath, LXSerializable, LXTriggerSource, LXOscComponent, LXParameterListener
public class Tempo extends LXModulatorComponent implements LXOscComponent, LXTriggerSource
Class to represent a musical tempo at which patterns are operating. This can be updated in real-time via invoking the tap() method. Note there is no automatic beat detection - the Tempo object must be explicitly tap()'d to learn the tempo. "Beats" are indicated by the return value of beat(). ramp() returns the current beat phase from 0 to 1 The bpm parameter indicates the current BPM, and period can be used to invert the beat frequency (BPM) into a listenable period (ms per beat). Additional utility functions are available that assume beats represent the tempo: - measure() can be polled to check measure beats, respectively. - Tempo.Listener's can be added to trigger on beats or measures without polling the Tempo object.

  • Field Details

  • Constructor Details

    • Tempo

      public Tempo(LX lx)

  • Method Details

    • newQuantizationParameter

      public static ObjectParameter<Tempo.Quantization> newQuantizationParameter(String label, String description)

    • initialize

      public void initialize()

    • hasLaunchQuantization

      public boolean hasLaunchQuantization()
      Whether launch quantization is enabled in the tempo engine
      Returns:
      If a launch quantization division is selected

    • getLaunchQuantization

      public Tempo.Division getLaunchQuantization()
      Gets the current launch quantization value
      Returns:
      Division value, or null if none selected

    • setOscBpmRange

      public Tempo setOscBpmRange(double min, double max)

    • isValidOscBpm

      public boolean isValidOscBpm(double bpm)

    • handleOscMessage

      public boolean handleOscMessage(OscMessage message, String[] parts, int index)
      Description copied from class: LXComponent
      Handles an OSC message sent to this component. By default this method handles registered components and parameters, but subclasses may override this method to handle different types of OSC messages.
      Specified by:
      handleOscMessage in interface LXOscComponent
      Overrides:
      handleOscMessage in class LXComponent
      Parameters:
      message - Full OSC message object
      parts - The OSC address pattern, broken into an array of parts
      index - Which index into the parts array corresponds to this component's children
      Returns:
      true if the OSC message was handled and should be considered consumed, false otherwise

    • getLabel

      public String getLabel()
      Description copied from class: LXComponent
      Accessor for the user-facing label of this component. Objects that implement the LXComponent.Renamable interface may allow the user to change this value.
      Specified by:
      getLabel in interface LXPath
      Overrides:
      getLabel in class LXComponent
      Returns:
      Label for this component

    • onParameterChanged

      public void onParameterChanged(LXParameter p)
      Description copied from class: LXComponent
      Subclasses are free to override this if desired. It will automatically fire for any listenable parameter that is registered with this component.
      Specified by:
      onParameterChanged in interface LXParameterListener
      Overrides:
      onParameterChanged in class LXComponent
      Parameters:
      p - Parameter that has a value change

    • addListener

      public Tempo addListener(Tempo.Listener listener)

    • removeListener

      public Tempo removeListener(Tempo.Listener listener)

    • beat

      public boolean beat()
      Method to indicate when we are on-beat, assuming quarter-notes being given one beat.
      Returns:
      true if we are on a quarter-note beat

    • barCount

      public int barCount()
      Returns the count of what bar number we are on
      Returns:
      Bar count

    • beatCount

      public int beatCount()
      Gets the count of the current beat we are on, 0-indexed and absolute
      Returns:
      Beat count

    • beatCountWithinBar

      public int beatCountWithinBar()
      Gets the count of the current beat we are on, 0-indexed and within the range [0, beatsPerBar-1]
      Returns:
      Beat count within bar

    • getCompositeBasis

      public double getCompositeBasis()
      Gets the composite basis of the tempo, which is the beatCount combined with the current basis cycle.
      Returns:
      Number of full beats completed since beginning of tempo

    • getCycleCount

      public int getCycleCount(Tempo.Division division)
      Gets the cycle count at this tempo division
      Parameters:
      division - Division level
      Returns:
      Measure count

    • getCycleCount

      public int getCycleCount(double multiplier)

    • getBasis

      public double getBasis(Tempo.Division division)
      Gets the basis of the tempo, relative to a tempo division. The result is between 0 and strictly less than 1
      Parameters:
      division - Tempo division
      Returns:
      Relative tempo division cycle basis from 0-1

    • measure

      @Deprecated public boolean measure()
      Deprecated.
      Use bar()
      Method to indicate the start of a measure.
      Returns:
      true if we are on a measure-beat

    • bar

      public boolean bar()
      Method to indicate the start of a bar.
      Returns:
      true if we are on a bar-beat

    • basis

      public double basis()
      Indicates phase of the current beat. On the beat the value will be 0, then ramp up to 1 before the next beat triggers.
      Returns:
      value from 0-1 indicating phase of beat

    • basisf

      public float basisf()

    • ramp

      @Deprecated public double ramp()
      Deprecated.
      Indicates phase of the current beat. On the beat the value will be 0, then ramp up to 1 before the next beat triggers. This is deprecated, should use basis() instead.
      Returns:
      value from 0-1 indicating phase of beat

    • rampf

      @Deprecated public float rampf()
      Deprecated.
      Indicates beat phase in floating point. This is deprecated, should use basisf() instead.
      Returns:
      value from 0-1 indicating phase of beat

    • bpm

      public double bpm()
      Returns the current tempo in Beats Per Minute
      Returns:
      Current tempo

    • bpmf

      public float bpmf()
      Returns the tempo in floating point
      Returns:
      Current tempo in float

    • setBpm

      public Tempo setBpm(double bpm)
      Sets the BPM to the given value
      Parameters:
      bpm - Number of beats per minute
      Returns:
      this

    • adjustBpm

      public Tempo adjustBpm(double amount)
      Adjust the BPM by the given amount
      Parameters:
      amount - Amount to adjust BPM by
      Returns:
      this

    • setPeriod

      public Tempo setPeriod(double beatMillis)
      Sets the period of one beat
      Parameters:
      beatMillis - Milliseconds in a beat
      Returns:
      this

    • resetOnNextBeat

      public Tempo resetOnNextBeat()
      When in internal clock mode, the next beat will reset the beat count to 0.

    • trigger

      public void trigger()
      Re-triggers the metronome, so that it immediately beats. Also resetting the beat count to be at the beginning of a measure.

    • triggerBeatWithinBar

      public void triggerBeatWithinBar(int beatWithinBar, OscMessage message)
      Triggers the given beat within bar, keeping count over subsequent bars if desired.
      Parameters:
      beatWithinBar - Beat within bar, 1-indexed
      message - OSC message that triggered the beat, for timing adjustment

    • triggerBeatWithinBar

      public void triggerBeatWithinBar(int beatWithinBar, long nanoTime)
      Triggers the given beat within bar, keeping count over subsequent bars if desired.
      Parameters:
      beatWithinBar - Beat within bar, 1-indexed
      nanoTime - System.nanoTime() value for the event causing trigger

    • triggerBarAndBeat

      public void triggerBarAndBeat(int bar, int beat)
      Trigger the given bar and beat position, both 1-indexed
      Parameters:
      bar - Bar number, 1-indexed
      beat - Beat number, 1-indexed

    • triggerBarAndBeat

      public void triggerBarAndBeat(int bar, int beat, OscMessage message)
      Trigger the given bar and beat position, both 1-indexed
      Parameters:
      bar - Bar number, 1-indexed
      beat - Beat number, 1-indexed
      message - Source message, for timing adjustment

    • triggerBarAndBeat

      public void triggerBarAndBeat(int bar, int beat, long nanoTime)
      Trigger the given bar and beat position, both 1-indexed
      Parameters:
      bar - Bar number, 1-indexed
      beat - Beat number, 1-indexed
      nanoTime - System.nanoTime() value of the event that caused the trigger

    • trigger

      public void trigger(boolean resetBeat)
      Triggers a beat, optionally resetting the beat count
      Parameters:
      resetBeat - True if the beat count should be reset to 0

    • trigger

      public void trigger(int beat)
      Triggers the metronome, setting the beat count to the given explicit value
      Parameters:
      beat - Beat count, 0-indexed

    • trigger

      public void trigger(int beat, OscMessage message)
      Triggers the metronome, setting the beat count to the given value with a specified offset into the beat.
      Parameters:
      beat - Beat count, 0-indexed
      message - OSC message that caused the trigger, for timing adjustment

    • trigger

      public void trigger(int beat, long nanoTime)
      Triggers the metronome, setting the beat count to the given value with a specified offset into the beat.
      Parameters:
      beat - Beat count, 0-indexed
      nanoTime - System.nanoTime() value of event that caused the trigger

    • tap

      public void tap()
      Adjusts the tempo in realtime by tapping. Whenever tap() is invoked the time between previous taps is averaged to compute a new tempo. At least three taps are required to compute a tempo. Otherwise, tapping just re-triggers the beat. It is better to use the trigger() method directly if this is all that is desired.

    • tap

      public void tap(long nanoTime)
      Adjusts the tempo, specifying an exact timestamp in milliseconds of when the tap event occurred.
      Parameters:
      nanoTime - Timestamp of event, should be equivalent to System.nanoTime()

    • stop

      public void stop()
      Stop the metronome running

    • loop

      public void loop(double deltaMs)
      Specified by:
      loop in interface LXLoopTask
      Overrides:
      loop in class LXModulatorComponent

    • getTriggerSource

      public BooleanParameter getTriggerSource()
      Specified by:
      getTriggerSource in interface LXTriggerSource

    • dispose

      public void dispose()
      Description copied from class: LXComponent
      Invoked when a component is being removed from the system and will no longer be used at all. This unregisters the component and should free up any resources and parameter listeners. Ideally after this method is called the object should be eligible for garbage collection. Subclasses are generally expected to override this method to handle their particular cleanup work. They should also generally call super.dispose() at the appropriate time to perform the basic cleanup, which may need to happen either before or after cleaning up other objects.
      Overrides:
      dispose in class LXModulatorComponent