src/Agent.js | API Document

# src/Agent.js

    /**
     * Agent is the central class for beat tracking
     * @class
     */
    export default class Agent {
        /**
         * Constructor
         * @param {Number} tempo - tempo hypothesis of the Agent
         * @param {Number} firstBeatTime - the time of the first beat accepted by this Agent
         * @param {Number} firsteventScore - salience value of the first beat accepted by this Agent
         * @param {Array} agentList - reference to the agent list
         * @param {Object} [params={}] - parameters
         * @param {Number} [params.expiryTime=10] - the time after which an Agent that has not accepted any beat will be destroyed
         * @param {Number} [params.toleranceWndInner=0.04] - the maximum time that a beat can deviate from the predicted beat time without a fork occurring
         * @param {Number} [params.toleranceWndPre=0.15] - the maximum amount by which a beat can be earlier than the predicted beat time, expressed as a fraction of the beat period
         * @param {Number} [params.toleranceWndPost=0.3] - the maximum amount by which a beat can be later than the predicted beat time, expressed as a fraction of the beat period
         * @param {Number} [params.correctionFactor=50] - correction factor for updating beat period
         * @param {Number} [params.maxChange=0.2] - the maximum allowed deviation from the initial tempo, expressed as a fraction of the initial beat period
         * @param {Number} [params.penaltyFactor=0.5] - factor for correcting score, if onset do not coincide precisely with predicted beat time
         */
        constructor(tempo, firstBeatTime, firsteventScore, agentList, params = {}) {
            /**
             * the time after which an Agent that has not accepted any beat will be destroyed
             * @type {Number}
             */
            this.expiryTime = params.expiryTime || 10;
            /**
             * the maximum time that a beat can deviate from the predicted beat time without a fork occurring
             * @type {Number}
             */
            this.toleranceWndInner = params.toleranceWndInner || 0.04;
            /**
             * the maximum amount by which a beat can be earlier than the predicted beat time, expressed as a fraction of the beat period
             * @type {Number}
             */
            this.toleranceWndPre = params.toleranceWndPre || 0.15;
            /**
             * the maximum amount by which a beat can be later than the predicted beat time, expressed as a fraction of the beat period
             * @type {Number}
             */
            this.toleranceWndPost = params.toleranceWndPost || 0.3;

            this.toleranceWndPre *= tempo;
            this.toleranceWndPost *= tempo;

            /**
             * correction factor for updating beat period
             * @type {Number}
             */
            this.correctionFactor = params.correctionFactor || 50;
            /**
             * the maximum allowed deviation from the initial tempo, expressed as a fraction of the initial beat period
             * @type {Number}
             */
            this.maxChange = params.maxChange || 0.2;
            /**
             * factor for correcting score, if onset do not coincide precisely with predicted beat time
             * @type {Number}
             */
            this.penaltyFactor = params.penaltyFactor || 0.5;

            /**
             * the current tempo hypothesis of the Agent, expressed as the beat period
             * @type {Number}
             */
            this.beatInterval = tempo;
            /**
             * the initial tempo hypothesis of the Agent, expressed as the beat period
             * @type {Number}
             */
            this.initialBeatInterval = tempo;
            /**
             * the time of the most recent beat accepted by this Agent
             * @type {Number}
             */
            this.beatTime = firstBeatTime;
            /**
             * the number of beats found by this Agent, including interpolated beats
             * @type {Number}
             */
            this.totalBeatCount = 1;
            /**
             * the array of onsets accepted by this Agent as beats, plus interpolated beats
             * @type {Array}
             */
            this.events = [firstBeatTime];
            /**
             * sum of salience values of the onsets which have been interpreted as beats by this Agent
             * @type {Number}
             */
            this.score = firsteventScore;
            /**
             * reference to the agent list
             * @type {Array}
             */
            this.agentListRef = agentList;
        }
        /**
         * The event time is tested if it is a beat time
         * @param {Number} eventTime - the event time to be tested
         * @param {Number} eventScore - salience values of the event time
         * @return {Boolean} indicate whether the given event time was accepted as a beat time
         */
        considerEvent(eventTime, eventScore) {
            if (eventTime - this.events[this.events.length - 1] > this.expiryTime) {
                this.score = -1;
                return false;
            }

            let beatCount = Math.round( (eventTime - this.beatTime) / this.beatInterval );
            let err = eventTime - this.beatTime - beatCount * this.beatInterval;

            if (beatCount > 0 && err >= -this.toleranceWndPre && err <= this.toleranceWndPost) {
                if (Math.abs(err) > this.toleranceWndInner) {
                    this.agentListRef.push(this.clone());
                }
                this.acceptEvent(eventTime, eventScore, err, beatCount);
                return true;
            }
            return false;
        }
        /**
         * Accept the event time as a beat time, and update the state of the Agent accordingly
         * @param {Number} eventTime - the event time to be accepted
         * @param {Number} eventScore - salience values of the event time
         * @param {Number} err - the difference between the predicted and actual beat times
         * @param {Number} beatCount - the number of beats since the last beat
         */
        acceptEvent(eventTime, eventScore, err, beatCount) {
            this.beatTime = eventTime;
            this.events.push(eventTime);

            let corrErr = err / this.correctionFactor;
            if (Math.abs(this.initialBeatInterval - this.beatInterval - corrErr) < this.maxChange * this.initialBeatInterval) {
                this.beatInterval += corrErr;
            }
            this.totalBeatCount += beatCount;
            let errFactor =  err > 0 ? err / this.toleranceWndPost : err / -this.toleranceWndPre;
            let scoreFactor = 1 - this.penaltyFactor * errFactor;
            this.score += eventScore * scoreFactor;
        }
        /**
         * Interpolates missing beats in the Agent's beat track
         */
        fillBeats() {
            let prevBeat, nextBeat, currentInterval, beats;
            prevBeat = 0;
            if (this.events.length > 2) {
                prevBeat = this.events[0];
            }

            for (let i = 0; i < this.events.length; i++) {
                nextBeat = this.events[i];
                beats = Math.round((nextBeat - prevBeat) / this.beatInterval - 0.01);
                currentInterval = (nextBeat - prevBeat) / beats;
                let k = 0;
                for ( ; beats > 1; beats--) {
                    prevBeat += currentInterval;
                    this.events.splice(i + k, 0, prevBeat);
                    k++;
                }
                prevBeat = nextBeat;
            }
        }
        /**
         * Makes a clone of the Agent
         * @return {Agent} agent's clone
         */
        clone() {
            let newAgent = new Agent();
            newAgent.beatInterval = this.beatInterval;
            newAgent.initialBeatInterval = this.initialBeatInterval;
            newAgent.beatTime = this.beatTime;
            newAgent.totalBeatCount = this.totalBeatCount;
            newAgent.events = this.events.slice();
            newAgent.expiryTime = this.expiryTime;
            newAgent.toleranceWndInner = this.toleranceWndInner;
            newAgent.toleranceWndPre = this.toleranceWndPre;
            newAgent.toleranceWndPost = this.toleranceWndPost;
            newAgent.correctionFactor = this.correctionFactor;
            newAgent.maxChange = this.maxChange;
            newAgent.penaltyFactor = this.penaltyFactor;
            newAgent.score = this.score;
            newAgent.agentListRef = this.agentListRef;

            return newAgent;
        }
    }