Skip to content Skip to main navigation Skip to footer

Understand SPE audio converter

SPE directly supports limited list of audio formats (codecs and containers), see Supported audio formats FAQ. Other audio formats must be converted using external tools.

This conversion can be done either completely outside of SPE, before passing the files to SPE, or you can set up SPE to convert the files automatically. Then, depending on the capabilities of the conversion tool, you can upload essentially any audio- or even videofile to SPE and it will be automatically converted to audio format supported natively by SPE.

NOTE: The automatic conversion is done only when uploading audiofiles to SPE, it’s not done when registering files! For more info about uploading/registering audiofiles, see Understanding SPE home directory article.

Converter installation

As a first step it’s necessary to install external converter of your choice on your operating system.

We recommend using either the well-known FFmpeg (ffmpeg.org) or SoX (sox.sourceforge.net), but you can use any other command line tool or script which accepts input file name and output file name as parameters (like my_converter <inputfile> <outputfile>).

? Linux
Use your distro’s package manager to install the converter (e.g. on Ubuntu: sudo apt install ffmpeg, on CentOS sudo yum install ffmpeg, or similar, depending on your OS, version and configuration).

Windows
The simplest way is to download the converter distribution package from its site and copy the executable (ffmpeg.exe, sox.exe, etc.) and all required accompanying DLLs to the SPE installation directory, i.e. along the phxspe.exe.
FFmpeg: https://ffmpeg.org/download.html
SoX: https://sourceforge.net/projects/sox/files/sox/
(The FFmpeg is a bit ‘cleaner’ choice on Windows, since it’s available also as single-executable static build, unlike SoX whose 10+ DLLs clutter up the SPE directory)

SPE configuration

As a next step it’s necessary to enable and set up the converter in SPE configuration file (in settings/phxspe.properties).

  1. Set the audio_converter.enabled to true to enable the converter
  2. Set the audio_converter.command to the actual command to be executed by the converter. Use %1 as placeholder for the input file, and %2 as placeholder for the output file.

The SPE configuration file contains ready-to-use example commands for both FFmpeg and SoX. For both of these tools it is basically enough to specify the input file and output file… and the converter does its best guess on what exactly needs to be done.

After changing the configuration, restart SPE and the automatic audio conversion is ready for use.

How the audio conversion works

After uploading the file, internal subsystem checks the file format (i.e. checks whether it’s supported natively). And the outcome can be basically one of the following:

  • it’s one of the natively supported formats – then SPE simply continues the processing
  • it’s one of “internally recognized”, but not natively supported formats (e.g. MP3 audio) – then
    • if converter is enabled, SPE tries to convert the file
    • if converter is disabled, upload ends up with error
  • it’s some “internally unrecognized” format – this causes error during format detection and then
    • if converter is enabled, SPE tries to convert the file
    • if converter is disabled, upload ends up with error

Example

Below you can see example of the 3rd case, the “internally unrecognized” format (in this case it was G.723.1 codec, but it’s not relevant).

First, the file was uploaded to SPE with converter enabled – the “Corrupted WAVE file format” BSAPI exception is somehow confusing here, since it’s actually a harmless error, meaning just that the format detection failed. However, since the converter is enabled, SPE called the converter, file was converted and successfully recognized afterwards – the response contains the converted file attributes.

The second time, the file was uploaded to SPE with converter disabled – the subsystem again failed to detect the format (BSAPI exception) and SPE couldn’t call the converter because it’s disabled – the upload fails with Unsupported audio format error response.

 

SPE log
=======
2021-01-30 20:49:26 [Debug] server: Incoming request: [RID=2] from=127.0.0.1:52762, method=POST, URI=/audiofile?path=%2Ftest1.wav&format=json
2021-01-30 20:49:26 [Trace] ConverterSubsystem: Request stream saved to temporary file: C:\TMP\tmp9408aaaaaa
2021-01-30 20:49:26 [Error] ConverterSubsystem: Error during detecting file format 'C:\TMP\tmp9408aaaaaa': BsapiException: SWaveFileI(1751): Corrupted WAVE file format: 'C:\TMP\tmp9408aaaaaa'.
2021-01-30 20:49:26 [Trace] ConverterSubsystem: Converting C:\TMP\tmp9408aaaaaa -> C:\TMP\tmp9408baaaaa.wav
2021-01-30 20:49:27 [Debug] ConverterSubsystem: File C:\TMP\tmp9408aaaaaa has been converted.
2021-01-30 20:49:27 [Trace] ConverterSubsystem: Removed temporary file: C:\TMP\tmp9408aaaaaa
2021-01-30 20:49:27 [Trace] Data: Moving: 'C:\TMP\tmp9408baaaaa.wav' -> 'D:\SPE\home\admin\storage\test1.wav'
2021-01-30 20:49:27 [Trace] Data: Moved: 'C:\TMP\tmp9408baaaaa.wav' -> 'D:\SPE\home\admin\storage\test1.wav'
2021-01-30 20:49:27 [Trace] Data: File '/test1.wav' registered in database
2021-01-30 20:49:27 [Trace] Rest.Object.AudioFile: [RID=2] Response HTTP: 200

JSON reposnse (all OK)
======================
{
  "result" : {
    "version" : 3,
    "name" : "AudioFileInfoResult",
    "info" : {
      "name" : "test1.wav",
      "last_modified" : "2021-01-30T19:49:27Z",
      "created" : "2021-09-27T18:16:59Z",
      "size" : 12800718,
      "is_directory" : false,
      "is_registered" : true,
      "frequency" : 8000,
      "length" : 400.02,
      "n_channels" : 2,
      "format" : "lin16"
    }
  }
}

 

SPE log
=======
2021-01-30 20:59:52 [Debug] server: Incoming request: [RID=2] from=127.0.0.1:51052, method=POST, URI=/audiofile?path=%2Ftest1.wav&format=json
2021-01-30 20:59:52 [Trace] ConverterSubsystem: Request stream saved to temporary file: C:\TMP\tmp11452aaaaaa
2021-01-30 20:59:52 [Error] ConverterSubsystem: Error during detecting file format 'C:\TMP\tmp11452aaaaaa': BsapiException: SWaveFileI(1751): Corrupted WAVE file format: 'C:\TMP\tmp11452aaaaaa'.
2021-01-30 20:59:52 [Error] ConverterSubsystem: Audio can't be converted: Converter is disabled
2021-01-30 20:59:52 [Trace] ConverterSubsystem: Removed temporary file: C:\TMP\tmp11452aaaaaa
2021-01-30 20:59:52 [Error] Rest.Object.AudioFile: [RID=2] REST error: (1007) Unsupported audio format
2021-01-30 20:59:52 [Trace] Rest.Object.AudioFile: [RID=2] Response HTTP: 415 RESTError: 1007




JSON response (error)
=====================
{
  "result" : {
    "version" : 2,
    "name" : "ErrorResult",
    "code" : 1007,
    "message" : "(1007) Unsupported audio format"
  }
}
Related Articles