at.ofai.music.beatroot
Class Agent

java.lang.Object
  at.ofai.music.beatroot.Agent

public class Agent
extends java.lang.Object

Agent is the central class for beat tracking. Each Agent object has a tempo hypothesis, a history of tracked beats, and a score evaluating the continuity, regularity and salience of its beat track.

Field Summary

int	beatCount The number of beats found by this Agent, including interpolated beats.
double	beatInterval The current tempo hypothesis of the Agent, expressed as the beat period in seconds.
double	beatTime The time of the most recent beat accepted by this Agent.
static double	CONF_FACTOR The slope of the penalty function for onsets which do not coincide precisely with predicted beat times.
protected static double	correctionFactor Controls the reactiveness/inertia balance, i.e.
static boolean	debug Print debugging information
protected static double	decayFactor For scoring Agents in a (non-existent) real-time version (otherwise not used).
static double	DEFAULT_CORRECTION_FACTOR The reactiveness/inertia balance, i.e.
static double	DEFAULT_EXPIRY_TIME The default value of expiryTime, which is the time (in seconds) after which an Agent that has no Event matching its beat predictions will be destroyed.
at.ofai.music.util.EventList	events The list of Events (onsets) accepted by this Agent as beats, plus interpolated beats.
protected static double	expiryTime The time (in seconds) after which an Agent that has no Event matching its beat predictions will be destroyed.
protected static int	idCounter The identity number of the next created Agent
protected int	idNumber The Agent's unique identity number.
double	initialBeatInterval The initial tempo hypothesis of the Agent, expressed as the beat period in seconds.
static double	INNER_MARGIN The default value of innerMargin, which is the maximum time (in seconds) that a beat can deviate from the predicted beat time without a fork occurring.
protected static double	innerMargin The maximum time (in seconds) that a beat can deviate from the predicted beat time without a fork occurring (i.e.
static double	MAX_CHANGE The maximum allowed deviation from the initial tempo, expressed as a fraction of the initial beat period.
double	phaseScore Sum of salience values of the Events which have been interpreted as beats by this Agent, weighted by their nearness to the predicted beat times.
static double	POST_MARGIN_FACTOR The maximum amount by which a beat can be later than the predicted beat time, expressed as a fraction of the beat period.
double	postMargin The size of the outer half-window after the predicted beat time.
static double	PRE_MARGIN_FACTOR The maximum amount by which a beat can be earlier than the predicted beat time, expressed as a fraction of the beat period.
double	preMargin The size of the outer half-window before the predicted beat time.
double	tempoScore To be used in real-time version??
double	topScoreTime How long has this agent been the best? For real-time version; otherwise not used.

Constructor Summary

Agent(Agent clone)
Copy constructor.

Agent(double ibi)
Constructor: the work is performed by init()

Method Summary

protected void	accept(at.ofai.music.util.Event e, double err, int beats) Accept a new Event as a beat time, and update the state of the Agent accordingly.
boolean	considerAsBeat(at.ofai.music.util.Event e, AgentList a) The given Event is tested for a possible beat time.
protected void	fillBeats() Interpolates missing beats in the Agent's beat track, starting from the beginning of the piece.
protected void	fillBeats(double start) Interpolates missing beats in the Agent's beat track.
protected void	init(double ibi) Initialise all the fields of this Agent.
void	print() Output debugging information about this Agent, at the default (highest) level of detail.
void	print(int level) Output debugging information about this Agent.
void	showTracking(at.ofai.music.util.EventList allEvents) Show detailed debugging output describing the beat tracking behaviour of this agent.
void	showTracking(at.ofai.music.util.EventList allEvents, double level) Show detailed debugging output describing the beat tracking behaviour of this agent.

Methods inherited from class java.lang.Object

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

Field Detail

debug

public static boolean debug

Print debugging information

POST_MARGIN_FACTOR

public static double POST_MARGIN_FACTOR

The maximum amount by which a beat can be later than the predicted beat time, expressed as a fraction of the beat period.

PRE_MARGIN_FACTOR

public static double PRE_MARGIN_FACTOR

The maximum amount by which a beat can be earlier than the predicted beat time, expressed as a fraction of the beat period.

INNER_MARGIN

public static final double INNER_MARGIN

The default value of innerMargin, which is the maximum time (in seconds) that a beat can deviate from the predicted beat time without a fork occurring.

See Also:

Constant Field Values

MAX_CHANGE

public static double MAX_CHANGE

The maximum allowed deviation from the initial tempo, expressed as a fraction of the initial beat period.

CONF_FACTOR

public static double CONF_FACTOR

The slope of the penalty function for onsets which do not coincide precisely with predicted beat times.

DEFAULT_CORRECTION_FACTOR

public static final double DEFAULT_CORRECTION_FACTOR

The reactiveness/inertia balance, i.e. degree of change in the tempo, is controlled by the correctionFactor variable. This constant defines its default value, which currently is not subsequently changed. The beat period is updated by the reciprocal of the correctionFactor multiplied by the difference between the predicted beat time and matching onset.

See Also:

Constant Field Values

DEFAULT_EXPIRY_TIME

public static final double DEFAULT_EXPIRY_TIME

The default value of expiryTime, which is the time (in seconds) after which an Agent that has no Event matching its beat predictions will be destroyed.

See Also:

Constant Field Values

idCounter

protected static int idCounter

The identity number of the next created Agent

innerMargin

protected static double innerMargin

The maximum time (in seconds) that a beat can deviate from the predicted beat time without a fork occurring (i.e. a 2nd Agent being created).

correctionFactor

protected static double correctionFactor

Controls the reactiveness/inertia balance, i.e. degree of change in the tempo. The beat period is updated by the reciprocal of the correctionFactor multiplied by the difference between the predicted beat time and matching onset.

expiryTime

protected static double expiryTime

The time (in seconds) after which an Agent that has no Event matching its beat predictions will be destroyed.

decayFactor

protected static double decayFactor

For scoring Agents in a (non-existent) real-time version (otherwise not used).

preMargin

public double preMargin

The size of the outer half-window before the predicted beat time.

postMargin

public double postMargin

The size of the outer half-window after the predicted beat time.

idNumber

protected int idNumber

The Agent's unique identity number.

tempoScore

public double tempoScore

To be used in real-time version??

phaseScore

public double phaseScore

Sum of salience values of the Events which have been interpreted as beats by this Agent, weighted by their nearness to the predicted beat times.

topScoreTime

public double topScoreTime

How long has this agent been the best? For real-time version; otherwise not used.

beatCount

public int beatCount

The number of beats found by this Agent, including interpolated beats.

beatInterval

public double beatInterval

The current tempo hypothesis of the Agent, expressed as the beat period in seconds.

initialBeatInterval

public double initialBeatInterval

The initial tempo hypothesis of the Agent, expressed as the beat period in seconds.

beatTime

public double beatTime

The time of the most recent beat accepted by this Agent.

events

public at.ofai.music.util.EventList events

The list of Events (onsets) accepted by this Agent as beats, plus interpolated beats.

Constructor Detail

Agent

public Agent(double ibi)

Constructor: the work is performed by init()

Parameters:

ibi - The beat period (inter-beat interval) of the Agent's tempo hypothesis.

Agent

public Agent(Agent clone)

Copy constructor.

Parameters:

clone - The Agent to duplicate.

Method Detail

init

protected void init(double ibi)

Initialise all the fields of this Agent.

Parameters:

ibi - The initial tempo hypothesis of the Agent.

print

public void print()

Output debugging information about this Agent, at the default (highest) level of detail.

print

public void print(int level)

Output debugging information about this Agent.

Parameters:

level - The level of detail in debugging

accept

protected void accept(at.ofai.music.util.Event e,
                      double err,
                      int beats)

Accept a new Event as a beat time, and update the state of the Agent accordingly.

Parameters:

e - The Event which is accepted as being on the beat.

err - The difference between the predicted and actual beat times.

beats - The number of beats since the last beat that matched an Event.

considerAsBeat

public boolean considerAsBeat(at.ofai.music.util.Event e,
                              AgentList a)

The given Event is tested for a possible beat time. The following situations can occur: 1) The Agent has no beats yet; the Event is accepted as the first beat. 2) The Event is beyond expiryTime seconds after the Agent's last 'confirming' beat; the Agent is terminated. 3) The Event is within the innerMargin of the beat prediction; it is accepted as a beat. 4) The Event is within the outerMargin's of the beat prediction; it is accepted as a beat by this Agent, and a new Agent is created which doesn't accept it as a beat. 5) The Event is ignored because it is outside the windows around the Agent's predicted beat time.

Parameters:

e - The Event to be tested

a - The list of all agents, which is updated if a new agent is created.

Returns:

Indicate whether the given Event was accepted as a beat by this Agent.

fillBeats

protected void fillBeats()

Interpolates missing beats in the Agent's beat track, starting from the beginning of the piece.

fillBeats

protected void fillBeats(double start)

Interpolates missing beats in the Agent's beat track.

Parameters:

start - Ignore beats earlier than this start time

showTracking

public void showTracking(at.ofai.music.util.EventList allEvents)

Show detailed debugging output describing the beat tracking behaviour of this agent. Calls showTracking()/1 with a default metrical level of 1.

Parameters:

allEvents - An EventList of all onsets

showTracking

public void showTracking(at.ofai.music.util.EventList allEvents,
                         double level)

Show detailed debugging output describing the beat tracking behaviour of this agent.

Parameters:

allEvents - An EventList of all onsets

level - The metrical level of beat tracking relative to the notated beat (used to count beats)