Developer Documentation

Authentication

Separation

Create Upload Start separation Poll progress Download separated files

Additional Features

Metadata Start trial separation Create mix Create zip

Overview

This documentation shows the workflow of the DeMIX API and examples of requests/responses of each endpoint.

The main process of a separation is as follows:
- Authenticate to receive a token
- Create a separation
- Upload request file
- Start separation
- Poll for progress
- Download separated files

Other optional features of the separation api are:
- Get metadata about the file uploaded
- Download a custom mix of separated tracks
- Download a zip file with multiple separated tracks
- Start trial separation (time-restricted, potentially random section of the file)

Authenticate

POST

https://api2.sourceresoftware.com/auth/

In order to use protected API endpoints (such as /separation/create) you will need an authorization token. Using the POST /auth endpoint you can exchange your API username and key for such a token.

Once you receive your token, use it as your "Authorization" header value for all requests to protected endpoints.

Example:
If the token you received is the following: Bearer eyJhbGci.eyJzdWIiOiJhZG1.FXg1angK

Then you should add this header to your requests:
Authorization: Bearer eyJhbGci.eyJzdWIiOiJhZG1.FXg1angK

Headers

Copy

Content-Type: application/json

Payload

Copy

{
	"username":"demixr.com",
	"password":"r0s4nn4"
}

Response

Copy

{
	"token": "Bearer xxxxxxxxxxxxxxxx",
	"expiry": 86400,
	"token_type": "Bearer "
}

Create

POST

https://api2.sourceresoftware.com/separation/create

To create a separation, you will need to upload your audio file to our cloud storage. This is a two step process that starts by calling this endpoint.

You will be given a signed URL to upload your file to, valid for a limited time only, and also an upload ID to reference this uploaded file when calling other endpoints.

Headers

Copy

Authorization: [token_bearer]
Content-Type: application/json

Response

Copy

{
	"uploadId": "xxxxxxxxxxxxxxxx",
	"signedUrl": "https://storage.googleapis.com/staging-separations/demixr.com/xxxxxxxxxxxxxxxx",
	"expiry": "2020-07-14T13:20:58.140",
	"method": "PUT"
}

Upload

POST or PUT

[signed_url]

Once the signed url was received from the Create endpoint, the audio content to separate can be uploaded to it.

Make sure you take into account the method field the the Create response since it could be either POST or PUT, as well as the expiry time since signed urls are valid for a limited amount of time (usually about one hour)

The reason for using signed urls is so the audio files can be uploaded directly to cloud storage services (it could be Google Storage, Amazon S3,...), which are designed specifically for this purpose.
Furthermore this signed url can be given safely to end-users so they can upload their song directly from their machine without the need to go through our authenticated API.

Headers

Copy

Content-Type: text/plain

Payload

Copy

The binary file to upload for separation (any supported audio format: wav, mp3, m4a, flac...)

Start separation

PUT

https://api2.sourceresoftware.com/separation/start

To actually start the separation process you need to identify the upload you wish to separate and the algorithm you want to use.

4 is our two stem drum algorithm: drums and everything but drums
5 is our two stem bass algorithm: bass and everything but bass
6 is our two stem vocal algorithm: vocal and karaoke backing track
7 is our four stem separation for vocals, drums, bass and other instruments

Please note that if you call this endpoint before the Upload is completed the separation will fail.

This endpoints has multiple optional parameters:

outputFormats:
This is an array containing the various formats that the separated files should be converted in automatically. The file formats allowed are mp3,m4a,wav,flac (wav will always be generated, but others must be specified in this array).

priority:
Two values are possible for this field: ONDEMAND (default) and BATCH.
Please refer to the API pricing to pick the right priority level.

priorityOffset:
This value is optional and is only used to finely set in which order several separations will run (for example if a single user requests several files at once). Setting this won't affect the cost of your separation.

callbackUrl:
Additionally you can set a callback URL that our servers will call when the separation finishes.
Our callback will be a POST request with the same payload than the Progress endpoint response (see Poll progress for more information)

Headers

Copy

Authorization: [token_bearer]
Content-Type: application/json

Payload

Copy

{
	"uploadId": "[upload_id]",
	"separationAlgorithm":6,
	"outputFormats": "["mp3"]",
	"priority": "ONDEMAND",
	"priorityOffset": 0,
	"callbackUrl" : "example-url.com"
}

Response

Copy

{
	"separationId": "xxxxxxxxxxxxxxxx"
}

Poll progress

GET

https://api2.sourceresoftware.com/separation/progress?separationId=[separation_id]

If you didn't set a callback URL from the start or trial/start endpoints or if our callback fails for any reason. You can check the progress of your separation by calling this endpoint.
Even if you're using a callback URL it would be a good idea to call this endpoint every now and then in case anything wrong happens with the callback.

The separation is finished when "outputFiles" is not empty. The last event ("Finalising") means that the separated files are being uploaded, so there can still be a few seconds before "outputFiles" is filled.

Headers

Copy

Authorization: [token_bearer]
Content-Type: application/json

Response

Copy

{
	"events": [
    	{
        	"event": "Formatting Request File",
        	"guid": "de7ba252-3139-4eab-9dec-07d826e416bb",
        	"timestamp": "2020-07-21T14:50:57.396Z",
        	"message": "Formatting requestData into wav"
    	},
    	{
        	"event": "Request Formatting Done",
        	"guid": "d05602f0-36c4-42d2-8c6d-4fe9aaeec59f",
        	"timestamp": "2020-07-21T14:51:05.458Z",
        	"message": ""
    	},
    	{
        	"event": "Requesting Metadata",
        	"guid": "78e690ec-d48a-45c7-8ff7-c1f39f66b9b6",
        	"timestamp": "2020-07-21T14:51:05.478Z",
        	"message": "Requesting metadata from server"
    	},
    	{
        	"event": "Metadata Task Done",
        	"guid": "7c67c326-4983-4c32-81e8-0a231ff90d2f",
        	"timestamp": "2020-07-21T14:51:05.484Z",
        	"message": ""
    	},
    	{
        	"event": "Trial Chunking Start",
        	"guid": "5f4fd7f3-2443-4b31-ad84-7c273ab2b2fc",
        	"timestamp": "2020-07-21T14:51:05.513Z",
        	"message": ""
    	},
    	{
        	"event": "Trial Chunking Done",
        	"guid": "d5eb44c5-64cf-4067-88f2-c1a1acdff93c",
        	"timestamp": "2020-07-21T14:51:11.922Z",
        	"message": ""
    	},
    	{
        	"event": "Starting Separation",
        	"guid": "9f984b6c-285c-4732-b61a-c8f5a8be3ce0",
        	"timestamp": "2020-07-21T14:51:11.950Z",
        	"message": "Starting Separation process"
    	},
    	{
        	"event": "Queue message received",
        	"guid": "51510fe0-8a97-41fb-b213-b548f4b3c982",
        	"timestamp": "2020-07-21T14:51:15.176Z",
        	"message": "Attempt number 1"
    	},
    	{
        	"event": "Processing",
        	"guid": "b30f2f98-df30-460e-984c-f5c5f63f7dd7",
        	"timestamp": "2020-07-21T14:51:15.846Z",
        	"message": null
    	},
    	{
        	"event": "Finalising",
        	"guid": "85164348-d805-4c42-9faa-894d4f708362",
        	"timestamp": "2020-07-21T14:52:06.007Z",
        	"message": null
    	}
	],
	"outputFiles": [
    	    	"track.wav",
    	    	"vocals.wav"
	]
}

Download separated files

GET

https://api2.sourceresoftware.com/separation/download?separationId=[separation_id]&fileName=vocals&fileFormat=wav

To download a separated file you will need the filename returned from the progress endpoint with no file extension.

The file format that you wish to download can be written as wav or .wav either way is fine.

NB: the file formats allowed are mp3,m4a,wav,flac

If the file to download exists, this endpoint will return HTTP status 200. The response body will contain a signed url that can be used to download the file directly for a limited period of time. It is safe to send that url to a customer facing front-end as it doesn't include any API authentication information.

If the file doesn't exist yet, but can be generated (i.e. converting an existing wav file to mp3), this endpoint will return HTTP status 202 and you should keep calling it until the file is ready and you receive the response described above.

By default, only wav files are generated after a separation, if your application always needs other formats we suggest using the "outputFormats" parameter of the start or trial/start endpoints.

Headers

Copy

Authorization: [token_bearer]
Content-Type: application/json

Response

Copy

{
	"signedUrl": "[signed_url]",
	"expiry": "2020-07-09T15:27:32.723",
	"method": "GET"
}

Metadata

GET

https://api2.sourceresoftware.com/separation/metadata?uploadId=[upload_id]

You can use this endpoint to get information about a file that was uploaded.

This would be used if your users can upload their own files directly through the signed urls and you don't get the chance to collect that data yourself. For example you could validate the file format and duration of the files uploaded and make sure that they can be processed before starting the separation.

Metadata isn't calculated automatically, you must request it. If the metadata hasn't been calculated for this file yet, this endpoint will return HTTP status 202 and you should keep calling it until you receive HTTP status 200 and the metadata information in the response payload.

Headers

Copy

Authorization: [token_bearer]
Content-Type: application/json

Response

Copy

{
	"duration": 33.827868, (in seconds)
	"numChannels": 2,
	"sampleRate": 44100,
	"message": "completed",
	"success": true
}

Start trial separation

PUT

https://api2.sourceresoftware.com/separation/trial/start

This endpoint is intended for giving customers a preview of a separation before they can decide to separate it fully.

It works very similarly to the separation start endpoint, but instead of separating the entire file you can define how long of a snippet to take or where to start the snippet from, if these are not set a random 30 seconds of the file will be processed.

Optional parameters for trial:

trialSectionStart: the position in seconds at which the trial snippet should start (it will be random if unspecified)

trialSectionSeconds: the duration of the trial snippet in seconds. This must be longer than 15 seconds and shorter than one third of the total duration of the file. If not specified, it will be set to 30 seconds, or shorter if the song is shorter than 90 seconds.

NB: Please note that if the file uploaded is 45 seconds or less, the trial will fail.

Headers

Copy

Authorization: [token_bearer]
Content-Type: application/json

Payload

Copy

{
	"uploadId": "xxxxxxxxxxxxxxxx",
	"separationAlgorithm":6,
	"trialSectionSeconds":50.6,
	"trialSectionStart":10.2,
	"customMetadata":"your custom meta data",
	"callbackUrl" : "example-url.com"
}

Response

Copy

{
	"separationId": "xxxxxxxxxxxxxxxx"
}

Create mix

POST

https://api2.sourceresoftware.com/separation/mix

You can use this endpoint to request a custom mix of separated stems. When requesting a new mix you must provide the list of tracks that should be mixed together, and set a volume and panning level for each of them.

The volume should be a value between 0 and 1, and the panning value should be between -1: full left, to 1: full right.

Call this endpoint only once to request your mix, you will receive a "mixId". The mix can then be downloaded just like any other file, by calling the download endpoint as follows:
/separation/download?separationId=[separation_id]&fileName=[mix_id]&fileFormat=[format]

The download endpoint always returns http status 202 until the file is ready at which point http status 200 and a json response containing the signed url to download will be provided.

Headers

Copy

Authorization: [token_bearer]
Content-Type: application/json

Payload

Copy

{
	"tracks": [
	{
  		"fileName": "track.wav",
  		"volume": 0.61,
  		"pan": -1
	},
	{
  		"fileName": "vocals.wav",
  		"volume": 0.90,
  		"pan": 1
	}
	],
	"separationId": "xxxxxxxxxxxxxxxx"
	"mixName": "my mix"
}

Response

Copy

{
	"mixId": "mix/mix_xxxxxxxxxxxxxxxx"
}

Create zip

POST

https://api2.sourceresoftware.com/separation/zip

If you wish to download a zipped folder containing some or all of the stems from a separation you can use this endpoint.

Call this endpoint only once to request your zip file, you will receive a "zipFilePath". The zip will then be downloaded just like any other file, by calling the download endpoint as follows:
https://api2.staging.sourceresoftware.com/separation/download?separationId=[separation_id]&fileName=[zip_file_path].zip&fileFormat=zip

NB: keep the ".zip" part of "zipFilePath", but also specify fileFormat=zip when calling the download endpoint

The download endpoint always returns http status 202 until the file is ready at which point http status 200 and a json response containing the signed url to download will be provided.

Headers

Copy

Authorization: [token_bearer]
Content-Type: application/json

Payload

Copy

{
    "separationId":"5f212898dbe5b2724453e8c2",
    "tracks":["bass","other","drums","vocals"],
    "format":"mp3",
    "zipFileName": "myzipfile"
}

Response

Copy

{
	"zipFilePath": "zip/xxxxxxxxxxxxxxxx.zip"
}