Get the beats and downbeats of an audio

Learn how to create a request for beat tracking.

1. 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 = {
    'webhook_url': '{YOUR_WEBHOOK_ENDPOINT_URL}' # optional, but recommended
  }

  multipart_params = {
    'file': audio_file
  }

  resp = requests.post(
    'https://api.klang.io/beat-tracking',
    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'
    # }

2. Check Job Status

See step 2 in Basic Job Workflow

3. Get the Output Data

Once the beat tracking 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 beat tracking 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())

4. Result format

The beat tracking detects the time signature of the audio file and returns you the downbeat and timestamps in seconds where the downbeat occurs.

The result is a json array, containing tuples in the format [<beat_timestamp_in_seconds>, <downbeat>] with the type [float, float].

For a 3/4 beat the downbeat has the values in [1.0, 2.0, 3.0] and for a 4/4 beat the downbeat has the values in [1.0, 2.0, 3.0, 4.0].

Example output json:

[
    [  0.14, 1.0 ],
    [  0.76, 2.0 ],
    [  1.35, 3.0 ],
    [  1.95, 4.0 ],
    [  2.59, 1.0 ],
    [   3.2, 2.0 ],
    [  3.82, 3.0 ],
    [  4.45, 4.0 ],
    [  5.07, 1.0 ],
    [   5.7, 2.0 ],
    [  6.34, 3.0 ],
    [  6.97, 4.0 ],
    [  7.61, 1.0 ],
    [  8.22, 2.0 ],
    [  8.85, 3.0 ],
    [  9.49, 4.0 ],
    [ 10.12, 1.0 ],
    [ 10.73, 2.0 ],
    [ 11.36, 3.0 ],
    [  12.0, 4.0 ],
    [ 12.65, 1.0 ],
    [ 13.27, 2.0 ],
    [ 13.92, 3.0 ],
    [ 14.55, 4.0 ]
]