6 Nov 2008. Automatic frame size calculation (maintaining aspect ratio)

size [optional] - Video frame size.

Allowed values:

All: WxH, where W and N are any even integers.
3gp: 128x96, 176x144, 352x288, 704x576, 1408x1152
ipod: 320x240, 640x480
iphone: 480x368
appletv: 710x480
zune: 320x180, 320x240

Default:

All: none
3gp: 176x144
iphone: 480x368
appletv: 710x480
psp: 368x192
zune: 320x180

Note: You can specify only one dimension: either width or height. In this case, set other dimension to 0. (I.e. 640x0).

21 Oct 2008. Additional encoding options

<?xml version="1.0"?>

<query>

<!-- Format fields -->

        <output>[Output format]</output>

        <video_codec>[Video Codec]</video_codec>

        <audio_codec>[Audio Codec]</audio_codec>

        <bitrate>[Video bitrate]</bitrate>

        <audio_bitrate>[Audio bitrate]</audio_bitrate>

        <audio_sample_rate>[Audio quality]</audio_sample_rate>

        <size>[Size]</size>

        <crop_left>[Crop Left]</crop_left>

        <crop_top>[Crop Top]</crop_top>

        <crop_right>[Crop Right]</crop_right>

        <crop_bottom>[Crop Bottom]</crop_bottom>

        <thumb_time>[Thumb time]</thumb_time>

        <thumb_size>[Thumb size]</thumb_size>

        <add_meta>[yes/no]</add_meta>

        <rc_init_occupancy>[RC Occupancy]</rc_init_occupancy>

        <minrate>[Min Rate]</minrate>

        <maxrate>[Max Rate]</maxrate>

        <bufsize>[RC Buffer Size]</bufisize>

<!-- Destination fields -->

        ...             

<!-- Logo fields (OPTIONAL) -->     

        ...

    </format>

</query>

...

Format fields

maxrate [optional] - Maximum allowed video bitrate.

Allowed values:

N or Nk - where N is any non-zero integer.

Default:

None

minrate [optional] - Minimum allowed video bitrate.

Allowed values:

N or Nk - where N is any non-zero integer.

Default:

None

bufsize [optional] - Rate control buffer size (bits).

Allowed values:

N or Nk - where N is any non-zero integer.

Default:

None

rc_init_occpancy [optional] - Initial rate control buffer occupancy (bits).

Allowed values:

N or Nk - where N is any non-zero integer.

Default:

None

20 Oct 2008. Additional S3 Options

Main fields

UserID – an unique user identifier. Can be taken from user’s page.
UserKey – user’s key string. Creates automatically when user created and can be changed by user.
Action – the action to be performed.
- AddMedia – add new media to user’s media list, creates new items in a queue according to formats specified in XML
- AddMediaBenchmark - add new media to user's media list and set a flag for NOT processing it after downloading. Format fields could be specified as well. If NotifyURL is set, a notification will be sent after the media will have been ready for processing.
- UpdateMedia – replace information about existing media's formats. All old format items will be deleted, and the new ones added.
- ProcessMedia - start encoding of previously downloaded media (one that added with AddMediaBenchmark action)
- CancelMedia – delete specified media and all its items in queue
- GetMediaList – return list of user’s media
- GetStatus – return information about selected user’s media and all its items in queue
- GetMediaInfo - returns some video parameters of the specified media, if available
MediaID – an unique identifier of media. This field must be specified for the following actions: UpdateMedia, CancelMedia, GetStatus.
SourceFile – media source file. It can be in the following formats: http://[user]:[password]@ [server]/[path]/[filename] or ftp://[user]:[password]@[server]/[path]/[filename] or sftp://[user]:[password]@[server]/[path]/[filename] or http://[AWS_KEY:AWS_PWD@][bucket].s3.amazonaws.com/[filename] – If you need your S3 files to be accessed with your own AWS credentials, add your AWS key/secret to the URL. Note: do not forget to encode your AWS_SECRET, specifically replace '/ ' with '%2F'. If you don't specify AWS key/secret, the object must have READ permission for AWS user 1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869 (or for all users). See http://docs.amazonwebservices.com/AmazonS3/2006-03-01/S3_ACLs.html#S3_ACLs_Grantees∞ for details. This field must be specified only for AddMedia and AddMediaBenchmark actions.
NotifyURL – could be either an HTTP(S) URL of the script the result would be posted to, or a mailto: link with email address the result info to be sent. This field may be specified for AddMedia and AddMediaBenchmark actions.

...

Destination fields

destination [optional] - The destination URL to put the encoded file.

Allowed values:

ftp://[user]:[password]@[server]/[path]/[filename][?passive=yes],
sftp://[user]:[password]@[server]/[path]/[filename],
http://[AWS_KEY:AWS_SECRET@][bucket].s3.amazonaws.com/[filename][?acl=public-read | authenticated-read] - If you need your S3 files to be accessed with your own AWS credentials, add your AWS key/secret to the URL.
Note: do not forget to encode your AWS_SECRET, specifically replace '/ ' with '%2F'.
If you don't specify AWS key/secret, the bucket must have WRITE permission for AWS user 1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869, See http://docs.amazonwebservices.com/AmazonS3/2006-03-01/S3_ACLs.html#S3_ACLs_Grantees∞ for details.
Also, you can add ?acl=public-read OR ?acl=authenticated-read after the filename. This will explicitly set access rights to the saved object instead of the default settings.

Default:

None

thumb_destination [optional] - The destination URL to put the thumbnail.

Allowed values:

ftp://[user]:[password]@[server]/[path]/[filename],
http://[AWS_KEY:AWS_SECRET@][bucket].s3.amazonaws.com/[filename]

Default:

None

20 Oct 2008. Watermarking

XML format for user’s API request

<?xml version="1.0"?>

<query>

<!-- Main fields -->

    <userid>[UserID]</userid>

    <userkey>[UserKey]</userkey>

    <action>[Action]</action>

    <mediaid>[MediaID]</mediaid>

    <source>[SourceFile]</source>

    <notify>[NotifyURL]</notify>

    <format>

<!-- Format fields -->

        <output>[Output format]</output>

        <video_codec>[Video Codec]</video_codec>

        <audio_codec>[Audio Codec]</audio_codec>

        <bitrate>[Video bitrate]</bitrate>

        <audio_bitrate>[Audio bitrate]</audio_bitrate>

        <audio_sample_rate>[Audio quality]</audio_sample_rate>

        <size>[Size]</size>

        <crop_left>[Crop Left]</crop_left>

        <crop_top>[Crop Top]</crop_top>

        <crop_right>[Crop Right]</crop_right>

        <crop_bottom>[Crop Bottom]</crop_bottom>

        <thumb_time>[Thumb time]</thumb_time>

        <thumb_size>[Thumb size]</thumb_size>

        <add_meta>[yes/no]</add_meta>

<!-- Destination fields -->

        <destination>[DestFile]</destination>

        <thumb_destination>[Thumb Dest]</thumb_destination>     

<!-- Logo fields (OPTIONAL) -->     

        <logo>

                <logo_source>[LogoURL]</logo_source>

                <logo_x>[LogoLeft]</logo_x>     

                <logo_y>[LogoTop]</logo_y>                      

        </logo>

    </format>

</query>

Logo fields

logo_source [required] - The URL of the logo image. The image format can be GIF, JPG or PNG.

Allowed values:

http://[user]:[password]@ [server]/[path]/[filename],
ftp://[user]:[password]@[server]/[path]/[filename][?passive=yes],
sftp://[user]:[password]@[server]/[path]/[filename],

Default:

none

logo_x [optional] - left offset of logo image

Allowed values:

non-negative integer

Default:

logo_y [optional] - top offset of logo image

Allowed values:

non-negative integer

Default:

29 Sep 2008. Temporary http download of encoded videos

GetStatus action

<?xml version="1.0"?>

<response>

    <id>[MediaID]</id>

    <userid>[UserID]</userid>

    <sourcefile>[SourceFile]</sourcefile>

    <status>[MediaStatus]</status>

    <notifyurl>[NotifyURL]</notifyurl>

    <created>[Date]</created>

    <started>[Date]</started>

    <finished>[Date]</finished>

    <prevstatus>[MediaStatus]</prevstatus>

    <downloaded>[Date]</downloaded>

    <uploaded>[Date]</uploaded>

    <time_left>[TotalTimeLeft]</time_left>

    <progress>[TotalProgress]</progress>

    <time_left_current>[StatusTimeLeft]</time_left_current>

    <progress_current>[StatusProgress]</progress_current>   

    <format>

        <id>[ID]</id>

        <status>[Status]</status>

        <created>[Date]</created>

        <started>[Date]</started>

        <finished>[Date]</finished>

        [FormatFields]

        <s3_destination>[TempS3Link]</s3_destination>

    </format>

    <format>

    …

    </format>

</response>

Where Date is of the format: YYYY-MM-DD HH:MM:SS
FormatFields is a set of fields corresponding to <format> section of an user’s API request
TotalTimeLeft is an estimated time until the media processing would be finished
StatusTimeLeft is an estimated time left for the media's current status
TotalProgress is an estimated progress for entire media processing (in percent)
StatusProgress is an estimated progress for the media's current status (in percent)
TempS3Link S3 URL of the encoded file, if the <destination> was empty

29 Sep 2008. Passive FTP support

Main fields

UserID – an unique user identifier. Can be taken from user’s page.
UserKey – user’s key string. Creates automatically when user created and can be changed by user.
Action – the action to be performed.
- AddMedia – add new media to user’s media list, creates new items in a queue according to formats specified in XML
- AddMediaBenchmark - add new media to user's media list and set a flag for NOT processing it after downloading. Format fields could be specified as well.
- UpdateMedia – replace information about existing media's formats. All old format items will be deleted, and the new ones added.
- ProcessMedia - start encoding of previously downloaded media (one that added with AddMediaBenchmark action)
- CancelMedia – delete specified media and all its items in queue
- GetMediaList – return list of user’s media
- GetStatus – return information about selected user’s media and all its items in queue
- GetMediaInfo - returns some video parameters of the specified media, if available
MediaID – an unique identifier of media. This field must be specified for the following actions: UpdateMedia, CancelMedia, GetStatus.
SourceFile – media source file. It can be in the following formats: http://[user]:[password]@ [server]/[path]/[filename] or ftp://[user]:[password]@[server]/[path]/[filename][?passive=yes] or sftp://[user]:[password]@[server]/[path]/[filename] or http://[bucket].s3.amazonaws.com/[filename] – the object must have READ permission for AWS user 1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869 (or for all users). See http://docs.amazonwebservices.com/AmazonS3/2006-03-01/S3_ACLs.html#S3_ACLs_Grantees∞ for details. This field must be specified only for AddMedia action.
NotifyURL – could be either an URL of the script the result would be posted to, or a mailto: link with email address the result info to be sent. This field may be specified for AddMedia action.

......

Destination fields

destination [optional] - The destination URL to put the encoded file.

Allowed values:

ftp://[user]:[password]@[server]/[path]/[filename][?passive=yes],
sftp://[user]:[password]@[server]/[path]/[filename],
http://[bucket].s3.amazonaws.com/[filename] (the bucket must have WRITE permission for AWS user 1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869, See http://docs.amazonwebservices.com/AmazonS3/2006-03-01/S3_ACLs.html#S3_ACLs_Grantees∞ for details).

Default:

None

thumb_destination [optional] - The destination URL to put the thumbnail.

Allowed values:

ftp://[user]:[password]@[server]/[path]/[filename],
http://[bucket].s3.amazonaws.com/[filename] (the bucket must have WRITE permission for AWS user 1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869, See http://docs.amazonwebservices.com/AmazonS3/2006-03-01/S3_ACLs.html#S3_ACLs_Grantees∞ for details).

Default:

None

Note: Adding ?passive=yes to the FTP URL forces downloader/uploader use Passive Mode for FTP Transfer. Also, you can specify ?passive=no (the default) explicitly. It will take the same effect that if you don't specify this parameter at all.

29 Sep 2008. Realtime status updates

GetStatus action

<?xml version="1.0"?>

<response>

    <id>[MediaID]</id>

    <userid>[UserID]</userid>

    <sourcefile>[SourceFile]</sourcefile>

    <status>[MediaStatus]</status>

    <notifyurl>[NotifyURL]</notifyurl>

    <created>[Date]</created>

    <started>[Date]</started>

    <finished>[Date]</finished>

    <downloaded>[Date]</downloaded>

    <time_left>[TotalTimeLeft]</time_left>

    <progress>[TotalProgress]</progress>

    <time_left_current>[StatusTimeLeft]</time_left_current>

    <progress_current>[StatusProgress]</progress_current>   

    <format>

        <id>[ID]</id>

        <status>[Status]</status>

        <created>[Date]</created>

        <started>[Date]</started>

        <finished>[Date]</finished>

        [FormatFields]

    </format>

    <format>

    …

    </format>

</response>

29 Sep 2008. Notification after AddMediaBenchMark call

Main fields

UserID – an unique user identifier. Can be taken from user’s page.
UserKey – user’s key string. Creates automatically when user created and can be changed by user.
Action – the action to be performed.
- AddMedia – add new media to user’s media list, creates new items in a queue according to formats specified in XML
- AddMediaBenchmark - add new media to user's media list and set a flag for NOT processing it after downloading. Format fields could be specified as well. If NotifyURL is set, a notification will be sent after the media will have been ready for processing.

28 Aug 2008. API requests through SSL

The XML API Overview

The communication with the encoding.com is realized through a single interface: by sending HTTP(S) requests to the manage.encoding.com/. All client requests and server answers use XML format. Client must send HTTP(S) POST request with single parameter named xml.
The server response is a normal XML document.

20 Aug 2008. Additional information added to GetMediaInfo response

GetMediaInfo action

<?xml version="1.0"?>

<response>

    <bitrate>364k</bitrate>

    <duration>175.21</duration>

    <video_codec>h264</video_codec>

    <frame_rate>23.98</frame_rate>  

    <audio_sample_rate>44100</audio_sample_rate>        

    <size>352x288</size>

</response>

19 Aug 2008. New API features

Format fields

The following parameters was added:

two_pass [optional] - Whether to use 2-pass encoding

Allowed values:

yes, no

Defualt:

cbr [optional] - Whether to use CBR (Constant bitrate)

Allowed values:

yes, no

Defualt:

deinterlacing [optional] - Whether to use de-interlacing

Allowed values:

yes, no

Defualt:

06 Aug 2008. Default frame size changed

At the section XML format for user’s API request
Changed:

Format fields

size [optional] - Video frame size.

Allowed values:

All: WxH, whereW and N are any non-zero even integers.
3gp: 128x96, 176x144, 352x288, 704x576, 1408x1152
ipod: 320x240, 640x480
iphone: 480x368
appletv: 710x480
zune: 320x180, 320x240

Default:

All: none
3gp: 176x144
iphone: 480x368
appletv: 710x480
psp: 368x192
zune: 320x180

06 Aug 2008. Media Benchmarking API functions

At the section XML format for user’s API request
Changed:

Main fields

UserID – an unique user identifier. Can be taken from user’s page.
UserKey – user’s key string. Creates automatically when user created and can be changed by user.
Action – the action to be performed.
- AddMedia – add new media to user’s media list, creates new items in a queue according to formats specified in XML
- AddMediaBenchmark - add new media to user's media list and set a flag for NOT processing it after downloading. Format fields could be specified as well.
- UpdateMedia – replace information about existing media's formats. All old format items will be deleted, and the new ones added.
- ProcessMedia - start encoding of previously downloaded media (one that added with AddMediaBenchmark action)
- CancelMedia – delete specified media and all its items in queue
- GetMediaList – return list of user’s media
- GetStatus – return information about selected user’s media and all its items in queue
- GetMediaInfo - returns some video parameters of the specified media, if available
MediaID – an unique identifier of media. This field must be specified for the following actions: UpdateMedia, CancelMedia, GetStatus.
SourceFile – media source file. It can be in the following formats: http://[user]:[password]@ [server]/[path]/[filename] or ftp://[user]:[password]@[server]/[path]/[filename] or sftp://[user]:[password]@[server]/[path]/[filename] or http://[bucket].s3.amazonaws.com/[filename] – the object must have READ permission for AWS user 1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869 (or for all users). See http://docs.amazonwebservices.com/AmazonS3/2006-03-01/S3_ACLs.html#S3_ACLs_Grantees∞ for details. This field must be specified only for AddMedia action.
NotifyURL – could be either an URL of the script the result would be posted to, or a mailto: link with email address the result info to be sent. This field may be specified for AddMedia action.

At the section Server Response XML format
Added:

GetMediaInfo action

<?xml version="1.0"?>

<response>

    <bitrate>364k</bitrate>

    <duration>175.21</duration>

    <video_codec>h264</video_codec>

    <size>352x288</size>

</response>

15 Jul 2008

At the section XML format for user’s API request
Added:

Multiple Thumbnail Support

Instead of using thumb_ parameters within <format>, you can specify separate encoding task with output = thumbnail:

    <format>

    <!-- Format fields -->

        <output>thumbnail</output>

        <time>[Size]</time>     

        <width>[Width]</width>

        <height>[Size]</height>

    <!-- Destination fields -->

        <destination>[DestFile]</destination>

    </format>

With the following specific parameters:

time [optional] – Timestamp (in seconds) to capture thumbnail.

Allowed values:

Non-negative integer or hh:mm:ss.ms

Default: 5

width [optional] - Thumbnail width (in pixels)

Allowed values:

Non-negative integer

Default: none

height [optional] - Thumbnail height (in pixels)

Allowed values:

Non-negative integer

Default: none

destination [optional] - The destination URL to put the thumbnail.

If you specify both width and height, you'll get a thumbnail with these dimensions, and if your video have another aspect ratio than the thumbnail, black spaces will be added to the picture.
If you specify only one parameter from this pair, the other one will be calculated according to your video size.
If none of those parameters specified, the thumbnail will have the same size as your video have.
Now only JPEG format is supported for thumbnails.

15 Jul 2008

At the section Server Response XML format
New server response format added:

AddMedia action

<?xml version="1.0"?>

<response>

    <message>Added</message>

    <MediaID>[MediaID]</MediaID>

</response>

3 Jul 2008. VP6 Support

Added:

VP6 Features

If you choose vp6 for output format, your XML query will differ (you can specify only two parameters in addition to output at format fields section):

    <format>

    <!-- Format fields -->

        <output>vp6</output>

        <profile>[VP6 profile]</profile>

        <size>[Size]</size>

    <!-- Destination fields -->

        <destination>[DestFile]</destination>

    </format>

The specific parameter profile is added:

profile [optional] – VP6 profile.

Allowed values:

VP6-E, VP6-S

Default: VP6-E

destination [required] - The destination URL to put the encoded file.