Skip to content

Commit

Permalink
Beats: Improve comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@Holzhaus
Holzhaus committed Jul 6, 2021
1 parent 87e6ec6 commit 1c6d600
Showing 1 changed file with 63 additions and 56 deletions.
119 changes: 63 additions & 56 deletions src/track/beats.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,22 +22,28 @@ class BeatIterator {
virtual double next() = 0;
};

// Beats is the base class for BPM and beat management classes. It
// provides a specification of all methods a beat-manager class must provide, as
// well as a capability model for representing optional features.
/// Beats is the base class for BPM and beat management classes. It provides a
/// specification of all methods a beat-manager class must provide, as well as
/// a capability model for representing optional features.
class Beats {
public:
virtual ~Beats() = default;

enum Capabilities {
BEATSCAP_NONE = 0x0000,
BEATSCAP_ADDREMOVE = 0x0001, // Add or remove a single beat
BEATSCAP_TRANSLATE = 0x0002, // Move all beat markers earlier or later
BEATSCAP_SCALE = 0x0004, // Scale beat distance by a fixed ratio
BEATSCAP_MOVEBEAT = 0x0008, // Move a single Beat
BEATSCAP_SETBPM = 0x0010 // Set new bpm, beat grid only
BEATSCAP_NONE = 0x0000,
/// Add or remove a single beat
BEATSCAP_ADDREMOVE = 0x0001,
/// Move all beat markers earlier or later
BEATSCAP_TRANSLATE = 0x0002,
/// Scale beat distance by a fixed ratio
BEATSCAP_SCALE = 0x0004,
/// Move a single Beat
BEATSCAP_MOVEBEAT = 0x0008,
/// Set new bpm, beat grid only
BEATSCAP_SETBPM = 0x0010
};
typedef int CapabilitiesFlags; // Allows us to do ORing
/// Allows us to do ORing
typedef int CapabilitiesFlags;

enum BPMScale {
DOUBLE,
Expand All @@ -48,17 +54,18 @@ class Beats {
THREEHALVES,
};

/// Retrieve the capabilities supported by the beats implementation.
virtual Beats::CapabilitiesFlags getCapabilities() const = 0;

// Serialization
/// Serialize beats to QByteArray.
virtual QByteArray toByteArray() const = 0;

// A string representing the version of the beat-processing code that
// produced this Beats instance. Used by BeatsFactory for associating a
// given serialization with the version that produced it.
/// A string representing the version of the beat-processing code that
/// produced this Beats instance. Used by BeatsFactory for associating a
/// given serialization with the version that produced it.
virtual QString getVersion() const = 0;
// A sub-version can be used to represent the preferences used to generate
// the beats object.
/// A sub-version can be used to represent the preferences used to generate
/// the beats object.
virtual QString getSubVersion() const = 0;

////////////////////////////////////////////////////////////////////////////
Expand All @@ -70,62 +77,62 @@ class Beats {
// TODO: We may want to implement these with common code that returns
// the triple of closest, next, and prev.

// Starting from sample dSamples, return the sample of the next beat in the
// track, or -1 if none exists. If dSamples refers to the location of a
// beat, dSamples is returned.
/// Starting from dSamples, return the sample of the next beat in the
/// track, or -1 if none exists. If dSamples refers to the location of a
/// beat, dSamples is returned.
virtual double findNextBeat(double dSamples) const = 0;

// Starting from sample dSamples, return the sample of the previous beat in
// the track, or -1 if none exists. If dSamples refers to the location of
// beat, dSamples is returned.
/// Starting from sample dSamples, return the sample of the previous beat
/// in the track, or -1 if none exists. If dSamples refers to the location
/// of beat, dSamples is returned.
virtual double findPrevBeat(double dSamples) const = 0;

// Starting from sample dSamples, fill the samples of the previous beat
// and next beat. Either can be -1 if none exists. If dSamples refers
// to the location of the beat, the first value is dSamples, and the second
// value is the next beat position. Non- -1 values are guaranteed to be
// even. Returns false if *at least one* sample is -1. (Can return false
// with one beat successfully filled)
/// Starting from sample dSamples, fill the samples of the previous beat
/// and next beat. Either can be -1 if none exists. If dSamples refers to
/// the location of the beat, the first value is dSamples, and the second
/// value is the next beat position. Non- -1 values are guaranteed to be
/// even. Returns false if *at least one* sample is -1. (Can return false
/// with one beat successfully filled)
virtual bool findPrevNextBeats(double dSamples,
double* dpPrevBeatSamples,
double* dpNextBeatSamples,
bool snapToNearBeats) const = 0;

// Starting from sample dSamples, return the sample of the closest beat in
// the track, or -1 if none exists. Non- -1 values are guaranteed to be
// even.
/// Starting from sample dSamples, return the sample of the closest beat in
/// the track, or -1 if none exists. Non- -1 values are guaranteed to be
/// even.
virtual double findClosestBeat(double dSamples) const = 0;

// Find the Nth beat from sample dSamples. Works with both positive and
// negative values of n. Calling findNthBeat with n=0 is invalid. Calling
// findNthBeat with n=1 or n=-1 is equivalent to calling findNextBeat and
// findPrevBeat, respectively. If dSamples refers to the location of a beat,
// then dSamples is returned. If no beat can be found, returns -1.
/// Find the Nth beat from sample dSamples. Works with both positive and
/// negative values of n. Calling findNthBeat with n=0 is invalid. Calling
/// findNthBeat with n=1 or n=-1 is equivalent to calling findNextBeat and
/// findPrevBeat, respectively. If dSamples refers to the location of a
/// beat, then dSamples is returned. If no beat can be found, returns -1.
virtual double findNthBeat(double dSamples, int n) const = 0;

int numBeatsInRange(double dStartSample, double dEndSample) const;

// Find the sample N beats away from dSample. The number of beats may be
// negative and does not need to be an integer.
/// Find the sample N beats away from dSample. The number of beats may be
/// negative and does not need to be an integer.
double findNBeatsFromSample(double fromSample, double beats) const;


// Adds to pBeatsList the position in samples of every beat occurring between
// startPosition and endPosition. BeatIterator must be iterated while
// holding a strong references to the Beats object to ensure that the Beats
// object is not deleted. Caller takes ownership of the returned BeatIterator;
/// Adds to pBeatsList the position in samples of every beat occurring
/// between startPosition and endPosition. BeatIterator must be iterated
/// while holding a strong references to the Beats object to ensure that
/// the Beats object is not deleted. Caller takes ownership of the returned
/// BeatIterator;
virtual std::unique_ptr<BeatIterator> findBeats(double startSample, double stopSample) const = 0;

// Return whether or not a sample lies between startPosition and endPosition
/// Return whether or not a sample lies between startPosition and endPosition.
virtual bool hasBeatInRange(double startSample, double stopSample) const = 0;

// Return the average BPM over the entire track if the BPM is
// valid, otherwise returns -1
/// Return the average BPM over the entire track if the BPM is valid,
/// otherwise returns -1
virtual mixxx::Bpm getBpm() const = 0;

// Return the average BPM over the range of n*2 beats centered around
// curSample. (An n of 4 results in an averaging of 8 beats). Invalid
// BPM returns -1.
/// Return the average BPM over the range of n*2 beats centered around
/// curSample. (An n of 4 results in an averaging of 8 beats). Invalid
/// BPM returns -1.
virtual mixxx::Bpm getBpmAroundPosition(double curSample, int n) const = 0;

virtual audio::SampleRate getSampleRate() const = 0;
Expand All @@ -134,17 +141,17 @@ class Beats {
// Beat mutations
////////////////////////////////////////////////////////////////////////////

// Translate all beats in the song by dNumSamples samples. Beats that lie
// before the start of the track or after the end of the track are not
// removed. Beats instance must have the capability BEATSCAP_TRANSLATE.
/// Translate all beats in the song by dNumSamples samples. Beats that lie
/// before the start of the track or after the end of the track are not
/// removed. Beats instance must have the capability BEATSCAP_TRANSLATE.
virtual BeatsPointer translate(double dNumSamples) const = 0;

// Scale the position of every beat in the song by dScalePercentage. Beats
// class must have the capability BEATSCAP_SCALE.
/// Scale the position of every beat in the song by dScalePercentage. Beats
/// class must have the capability BEATSCAP_SCALE.
virtual BeatsPointer scale(enum BPMScale scale) const = 0;

// Adjust the beats so the global average BPM matches bpm. Beats class must
// have the capability BEATSCAP_SET.
/// Adjust the beats so the global average BPM matches bpm. Beats class
/// must have the capability BEATSCAP_SET.
virtual BeatsPointer setBpm(mixxx::Bpm bpm) = 0;
};

Expand Down

0 comments on commit 1c6d600

Please sign in to comment.