API Examples

Here are examples with questions from our users and some special features.

Further API examples are in the auphonic-api-examples github repository. Additional examples and pull requests are very welcome!

If you have any further questions or need any other special API features, don’t hesitate to contact us at feedback _at_ auphonic.com!

Fade In/Out Time of Audio Files

With our API, you can set the fade in/out time in ms at the start/end of output files. The default fade time is 100ms, values between 0ms and 5000ms are allowed.

This is a “hidden” API feature, as it is not supported in the web interface! The same feature is also available in our Auphonic Leveler Desktop App.

To set a manual fade in/out time, please use the parameter fadetime in our audio algorithms settings:

curl -H "Content-Type: application/json" -X POST \
    https://auphonic.com/api/production/{uuid}/algorithms.json \
    -u username:password \
    -d '{
          "leveler": true, "normloudness": true, "hipfilter": true,
          "fadetime": 0
        }'

It is of course also possible to Set all Details in one Request:

curl -X POST -H "Content-Type: application/json" \
    https://auphonic.com/api/productions.json \
    -u username:password \
    -d '{
            "input_file": "http://your_server.com/somefile.mp3",
            "algorithms": {
                "hipfilter": true, "leveler": true, "normloudness": true,
                "fadetime": 250
            },
            "metadata": {
                "title": "Production with custom fade in/out",
            },
            "output_files": [
                {"format":"aac", "bitrate":"32", "suffix":"-small"},
                {"format": "flac"}
            ]
        }'

Cut Start/End of Audio Files

In singletrack productions, it is possible to cut the start and/or end of the uploaded audio file. All timing information (chapters, etc.) will be shifted accordingly.

This is again a “hidden” API feature - so far it is not supported in the web interface!

To cut from the start of an audiofile, set the parameter cut_start (in seconds) when creating a production. To cut from the end, please use the parameter cut_stop (calculated in seconds from the end of the audio file):

curl -X POST -H "Content-Type: application/json" \
    https://auphonic.com/api/productions.json \
    -u username:password \
    -d '{
            "cut_start": 2.34,
            "cut_end": 5.142,
            "metadata": { "title": "Cut the audio file!" }
        }'

You can use the same parameters when modifying an existing production:

curl -X POST -H "Content-Type: application/json" \
    https://auphonic.com/api/production/{uuid}.json \
    -u username:password \
    -d '{"cut_start": 2.34, "cut_end": 5.142}'

Simple Audio File Upload with JavaScript (CORS)

If you want to integrate Auphonic into your own web application, direct file uploads from your users to our servers are possible with cross-origin requests (CORS). For more details about CORS see New Tricks in XMLHttpRequest2.

If you want to upload and start a production using the Auphonic Simple API, you can create a POST request directly in JavaScript:

// Create the XHR object.
function createCORSRequest(method, url) {
  var xhr = new XMLHttpRequest();
  if ("withCredentials" in xhr) {
    // XHR for Chrome/Firefox/Opera/Safari.
    xhr.open(method, url, true);
  } else if (typeof XDomainRequest != "undefined") {
    // XDomainRequest for IE.
    xhr = new XDomainRequest();
    xhr.open(method, url);
  } else {
    // CORS not supported.
    xhr = null;
  }
  return xhr;
}

function createProduction() {
  // create CORS request to Auphonic Simple API
  var xhr = new createCORSRequest("POST", "https://auphonic.com/api/simple/productions.json");
  // IMPORTANT: if you use OAuth, you must provide your bearer token here!
  //            otherwise you can also use HTTP Basic Authentication ...
  xhr.setRequestHeader("Authorization", "Bearer XXXXXXX");

  // production metadata and details
  var formData = new FormData();
  formData.append("title", "javascript upload test");
  formData.append("artist", "me");
  formData.append("loudnesstarget", -23);
  formData.append("action", "start");

  // add the media file which should be uploaded
  // the audio file must be selected in an HTML form with id files, e.g.:
  //   <input type="file" id="files" name="files[]" multiple />
  formData.append("input_file", document.querySelector('#files').files[0]);

  // submit request
  xhr.send(formData);
}

// event listener to trigger the upload when the user selects a new file
document.getElementById('files').addEventListener('change', createProduction, false);

In your HTML, you must have a corresponding file input form to make the above example working:

<input type="file" id="files" name="files[]" multiple />

For a more complex example with upload progress and multiple requests, see Complex Audio File Upload with JavaScript (CORS).

Complex Audio File Upload with JavaScript (CORS)

For full controll, you might want to use our JSON-based API. There it’s necessary to first create a production with all details and then upload a media file in a second request, see Start a Production and Upload a File.

Here is an example with two requests which also displays the upload progress:

// Create the XHR object.
function createCORSRequest(method, url) {
  var xhr = new XMLHttpRequest();
  if ("withCredentials" in xhr) {
    // XHR for Chrome/Firefox/Opera/Safari.
    xhr.open(method, url, true);
  } else if (typeof XDomainRequest != "undefined") {
    // XDomainRequest for IE.
    xhr = new XDomainRequest();
    xhr.open(method, url);
  } else {
    // CORS not supported.
    xhr = null;
  }
  return xhr;
}

function get_token() {
  // your OAuth2 bearer token
  return 'XXXXXXX';
}

// create new production using the JSON API
// NOTE: Content-type must be application/json!
var xhr = new createCORSRequest("POST", "https://auphonic.com/api/productions.json");
xhr.setRequestHeader("Content-type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer " + get_token());
xhr.onload = function(e) {
  console.log("Production: created");

  // parse response of first request to get the production UUID
  var response = JSON.parse(e.target.response);
  var data = response.data;
  var production_uuid = data.uuid;

  // the audio file must be selected in an HTML form with id files, e.g.:
  //   <input type="file" id="files" name="files[]" multiple />
  var file = document.querySelector('#files').files[0];

  if (file) {
    console.log("File Upload: started");

    // second request to add audio file to the production
    // IMPORTANT: we must not set the Content Type to JSON here!
    var url = 'https://auphonic.com/api/production/{uuid}/upload.json'.replace('{uuid}', production_uuid);
    var xhr2 = new createCORSRequest("POST", url);
    xhr2.setRequestHeader("Authorization","Bearer " + get_token());

    // event listener to show upload progress
    xhr2.upload.addEventListener("progress", function(e) { console.log((e.loaded / e.total) * 100); }, false);

    // callback when upload finished
    xhr2.onload = function(e) {
      console.log("File Upload: Done");
    };

    // append file to our form and send second request
    var formData = new FormData();
    formData.append('input_file', file);
    xhr2.send(formData);
  }
};

// send first request and set some production details in JSON
xhr.send(JSON.stringify({"metadata":{"title": "test upload 2"}}));