org.deepsymmetry.electro

Class Metronome

java.lang.Object

org.deepsymmetry.electro.Metronome

All Implemented Interfaces:

Snapshot

public class Metronome
extends Object
implements Snapshot

A beat management tool. Tell it what BPM you want, and it will compute beat, bar, and phrase timestamps accordingly. If you only need a single piece of information, you can obtain it directly from the metronome. If you need to work with two or more values, you need to call getSnapshot() and ask the snapshot for them or you will see inconsistent results, since time will move on between each question you ask the metronome itself.

Inspired by Jeff Rose's work in Overtone.

Author:

James Elliott

Constructor Summary

Constructors

Constructor and Description
Metronome()

Method Summary

Modifier and Type	Method and Description
void	adjustStart(long ms) Adds a number of milliseconds to the start time of the metronome.
static double	beatsToMilliseconds(long beats, double tempo) Calculate the number of milliseconds taken by the specified number of beats at the specified tempo.
double	distanceFromBar() Determine how far in time the metronome is from its closest bar boundary.
double	distanceFromBeat() Determine how far in time the metronome is from the closest beat.
double	distanceFromPhrase() Determine how far in time the metronome is from its closest phrase boundary.
static double	enhancedPhase(long markerNumber, double markerPhase, double desiredRatio) Helper function to calculate phase with respect to multiples or fractions of a marker (beat, bar, or phrase), given the phase with respect to that marker, the marker number, and the desired ratio.
static double	enhancedPhase(long markerNumber, double markerPhase, long numerator, long denominator) Helper function to calculate phase with respect to multiples or fractions of a marker (beat, bar, or phrase), given the phase with respect to that marker, the marker number, and the desired ratio.
static double	findClosestDelta(double delta) Figures out the least disruptive phase shift that ends up in a target phase.
long	getBar() Get the current bar being played.
double	getBarInterval() Get the number of milliseconds a bar lasts given the current configuration and tempo.
double	getBarPhase() Determine the distance traveled into the current bar as a phase number in the range [0.0, 1.0).
int	getBarsPerPhrase() Get the number of bars per phrase in the metronome's beat grid.
int	getBarWithinPhrase() Return the current bar number relative to the start of the phrase: the phrase starts with bar 1, and the range goes up to the value of getBarsPerPhrase().
long	getBeat() Get the current beat being played.
double	getBeatInterval() Get the number of milliseconds a beat lasts given the current tempo.
double	getBeatPhase() Determine the distance traveled into the current beat as a phase number in the range [0.0, 1.0).
int	getBeatsPerBar() Get the number of beats per bar in the metronome's beat grid.
int	getBeatWithinBar() Return the current beat number relative to the start of the bar: the down beat is 1, and the range goes up to the value of getBeatsPerBar().
int	getBeatWithinPhrase() Return the current beat number relative to the start of the phrase: the phrase starts with beat 1, and the range goes up to the value of getBeatsPerBar() times getBarsPerPhrase().
long	getInstant() Checks when a snapshot was taken; since you are working with a live metronome, always returns the current time.
String	getMarker() Returns the current count of the metronome as "phrase.bar.beat".
long	getPhrase() Get the current phrase being played.
double	getPhraseInterval() Get the number of milliseconds a phrase lasts given the current configuration and tempo.
double	getPhrasePhase() Determine the distance traveled into the current phrase as a phase number in the range [0.0, 1.0).
Snapshot	getSnapshot() Take a snapshot of the current beat, bar, phrase, and phase state, so coherent calculations about them can be performed with respect to a static point in time.
Snapshot	getSnapshot(long instant) Take a snapshot of the beat, bar, phrase, and phase state that the metronome would have at the specified millisecond timestamp, so coherent calculations about them can be performed with respect to that static point in time.
long	getStartTime() Returns the time at which this metronome was effectively started (tempo changes will shift this, as will a variety of methods which adjust the timeline).
double	getTempo() Get the tempo at which this metronome is running.
long	getTimeOfBar(long bar) Determine the millisecond timestamp at which a particular bar will occur.
long	getTimeOfBeat(long beat) Determine the millisecond timestamp at which a particular beat will occur.
long	getTimeOfPhrase(long phrase) Determine the millisecond timestamp at which a particular phrase will occur.
boolean	isDownBeat() Checks whether the current beat is the first beat in its bar.
boolean	isPhraseStart() Checks whether the current beat is the first beat in its phrase.
void	jumpToBar(long bar) Restarts the metronome at the start of the specified bar, keeping the beat phase unchanged in case it is being synchronized to an external source.
void	jumpToBeat(long beat) Restarts the metronome at the beginning of the specified beat number.
void	jumpToPhrase(long phrase) Restarts the metronome at the start of the specified phrase, keeping the beat phase unchanged in case it is being synchronized to an external source.
static long	markerNumber(long instant, long start, double interval) Helper function to calculate the beat, bar, or phrase number in effect at a given instant (in milliseconds) given a timeline starting point (start, also in milliseconds), and the interval (also in milliseconds) between beats, bars, or phrases.
static double	markerPhase(long instant, long start, double interval) Helper function to calculate the beat, bar, or phrase phase at a given instant (in milliseconds), given a timeline starting point (start, also in milliseconds), and the interval (also in milliseconds) between beats, bars, or phrases.
static double	normalizePhase(double phase) Ensure that a phase falls in the range [0.0, 1.0).
void	setBarPhase(double phase) Nudge the metronome so that it has reached the specified part of its current bar.
void	setBarsPerPhrase(int barsPerPhrase) Establish a new number of bars per phrase in the metronome's beat grid.
void	setBeatPhase(double phase) Nudge the metronome so that it has reached the specified part of its current beat.
void	setBeatsPerBar(int beatsPerBar) Establish a new number of beats per bar in the metronome's beat grid.
void	setPhrasePhase(double phase) Nudge the metronome so that it has reached the specified part of its current phrase.
void	setTempo(double bpm) Establish a new tempo for the metronome.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Metronome

public Metronome()

Method Detail

getStartTime

public long getStartTime()

Returns the time at which this metronome was effectively started (tempo changes will shift this, as will a variety of methods which adjust the timeline).

Specified by:

getStartTime in interface Snapshot

Returns:

the millisecond timestamp at which the beat grid originates.

adjustStart

public void adjustStart(long ms)

Adds a number of milliseconds to the start time of the metronome. Useful to nudge it back into synchronization with an external source.

Parameters:

ms - the number of milliseconds to add to the start time

getTempo

public double getTempo()

Get the tempo at which this metronome is running.

Specified by:

getTempo in interface Snapshot

Returns:

the number of beats per minute being counted

setTempo

public void setTempo(double bpm)

Establish a new tempo for the metronome. The start time will be adjusted so that the current beat and phase are unaffected by the tempo change.

Parameters:

bpm - the number of beats per minute at which the metronome should now run

getBeatsPerBar

public int getBeatsPerBar()

Get the number of beats per bar in the metronome's beat grid. The default value is four.

Specified by:

getBeatsPerBar in interface Snapshot

Returns:

the number of beats per bar being counted

setBeatsPerBar

public void setBeatsPerBar(int beatsPerBar)

Establish a new number of beats per bar in the metronome's beat grid.

Parameters:

beatsPerBar - a positive number of beats per bar being counted

Throws:

IllegalArgumentException - if beatsPerBar is not greater than zero

getBarsPerPhrase

public int getBarsPerPhrase()

Get the number of bars per phrase in the metronome's beat grid.

Specified by:

getBarsPerPhrase in interface Snapshot

Returns:

the number of bars per phrase being counted

setBarsPerPhrase

public void setBarsPerPhrase(int barsPerPhrase)

Establish a new number of bars per phrase in the metronome's beat grid.

Parameters:

barsPerPhrase - a positive number of bars per phrase being counted

Throws:

IllegalArgumentException - if barsPerPhrase is not greater than zero

beatsToMilliseconds

public static double beatsToMilliseconds(long beats,
                                         double tempo)

Calculate the number of milliseconds taken by the specified number of beats at the specified tempo.

Parameters:

beats - the number of beats to time

tempo - the number of that play in a minute

Returns:

the number of milliseconds that would pass while that many beats play at that tempo

markerNumber

public static long markerNumber(long instant,
                                long start,
                                double interval)

Helper function to calculate the beat, bar, or phrase number in effect at a given instant (in milliseconds) given a timeline starting point (start, also in milliseconds), and the interval (also in milliseconds) between beats, bars, or phrases.

Parameters:

instant - the time (in milliseconds) for which a marker number is desired

start - the time (in milliseconds) at which the metronome started counting

interval - the time (in milliseconds) between markers

Returns:

the marker number currently in effect for the metronome at the specified instant

markerPhase

public static double markerPhase(long instant,
                                 long start,
                                 double interval)

Helper function to calculate the beat, bar, or phrase phase at a given instant (in milliseconds), given a timeline starting point (start, also in milliseconds), and the interval (also in milliseconds) between beats, bars, or phrases. A marker phase starts at 0.0 at the beginning of the beat, bar, or phrase, rises linearly during the beat, bar, or phrase, but never reaches 1.0, because that is the start of the next beat, bar, or phrase.

Parameters:

instant - the time (in milliseconds) for which a marker phase is desired

start - the time (in milliseconds) at which the metronome started counting

interval - the time (in milliseconds) between markers

Returns:

the phase in effect for the specified marker at the specified instant, in the range [0.0, 1.0)

enhancedPhase

public static double enhancedPhase(long markerNumber,
                                   double markerPhase,
                                   double desiredRatio)

Helper function to calculate phase with respect to multiples or fractions of a marker (beat, bar, or phrase), given the phase with respect to that marker, the marker number, and the desired ratio. A desiredRatio of 1.0 returns the phase unchanged; 0.5 (1/2) oscillates twice as fast, 0.75 (3/4) oscillates 4 times every 3 markers...

See the Ratios illustration in the Afterglow documentation for more details with graphs.

Only positive values were considered for the ratio when writing this algorithm, the results you'll get if you pass in zero or a negative value, are not likely meaningful.

Parameters:

markerNumber - the current marker number being considered, as returned by markerNumber(long, long, double)

markerPhase - the current phase with respect to the marker, as returned by markerPhase(long, long, double)

desiredRatio - the ratio by which to oscillate the phase

Returns:

the oscillated phase

Since:

0.1.1

See Also:

enhancedPhase(long, double, long, long)

enhancedPhase

public static double enhancedPhase(long markerNumber,
                                   double markerPhase,
                                   long numerator,
                                   long denominator)

Helper function to calculate phase with respect to multiples or fractions of a marker (beat, bar, or phrase), given the phase with respect to that marker, the marker number, and the desired ratio. A ration of 1/1 returns the phase unchanged; 1/2 oscillates twice as fast, 3/4 oscillates 4 times every 3 markers...

See the Ratios illustration in the Afterglow documentation for more details with graphs.

Only positive values were considered for the numerator and denominator when writing this algorithm, the results you'll get if you pass in zero or a negative value, are not likely meaningful.

Parameters:

markerNumber - the current marker number being considered, as returned by markerNumber(long, long, double)

markerPhase - the current phase with respect to the marker, as returned by markerPhase(long, long, double)

numerator - over how many markers should an oscillation cycle span

denominator - how many oscillations should occur in that span

Returns:

the oscillated phase

Since:

0.1.1

See Also:

enhancedPhase(long, double, double)

normalizePhase

public static double normalizePhase(double phase)

Ensure that a phase falls in the range [0.0, 1.0). Values outside the range will have their non-fractional part discarded.

Parameters:

phase - a phase value that may require normalization to within the unit range

Returns:

the normalized phase

getBeatInterval

public double getBeatInterval()

Get the number of milliseconds a beat lasts given the current tempo.

Specified by:

getBeatInterval in interface Snapshot

Returns:

the duration of a beat

getBarInterval

public double getBarInterval()

Get the number of milliseconds a bar lasts given the current configuration and tempo.

Specified by:

getBarInterval in interface Snapshot

Returns:

the duration of a bar

getPhraseInterval

public double getPhraseInterval()

Get the number of milliseconds a phrase lasts given the current configuration and tempo.

Specified by:

getPhraseInterval in interface Snapshot

Returns:

the duration of a phrase

getBeat

public long getBeat()

Get the current beat being played.

Specified by:

getBeat in interface Snapshot

Returns:

the current beat number, which starts at 1

jumpToBeat

public void jumpToBeat(long beat)

Restarts the metronome at the beginning of the specified beat number.

Parameters:

beat - the beat to which the metronome should jump; the first beat is beat 1

getTimeOfBeat

public long getTimeOfBeat(long beat)

Determine the millisecond timestamp at which a particular beat will occur.

Specified by:

getTimeOfBeat in interface Snapshot

Parameters:

beat - the number of the beat whose start time is desired

Returns:

the time at which the specified beat begins, to the nearest millisecond

getBeatPhase

public double getBeatPhase()

Determine the distance traveled into the current beat as a phase number in the range [0.0, 1.0).

Specified by:

getBeatPhase in interface Snapshot

Returns:

the current beat phase

findClosestDelta

public static double findClosestDelta(double delta)

Figures out the least disruptive phase shift that ends up in a target phase.

Parameters:

delta - the amount to be added to our current phase to achieve a desired phase

Returns:

an amount that will yield the same phase while changing our position the least

setBeatPhase

public void setBeatPhase(double phase)

Nudge the metronome so that it has reached the specified part of its current beat. If the value supplied is outside the range of a beat phase (less than zero or greater than or equal to one), it will be normalized to fit into that range by ignoring the non-fractional part.

Parameters:

phase - the desired beat phase, in the range [0.0, 1.0).

getBar

public long getBar()

Get the current bar being played.

Specified by:

getBar in interface Snapshot

Returns:

the current bar number, which starts at 1

jumpToBar

public void jumpToBar(long bar)

Restarts the metronome at the start of the specified bar, keeping the beat phase unchanged in case it is being synchronized to an external source.

Parameters:

bar - the bar to which the metronome should jump; the first bar is bar 1

getTimeOfBar

public long getTimeOfBar(long bar)

Determine the millisecond timestamp at which a particular bar will occur.

Specified by:

getTimeOfBar in interface Snapshot

Parameters:

bar - the number of the bar whose start time is desired

Returns:

the time at which the specified bar begins, rounded to the nearest millisecond

getBarPhase

public double getBarPhase()

Determine the distance traveled into the current bar as a phase number in the range [0.0, 1.0).

Specified by:

getBarPhase in interface Snapshot

Returns:

the current bar phase

setBarPhase

public void setBarPhase(double phase)

Nudge the metronome so that it has reached the specified part of its current bar. If the value supplied is outside the range of a bar phase (less than zero or greater than or equal to one), it will be normalized to fit into that range by ignoring the non-fractional part.

Parameters:

phase - the desired bar phase, in the range [0.0, 1.0).

getPhrase

public long getPhrase()

Get the current phrase being played.

Specified by:

getPhrase in interface Snapshot

Returns:

the current phrase number, which starts at 1

jumpToPhrase

public void jumpToPhrase(long phrase)

Restarts the metronome at the start of the specified phrase, keeping the beat phase unchanged in case it is being synchronized to an external source.

Parameters:

phrase - the phrase to which the metronome should jump; the first phrase is phrase 1

getTimeOfPhrase

public long getTimeOfPhrase(long phrase)

Determine the millisecond timestamp at which a particular phrase will occur.

Specified by:

getTimeOfPhrase in interface Snapshot

Parameters:

phrase - the number of the phrase whose start time is desired

Returns:

the time at which the specified phrase begins, rounded to the nearest millisecond

getPhrasePhase

public double getPhrasePhase()

Determine the distance traveled into the current phrase as a phase number in the range [0.0, 1.0).

Specified by:

getPhrasePhase in interface Snapshot

Returns:

the current phrase phase

setPhrasePhase

public void setPhrasePhase(double phase)

Nudge the metronome so that it has reached the specified part of its current phrase. If the value supplied is outside the range of a phrase phase (less than zero or greater than or equal to one), it will be normalized to fit into that range by ignoring the non-fractional part.

Parameters:

phase - the desired phrase phase, in the range [0.0, 1.0).

getSnapshot

public Snapshot getSnapshot()

Take a snapshot of the current beat, bar, phrase, and phase state, so coherent calculations about them can be performed with respect to a static point in time.

Returns:

a representation of the detailed metronome state at the current moment

getSnapshot

public Snapshot getSnapshot(long instant)

Take a snapshot of the beat, bar, phrase, and phase state that the metronome would have at the specified millisecond timestamp, so coherent calculations about them can be performed with respect to that static point in time.

Parameters:

instant - the point in time which this snapshot should capture

Returns:

a representation of the detailed metronome state at the specified moment

getMarker

public String getMarker()

Returns the current count of the metronome as "phrase.bar.beat".

Specified by:

getMarker in interface Snapshot

Returns:

a concise textual representation of the current metronome position

getInstant

public long getInstant()

Checks when a snapshot was taken; since you are working with a live metronome, always returns the current time. If you are doing computations around this, you probably want to call getSnapshot() and work with that instead.

Specified by:

getInstant in interface Snapshot

Returns:

the current system time in milliseconds

getBeatWithinBar

public int getBeatWithinBar()

Return the current beat number relative to the start of the bar: the down beat is 1, and the range goes up to the value of getBeatsPerBar().

Specified by:

getBeatWithinBar in interface Snapshot

Returns:

the beat number within the current bar being counted

isDownBeat

public boolean isDownBeat()

Checks whether the current beat is the first beat in its bar.

Specified by:

isDownBeat in interface Snapshot

Returns:

true we are currently in the first beat of a bar

getBeatWithinPhrase

public int getBeatWithinPhrase()

Return the current beat number relative to the start of the phrase: the phrase starts with beat 1, and the range goes up to the value of getBeatsPerBar() times getBarsPerPhrase().

Specified by:

getBeatWithinPhrase in interface Snapshot

Returns:

the beat number within the current phrase being counted

isPhraseStart

public boolean isPhraseStart()

Checks whether the current beat is the first beat in its phrase.

Specified by:

isPhraseStart in interface Snapshot

Returns:

true if we are currently in the first beat of a phrase

getBarWithinPhrase

public int getBarWithinPhrase()

Return the current bar number relative to the start of the phrase: the phrase starts with bar 1, and the range goes up to the value of getBarsPerPhrase().

Specified by:

getBarWithinPhrase in interface Snapshot

Returns:

the bar number within the current phrase being counted

distanceFromBeat

public double distanceFromBeat()

Determine how far in time the metronome is from the closest beat. The result will be positive if the beat has already occurred, and negative if it is coming up.

Specified by:

distanceFromBeat in interface Snapshot

Returns:

the distance in milliseconds from the closest beat on the metronome's timeline

distanceFromBar

public double distanceFromBar()

Determine how far in time the metronome is from its closest bar boundary. The result will be positive if the bar has already started, and negative if it is coming up.

Specified by:

distanceFromBar in interface Snapshot

Returns:

the distance in milliseconds from the closest bar boundary on the metronome's timeline

distanceFromPhrase

public double distanceFromPhrase()

Determine how far in time the metronome is from its closest phrase boundary. The result will be positive if the phrase has already started, and negative if it is coming up.

Specified by:

distanceFromPhrase in interface Snapshot

Returns:

the distance in milliseconds from the closest phrase boundary on the metronome's timeline

toString

public String toString()

Overrides:

toString in class Object