File Processing - Audio Conversion

Video and Audio Transcoding are included in the PLUS and higher plans. Choose Plan

Filestack supports audio transcoding. Just upload any of the following audio formats to Filestack (mp3, wav, ogg, aac, wma) and you can transcode it to another audio format by calling video_convert.

Note: Each second of audio transcoded counts as 2 image transformations. Please take your plan's conversion limits into account before processing any audio, as you can quickly exceed your plan's limits and incur overages.

Here is Op.14, Scherzo No.2 in C minor for piano (1845) by Clara Schumann in OGG format

Here is the same recording converted to mp3 using Filestack

Convert ( GET / video_convert )

This api endpoint is extremely simple to use, just send GET to your FileLink with conversion parameters like this (sample conversion from above):

>>> curl -X GET "https://process.filestackapi.com/AhTgLagciQByzXpFGRI0Az/video_convert=audio_bitrate:64,audio_sample_rate:48000,filename:custom,preset:mp3/https://upload.wikimedia.org/wikipedia/commons/b/b5/Op.14%2C_Scherzo_No.2_in_C_minor_for_piano%2C_C._Schumann.ogg"
            

In response you will get:

{
  "data":{},
  "metadata":{"result":{},"source":{}},
  "status":"started",
  "timestamp":"1456384569",
  "uuid":"57694303a5d29c148154d5f706b4c256"
}
          

Notice the uuid field. You will need it later when the webhook comes in order to identify which audio file has completed conversion.

Audio Transcoding Parameters

video_convert=preset:mp3
String

Can be abbreviated as p:oga

The API supports converting from and to any of the following formats (presets):

  • mp3
  • oga
  • m4a
  • aac
  • hls.variant.audio

Note: When using the HLS preset, many files will be generated in your storage container and we will return you a special processing engine link to the playlist file: https://process.filestackapi.com/AHvhedybhQMqZOqRvZquez/video_playlist/3SWjVSVQFqadVP6irhJQ. The video_playlist task generates the playlist dynamically so that all the segments in the playlist can have the same security policy and signature applied in the request if security is enabled for your API key.

video_convert=force:true
Boolean

Cannot be abbreviated

Restarts completed or pending audio encoding. If a transcoding fails, and you make the same request again, it will not restart the transcoding process without force:true.

video_convert=title:test
String

Can be abbreviated as t:something

Set the title in the file metadata.

video_convert=extname:.mp4
String

Can be abbreviated as e:.webm

Set the file extension for the audio file that is generated by the transcoding process.

video_convert=filename:myvideo
String

Cannot be abbreviated.

Set the filename of the audio file that is generated by the transcoding process.

video_convert=location:S3
String

Cannot be abbreviated.

The custom storage service to store the converted file to, options incude 'S3', 'azure', 'gcs', 'rackspace', and 'dropbox'

video_convert=path:"/myfiles/1234.mp4"
String

Cannot be abbreviated.

The path to store the file at within the specified file store. For S3, this is the key where the file will be stored at. By default, Filestack stores the file at the root at a unique id, followed by an underscore, followed by the filename, for example "3AB239102DB_myaudio.mp3"

video_convert=access:public
String

Cannot be abbreviated.

Indicates that the file should be stored in a way that allows public access going directly to the underlying file store. For instance, if the file is stored on S3, this will allow the S3 url to be used directly. This has no impact on the ability of users to read from the Filestack file URL. Defaults to 'private'.

video_convert=container:user-videos
String

Cannot be abbreviated.

The bucket or container in the specified file store where the file should end up. This is especially useful if you have different containers for testing and production and you want to use them both on the same Filestack app. If this parameter is omitted, the file is stored in the default container specified in your developer portal.

video_convert=audio_bitrate:256
Integer

Cannot be abbreviated.

Sets the audio bitrate for the audio file that is generated by the transcoding process. Must be an integer between 0 and 999.

video_convert=audio_sample_rate:44100
Integer

Can be abbreviated as r:48000.

Set the audio sample rate for the audio file that is generated by the transcoding process. Can be an integer between 0 and 99999. Default is 44100.

video_convert=audio_channels:2
Integer

Can be abbreviated as c:2.

Set the number of audio channels for the audio file that is generated by the transcoding process. Can be an integer between 1 and 12. Default is same as source audio.

video_convert=clip_length:00:00:20
String

Can be abbreviated as l:00:10:00.

Set the length of the audio file that is generated by the transcoding process. Should be a timecode that includes hours, minutes and seconds.

video_convert=clip_offset:00:00:10
String

Can be abbreviated as o:00:00:05.

Set the point to begin the audio clip from. For example, clip_offset:00:00:10 will start the audio transcode 10 seconds into the source audio file. Should be a timecode that includes hours, minutes and seconds.

security=policy:your_base64_encoded_policy
String

Can be abbreviated as p:your_base64_encoded_policy.

If you have security enabled for your Filestack account, this is the policy to sign your request with. The policy needs to be part of the security task (this is separate from the video_covert task). The URL will look like this: https://process.filestackapi.com/security=policy:eyJleHBpcnkiOiAxNDg1MTAxNjc4fQ==,signature:0888187c8ea0773fb136fe267ee160a72da3c3c2d4faae9273759a8dc167894f/lUMgI8FDRQGJJMzbIPD9/video_convert=width:12/lUMgI8FDRQGJJMzbIPD9

security=signature:your_HMAC-SHA256_hex_encoded_signature
String

Can be abbreviated as s:your_HMAC-SHA256_hex_encoded_signature.

If you have security enabled for your Filestack account, this is the signature to sign your request with. The signature needs to be part of the security task (this is separate from the video_covert task). The URL will look like this: https://process.filestackapi.com/security=policy:eyJleHBpcnkiOiAxNDg1MTAxNjc4fQ==,signature:0888187c8ea0773fb136fe267ee160a72da3c3c2d4faae9273759a8dc167894f/lUMgI8FDRQGJJMzbIPD9/video_convert=width:12/lUMgI8FDRQGJJMzbIPD9

Audio Webhooks

Webhooks are used to notify you when the transcoding has completed.

You can specify webhook URL in your Filestack Developer Portal:

Once your audio file has finished processing you will receive a notification webhook to the URL you specify in your developer portal:

{
   "data":{
      "url":"https://cdn.filestackcontent.com/2xIn8g3AQdmfFPD5Brkk"
   },
   "metadata":{
      "result":{
         "audio_bitrate":64,
         "audio_channels":2,
         "audio_codec":"mp3",
         "audio_sample_rate":48000,
         "created_at":"2016/02/25 07:16:08 +0000",
         "duration":251472,
         "encoding_progress":100,
         "encoding_time":16,
         "extname":".mp3",
         "file_size":2.012013e+06,
         "mime_type":"audio/mpeg",
         "started_encoding_at":"2016/02/25 07:16:09 +0000",
         "updated_at":"2016/02/25 07:16:27 +0000"
      },
      "source":{
         "audio_bitrate":128,
         "audio_channels":2,
         "audio_codec":"vorbis",
         "audio_sample_rate":44100,
         "created_at":"2016/02/25 07:16:08 +0000",
         "duration":251427,
         "extname":".ogg",
         "file_size":3.062342e+06,
         "mime_type":"audio/ogg",
         "updated_at":"2016/02/25 07:16:27 +0000"
      }
   },
   "status":"completed",
   "timestamp":"1456384626",
   "uuid":"57694303a5d29c148154d5f706b4c256"
}
            

Returned Filestack Webhook Data:

url FileLink to encoded audio file.

Cache

Encodings for FileLinks with the same parameters are cached. So if you run the same conversion multiple times, you will receive results immediately:

>>> curl -X GET "https://process.filestackapi.com/AhTgLagciQByzXpFGRI0Az/video_convert=audio_bitrate:64,audio_sample_rate:48000,filename:custom,preset:mp3/https://upload.wikimedia.org/wikipedia/commons/b/b5/Op.14%2C_Scherzo_No.2_in_C_minor_for_piano%2C_C._Schumann.ogg"
            

Response:

{
   "data":{
      "url":"https://cdn.filestackcontent.com/2xIn8g3AQdmfFPD5Brkk"
   },
   "metadata":{
      "result":{
         "audio_bitrate":64,
         "audio_channels":2,
         "audio_codec":"mp3",
         "audio_sample_rate":48000,
         "created_at":"2016/02/25 07:16:08 +0000",
         "duration":251472,
         "encoding_progress":100,
         "encoding_time":16,
         "extname":".mp3",
         "file_size":2.012013e+06,
         "mime_type":"audio/mpeg",
         "started_encoding_at":"2016/02/25 07:16:09 +0000",
         "updated_at":"2016/02/25 07:16:27 +0000"
      },
      "source":{
         "audio_bitrate":128,
         "audio_channels":2,
         "audio_codec":"vorbis",
         "audio_sample_rate":44100,
         "created_at":"2016/02/25 07:16:08 +0000",
         "duration":251427,
         "extname":".ogg",
         "file_size":3.062342e+06,
         "mime_type":"audio/ogg",
         "updated_at":"2016/02/25 07:16:27 +0000"
      }
   },
   "status":"completed",
   "timestamp":"1456384626",
   "uuid":"57694303a5d29c148154d5f706b4c256"
}
            

Audio Transcoding Examples:

Audio conversion - Changing audio bitrate/sample rate and using custom filename

>>> curl -X GET "https://process.filestackapi.com/AhTgLagciQByzXpFGRI0Az/video_convert=audio_bitrate:64,audio_sample_rate:48000,filename:custom,preset:mp3/ualPLxPTQZig8xCA88nB"
            

Result:

Audio conversion - clipping the track

>>> curl -X GET "https://process.filestackapi.com/AhTgLagciQByzXpFGRI0Az/video_convert=preset:mp3,clip_offset:00:00:05,clip_length:00:00:10/ualPLxPTQZig8xCA88nB"
            

Result:

Audio conversion - Convert stereo to mono

>>> curl -X GET "https://process.filestackapi.com/AhTgLagciQByzXpFGRI0Az/video_convert=preset:m4a,audio_channels:1/ualPLxPTQZig8xCA88nB"
            

Result: