Recognize chords

Learn how to create requests to recognize played chords in audio.

1. Selecting vocabulary

You can restrict the vocabulary used for the chord recognition. Currently there are the following two options to choose from:

Vocabulary	Regex for possible values
major-minor	^((N|X){1}$)|\((C|C#|D|D#|E|E#|F|F#|G|G#|A|A#|B|B#){1}(:(min|maj))?\)$
full	^((N|X){1}$)|\((C|C#|D|D#|E|E#|F|F#|G|G#|A|A#|B|B#){1}(:(min|maj|dim|aug|min6|maj6|min7|maj7|minmaj7|7|dim7|hdim7|sus2|sus4))?\)$

N: no chord X: Unknown Chord

Using the reduced major-minor vocabulary yields a better hit-rate compared to the full vocabulary. Choose the vocabulary based on your needs.

2. Request via API

Example python snippet: (also see step 1 in Basic Job Workflow)

  import requests
  
  API_KEY = 'YOUR_KLANGIO_API_KEY'

  audio_file = open('{YOUR_FILE_NAME}', 'rb')

  query_parameters = {
    'vocabulary': 'major-minor', # required
    'webhook_url': '{YOUR_WEBHOOK_ENDPOINT_URL}' # optional, but recommended
  }

  multipart_params = {
    'file': audio_file
  }

  resp = requests.post(
    'https://api.klang.io/chord-recognition',
    headers={
        'kl-api-key': API_KEY
    },
    params=query_parameters,
    files=multipart_params
  )

  if resp.status_code == 200:
    print(resp.json())
    # {
    #  'job_id': 'SOME_JOB_ID', 
    #  'creation_date': '2023-01-01', 
    #  'deletion_date': '2023-02-01',
    #  'status_endpoint_url': 'https://api.klang.io/job/{SOME_JOB_ID}/status'
    # }

3. Check Job Status

See step 2 in Basic Job Workflow

4. Get the Output Data

Once the chord recognition job is in state COMPLETED or the webhook notification is received, you can fetch the output results from the job/{job_id}/json endpoint.

Here is an example python code snippet to fetch the json of the chord recognition job: (also see step 3 in Basic Job Workflow)

  import requests

  API_KEY = 'YOUR_KLANGIO_API_KEY'

  resp = requests.get(
    'https://api.klang.io/job/{YOUR_JOB_ID}/json',
    headers={
      'kl-api-key': API_KEY
    })

  if resp.status_code == 200:
    print(resp.json())

5. Result format

The chord recognition detects the chords within time intervals of the audio file and returns you the list of start- and end-times of such an interval with the detected chord.

The job result is a json array, containing only triplet entries [<start_time_in_seconds>, <end_time_in_seconds>, <chord_name>] with the type [float, float, string]. The chord_name contains the values in range of the specified vocabulary.

Example:

[
    [
        0.0,
        1.0185185185185184,
        "N"
    ],
    [
        1.0185185185185184,
        3.2407407407407405,
        "E:maj"
    ],
    [
        3.2407407407407405,
        3.518518518518518,
        "D#:maj"
    ],
    [
        3.518518518518518,
        5.7407407407407405,
        "E:maj"
    ],
    [
        5.7407407407407405,
        6.018518518518518,
        "D#:maj"
    ],
    [
        6.018518518518518,
        7.222222222222221,
        "N"
    ],
    [
        7.222222222222221,
        9.537037037037036,
        "E:maj"
    ],
    [
        9.537037037037036,
        10.0,
        "D#:maj"
    ],
    [
        10.0,
        12.314814814814815,
        "E:maj"
    ],
    [
        12.314814814814815,
        15.0,
        "N"
    ]
]