File Processing - Video Conversion

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

Filestack supports video and audio transcoding, just upload any video/audio file to filestack and you can transcode it by calling video_convert.

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

Here is a video file uploaded as mp4/h264

Here is the same video converted to webm

Convert ( GET / video_convert )

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

>>> curl -X GET "https://process.filestackapi.com/AhTgLagciQByzXpFGRI0Az/video_convert=height:260,width:300,preset:webm/Q5eBTKldRfCSuEjUYuAz"
            

In response you will receive:

{
  "data":{},
  "status":"started",
  "timestamp":"1450730720",
  "uuid":"638311d89d2bc849563a674a45809b7c"
}
          

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

Video Transcoding Parameters

video_convert=preset:webm
String

Can be abbreviated as p:h264

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

  • h264
  • h264.hi
  • webm
  • webm.hi
  • ogg
  • ogg.hi
  • hls.variant
  • 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 video encoding. If a transcoding fails, and you make the same request again, it will not restart the transcoding process without force:true.

video_convert=width:1080
Integer

Can be abbreviated as w:1080

Set the width in pixels of the video that is generated by the transcoding process.

video_convert=height:720
Integer

Can be abbreviated as h:720

Set the height in pixels of the video that is generated by the transcoding process.

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 video that is generated by the transcoding process.

video_convert=filename:myvideo
String

Cannot be abbreviated.

Set the filename of the video 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_myvideo.mp4"

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=upscale:true
Boolean

Can be abbreviated as u:false.

Upscale the video resolution to match your profile. Defaults to true.

video_convert=aspect_mode:letterbox
String

Can be abbreviated as a:preserve.

(default: letterbox) Available options: constrain, letterbox, pad, crop, preserve

  • 'preserve` - Original size and ratio is preserved. If height and width parameters are passed along with apect_mode=preserve they will be ignored
  • 'constrain' - Aspect ratio is maintained, No black bars are added to the output
  • 'letterbox' - Adds black bars to defined height
  • 'pad' - Adds black bars to output to match defined frame size
  • 'crop' - Fills frame size and crops the rest

video_convert=two_pass:true
Boolean

Can be abbreviated as s:true.

Specify that the transcoding process should do two passes to improve video quality. Defaults to false.

video_convert=video_bitrate:3000
Integer

Can be abbreviated as b:1024.

Specify the video bitrate for the video that is generated by the transcoding process. Must be an integer between 1 and 5000

video_convert=fps:24
Integer

Can be abbreviated as f:30.

Specify the frames per second of the video that is generated by the transcoding process. Must be an integer between 1 and 300 Default is to copy the original fps of the source file.

video_convert=keyframe_interval:250
Integer

Can be abbreviated as k:250.

Adds a key frame every 250 frames to the video that is generated by the transcoding process. Default is 250.

video_convert=audio_bitrate:256
Integer

Cannot be abbreviated.

Sets the audio bitrate for the video 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 video 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 video that is generated by the transcoding process. Can be an integer between 1 and 12. Default is same as source video.

video_convert=clip_length:00:00:20
String

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

Set the length of the video 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 video clip from. For example, clip_offset:00:00:10 will start the video transcode 10 seconds into the source video. Should be a timecode that includes hours, minutes and seconds.

video_convert=watermark_url:Bc2FQwXReueTsaeXB6rO
String

Cannot be abbreviated.

The Filestack handle or URL of the image file to use as a watermark on the transcoded video.

video_convert=watermark_url:Bc2FQwXReueTsaeXB6rO
String

Cannot be abbreviated.

The Filestack handle or URL of the image file to use as a watermark on the transcoded video.

video_convert=watermark_top:10
Integer

Cannot be abbreviated.

The distance from the top of the video frame to place the watermark on the video. Default is 0. Can be an integer between 0 and 9999.

video_convert=watermark_bottom:10
Integer

Cannot be abbreviated.

The distance from the bottom of the video frame to place the watermark on the video. Default is 0. Can be an integer between 0 and 9999.

video_convert=watermark_left:10
Integer

Cannot be abbreviated.

The distance from the left side of the video frame to place the watermark on the video. Default is 0. Can be an integer between 0 and 9999.

video_convert=watermark_right:10
Integer

Cannot be abbreviated.

The distance from the right side of the video frame to place the watermark on the video. Default is 0. Can be an integer between 0 and 9999.

video_convert=watermark_width:300
Integer

Cannot be abbreviated.

Resize the width of the watermark

video_convert=watermark_height:200
Integer

Cannot be abbreviated.

Resize the height of the watermark

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

Video Webhooks

Webhooks are used to notify you when the transcoding has completed. You can specify your webhook URL in your Filestack Developer Portal:

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

{
   "status":"completed",
   "message":"Done",
   "data":{
      "thumb":"https://cdn.filestackcontent.com/f1e8V88QDuxzOvtOAq1W",
      "thumb100x100":"https://process.filestackapi.com/AhTgLagciQByzXpFGRI0Az/resize=w:100,h:100,f:crop/output=f:jpg,q:66/https://cdn.filestackcontent.com/f1e8V88QDuxzOvtOAq1W",
      "thumb200x200":"https://process.filestackapi.com/AhTgLagciQByzXpFGRI0Az/resize=w:200,h:200,f:crop/output=f:jpg,q:66/https://cdn.filestackcontent.com/f1e8V88QDuxzOvtOAq1W",
      "thumb300x300":"https://process.filestackapi.com/AhTgLagciQByzXpFGRI0Az/resize=w:300,h:300,f:crop/output=f:jpg,q:66/https://cdn.filestackcontent.com/f1e8V88QDuxzOvtOAq1W",
      "url":"https://cdn.filestackcontent.com/VgvFVdvvTkml0WXPIoGn"
   },
   "metadata":{
      "result":{
         "audio_channels":2,
         "audio_codec":"vorbis",
         "audio_sample_rate":44100,
         "created_at":"2015/12/21 20:45:19 +0000",
         "duration":10587,
         "encoding_progress":100,
         "encoding_time":8,
         "extname":".webm",
         "file_size":293459,
         "fps":24,
         "height":260,
         "mime_type":"video/webm",
         "started_encoding_at":"2015/12/21 20:45:22 +0000",
         "updated_at":"2015/12/21 20:45:32 +0000",
         "video_bitrate":221,
         "video_codec":"vp8",
         "width":300
      },
      "source":{
         "audio_bitrate":125,
         "audio_channels":2,
         "audio_codec":"aac",
         "audio_sample_rate":44100,
         "created_at":"2015/12/21 20:45:19 +0000",
         "duration":10564,
         "extname":".mp4",
         "file_size":875797,
         "fps":24,
         "height":360,
         "mime_type":"video/mp4",
         "updated_at":"2015/12/21 20:45:32 +0000",
         "video_bitrate":196,
         "video_codec":"h264",
         "width":480
      }
   },
   "timestamp":"1453850583",
   "uuid":"638311d89d2bc849563a674a45809b7c"
}
            

Returned Filestack Webhook Data:

url FileLink to encoded video.
thumb A full frame captured from the encoded video. (Video only)
thumb100x100 Thumbnail 100 x 100 from video. (Video only)
thumb200x200 Thumbnail 200 x 200 from video. (Video only)
thumb300x300 Thumbnail 300 x 300 from video. (Video only)

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=height:260,width:300,preset:webm/Q5eBTKldRfCSuEjUYuAz"
            

Response:

{
   "status":"completed",
   "message":"Done",
   "data":{
      "thumb":"https://cdn.filestackcontent.com/f1e8V88QDuxzOvtOAq1W",
      "thumb100x100":"https://process.filestackapi.com/AhTgLagciQByzXpFGRI0Az/resize=w:100,h:100,f:crop/output=f:jpg,q:66/https://cdn.filestackcontent.com/f1e8V88QDuxzOvtOAq1W",
      "thumb200x200":"https://process.filestackapi.com/AhTgLagciQByzXpFGRI0Az/resize=w:200,h:200,f:crop/output=f:jpg,q:66/https://cdn.filestackcontent.com/f1e8V88QDuxzOvtOAq1W",
      "thumb300x300":"https://process.filestackapi.com/AhTgLagciQByzXpFGRI0Az/resize=w:300,h:300,f:crop/output=f:jpg,q:66/https://cdn.filestackcontent.com/f1e8V88QDuxzOvtOAq1W",
      "url":"https://cdn.filestackcontent.com/VgvFVdvvTkml0WXPIoGn"
   },
   "metadata":{
      "result":{
         "audio_channels":2,
         "audio_codec":"vorbis",
         "audio_sample_rate":44100,
         "created_at":"2015/12/21 20:45:19 +0000",
         "duration":10587,
         "encoding_progress":100,
         "encoding_time":8,
         "extname":".webm",
         "file_size":293459,
         "fps":24,
         "height":260,
         "mime_type":"video/webm",
         "started_encoding_at":"2015/12/21 20:45:22 +0000",
         "updated_at":"2015/12/21 20:45:32 +0000",
         "video_bitrate":221,
         "video_codec":"vp8",
         "width":300
      },
      "source":{
         "audio_bitrate":125,
         "audio_channels":2,
         "audio_codec":"aac",
         "audio_sample_rate":44100,
         "created_at":"2015/12/21 20:45:19 +0000",
         "duration":10564,
         "extname":".mp4",
         "file_size":875797,
         "fps":24,
         "height":360,
         "mime_type":"video/mp4",
         "updated_at":"2015/12/21 20:45:32 +0000",
         "video_bitrate":196,
         "video_codec":"h264",
         "width":480
      }
   },
   "timestamp":"1453850583",
   "uuid":"638311d89d2bc849563a674a45809b7c"
}
            

Transcoding Examples:

Watermark

curl -X GET "https://process.filestackapi.com/AhTgLagciQByzXpFGRI0Az/video_convert=watermark_url:Bc2FQwXReueTsaeXB6rO,watermark_top:10,watermark_right:50,preset:webm/Q5eBTKldRfCSuEjUYuAz"
            

Result

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