Superpowered Logo
Getting StartedGuidesAPI Reference
SDKLanguage
Getting StartedGuidesAPI Reference

Class: AutomaticVocalPitchCorrection

Interactive example

Get some headphone on, clear your throat and hit microphone on the input stage! It'd be rude to not give singing a try, wouldn't it?

Overview

The Automatic Vocal Pitch Correction (Automatic Tune) class applies realtime pitch correction to an input signal based on the following three parameters:

  • scale - Which scale (or set of custom notes) to snap the input signal to.
  • range - Tells the effect what frequency range it's dealing with to improve accuracy.
  • speed - How fast the pitch transform is applied.
  • clamp - Controls the incoming pitch variance threshold for switching to a new note for the output..

In this example, we're taking the output from the AutomaticVocalPitchCorrection and feeding it into a Superpowered Compressor, Superpowered Reverb and finally to the speakers.

One instance allocates around 20kb memory.

Please note

The Superpowered Automatic Vocal Pitch Correction effect will always work best with simple monophonic tones, such as the human voice. It will struggle with the piano due to the number of harmonics present in the notes.

We’d like to draw attention to the clamp setting, which we find sounds best when set to LOOSE. This is to prevent the corrections from changing too quickly and will sound more natural. We advise testing different clamp settings using your microphone on the interactive audio example above.

It's also worth noting that this effect is not designed to produce the heavily overtuned robotic sound you may associate with this kind of effect category. Setting the speed property to EXTREME and clamp to OFF will put the effect in it's most extreme configuration.

Overall, our pitch correction algorithms are quite new. We believe the audio quality is of a good standard but we are striving to continue to improve over time.

Sound sources

This effect is designed for monophonic audio vocal sources. By monophonic, we mean any sound that has a single dominant frequency, such as a single solo human voice. A choir of singers on the other hand has potentially many simultaneous notes being sang at once, so can be considered polyphonic. The autotune cannot process polyphonic audio reliably, so please consider carefully where and when this effect is being applied in your application. That being said, there's nothing wrong with experimentation, maybe you'll find some interesting results.

Scales

The effect allows you to define the musical notes (key) that you'd like the input signal to snap to. You can either set to common major and minor keys by setting scale with one of the constants, or your can define your own note range by setting scale to CUSTOM and then using the setCustomScaleNote() method to set each required note enabled or disabled between C and B (on all octaves), with note numbers 0 - 11.

Range and speed

By supplying range, you'll find the effect if more capable of snapping the input source to the desired notes. It's not always possible to know the range of the input vocals, so we've provided WIDE, which tries it's best with most of the vocal ranges you can throw at it, but might still struggle with the death metal growls.

The speed parameter defines how quickly the pitch transform takes place on the original signal ranging from SUBTLE for a more natural sound, MEDIUM and EXTREME for a robotic more pronounced stylised sound.

Altering frequencyOfA will set the reference pitch the effect is using internally between 470Hz and 410Hz

Clamp range

As of Superpowered v2.6.2, you can now define the clamp parameter. This parameter defines how much pitch varience must be detected before the effect with repitch up or down to the next note. The parameter defaults to LOOSE, which will swich to another not if the incoming pitch detected is 0.7 semitones above or below from the currently held pitch. In other words, it establishs a stable area 1.4 semitones wide centered around the current note.

How to implement

You'll find the constants required for scale, range, clamp and speed under the main class. Please use these when setting properties, as demonstrated below.

Please also not that unlike the other effect, this class does not have a return value from the process method.

class SuperpoweredAutomaticVocalPitchCorrectionProcessor extends SuperpoweredWebAudio.AudioWorkletProcessor {
  // Runs after the constructor
  onReady() {
    this.effect = new this.Superpowered.AutomaticVocalPitchCorrection(
      this.samplerate
    );


    this.effect.scale = this.Superpowered.AutomaticVocalPitchCorrection.DMINOR;
    this.effect.range = this.Superpowered.AutomaticVocalPitchCorrection.ALTO;
    this.effect.speed = this.Superpowered.AutomaticVocalPitchCorrection.MEDIUM;
    this.effect.clamp = this.Superpowered.AutomaticVocalPitchCorrection.LOOSE;
    this.sendMessageToMainScope({ event: 'ready' });
  }


  // Runs before the node is destroyed.
  onDestruct() {
    this.effect.destruct();
  }


  applyCustomNotes(activeNotes) {
    // scaled to midi note numbers
    for (let index = 0; index < 12; index++) {
        if (activeNotes.includes(index+48)) {
            this.effect.setCustomScaleNote(
                index,   // The note (between 0..11).
                1 // Note enabled or not.
            );
        } else {
            this.effect.setCustomScaleNote(
                index,   // The note (between 0..11).
                0 // Note enabled or not.
            );
        }
    }
  }


  // messages are received from the main scope through this method.
  onMessageFromMainScope(message) {


    if (typeof message.range !== "undefined") this.effect.range = this.Superpowered.AutomaticVocalPitchCorrection[message.range];


    if (typeof message.speed !== "undefined") this.effect.speed = this.Superpowered.AutomaticVocalPitchCorrection[message.speed];


    if (typeof message.clamp !== "undefined") this.effect.clamp = this.Superpowered.AutomaticVocalPitchCorrection[message.clamp];


    if (typeof message.frequencyOfA !== "undefined") this.effect.frequencyOfA = message.frequencyOfA;


    if (typeof message.scale !== "undefined") this.effect.scale = this.Superpowered.AutomaticVocalPitchCorrection[message.scale];


    if (typeof message.activeNotes !== "undefined") this.applyCustomNotes(message.activeNotes)
  }


  processAudio(inputBuffer, outputBuffer, buffersize, parameters) {
    // Ensure the samplerate is in sync on every audio processing callback
    // this.effect.samplerate = this.samplerate;


    // Render the output buffers
    this.effect.process(
      inputBuffer.pointer,
      outputBuffer.pointer,
      true,
      buffersize
    );
    // if (!) this.Superpowered.memoryCopy(outputBuffer.pointer, inputBuffer.pointer, buffersize * 8);
  }
}
#include "SuperpoweredAutomaticVocalPitchCorrection.h"


Superpowered::AutomaticVocalPitchCorrection *autotune = new Superpowered::AutomaticVocalPitchCorrection();


// Do this when the sample rate changes.
autotune->samplerate = 48000;


// Set the music scale.
autotune->scale = Superpowered::AutomaticVocalPitchCorrection::CMAJOR;


// Custom scale can also be used.
autotune->scale = Superpowered::AutomaticVocalPitchCorrection::CUSTOM;
autotune->setCustomScaleNote(
    0,   // The note (between 0..11).
    true // Note enabled or not.
);


// Query the custom scale.
bool note_0_enabled = autotune->getCustomScaleNote(
    0    // The note (between 0..11).
);


// Set the vocal range of the singer.
autotune->range = Superpowered::AutomaticVocalPitchCorrection::TENOR;


// How fast auto-tune should adapt, how "strong" it is.
autotune->speed = Superpowered::AutomaticVocalPitchCorrection::SUBTLE;


// Controls the incoming pitch variance threshold for switching to a new note for the output.
autotune->clamp = Superpowered::AutomaticVocalPitchCorrection::LOOSE;


// Middle A is not 440 Hz? No problem:
autotune->frequencyOfA = 430;


// Processes the audio. Has no return value.
// It's never blocking for real-time usage. You can change any properties concurrently with process().
autotune->process(
    input,  // Input pointer (audio in 32-bit floating point numbers).
    output, // Output pointer (audio in 32-bit floating point numbers).
    true,   // True: input and output are interleaved stereo. False: mono.
    128     // Number of frames to process.
);


//  Set all internals to initial state.
autotune->reset();

Constants

  • Superpowered.AutomaticVocalPitchCorrection

    CONSTANTS
    Scale
    ValueDescription
    CHROMATIC
    CMAJOR
    AMINOR
    CSHARPMAJOR
    ASHARPMINOR
    DMAJOR
    BMINOR
    DSHARPMAJOR
    CMINOR
    EMAJOR
    CSHARPMINOR
    FMAJOR
    DMINOR
    FSHARPMAJOR
    DSHARPMINOR
    GMAJOR
    EMINOR
    GSHARPMAJOR
    FMINOR
    AMAJOR
    FSHARPMINOR
    ASHARPMAJOR
    GMINOR
    BMAJOR
    GSHARPMINOR
    CUSTOM

  • Superpowered::AutomaticVocalPitchCorrection

    CONSTANTS
    Scale
    ValueDescription
    CHROMATIC
    CMAJOR
    AMINOR
    CSHARPMAJOR
    ASHARPMINOR
    DMAJOR
    BMINOR
    DSHARPMAJOR
    CMINOR
    EMAJOR
    CSHARPMINOR
    FMAJOR
    DMINOR
    FSHARPMAJOR
    DSHARPMINOR
    GMAJOR
    EMINOR
    GSHARPMAJOR
    FMINOR
    AMAJOR
    FSHARPMINOR
    ASHARPMAJOR
    GMINOR
    BMAJOR
    GSHARPMINOR
    CUSTOM

  • Superpowered.AutomaticVocalPitchCorrection

    CONSTANTS
    Range
    ValueDescription
    WIDEWide range, 40 to 3000 Hz
    BASSBass singer, 40 to 350 Hz
    TENORTenor, 100 to 600 Hz
    ALTOAlto, 150 to 1400 Hz
    SOPRANOSoprano, 200 to 3000 Hz

  • Superpowered::AutomaticVocalPitchCorrection

    CONSTANTS
    Range
    ValueDescription
    WIDEWide range, 40 to 3000 Hz
    BASSBass singer, 40 to 350 Hz
    TENORTenor, 100 to 600 Hz
    ALTOAlto, 150 to 1400 Hz
    SOPRANOSoprano, 200 to 3000 Hz

  • Superpowered.AutomaticVocalPitchCorrection

    CONSTANTS
    Speed
    ValueDescription
    SUBTLESubtle pitch correction
    MEDIUMMedium pitch correction
    EXTREMEClassic pitch correction effect

  • Superpowered::AutomaticVocalPitchCorrection

    CONSTANTS
    Speed
    ValueDescription
    SUBTLESubtle pitch correction
    MEDIUMMedium pitch correction
    EXTREMEClassic pitch correction effect

  • Superpowered.AutomaticVocalPitchCorrection

    CONSTANTS
    Clamp
    ValueDescription
    OFFAlways switch to the nearest key in the selected scale as output note
    LOOSESwitch if the detected key is 0.7 semitones above or below the current output note.
    TIGHTSwitch if the detected key is 1.2 semitones above or below the current output note, stable area centered around current note is 2.4 semitones

  • Superpowered::AutomaticVocalPitchCorrection

    CONSTANTS
    Clamp
    ValueDescription
    OFFAlways switch to the nearest key in the selected scale as output note
    LOOSESwitch if the detected key is 0.7 semitones above or below the current output note.
    TIGHTSwitch if the detected key is 1.2 semitones above or below the current output note, stable area centered around current note is 2.4 semitones

Properties

clamp

PROPERTY
Controls the incoming pitch variance threshold for switching to a new note for the output.
TypeMinMaxDefault
Number
OFFTIGHTLOOSE

clamp

PROPERTY
Controls the incoming pitch variance threshold for switching to a new note for the output.
TypeMinMaxDefault
Superpowered.AutomaticVocalPitchCorrection
OFFTIGHTLOOSE

frequencyOfA

PROPERTY
Frequency for middle A.
TypeMinMaxDefault
Number
410470440

frequencyOfA

PROPERTY
Frequency for middle A.
TypeMinMaxDefault
float
410470440

range

PROPERTY
Vocal range for pitch detection.
TypeMinMaxDefault
Number
WIDE (40 to 3000 Hz)

range

PROPERTY
Vocal range for pitch detection.
TypeMinMaxDefault
Superpowered.AutomaticVocalPitchCorrection
WIDE (40 to 3000 Hz)

samplerate

PROPERTY
Input/output sample rate in Hz.
TypeMinMaxDefault
Number
48000

samplerate

PROPERTY
Input/output sample rate in Hz.
TypeMinMaxDefault
unsigned int
48000

scale

PROPERTY
Music scale.
TypeMinMaxDefault
Number
CHROMATIC (all twelve keys of the octave are allowed)

scale

PROPERTY
Music scale.
TypeMinMaxDefault
Superpowered.AutomaticVocalPitchCorrection
CHROMATIC (all twelve keys of the octave are allowed)

speed

PROPERTY
Speed for tune correction.
TypeMinMaxDefault
Number
EXTREME

speed

PROPERTY
Speed for tune correction.
TypeMinMaxDefault
Superpowered.AutomaticVocalPitchCorrection
EXTREME

Methods

  • constructor

    METHOD
    Creates an instance of the AutomaticVocalPitchCorrection class.
    Parameters
    None
    Returns
    TypeDescription
    Superpowered.AutomaticVocalPitchCorrectionThe constructed instance.

  • constructor

    METHOD
    Creates an instance of the AutomaticVocalPitchCorrection class.
    Parameters
    None
    Returns
    TypeDescription
    Superpowered::AutomaticVocalPitchCorrectionThe constructed instance.

  • destruct

    METHOD
    Destructor to free Linear Memory.
    Parameters
    None
    Returns
    None

  • getCustomScaleNote

    METHOD
    Get note (on all octaves) for scale == CUSTOM.
    Parameters
    NameTypeDescription
    noteNumberThe note (between 0..11).
    Returns
    None

  • getCustomScaleNote

    METHOD
    Get note (on all octaves) for scale == CUSTOM.
    Parameters
    NameTypeDefaultDescription
    noteunsigned charThe note (between 0..11).
    Returns
    None

  • process

    METHOD
    It's never blocking for real-time usage. You can change any properties concurrently with process().
    Parameters
    NameTypeDescription
    inputNumber (pointer in Linear Memory)32-bit input.
    outputNumber (pointer in Linear Memory)32-bit output.
    stereoBooleanInterleaved stereo or mono input and output.
    numberOfFramesNumberNumber of frames to process.
    Returns
    None

  • process

    METHOD
    It's never blocking for real-time usage. You can change any properties concurrently with process().
    Parameters
    NameTypeDefaultDescription
    inputfloat *32-bit input.
    outputfloat *32-bit output.
    stereoboolInterleaved stereo or mono input and output.
    numberOfFramesunsigned intNumber of frames to process.
    Returns
    None

  • reset

    METHOD
    Set all internals to initial state.
    Parameters
    None
    Returns
    None

  • reset

    METHOD
    Set all internals to initial state.
    Parameters
    None
    Returns
    None

  • setCustomScaleNote

    METHOD
    Set note (on all octaves) for scale == CUSTOM.
    Parameters
    NameTypeDescription
    noteNumberThe note (between 0..11).
    enabledBooleanNote enabled or not.
    Returns
    None

  • setCustomScaleNote

    METHOD
    Set note (on all octaves) for scale == CUSTOM.
    Parameters
    NameTypeDefaultDescription
    noteunsigned charThe note (between 0..11).
    enabledboolNote enabled or not.
    Returns
    None
v2.7.2