29 September 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/latest/dev/ACLOverview.html#SpecifyingGranteefor 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

Format Name	Description	Allowed Values	Default Values
destination	The destination URL to put the encoded file.	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/latest/dev/ACLOverview.html#SpecifyingGrantee for details).	None
thumb_destination	The destination URL to put the thumbnail.	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/latest/dev/ACLOverview.html#SpecifyingGrantee for details).	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.

GetStatus action

<?xml version="1.0"?>
<response>
    <id>[MediaID]</id>
    <userid><<id>></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>
        <!-- Format fields -->
    </format>
    <format>
        <!-- ... -->
    </format>
</response>

{
    "response": {
        "id": "[MediaID]",
        "userid": "<<id>>",
        "sourcefile": "[SourceFile]",
        "status": "[MediaStatus]",
        "notifyurl": "[NotifyURL]",
        "created": "[Date]",
        "started": "[Date]",
        "finished": "[Date]",
        "downloaded": "[Date]",
        "time_left": "[TotalTimeLeft]",
        "progress": "[TotalProgress]",
        "time_left_current": "[StatusTimeLeft]",
        "progress_current": "[StatusProgress]",
        "format": [
            {
                "id": "[ID]",
                "status": "[Status]",
                "created": "[Date]",
                "started": "[Date]",
                "finished": "[Date]"
            }
        ]
    }
}

Where Date is of the format: YYYY-MM-DD HH:MM:SS

FormatFields is a set of fields corresponding to 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)

Notification after AddMediaBenchMark call