Skip to main content
  • KSP Reference Manual
  • Music Information Retrieval

Music Information Retrieval

General Information

Music Information Retrieval (MIR) allows the extraction of meaningful features from audio files, such as pitch or the volume level of a sample. New KSP commands allow extraction of such parameters from samples via script. MIR functions are not asyncronous in the on init callback, but in all other callbacks they will run asynchronous.

Note: the type detection functions listed below (Sample Type, Drum Type, and Instrument Type) are designed to process one-shot audio samples.

detect_pitch()

detect_pitch(<zone-id>, <pitch-result>)

Returns a real value representing the fundamental frequency of an audio sample, in semitones and cents. If detection fails, the function will return ~NI_DETECT_PITCH_INVALID.

<zone-id>

The ID of the zone

<pitch-result>

The MIDI note value of the detected pitch

detect_loudness()

detect_loudness(<zone-id>, <loudness-result>)

Returns a real value representing the loudness of an audio sample in dB. Loudness is measured according to the standard established by the International Telecommunication Union: Algorithms to measure audio program loudness and true-peak audio level - ITU-R BS.1770-4 (2015). If detection fails, the function will return ~NI_DETECT_LOUDNESS_INVALID.

<zone-id>

The ID of the zone

<loudness-result>

The real value of the detected loudness in dB

detect_peak()

detect_peak(<zone-id>, <peak-result>)

Returns a real value representing peak level of an audio sample in dB. Peak is measured according to the standard established by the International Telecommunication Union: Algorithms to measure audio program loudness and true-peak audio level - ITU-R BS.1770-4 (2015). If detection fails, the function will set <peak-result> to ~NI_DETECT_PEAK_INVALID.

<zone-id>

The ID of the zone

<peak-result>

The real value of the detected peak level in dB

detect_rms()

detect_rms(<zone-id>, <rms-result>)

Returns a real value representing the RMS level of an audio sample in dB. If detection fails, the function will return ~NI_DETECT_RMS_INVALID.

<zone-id>

The ID of the zone

<rms-result>

The real value of the RMS level of the audio sample in dB

detect_sample_type()

detect_sample_type(<zone-id>, <sample-type-result>)

Assigns <sample-type-result> a $NI_DETECT_SAMPLE_TYPE tag describing the whether an audio sample is a drum or an instrument. If detection fails, the function will return $NI_DETECT_SAMPLE_TYPE_INVALID.

<zone-id>

The ID of the zone

<sample-type-result>

The detected sample type, can be one of the following:

$NI_DETECT_SAMPLE_TYPE_INVALID

$NI_DETECT_SAMPLE_TYPE_INSTRUMENT

$NI_DETECT_SAMPLE_TYPE_DRUM

detect_drum_type()

detect_drum_type(<zone-id>, <drum-type-result>)

Assigns <drum-type-result> a $NI_DETECT_DRUM_TYPE tag describing the drum type of an audio sample. You can use this function if detect_sample_type() determines that a given audio sample is of type $NI_DETECT_SAMPLE_TYPE_DRUM. If detection fails, the function will return ~NI_DETECT_DRUM_TYPE_INVALID.

<zone-id>

The ID of the zone

<drum-type-result>

The detected drum type, can be one of the following:

$NI_DETECT_DRUM_TYPE_INVALID

$NI_DETECT_DRUM_TYPE_KICK

$NI_DETECT_DRUM_TYPE_SNARE

$NI_DETECT_DRUM_TYPE_CLOSED_HH

$NI_DETECT_DRUM_TYPE_OPEN_HH

$NI_DETECT_DRUM_TYPE_TOM

$NI_DETECT_DRUM_TYPE_CYMBAL

$NI_DETECT_DRUM_TYPE_CLAP

$NI_DETECT_DRUM_TYPE_SHAKER

$NI_DETECT_DRUM_TYPE_PERC_DRUM

$NI_DETECT_DRUM_TYPE_PERC_OTHER

detect_instrument_type()

detect_instrument_type(<zone-id>, <instrument-type-result>)

Assigns <drum-type-result> a $NI_DETECT_INSTRUMENT_TYPE tag describing the instrument type of an audio sample. Hint: use this function if detect_sample_type() determines that a given audio sample is of type $NI_DETECT_SAMPLE_TYPE_INSTRUMENT. If detection fails, the function will return $NI_DETECT_INSTRUMENT_TYPE_INVALID.

<zone-id>

The ID of the zone

<instrument-type-result>

The detected instrument type, can be one of the following:

$NI_DETECT_INSTRUMENT_TYPE_INVALID

$NI_DETECT_INSTRUMENT_TYPE_BASS

$NI_DETECT_INSTRUMENT_TYPE_BOWED_STRING

$NI_DETECT_INSTRUMENT_TYPE_BRASS

$NI_DETECT_INSTRUMENT_TYPE_FLUTE

$NI_DETECT_INSTRUMENT_TYPE_GUITAR

$NI_DETECT_INSTRUMENT_TYPE_KEYBOARD

$NI_DETECT_INSTRUMENT_TYPE_MALLET

$NI_DETECT_INSTRUMENT_TYPE_ORGAN

$NI_DETECT_INSTRUMENT_TYPE_PLUCKED_STRING

$NI_DETECT_INSTRUMENT_TYPE_REED

$NI_DETECT_INSTRUMENT_TYPE_SYNTH

$NI_DETECT_INSTRUMENT_TYPE_VOCAL

Examples

wait_async(detect_pitch(%NI_USER_ZONE_IDS[0], ~pitch_result))
wait_async(set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_ROOT_KEY, int(round(~pitch_result))))
wait_async(set_zone_par(%NI_USER_ZONE_IDS[0], $ZONE_PAR_TUNE, int(100.0 * (round(~pitch_result) - ~pitch_result)))

Set the zone root key by rounding the pitch result to an integer value. Then set the zone tune to correct for the pitch offset.

wait_async(detect_sample_type(%NI_USER_ZONE_IDS[0], $sample_type))

if ($sample_type = $NI_DETECT_SAMPLE_TYPE_INSTRUMENT)
    wait_async(detect_instrument_type(%NI_USER_ZONE_IDS[0], $instrument_type))
else
    wait_async(detect_drum_type(%NI_USER_ZONE_IDS[0], $drum_type))
end if

if ($sample_type = $NI_DETECT_SAMPLE_TYPE_INSTRUMENT)
    if ($instrument_type = $NI_DETECT_INSTRUMENT_TYPE_BASS)
        set_text($label_5, "Bass")
    end if
else
    if ($drum_type = $NI_DETECT_DRUM_TYPE_KICK)
        set_text($label_5, "Kick")
    end if
end if

Detect whether a sample is of type instrument or drum, and detect the corresponding drum or instrument type.