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, mp3-cbr, mp3-vbr, 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. | |
| mp3-cbr | bitrate | 192 | 32; 48; 64; 96; 128; 160; 192; 256; 320 | The bit rate of the file in kbps. Both, the file size and the audio quality increase with increasing bit rate. |
| samplerate | 44100 | 16000; 22050; 24000; 32000; 44100; 48000 | The number of audio samples per channel per second. | |
| mp3-vbr | compression | 4 | 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 | 16000; 22050; 24000; 32000; 44100; 48000 | The number of audio samples per channel per second. |
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