Chris@6: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */ Chris@6: Chris@6: /* Chris@6: Vamp feature extraction plugin for the BeatRoot beat tracker. Chris@6: Chris@6: Centre for Digital Music, Queen Mary, University of London. Chris@6: This file copyright 2011 Simon Dixon, Chris Cannam and QMUL. Chris@6: Chris@6: This program is free software; you can redistribute it and/or Chris@6: modify it under the terms of the GNU General Public License as Chris@6: published by the Free Software Foundation; either version 2 of the Chris@6: License, or (at your option) any later version. See the file Chris@6: COPYING included with this distribution for more information. Chris@6: */ Chris@6: Chris@6: #ifndef _AGENT_H_ Chris@6: #define _AGENT_H_ Chris@6: Chris@6: #include "Event.h" Chris@6: Chris@9: #include Chris@9: Chris@12: #ifdef DEBUG_BEATROOT Chris@12: #include Chris@12: #endif Chris@12: Chris@8: class AgentList; Chris@8: Chris@23: class AgentParameters Chris@23: { Chris@23: public: Chris@23: static const double DEFAULT_POST_MARGIN_FACTOR; Chris@23: static const double DEFAULT_PRE_MARGIN_FACTOR; Chris@23: static const double DEFAULT_MAX_CHANGE; Chris@23: static const double DEFAULT_EXPIRY_TIME; Chris@23: Chris@23: AgentParameters() : Chris@23: postMarginFactor(DEFAULT_POST_MARGIN_FACTOR), Chris@23: preMarginFactor(DEFAULT_PRE_MARGIN_FACTOR), Chris@23: maxChange(DEFAULT_MAX_CHANGE), Chris@23: expiryTime(DEFAULT_EXPIRY_TIME) { } Chris@23: Chris@23: /** The maximum amount by which a beat can be later than the Chris@23: * predicted beat time, expressed as a fraction of the beat Chris@23: * period. */ Chris@23: double postMarginFactor; Chris@23: Chris@23: /** The maximum amount by which a beat can be earlier than the Chris@23: * predicted beat time, expressed as a fraction of the beat Chris@23: * period. */ Chris@23: double preMarginFactor; Chris@23: Chris@23: /** The maximum allowed deviation from the initial tempo, Chris@23: * expressed as a fraction of the initial beat period. */ Chris@23: double maxChange; Chris@23: Chris@23: /** The default value of expiryTime, which is the time (in Chris@23: * seconds) after which an Agent that has no Event matching its Chris@23: * beat predictions will be destroyed. */ Chris@23: double expiryTime; Chris@23: }; Chris@23: Chris@6: /** Agent is the central class for beat tracking. Chris@6: * Each Agent object has a tempo hypothesis, a history of tracked beats, and Chris@6: * a score evaluating the continuity, regularity and salience of its beat track. Chris@6: */ Chris@6: class Agent Chris@6: { Chris@6: public: Chris@23: /** The default value of innerMargin, which is the maximum time Chris@23: * (in seconds) that a beat can deviate from the predicted beat Chris@23: * time without a fork occurring. */ Chris@6: static const double INNER_MARGIN; Chris@6: Chris@23: /** The slope of the penalty function for onsets which do not Chris@23: * coincide precisely with predicted beat times. */ Chris@23: static const double CONF_FACTOR; Chris@6: Chris@23: /** The reactiveness/inertia balance, i.e. degree of change in the Chris@23: * tempo, is controlled by the correctionFactor variable. This Chris@23: * constant defines its default value, which currently is not Chris@23: * subsequently changed. The beat period is updated by the Chris@23: * reciprocal of the correctionFactor multiplied by the Chris@23: * difference between the predicted beat time and matching Chris@23: * onset. */ Chris@6: static const double DEFAULT_CORRECTION_FACTOR; Chris@6: Chris@6: protected: Chris@6: /** The identity number of the next created Agent */ Chris@6: static int idCounter; Chris@6: Chris@23: /** The maximum time (in seconds) that a beat can deviate from the Chris@23: * predicted beat time without a fork occurring (i.e. a 2nd Agent Chris@23: * being created). */ Chris@23: double innerMargin; Chris@6: Chris@23: /** Controls the reactiveness/inertia balance, i.e. degree of Chris@23: * change in the tempo. The beat period is updated by the Chris@23: * reciprocal of the correctionFactor multiplied by the Chris@23: * difference between the predicted beat time and matching Chris@23: * onset. */ Chris@23: double correctionFactor; Chris@6: Chris@23: /** The time (in seconds) after which an Agent that has no Event Chris@23: * matching its beat predictions will be destroyed. */ Chris@23: double expiryTime; Chris@6: Chris@23: /** For scoring Agents in a (non-existent) real-time version Chris@23: * (otherwise not used). */ Chris@23: double decayFactor; Chris@6: Chris@6: public: Chris@6: /** The size of the outer half-window before the predicted beat time. */ Chris@6: double preMargin; Chris@6: Chris@6: /** The size of the outer half-window after the predicted beat time. */ Chris@6: double postMargin; Chris@6: Chris@6: /** The Agent's unique identity number. */ Chris@6: int idNumber; Chris@6: Chris@6: /** To be used in real-time version?? */ Chris@6: double tempoScore; Chris@6: Chris@23: /** Sum of salience values of the Events which have been Chris@23: * interpreted as beats by this Agent, weighted by their nearness Chris@23: * to the predicted beat times. */ Chris@6: double phaseScore; Chris@6: Chris@23: /** How long has this agent been the best? For real-time version; Chris@23: * otherwise not used. */ Chris@6: double topScoreTime; Chris@6: Chris@23: /** The number of beats found by this Agent, including Chris@23: * interpolated beats. */ Chris@6: int beatCount; Chris@6: Chris@23: /** The current tempo hypothesis of the Agent, expressed as the Chris@23: * beat period in seconds. */ Chris@6: double beatInterval; Chris@6: Chris@23: /** The initial tempo hypothesis of the Agent, expressed as the Chris@23: * beat period in seconds. */ Chris@6: double initialBeatInterval; Chris@6: Chris@6: /** The time of the most recent beat accepted by this Agent. */ Chris@6: double beatTime; Chris@23: Chris@23: /** The maximum allowed deviation from the initial tempo, Chris@23: * expressed as a fraction of the initial beat period. */ Chris@23: double maxChange; Chris@6: Chris@23: /** The list of Events (onsets) accepted by this Agent as beats, Chris@23: * plus interpolated beats. */ Chris@6: EventList events; Chris@6: Chris@6: /** Constructor: the work is performed by init() Chris@6: * @param ibi The beat period (inter-beat interval) of the Agent's tempo hypothesis. Chris@6: */ Chris@23: Agent(AgentParameters params, double ibi) : Chris@23: innerMargin(INNER_MARGIN), Chris@23: correctionFactor(DEFAULT_CORRECTION_FACTOR), Chris@23: expiryTime(params.expiryTime), Chris@23: decayFactor(0), Chris@23: preMargin(ibi * params.preMarginFactor), Chris@23: postMargin(ibi * params.postMarginFactor), Chris@23: idNumber(idCounter++), Chris@23: tempoScore(0.0), Chris@23: phaseScore(0.0), Chris@23: topScoreTime(0.0), Chris@23: beatCount(0), Chris@23: beatInterval(ibi), Chris@23: initialBeatInterval(ibi), Chris@23: beatTime(-1.0), Chris@23: maxChange(params.maxChange) { Chris@12: } // constructor Chris@6: Chris@16: Agent *clone() const { Chris@16: Agent *a = new Agent(*this); Chris@16: a->idNumber = idCounter++; Chris@12: return a; Chris@12: } Chris@6: Chris@12: protected: Chris@6: double threshold(double value, double min, double max) { Chris@6: if (value < min) Chris@6: return min; Chris@6: if (value > max) Chris@6: return max; Chris@6: return value; Chris@6: } Chris@6: Chris@8: public: Chris@6: /** Accept a new Event as a beat time, and update the state of the Agent accordingly. Chris@6: * @param e The Event which is accepted as being on the beat. Chris@6: * @param err The difference between the predicted and actual beat times. Chris@6: * @param beats The number of beats since the last beat that matched an Event. Chris@6: */ Chris@15: void accept(Event e, double err, int beats); Chris@6: Chris@6: /** The given Event is tested for a possible beat time. The following situations can occur: Chris@6: * 1) The Agent has no beats yet; the Event is accepted as the first beat. Chris@6: * 2) The Event is beyond expiryTime seconds after the Agent's last 'confirming' beat; the Agent is terminated. Chris@6: * 3) The Event is within the innerMargin of the beat prediction; it is accepted as a beat. Chris@9: * 4) The Event is within the postMargin's of the beat prediction; it is accepted as a beat by this Agent, Chris@6: * and a new Agent is created which doesn't accept it as a beat. Chris@6: * 5) The Event is ignored because it is outside the windows around the Agent's predicted beat time. Chris@6: * @param e The Event to be tested Chris@6: * @param a The list of all agents, which is updated if a new agent is created. Chris@6: * @return Indicate whether the given Event was accepted as a beat by this Agent. Chris@6: */ Chris@8: bool considerAsBeat(Event e, AgentList &a); Chris@6: Chris@6: /** Interpolates missing beats in the Agent's beat track, starting from the beginning of the piece. */ Chris@6: void fillBeats() { Chris@6: fillBeats(-1.0); Chris@6: } // fillBeats()/0 Chris@6: Chris@6: /** Interpolates missing beats in the Agent's beat track. Chris@6: * @param start Ignore beats earlier than this start time Chris@6: */ Chris@6: void fillBeats(double start); Chris@6: Chris@6: }; // class Agent Chris@6: Chris@6: #endif