Integrating Musical Analysis (BPM & Key)

Prerequisites

In this guide we are showcasing how you can query the musical analysis for a audio file you uploaded to Cyanite.ai.

It assumes that you already configured a Webhook. In case you did not, we recommend you to work through the Integrating InDepthAnalysis guide first.

FastMusicalAnalysis and FullScaleMusicalAnalysis

The Cyanite.ai GraphQL API exposes two types of musical analyses. Both provide the option for retrieving information about the BPM and Key of your audio files. However, there are some differences.

The FastMusicalAnalysis utilizes a less compute intense method for extracting BPM and Key which is applied on a short excerpt of the audio. The results are therefore retrieved much quicker but still prove very stable in accuracy. This is handy for an integration use-case that needs to show results as fast as possible.

The FullScaleMusicalAnalysis utilizes a more computationally intense method for extracting BPM and Key. The results are therefore most accurate with the trade-off of longer computational time than the FastMusicalAnalysis.

Enqueuing the Analysis

Both analyses types are automatically enqueued when enqueuing a InDepthAnalysis with the inDepthAnalysisEnqueueAnalysis GraphQL mutation.

For tracks that have already been analyzed before the introduction of FastMusicalAnalysis and FullScaleMusicalAnalysis the analysis can be re-enqueued by using the same inDepthAnalysisEnqueueAnalysis mutation again.

Querying for the Analysis Result

The result/error for a FastMusicalAnalysis or FullScaleMusicalAnalysis can be retrieved by querying the API endpoint.

Example query for fetching both the FastMusicalAnalysis and FullScaleMusicalAnalysis for a InDepthAnalysis record:

query analysis($id: ID!) {
inDepthAnalysis(recordId: $id) {
__typename
... on InDepthAnalysisNotFoundError {
message
}
... on InDepthAnalysis {
id
title
fastMusicalAnalysis {
__typename
... on FastMusicalAnalysisFailed {
error {
... on Error {
message
}
}
}
... on FastMusicalAnalysisFinished {
result {
bpm
key {
values
confidences
}
}
}
}
fullScaleMusicalAnalysis {
__typename
... on FullScaleMusicalAnalysisFailed {
error {
... on Error {
message
}
}
}
... on FullScaleMusicalAnalysisFinished {
result {
bpm
key {
values
confidences
}
}
}
}
}
}
}

You can try this query on the GraphQL Playground.

Example Query Result:

{
"data": {
"inDepthAnalysis": {
"__typename": "InDepthAnalysisYoutubeImport",
"id": "40459",
"title": "Lil Yachty - Demon Time ft. Draft Day",
"fastMusicalAnalysis": {
"__typename": "FastMusicalAnalysisFinished",
"result": {
"bpm": 130.43478260869566,
"key": {
"values": ["E minor", "A minor", "C# minor"],
"confidences": [
0.25384970357386066,
0.11542832807008041,
0.10871631404316075
]
}
}
},
"fullScaleMusicalAnalysis": {
"__typename": "FullScaleMusicalAnalysisFinished",
"result": {
"bpm": 130.4347826086954,
"key": {
"values": ["C# minor", "A minor", "F minor"],
"confidences": [
0.2682539588265765,
0.2183989992019643,
0.06956732375702233
]
}
}
}
}
}
}

Webhooks

After a FastMusicalAnalysis or FullScaleMusicalAnalysis has finished (or failed) a Webhook is sent to the configured integration endpoint.

Example payload:

{
"type": "IN_DEPTH_ANALYSIS", // resource type
"id": "9999", // id of the resource
"event": {
"type": "FULL_SCALE_MUSICAL_ANALYSIS", // "FULL_SCALE_MUSICAL_ANALYSIS" or "FAST_MUSICAL_ANALYSIS"
"status": "FINISHED" // status of the analysis "FINISHED" or "FAILED"
}
}

The id sent with the payload can be used for querying for the result through the Cyanite.ai GraphQL API.