at.ofai.music.beatroot

Class Agent

public class Agent extends 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
intbeatCount
The number of beats found by this Agent, including interpolated beats.
doublebeatInterval
The current tempo hypothesis of the Agent, expressed as the beat period in seconds.
doublebeatTime
The time of the most recent beat accepted by this Agent.
protected static doublecorrectionFactor
Controls the reactiveness/inertia balance, i.e. degree of change in the tempo.
static doubleCONF_FACTOR
The slope of the penalty function for onsets which do not coincide precisely with predicted beat times.
static booleandebug
Print debugging information
protected static doubledecayFactor
For scoring Agents in a (non-existent) real-time version (otherwise not used).
static doubleDEFAULT_CORRECTION_FACTOR
The reactiveness/inertia balance, i.e. degree of change in the tempo, is controlled by the correctionFactor variable.
static doubleDEFAULT_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.
EventListevents
The list of Events (onsets) accepted by this Agent as beats, plus interpolated beats.
protected static doubleexpiryTime
The time (in seconds) after which an Agent that has no Event matching its beat predictions will be destroyed.
protected static intidCounter
The identity number of the next created Agent
protected intidNumber
The Agent's unique identity number.
doubleinitialBeatInterval
The initial tempo hypothesis of the Agent, expressed as the beat period in seconds.
protected static doubleinnerMargin
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).
static doubleINNER_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.
static doubleMAX_CHANGE
The maximum allowed deviation from the initial tempo, expressed as a fraction of the initial beat period.
doublephaseScore
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.
doublepostMargin
The size of the outer half-window after the predicted beat time.
doublepreMargin
The size of the outer half-window before the predicted beat time.
static doublePOST_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.
static doublePRE_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.
doubletempoScore
To be used in real-time version?
doubletopScoreTime
How long has this agent been the best?
Constructor Summary
Agent(double ibi)
Constructor: the work is performed by init()
Agent(Agent clone)
Copy constructor.
Method Summary
protected voidaccept(Event e, double err, int beats)
Accept a new Event as a beat time, and update the state of the Agent accordingly.
booleanconsiderAsBeat(Event e, AgentList a)
The given Event is tested for a possible beat time.
protected voidfillBeats()
Interpolates missing beats in the Agent's beat track, starting from the beginning of the piece.
protected voidfillBeats(double start)
Interpolates missing beats in the Agent's beat track.
protected voidinit(double ibi)
Initialise all the fields of this Agent.
voidprint()
Output debugging information about this Agent, at the default (highest) level of detail.
voidprint(int level)
Output debugging information about this Agent.
voidshowTracking(EventList allEvents)
Show detailed debugging output describing the beat tracking behaviour of this agent.
voidshowTracking(EventList allEvents, double level)
Show detailed debugging output describing the beat tracking behaviour of this agent.

Field Detail

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.

beatTime

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

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.

CONF_FACTOR

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

debug

public static boolean debug
Print debugging information

decayFactor

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

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.

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.

events

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

expiryTime

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

idCounter

protected static int idCounter
The identity number of the next created Agent

idNumber

protected int idNumber
The Agent's unique identity number.

initialBeatInterval

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

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).

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.

MAX_CHANGE

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

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.

postMargin

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

preMargin

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

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.

tempoScore

public double tempoScore
To be used in real-time version??

topScoreTime

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

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

accept

protected void accept(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(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

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

showTracking

public void showTracking(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(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)