Superpowered Logo
Getting StartedGuidesAPI Reference
SDKLanguage
Getting StartedGuidesAPI Reference

Class: Analyzer

Overview

Performs bpm and key detection, loudness/peak analysis. Provides compact waveform data (150 points/sec and 1 point/sec resolution), beatgrid information.

Offline analysis example

The following code sandbox shows you how to take an audio file, convert it to the right format and pass the entire song into the Superpowered Analyser to extract information. This example is in Javascript, but the order and way methods are called is common across both web and native.

We display the various wavesform data on canvases and the audio features that are extracted in a table. We also show you how you might start to display the detected data provided by the getNotes() method.

---

How to implement

// Constructor.
let analyzer = new Superpowered.Analyzer(
    44100, // The sample rate of the audio input.
    60     // The length in seconds of the audio input. The analyzer will not be able to process more audio than this. You can change this value in the process() method.
);


// Processes some audio. This method can be used in a real-time audio thread if lengthSeconds is -1. Has no return value.
analyzer.process(
    input, // Pointer to floating point numbers. 32-bit interleaved stereo input.
    128,   // Number of frames to process.
    -1     // If the audio input length may change, set this to the current length. Use -1 otherwise. If this value is not -1, this method can NOT be used in a real-time audio thread.
);


// Makes results from the collected data. This method should NOT be used in a real-time audio thread, because it allocates memory. Has no return value.
analyzer.makeResults(
    60,   // Detected bpm will be more than or equal to this. Recommended value: 60.
    200,  // Detected bpm will be less than or equal to this. Recommended value: 200.
    0,    // If you know the bpm set it here. Use 0 otherwise.
    0,    // Provides a "hint" for the analyzer with this. Use 0 otherwise.
    true, // True: calculate beatgridStartMs. False: save some CPU with not calculating it.
    0,    // Provides a "hint" for the analyzer with this. Use 0 otherwise.
    true, // True: make overviewWaveform. False: save some CPU and memory with not making it.
    true, // True: make the low/mid/high waveforms. False: save some CPU and memory with not making them.
    true  // True: calculate keyIndex. False: save some CPU with not calculating it.
);


analyzer.peakDb;             // Peak volume in decibels. Available after calling makeResults().
analyzer.averageDb;          // Average volume in decibels. Available after calling makeResults().
analyzer.loudpartsAverageDb; // The average volume of the "loud" parts in decibel. (Quiet parts excluded.) Available after calling makeResults().
analyzer.bpm;                // Beats per minute. Available after calling makeResults().
analyzer.beatgridStartMs;    // Where the beatgrid starts (first beat) in milliseconds. Available after calling makeResults().
analyzer.keyIndex;           // The dominant key (chord) of the music. 0..11 are major keys from A to G#, 12..23 are minor keys from A to G#.


analyzer.waveformSize;       // The number of bytes in the peak, average, low, mid and high waveforms and notes.
let w = analyzer.getPeakWaveform();  // Superpowered.Uint8Buffer. 150 points/sec waveform data displaying the peak volume. Each byte represents one "pixel". Available after calling makeResults().
let w = analyzer.getAverageWaveform();  // Superpowered.Uint8Buffer. 150 points/sec waveform data displaying the average volume. Each byte represents one "pixel". Available after calling makeResults().
let w = analyzer.getLowWaveform();      // Superpowered.Uint8Buffer. 150 points/sec waveform data displaying the low frequencies (below 200 Hz). Each byte represents one "pixel". Available after calling makeResults().
let w = analyzer.getMidWaveform();      // Superpowered.Uint8Buffer. 150 points/sec waveform data displaying the mid frequencies (200-1600 Hz). Each byte represents one "pixel". Available after calling makeResults().
let w = analyzer.getHighWaveform();     // Superpowered.Uint8Buffer. 150 points/sec waveform data displaying the high frequencies (above 1600 Hz). Each byte represents one "pixel". Available after calling makeResults().
let n = analyzer.getNotes();            // Superpowered.Uint8Buffer. 150 points/sec data displaying the bass and mid keys. Upper 4 bits are the bass notes 0 to 11, lower 4 bits are the mid notes 0 to 11 (C, C#, D, D#, E, F, F#, G, G#, A, A#, B). The note value is 12 means "unknown note due low volume". Available after calling makeResults().


analyzer.overviewSize;          // The number bytes in overviewWaveform.
let w = analyzer.getOverviewWaveform(); // Superpowered.Uint8Buffer. 1 point/sec waveform data displaying the average volume in decibels. Useful for displaying the overall structure of a track. Int8Array. Each byte has the value of -128 to 0, in decibels.


// Destructor (to free up memory).
analyzer.destruct();


// Helper arrays to display keyIndex in musical, Camelot and Open Key formats:
let musicalChordNames = [
    "A", "A#", "B", "C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", /// major
    "Am", "A#m", "Bm", "Cm", "C#m", "Dm", "D#m", "Em", "Fm", "F#m", "Gm", "G#m" /// minor
];


let camelotChordNames = [
    "11B", "6B", "1B", "8B", "3B", "10B", "5B", "12B", "7B", "2B", "9B", "4B", /// major
    "8A", "3A", "10A", "5A", "12A", "7A", "2A", "9A", "4A", "11A", "6A", "1A" /// minor
];


let openkeyChordNames = [
    "4d", "11d", "6d", "1d", "8d", "3d", "10d", "5d", "12d", "7d", "2d", "9d", /// major
    "1m", "8m", "3m", "10m", "5m", "12m", "7m", "2m", "9m", "4m", "11m", "6m" /// minor
];
#include "SuperpoweredAnalyzer.h"


// Constructor.
Superpowered::Analyzer *analyzer = new Superpowered::Analyzer(
    44100, // The sample rate of the audio input.
    60     // The length in seconds of the audio input. The analyzer will not be able to process more audio than this. You can change this value in the process() method.
);


// Processes some audio. This method can be used in a real-time audio thread if lengthSeconds is -1. Has no return value.
analyzer->process(
    input, // Pointer to floating point numbers. 32-bit interleaved stereo input.
    128,   // Number of frames to process.
    -1     // If the audio input length may change, set this to the current length. Use -1 otherwise. If this value is not -1, this method can NOT be used in a real-time audio thread.
);


// Makes results from the collected data. This method should NOT be used in a real-time audio thread, because it allocates memory. Has no return value.
analyzer->makeResults(
    60,   // Detected bpm will be more than or equal to this. Recommended value: 60.
    200,  // Detected bpm will be less than or equal to this. Recommended value: 200.
    0,    // If you know the bpm set it here. Use 0 otherwise.
    0,    // Provides a "hint" for the analyzer with this. Use 0 otherwise.
    true, // True: calculate beatgridStartMs. False: save some CPU with not calculating it.
    0,    // Provides a "hint" for the analyzer with this. Use 0 otherwise.
    true, // True: make overviewWaveform. False: save some CPU and memory with not making it.
    true, // True: make the low/mid/high waveforms. False: save some CPU and memory with not making them.
    true  // True: calculate keyIndex. False: save some CPU with not calculating it.
);


analyzer->peakDb;             // Peak volume in decibels. Available after calling makeResults().
analyzer->averageDb;          // Average volume in decibels. Available after calling makeResults().
analyzer->loudpartsAverageDb; // The average volume of the "loud" parts in decibel. (Quiet parts excluded.) Available after calling makeResults().
analyzer->bpm;                // Beats per minute. Available after calling makeResults().
analyzer->beatgridStartMs;    // Where the beatgrid starts (first beat) in milliseconds. Available after calling makeResults().
analyzer->keyIndex;           // The dominant key (chord) of the music. 0..11 are major keys from A to G#, 12..23 are minor keys from A to G#. Check the static constants in this header for musical, Camelot and Open Key notations.


analyzer->waveformSize;       // The number of bytes in the peak, average, low, mid and high waveforms and notes.
unsigned char *w = analyzer->getPeakWaveform();  // 150 points/sec waveform data displaying the peak volume. Each byte represents one "pixel". Available after calling makeResults().
unsigned char *w = analyzer->getAverageWaveform();  // 150 points/sec waveform data displaying the average volume. Each byte represents one "pixel". Available after calling makeResults().
unsigned char *w = analyzer->getLowWaveform();      // 150 points/sec waveform data displaying the low frequencies (below 200 Hz). Each byte represents one "pixel". Available after calling makeResults().
unsigned char *w = analyzer->getMidWaveform();      // 150 points/sec waveform data displaying the mid frequencies (200-1600 Hz). Each byte represents one "pixel". Available after calling makeResults().
unsigned char *w = analyzer->getHighWaveform();     // 150 points/sec waveform data displaying the high frequencies (above 1600 Hz). Each byte represents one "pixel". Available after calling makeResults().
unsigned char *n = analyzer->getNotes();            // Superpowered.Uint8Buffer. 150 points/sec data displaying the bass and mid keys. Upper 4 bits are the bass notes 0 to 11, lower 4 bits are the mid notes 0 to 11 (C, C#, D, D#, E, F, F#, G, G#, A, A#, B). The note value is 12 means "unknown note due low volume". Available after calling makeResults().


analyzer->overviewSize;          // The number bytes in overviewWaveform.
char *w = analyzer->getOverviewWaveform(); // 1 point/sec waveform data displaying the average volume in decibels. Useful for displaying the overall structure of a track. Int8Array. Each byte has the value of -128 to 0, in decibels.


// Helper arrays to display keyIndex in musical, Camelot and Open Key formats:
const char *musicalChordNames[24] = {
    "A", "A#", "B", "C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", /// major
    "Am", "A#m", "Bm", "Cm", "C#m", "Dm", "D#m", "Em", "Fm", "F#m", "Gm", "G#m" /// minor
};


const char *camelotChordNames[24] = {
    "11B", "6B", "1B", "8B", "3B", "10B", "5B", "12B", "7B", "2B", "9B", "4B", /// major
    "8A", "3A", "10A", "5A", "12A", "7A", "2A", "9A", "4A", "11A", "6A", "1A" /// minor
};


const char *openkeyChordNames[24] = {
    "4d", "11d", "6d", "1d", "8d", "3d", "10d", "5d", "12d", "7d", "2d", "9d", /// major
    "1m", "8m", "3m", "10m", "5m", "12m", "7m", "2m", "9m", "4m", "11m", "6m" /// minor
};

Properties

AttributeTypeDescription
averageDbNumberAverage volume in decibels. Available after calling makeResults().
averageDbfloatAverage volume in decibels. Available after calling makeResults().
beatgridStartMsNumberWhere the beatgrid starts (first beat) in milliseconds. Available after calling makeResults().
beatgridStartMsfloatWhere the beatgrid starts (first beat) in milliseconds. Available after calling makeResults().
bpmNumberBeats per minute. Available after calling makeResults().
bpmfloatBeats per minute. Available after calling makeResults().
keyIndexNumberThe dominant key (chord) of the music. 0..11 are major keys from A to G#, 12..23 are minor keys from A to G#. Check the static constants in this header for musical, Camelot and Open Key notations.
keyIndexintThe dominant key (chord) of the music. 0..11 are major keys from A to G#, 12..23 are minor keys from A to G#. Check the static constants in this header for musical, Camelot and Open Key notations.
loudpartsAverageDbNumberThe average volume of the "loud" parts in decibel. (Quiet parts excluded.) Available after calling makeResults().
loudpartsAverageDbfloatThe average volume of the "loud" parts in decibel. (Quiet parts excluded.) Available after calling makeResults().
overviewSizeNumberThe number bytes in overviewWaveform.
overviewSizeintThe number bytes in overviewWaveform.
peakDbNumberPeak volume in decibels. Available after calling makeResults().
peakDbfloatPeak volume in decibels. Available after calling makeResults().
waveformSizeNumberThe number of bytes in the peak, average, low, mid and high waveforms and notes.
waveformSizeintThe number of bytes in the peak, average, low, mid and high waveforms and notes.

Methods

  • constructor

    METHOD
    Creates instance of Analyzer class
    Parameters
    NameTypeDescription
    samplerateNumberThe sample rate of the audio input.
    lengthSecondsNumberThe length in seconds of the audio input. The analyzer will not be able to process more audio than this. You can change this value in the process() method.
    Returns
    TypeDescription
    Superpowered.AnalyzerThe constructed instance.

  • constructor

    METHOD
    Creates instance of Analyzer class
    Parameters
    NameTypeDefaultDescription
    samplerateunsigned intThe sample rate of the audio input.
    lengthSecondsintThe length in seconds of the audio input. The analyzer will not be able to process more audio than this. You can change this value in the process() method.
    Returns
    TypeDescription
    Superpowered::AnalyzerThe constructed instance.

  • destruct

    METHOD
    Destructor to free Linear Memory.
    Parameters
    None
    Returns
    None

  • getAverageWaveform

    METHOD
    Returns with 150 points/sec waveform data displaying the average volume. Each number is an unsigned byte (8-bits), representing one "pixel". Available after calling makeResults().
    Parameters
    NameTypeDescription
    takeOwnershipBooleanIf true, you take ownership on the data, so don't forget to call the free() method of the returned Superpowered.Uint8Buffer the memory to prevent memory leaks.
    Returns
    TypeDescription
    Superpowered.Uint8Buffer150 points/sec waveform data

  • getAverageWaveform

    METHOD
    Returns with 150 points/sec waveform data displaying the average volume. Each number is an unsigned byte (8-bits), representing one "pixel". Available after calling makeResults().
    Parameters
    NameTypeDefaultDescription
    takeOwnershipboolfalseIf true, you take ownership on the data, so don't forget to free() the memory to prevent memory leaks. Use _aligned_free() on Windows.
    Returns
    TypeDescription
    unsigned char *150 points/sec waveform data

  • getHighWaveform

    METHOD
    Returns with 150 points/sec waveform data displaying the high frequencies above 1600 Hz. Each number is an unsigned byte (8-bits), representing one "pixel". Available after calling makeResults().
    Parameters
    NameTypeDescription
    takeOwnershipBooleanIf true, you take ownership on the data, so don't forget to call the free() method of the returned Superpowered.Uint8Buffer the memory to prevent memory leaks.
    Returns
    TypeDescription
    Superpowered.Uint8Buffer150 points/sec waveform data

  • getHighWaveform

    METHOD
    Returns with 150 points/sec waveform data displaying the high frequencies above 1600 Hz. Each number is an unsigned byte (8-bits), representing one "pixel". Available after calling makeResults().
    Parameters
    NameTypeDefaultDescription
    takeOwnershipboolfalseIf true, you take ownership on the data, so don't forget to free() the memory to prevent memory leaks. Use _aligned_free() on Windows.
    Returns
    TypeDescription
    unsigned char *150 points/sec waveform data

  • getLowWaveform

    METHOD
    Returns with 150 points/sec waveform data displaying the low frequencies below 200 Hz. Each number is an unsigned byte (8-bits), representing one "pixel". Available after calling makeResults().
    Parameters
    NameTypeDescription
    takeOwnershipBooleanIf true, you take ownership on the data, so don't forget to call the free() method of the returned Superpowered.Uint8Buffer the memory to prevent memory leaks.
    Returns
    TypeDescription
    Superpowered.Uint8Buffer150 points/sec waveform data

  • getLowWaveform

    METHOD
    Returns with 150 points/sec waveform data displaying the low frequencies below 200 Hz. Each number is an unsigned byte (8-bits), representing one "pixel". Available after calling makeResults().
    Parameters
    NameTypeDefaultDescription
    takeOwnershipboolfalseIf true, you take ownership on the data, so don't forget to free() the memory to prevent memory leaks. Use _aligned_free() on Windows.
    Returns
    TypeDescription
    unsigned char *150 points/sec waveform data

  • getMidWaveform

    METHOD
    Returns with 150 points/sec waveform data displaying the frequencies between 200 and 1600 Hz. Each number is an unsigned byte (8-bits), representing one "pixel". Available after calling makeResults().
    Parameters
    NameTypeDescription
    takeOwnershipBooleanIf true, you take ownership on the data, so don't forget to call the free() method of the returned Superpowered.Uint8Buffer the memory to prevent memory leaks.
    Returns
    TypeDescription
    Superpowered.Uint8Buffer150 points/sec waveform data

  • getMidWaveform

    METHOD
    Returns with 150 points/sec waveform data displaying the frequencies between 200 and 1600 Hz. Each number is an unsigned byte (8-bits), representing one "pixel". Available after calling makeResults().
    Parameters
    NameTypeDefaultDescription
    takeOwnershipboolfalseIf true, you take ownership on the data, so don't forget to free() the memory to prevent memory leaks. Use _aligned_free() on Windows.
    Returns
    TypeDescription
    unsigned char *150 points/sec waveform data

  • getNotes

    METHOD
    Returns with 150 points/sec waveform data displaying the bass and mid keys. Each bytes is further divided to 4-4 bits, representing one "pixel". Upper 4 bits are the bass notes 0 to 11, lower 4 bits are the mid notes 0 to 11 (C, C#, D, D#, E, F, F#, G, G#, A, A#, B). The note value is 12 means "unknown note due low volume". Available after calling makeResults().
    Parameters
    NameTypeDescription
    takeOwnershipBooleanIf true, you take ownership on the data, so don't forget to call the free() method of the returned Superpowered.Uint8Buffer the memory to prevent memory leaks.
    Returns
    TypeDescription
    Superpowered.Uint8Buffer150 points/sec waveform data

  • getNotes

    METHOD
    Returns with 150 points/sec waveform data displaying the bass and mid keys. Each bytes is further divided to 4-4 bits, representing one "pixel". Upper 4 bits are the bass notes 0 to 11, lower 4 bits are the mid notes 0 to 11 (C, C#, D, D#, E, F, F#, G, G#, A, A#, B). The note value is 12 means "unknown note due low volume". Available after calling makeResults().
    Parameters
    NameTypeDefaultDescription
    takeOwnershipboolfalseIf true, you take ownership on the data, so don't forget to free() the memory to prevent memory leaks. Use _aligned_free() on Windows.
    Returns
    TypeDescription
    unsigned char *150 points/sec waveform data

  • getOverviewWaveform

    METHOD
    Returns with 1 point/sec waveform data displaying the average volume in decibels. Useful for displaying the overall structure of a track. Each number is a signed byte (8-bits), representing one "pixel". Values are between -128 and 0, in decibels. Available after calling makeResults().
    Parameters
    NameTypeDescription
    takeOwnershipBooleanIf true, you take ownership on the data, so don't forget to call the free() method of the returned Superpowered.Uint8Buffer the memory to prevent memory leaks.
    Returns
    TypeDescription
    Superpowered.Uint8Buffer150 points/sec waveform data

  • getOverviewWaveform

    METHOD
    Returns with 1 point/sec waveform data displaying the average volume in decibels. Useful for displaying the overall structure of a track. Each number is a signed byte (8-bits), representing one "pixel". Values are between -128 and 0, in decibels. Available after calling makeResults().
    Parameters
    NameTypeDefaultDescription
    takeOwnershipboolfalseIf true, you take ownership on the data, so don't forget to free() the memory to prevent memory leaks. Use _aligned_free() on Windows.
    Returns
    TypeDescription
    unsigned char *150 points/sec waveform data

  • getPeakWaveform

    METHOD
    Returns with 150 points/sec waveform data displaying the peak volume. Each number is an unsigned byte (8-bits), representing one "pixel". Available after calling makeResults().
    Parameters
    NameTypeDescription
    takeOwnershipBooleanIf true, you take ownership on the data, so don't forget to call the free() method of the returned Superpowered.Uint8Buffer the memory to prevent memory leaks.
    Returns
    TypeDescription
    Superpowered.Uint8Buffer150 points/sec waveform data

  • getPeakWaveform

    METHOD
    Returns with 150 points/sec waveform data displaying the peak volume. Each number is an unsigned byte (8-bits), representing one "pixel". Available after calling makeResults().
    Parameters
    NameTypeDefaultDescription
    takeOwnershipboolfalseIf true, you take ownership on the data, so don't forget to free() the memory to prevent memory leaks. Use _aligned_free() on Windows.
    Returns
    TypeDescription
    unsigned char *150 points/sec waveform data

  • makeResults

    METHOD
    Makes results from the collected data. This method should NOT be used in a real-time audio thread, because it allocates memory. It is difficult for the algorithm to determine the time signature of music, so if the calculated BPM is far from the one expected, please provide a shorter range through the minimumBpm and maximumBpm or aroundBpm arguments.
    Parameters
    NameTypeDescription
    minimumBpmNumberDetected bpm will be more than or equal to this. Recommended value: 60.
    maximumBpmNumberDetected bpm will be less than or equal to this. Recommended value: 200.
    knownBpmNumberIf you know the bpm set it here. Use 0 otherwise.
    aroundBpmNumberProvides a "hint" for the analyzer with this. Use 0 otherwise.
    getBeatgridStartMsBooleanTrue: calculate beatgridStartMs. False: save some CPU with not calculating it.
    aroundBeatgridStartMsNumberProvides a "hint" for the analyzer with this. Use 0 otherwise.
    makeOverviewWaveformBooleanTrue: make overviewWaveform. False: save some CPU and memory with not making it.
    makeLowMidHighWaveformsBooleanTrue: make the low/mid/high waveforms. False: save some CPU and memory with not making them.
    getKeyIndexBooleanTrue: calculate keyIndex. False: save some CPU with not calculating it.
    Returns
    None

  • makeResults

    METHOD
    Makes results from the collected data. This method should NOT be used in a real-time audio thread, because it allocates memory. It is difficult for the algorithm to determine the time signature of music, so if the calculated BPM is far from the one expected, please provide a shorter range through the minimumBpm and maximumBpm or aroundBpm arguments.
    Parameters
    NameTypeDefaultDescription
    minimumBpmfloatDetected bpm will be more than or equal to this. Recommended value: 60.
    maximumBpmfloatDetected bpm will be less than or equal to this. Recommended value: 200.
    knownBpmfloatIf you know the bpm set it here. Use 0 otherwise.
    aroundBpmfloatProvides a "hint" for the analyzer with this. Use 0 otherwise.
    getBeatgridStartMsboolTrue: calculate beatgridStartMs. False: save some CPU with not calculating it.
    aroundBeatgridStartMsfloatProvides a "hint" for the analyzer with this. Use 0 otherwise.
    makeOverviewWaveformboolTrue: make overviewWaveform. False: save some CPU and memory with not making it.
    makeLowMidHighWaveformsboolTrue: make the low/mid/high waveforms. False: save some CPU and memory with not making them.
    getKeyIndexboolTrue: calculate keyIndex. False: save some CPU with not calculating it.
    Returns
    None

  • process

    METHOD
    Processes some audio. This method can be used in a real-time audio thread if lengthSeconds is -1.
    Parameters
    NameTypeDescription
    inputNumber (pointer in Linear Memory)32-bit interleaved stereo input. Special case: set to 0 to empty all buffered content.
    numberOfFramesNumberNumber of frames to process.
    lengthSecondsNumberIf the audio input length may change, set this to the current length. Use -1 otherwise. If this value is not -1, this method can NOT be used in a real-time audio thread.
    Returns
    None

  • process

    METHOD
    Processes some audio. This method can be used in a real-time audio thread if lengthSeconds is -1.
    Parameters
    NameTypeDefaultDescription
    inputfloat *32-bit interleaved stereo input. Special case: set to 0 to empty all buffered content.
    numberOfFramesunsigned intNumber of frames to process.
    lengthSecondsint-1If the audio input length may change, set this to the current length. Use -1 otherwise. If this value is not -1, this method can NOT be used in a real-time audio thread.
    Returns
    None
v2.7.2