Recognize chords (Extended)

Recognize played chords, strumming directions and key from audio.

1. Endpoint request format

note

This endpoint uses the same spec as the chord-recognition endpoint.

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-extended',
    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 extended 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 extended 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 extended chord recognition detects the played chords, the strumming directions and the key of the piece within time intervals of the audio file. The result returns the musical key and two lists, one for the chords and one for the strumming directions.

The values possible for "key": Regex: ^[A-G](?:#{1}|b{1})?\s+(?:major|minor)$

Similar to the chord recognition endpoint, the list of chords has the following format and is stored in chords: [<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.

The list of strumming directions is stored in strums and has the format: [<time_stamp_in_seconds>, <strum_direction>] with the type [float, string]. The <strum_direction> are the two values "U" for up- and "D" for down-strokes.

Example:

{
    "key": "A minor",
    "strums": [
        [
            0.6461865848302841,
            "D"
        ],
        ...
        [
            1.0264313435554504,
            "D"
        ],
    ],
    "chords": [
        [
            0.0,
            1.0185185185185184,
            "N"
        ],
        ...
        [
            1.0185185185185184,
            3.2407407407407405,
            "E:maj"
        ],
    ]
}