Skip to main content

Upload Library Tracks

Besides creating library tracks via the web app it is also possible to create them via the API. This is great for automating the process of analyzing audio files.

The process of creating the library tracks can be broken down into three simple steps:

  1. Requesting a file upload
  2. Uploading the file
  3. Create a library track from the file upload

Requesting a file upload​

A link as well as a ID which is used for creating a library track from an file upload can be retrieved with the Mutation.fileUploadRequest field.

A sample response might look like the following:

{
  "data": {
    "fileUploadRequest": {
      "id": "MS8yOWNjM2ZjZi03MmU4LTRjZjEtOTdlZC1hYTMwOGExMWU3ODY",
      "uploadUrl": "https://s3.eu-central-1.amazonaws.com/cyanite-file-storage/1/29cc3fef-7212-4cf1-97ed-aa308a22e786?Content-Type=audio%2Fmpeg&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIBJEAGRZG3RDV5AMfQ%2F20210204%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20210204TH32530Z&X-Amz-Expires=900&X-Amz-Signature=090f39a5c0180h079a0c857a84b1a544dc24ce0ca3373c9d74f585bf976f99be&X-Amz-SignedHeaders=host"
    }
  }
}

The response is important for the next two steps.

Uploading the file​

The result from the Mutation.fileUploadRequest field contains a uploadUrl which is the target where our file must be uploaded to.

The file must be uploaded via a PUT HTTP request to that given uploadUrl.

Example: Upload file via curl

curl -v --upload-file
 \ "frog.mp3"
 \ "https://s3.eu-central-1.amazonaws.com/cyanite-file-storage/1/a64ea798-3490-4b42-9917-2c63307d747d?Content-Type=audio%2Fmpeg&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJEAGRZG3TDV5AMHQ%2F20210204%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20210204T132927Z&X-Amz-Expires=900&X-Amz-Signature=8d8e8b8029dc2710e1ca27be1ef9094801e4e8bd7c0c313ac40da30a56330558&X-Amz-SignedHeaders=host"

Example: Upload file via fetch in Node.js

import fs from "fs/promises";
import fetch from "node-fetch";

const uploadUrl =
  "https://s3.eu-central-1.amazonaws.com/cyanite-file-storage/1/a64ea798-3490-4b42-9917-2c63307d747d?Content-Type=audio%2Fmpeg&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJEAGRZG3TDV5AMHQ%2F20210204%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20210204T132927Z&X-Amz-Expires=900&X-Amz-Signature=8d8e8b8029dc2710e1ca27be1ef9094801e4e8bd7c0c313ac40da30a56330558&X-Amz-SignedHeaders=host";
const fileName = "frog.mp3";

async function main() {
  const body = await fs.readFile(fileName);
  const result = await fetch(uploadUrl, {
    method: "PUT",
    body,
    headers: {
      "Content-Type": "audio/mpeg",
    },
  }).then((res) => res.text());
  console.log(result);
}

main();

Creating the Library Track​

After the file has been successfully uploaded, the id value returned on the Mutation.fileUploadRequest field can be used for creating the library track.

You can provide an optional externalId string in the input which can serve as identifier for your system.

The Mutation.libraryTrackCreate field returns a LibraryTrackCreateResult GraphQL union type, which can either be a LibraryTrackCreateSuccess or a LibraryTrackCreateError.

Creation failed​

In case an error occurred the code field on the LibraryTrackCreateError can be checked for the reason of the failed creation. A human readable message is also provided via the message field.

Example response​

{
  "data": {
    "libraryTrackCreate": {
      "__typename": "LibraryTrackCreateError",
      "code": "invalidUploadId",
      "message": "The provided upload id is invalid. It must be properly generated using the fileUploadRequest mutation."
    }
  }
}

Error code overview​

Error codeMeaning
fileUploadNotFoundStep two, uploading the file, has either been skipped or failed.
invalidUploadIdThe upload id does not belong to any requested file upload.
librarySizeLimitExceededErrorThe basic account tier has a library size limitation of 30. Any attempt to create more LibraryTracks after exceeding that limit will result in this error code.

Creation succeeded​

The Mutation.libraryTrackCreate field returns a LibraryTrackCreateSuccess result, the creation of the library track succeeded. It is possible to immediately query for the id (as well as other data) of the created track via the createdLibraryTrack field. This is useful for storing the id mapping from another database to the Cyanite.ai library track.

The track is also automatically enqueued for all eligible analysis types for the given account. The enqueue result can be selected via the enqueueResult field on the LibraryTrackCreateSuccess type. In case the account exceeded the analysis limit, the track will not be enqueued and it must be enqueued at a later point using the Mutation.libraryTrackEnqueue field.

Example response​

{
  "data": {
    "libraryTrackCreate": {
      "__typename": "LibraryTrackCreateSuccess",
      "createdLibraryTrack": {
        "id": "999"
      }
    }
  }
}

Deleting a Library Track​

Permanent operation

This operation cannot be undone so be careful when deleting tracks!

At some point you may want to delete some of your tracks, for example to exclude them from your similarity search results. The following query can be used to accomplish that.

This operation allows to delete at most 100 tracks at once.

The Mutation.libraryTracksDelete field returns a LibraryTracksDeleteResult GraphQL union type, which can either be a LibraryTracksDeleteSuccess or a LibraryTracksDeleteError.

Error code overview​

Error codeMeaning
tooManyTracksThe number of IDs sent with the request is greater than 100.

Example response​

{
  "data": {
    "libraryTracksDelete": {
      "__typename": "LibraryTracksDeleteSuccess"
    }
  }
}