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! 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.

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.

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

How to implement

You'll find the constants required for scale, range 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.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.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;


// 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
    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
    SUBTLEsubtle pitch correction
    MEDIUMmedium pitch correction
    EXTREMEclassic pitch correction effect

  • 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
    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
    SUBTLEsubtle pitch correction
    MEDIUMmedium pitch correction
    EXTREMEclassic pitch correction effect

Properties

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
v1.0.23