DeepTone™'s File Processing functionality allows you to extract insights from your audio files.
There are two ways to provide your audio files to the API.
- Send the URL of the wav file you would like to process in the
postrequest. The DeepTone™ Cloud API will then download the file and process it
- Upload the content of a local wav file directly with the
For code sample go to Example Usage
Working with stereo files
DeepTone™ processes each audio channel separately. If you provide a stereo file, you can provide a specific channel to be processed, otherwise, all channels will be processed separately.
Currently, processing WAV files is supported. Ideally, the files should be 16-bit PCM with the sample rate of 16 kHz. If a different sample rate is provided, the file will be up- or down-sampled accordingly. Please be aware though that using files with sample rates lower than recommended may lead to deterioration of analysis results.
If you're not sure your audio files meet these criteria you can use the CLI tool SoX for that verification by doing the following:
The result will be something similar to:
SoX also allows you to convert your files in case they don't match our criteria by using the following command:
File size limitations
Currently, the maximum allowed size for a file on the Cloud API is 15MB. We are actively working on expanding the supported file types and formats. Furthermore, this is not a limitation on on-premise deployments of the DeepTone™ API. If you would like to process files larger than 15MB with the Cloud API you can:
- use the streaming API to handle arbitrarily long audio streams - see Example usage in the Real-time processing section
- split the file into smaller chunks, up to 15MB each ( approximately 7min of PCM single-channel audio); send multiple requests and concatenate the results
To split the file, you could use SoX again:
Configuration options and outputs
There are different configuration parameters and types of outputs which can be requested.
Available configuration parameters
There are several possible parameters which can be passed to a post request to the
models- the list of model names to use for the audio analysis
output_period- how often (in milliseconds, multiple of 64) the output of the models should be returned
channel- optionally a channel to analyse, otherwise all channels will be analysed
include_summary- optionally if the output should contain of summary of the analysis, defaults to False
include_transitions- optionally if the output should contain transitions of the analysis, defaults to False
include_raw_values- optionally if the result should contain raw model outputs, defaults to False
volume_threshold- optionally if a volume level different than default should be considered (higher values will result in more of the data being treated as silence)
callback- optionally a callback URL that will be invoked once the results are ready. More info about this option here.
There are three possible output types, depending on the parameters that are set to
true on the request:
- a plain time series - default output type, returned always
- a plain time series with raw model outputs - raw values are appended when
- a summary - appended to the results when
- a simplified time series - appended to the results when
See below for examples of each of the three outputs:
- plain time series (according to the specified
- plain time series with additional raw outputs:
- summary (showing fraction of each class across the entire file):
- simplified time series (indicating transition points between alternating results):
callback parameter expects a valid URL that will be invoked when your job finishes processing.
Once the results are ready the API will invoke this endpoint using
POST and with a body that matches the one
returned by the
GET request to the
If the invocation to the
callback is successful the API expects a
2XX status code. In case of an unsuccessful
5XX status code) the API will retry invoking the endpoint up to 3 times. This retry mechanism means that
there's the possiblity that the
callback endpoint might receive multiple notifications, which should be handled by
the user. Any other status codes will not trigger the retry mechanism. The
callback endpoint provided should respond
within 10 seconds when being invoked, otherwise the request will timeout.
- Shell + Curl
To process a file that is available on this url:
To process a local file use the following