Feedback

sonicAPI.com

file/download

Download a file. The file can be either an audio file or a result file and can be accessed through its file_id.

Parameters

Parameter Type Description
access_id required string
One of your personal access_ids.
file_idrequired file
A file_id that identifies the output file from a processing or analysis task

You can find the file_id in the xml or json response from the task (if you used the blocking=false parameter) or in the "X-Sonicapi-File-Id" http header of the task's response

format optional string
[wav, aif, au, flax, ogg, xml, json, jsonp, xmlp] default: off
The format to use in the response. If you select an audio format, see the table below that lists which parameters are available to control the quality for each format.

Note that for the formats "jsonp" or "xmlp", the HTTP status code will always be 200.

callback optional string
Callback function name required when using the format "jsonp" or "xmlp."
foo_string optional string
Arbitrary string to add to the logs.

Allows you to add any strings you might find helpful for later analysis of the request logs.

Audio File Formats

The default audio format for downloads is Ogg (sample rate: 44.1 kHz). The following formats and format-dependent parameters are allowed.

Format Parameter Default Allowed Description
wav bits 16 8; 16; 24; 32 The word length in bit of one audio sample (raw PCM).
samplerate 44100 8-192 kHz* The number of audio samples per channel per second.
aif bits 16 8; 16; 24; 32 The word length in bit of one audio sample (raw PCM).
samplerate 44100 8-192 kHz* The number of audio samples per channel per second.
au bits 16 8; 16; 24; 32 The word length in bit of one audio sample (raw PCM).
samplerate 44100 8-192 kHz* The number of audio samples per channel per second.
flac compression 4 0; 1; 2; 3; 4; 5; 6; 7; 8; 9; 10 The compression level of the file. The file size decreases with increasing compression level.
samplerate 44100 8-192 kHz* The number of audio samples per channel per second.
ogg compression 3 0; 1; 2; 3; 4; 5; 6; 7; 8; 9; 10 The compression level of the file. Both, the file size and the audio quality increase with increasing compression level.
samplerate 44100 8-192 kHz* The number of audio samples per channel per second.
* supported sample rates: 8000; 11025; 16000; 22050; 24000; 32000; 44100; 48000; 88200; 96000; 192000


Response

There are three different possible responses for the download task depending on the format parameter and the (status of the) generating task.

  • process tasks
    • audio data (default) - choose an audio format from the table above (default format: mp3)
    • process info - choose json(p) or xml(p) formats to receive some processing meta-data (such as the parameter values being used, and the maximum amplitude of the output file)
  • analyze tasks
    • result (default) - choose json(p) or xml(p) formats to receive the result (default format: xml). See the analyze task description for response details.
  • a 409 error: "File operation is still in progress." - occurs if you try to download an output file from a non-blocking task before processing is complete. Check the http response code to catch this special case before you handle the response body (or use file/status to make sure the result file is available before trying to download it).


Usage example

These examples use the cURL command line tool to execute a series of http requests to demonstrate how to download the result of a processing task in various formats.

First, a processing task (the reverb effect) is executed using a saxophone recording as input file:

$ ACCESS_ID=deb464f7-f374-4ae8-a0b4-6c45cab86705
$ FILE_URL=http://sonicAPI.com/music/solo_sax.mp3
$ curl -i https://api.sonicapi.com/process/reverb?access_id=$ACCESS_ID\&input_file=$FILE_URL\&format=xml
HTTP/1.1 200 OK
Server: nginx/0.7.67
Date: Thu, 18 Oct 2012 14:01:16 GMT
Content-Type: application/xml
Connection: keep-alive
X-Powered-By: Express
X-Sonicapi-Request-Id: 9e067752-aa1b-4961-a122-a2aaa9a530c2
Access-Control-Allow-Origin: *
location: /file/download?file_id=52c1d6f7-67c4-4f13-848c-5f5a98f2f0c5
X-Sonicapi-File-Id: 52c1d6f7-67c4-4f13-848c-5f5a98f2f0c5
Content-Length: 326

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status code="200"/>
  <process_summary task="process/reverb">
    <output_info peak_level="-6.96" clipped="false"/>
    <parameters preset="medium_hall" reverb_time="1.33333337" pre_delay="0.00999999978" high_cut="8000" wetness="0.2"/>
  </process_summary>
</response>

Note the "format=xml" parameter in the URL that makes the webservice return an xml document with processing information (instead of the actual audio output). Using curl with the -i switch shows the response headers where we can find the id of the audio file in the "X-Sonicapi-File-Id" header. You can then download that file in various formats:

$ FILE_ID=52c1d6f7-67c4-4f13-848c-5f5a98f2f0c5
$ curl https://api.sonicapi.com/file/download?access_id=$ACCESS_ID\&file_id=$FILE_ID > download.mp3

This will download the file in the default format (mp3, 44100Hz, 192kB). You can choose different formats using the parameters listed above, e.g. to download a 48kHz lossless flac file, you could do:

$ curl https://api.sonicapi.com/file/download?access_id=$ACCESS_ID\&file_id=$FILE_ID\&format=flac\&samplerate=48000 > download.flac