API Overview

Hello Developers.

It's time to integrate an ultra fast cloud media processing service into your CMS, MAM or proprietary media workflow. Our API will give you access to over 25 professionally maintained encoding engines for all your media processing needs, from decoding, transcoding, audio processing, image processing, closed caption conversion, programmatic editing, adaptive bitrate packaging and digital right management.

Getting Started

1.Register
2.Build & Post
3.Integrate
 

Access both the Encoding.com and Vid.ly APIs via our Developer account that includes API credentials, 1 GB of free encoding bandwidth per month and access to all of our powerful features. Usage rates apply to Vidly usage.

When ready to deploy your video application, simply login to the Encoding.com Client Interface and select one of the Monthly or Pre-Pay plans to meet your projected encoding volumes and SLA requirements. High-volume users should connect directly with us for custom plans. All of our plans are designed to scale with your usage.

Select target formats:
Utilize one of our expert-designed web, mobile or set-top box Presets, or customize and save your own encoding profiles. Presets are a great way to begin.

Build your XML template:
Copy the XML from our web interface or code from scratch using our complete API documentation.

Post and Go:
Send your XML template to our API endpoint via an HTTP post. Or, use our browser-based XML submission tool to verify and test your XML without writing a single line of code.

Accelerate your development:
We have API wrappers for all popular languages: PHP, Zend, Ruby, Python, Java, ColdFusion, .NET, VBScript

Design your workflow:
Chose from basic or advanced workflows using AddMedia or AddMediaBenchmark. Add a simple listener script to receive our notification posts informing you when jobs are complete.

Browser video upload system (UGV):
Enable end users to upload videos directly to Encoding.com. Use our out-of-the-box PHP or .NET code that includes API integration, browser-based upload functions, a progress bar, notifications and cloud storage.

30 Second Sign Up No credit card required. 1GB every month!

Our official in-depth look at the complete API documentation — created by developers for developers.

API Workflow Overview

The Encoding.com API allows you to automate a high volume workflow by integrating a fast and scalable media processing platform into your, CMS, MAM, or application. Our XML or JSON API is the most mature, well documented and feature rich cloud encoding API on the market. Our API Builder will help generate properly format, and test your JSON or XML requests before writing a single line of code.

Here is how is works:

Your application sends either the AddMedia or AddMediaBenchmark API request to Encoding.com which includes:

  • The source location of your video.
  • Job notification location (http or email)
  • One or multiple custom or preset desired encoding recipes.
  • One or multiple delivery points for your video.

 

Encoding.com responds immediately with a media ID so your application can track the progress of the job.

With the fastest SLA backed queue times in the industry, Encoding.com processes all of your jobs in parallel on dedicated multi core servers. Chose from three processing speed level, Baseline (4 core), Turbo (8 core), Twin Turbo (16 core). Our platform scales and assigns compute in realtime based on your needs so if you sent us 1 jobs with 1 output, it would process just as fast as if you sent us 250 jobs each with 10 outputs.

When processing is complete we will automatically send your output to your specified delivery point and send a http or email notification to your application. Notification posts are originating from 74.205.109.120 to 74.205.109.120. See our help article for a complete list of IP ranges if you are interested in allowing firewalls access, however please note the IPs addresses within a public cloud environment are subject to change often and without notice.

Our XML or JSON API can be quickly integrated into applications written in any language. To accelerate your development we provide and support code libraries in many popular languages: PHP, Java, CFM, C#. There are also dozens of unofficial code libraries.

Some API Features to note:

Easily copy custom or preset XML encoding templates in the client interface and then use with the API
GetStatus or GetStatusExtended : Will deliver individual job progress per media ID throughout all phases of the job.
Possible status results are: 
 New, Downloading, Downloaded, Ready to process, Waiting for encoder, Processing, Saving, Finished, Error, Stopped
Perform advanced editing: watermarks, cropping, thumbnail generation, concatenation, picture in picture, custom text overlay.
GetmediaInfo: Get detailed media information about your source video to store in your application or customize your encoding recipes.
Complete sub user account system let's you manage sub users and isolate sub users encoding usage.

End Point

To send API requests to Encoding.com, please send HTTP(S) post requests to:
http(s)://manage.encoding.com
All client requests and server responses use the XML or JSON format. Clients must send the HTTP(S) POST request with a single parameter named xml. The server response will be a normal XML document or JSON string. Please urlencode any special characters in source or destination url paths and then url encode the entire XML request using content-type: application/x-www-form-urlencoded.

Authentication

UserID

A unique user identifier. This number can be found in the My Account tab of the Client Interface.

UserKey

A user's unique authentication key string. Created automatically when a user is created and can be regenerated at anytime in the My Account tab of the Client Interface.

Complete Request Template

<?xml version="1.0"?>
<query>
<!-- Main fields -->
    <userid>[UserID]</userid>
    <userkey>[UserKey]</userkey>
    <action>[Action]</action>
    <mediaid>[MediaID]</mediaid>
    <source>[SourceFile]</source>

    <!-- if multiple SourceFile added, they will be concatenated or join to split screen-->
    <source>[SourceFile1]</source>
    <!-- ... -->
    <source>[SourceFileN]</source>

    <!-- Split Screen fields (OPTIONAL) -->
    <split_screen>
        <columns>[ColumnsNumber]</columns>
        <rows>[RowsNumber]</rows>
        <padding_left>[PaddingLeftInPx]</padding_left>
        <padding_right>[PaddingRightInPx]</padding_right>
        <padding_bottom>[PaddingBottomInPx]</padding_bottom>
        <padding_top>[PaddingTopInPx]</padding_top>
    </split_screen>

    <region>[us-east-1|us-west-1|us-west-2|eu-west-1|ap-southeast-1|ap-southeast-2|ap-northeast-1|sa-east-1]</region> 
    <notify_format>[xml|json]</notify_format>
    <notify>[NotifyURL]</notify>
    <notify_encoding_errors>[NotifyEncodingErrorURL]</notify_encoding_errors>
    <notify_upload>[NotifyUploadURL]</notify_upload>
    <format>

        <!-- Format fields -->
        <noise_reduction>luma_spatial:chroma_spatial:luma_temp</noise_reduction>
        <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>
        <audio_channels_number>[Audio channels number]</audio_channels_number>
        <audio_volume>[Volume]</audio_volume>         
        <audio_normalization>[0-100]</audio_normalization>         
        <framerate>[Frame Rate]</framerate>
        <framerate_upper_threshold>[Frame Rate Upper Threshold]</framerate_upper_threshold>
        <size>[Size]</size>
        <fade_in>[FadeInStart:FadeInDuration]</fade_in>
        <fade_out>[FadeOutStart:FadeOutDuration]</fade_out>
        <crop_left>[Crop Left]</crop_left>
        <crop_top>[Crop Top]</crop_top>
        <crop_right>[Crop Right]</crop_right>
        <crop_bottom>[Crop Bottom]</crop_bottom>
        <keep_aspect_ratio>[yes/no]</keep_aspect_ratio>
        <set_aspect_ratio>[ASPECT_RATIO|source]</set_aspect_ratio>
        <add_meta>[yes/no]</add_meta>
        <hint>[yes/no]</hint>
        <rc_init_occupancy>[RC Occupancy]</rc_init_occupancy>
        <minrate>[Min Rate]</minrate>
        <maxrate>[Max Rate]</maxrate>
        <bufsize>[RC Buffer Size]</bufsize>
        <keyframe>[Keyframe Period (GOP)]</keyframe>
        <start>[Start From]</start>
        <duration>[Result Duration]</duration>
        <output>mpeg2</output>
        <keyframe>[12|15|25|30]</keyframe> 
        <force_keyframes>[Keyframe Period]</force_keyframes>
        <!-- Every Nth frame <force_keyframes>*/N</force_keyframes>-->
        <!-- Specified position for keyframes <force_keyframes>1,100,230,555</force_keyframes>-->
        <bframes>[2|0]</bframes>
        <gop>[cgop|sgop]</gop> 
        <output>[PRESET_NAME]</output>

        <!-- Metadata fields (OPTIONAL) -->
        <metadata> 
            <title>[Title]</title>
            <copyright>[Copyright]</copyright> 
            <author>[Author]</author> 
            <description>[Description]</description> 
            <album>[Album]</album> 
        </metadata> 

        <!-- Destination fields --> 
        <destination>[DestFile]</destination> 
        <destination>[DestFile2]</destination> 
        <!-- ... -->
        <destination>[DestFileN]</destination>

        <!-- Logo fields (OPTIONAL) --> 
        <logo> 
             <logo_source>[LogoURL]</logo_source> 
             <logo_x>[LogoLeft]</logo_x> 
             <logo_y>[LogoTop]</logo_y> 
             <logo_mode>[LogoMode]</logo_mode> 
             <logo_threshold>[LogoTreshold]</logo_threshold> 
        </logo>

        <!-- Overlay fields (OPTIONAL) -->
        <overlay>
            <overlay_source>[Overlay1Source]</overlay_source>
            <overlay_left>[Overlay1PositionXfromLeft]</overlay_left>
            <overlay_right>[Overlay1PositionXfromRight]</overlay_right>
            <overlay_top>[Overlay1PositionYfromTop]</overlay_top>
            <overlay_bottom>[Overlay1PositionYfromBottom]</overlay_bottom>
            <size>[Overlay1Size]</size>
            <overlay_start>[OverlayNStartInSeconds]</overlay_start>
            <overlay_duration>[OverlayNDurationInSeconds]</overlay_duration>
        </overlay>
        <!-- ... -->
        <overlay>
            <overlay_source>[OverlayNSource]</overlay_source>
            <overlay_left>[OverlayNPositionXfromLeft]</overlay_left>
            <overlay_right>[OverlayNPositionXfromRight]</overlay_right>
            <overlay_top>[OverlayNPositionYfromTop]</overlay_top>
            <overlay_bottom>[OverlayNPositionYfromBottom]</overlay_bottom>
            <size>[OverlayNSize]</size>
            <overlay_start>[OverlayNStartInSeconds]</overlay_start>
            <overlay_duration>[OverlayNDurationInSeconds]</overlay_duration>
        </overlay>    
    
        <!-- Text Overlay fields (OPTIONAL) -->
        <text_overlay>
            <text>[Text1]</text>
            <font_source>[Font1Source]</font_source>
            <font_size>[Font1Size]</font_size>
            <font_rotate>[Font1Rotate]</font_rotate>
            <font_color>[Font1Color]</font_color>
            <align_center>[0|1]</align_center>
            <overlay_x>[TextOverlay1PositionX]</overlay_x>
            <overlay_y>[TextOverlay1PositionY]</overlay_y>
            <size>[TextOverlay1Size]</size>
            <overlay_start>[TextOverlay1StartInSeconds]</overlay_start>
            <overlay_duration>[TextOverlay1DurationInSeconds]</overlay_duration>
        </text_overlay>
        <!-- ... -->
        <text_overlay>
            <text>[TextN]</text>
            <font_source>[FontNSource]</font_source>
            <font_size>[FontNSize]</font_size>
            <font_rotate>[FontNRotate]</font_rotate>
            <font_color>[FontNColor]</font_color>
            <align_center>[0|1]</align_center>
            <overlay_x>[TextOverlayNPositionX]</overlay_x>
            <overlay_y>[TextOverlayNPositionY]</overlay_y>
            <size>[TextOverlayNSize]</size>
            <overlay_start>[TextOverlayNStartInSeconds]</overlay_start>
            <overlay_duration>[TextOverlayNDurationInSeconds]</overlay_duration>
        </text_overlay>

        
        <!-- Video codec parameters (OPTIONAL, while only for libx264 video codec) --> 
        <video_codec_parameters> To see the example for parameters please follow this link below * </video_codec_parameters> 

        <!-- Profile (OPTIONAL, while only for libx264 video codec) --> 
        <profile>[high/main/baseline]</profile>

        <!-- Turbo Encoding switch (OPTIONAL) --> 
        <turbo>[yes/no]</turbo>

        <!-- Video rotation (OPTIONAL) -->
        <rotate>def|0|90|270</rotate>
        <set_rotate>def|0|90|270</set_rotate>

        <audio_sync>[1..N]</audio_sync> 
        <video_sync>old|passthrough|cfr|vfr|auto</video_sync>
        <force_interlaced>tff|bff|no</force_interlaced>
        <strip_chapters>[yes|no]</strip_chapters> 
    </format> 
</query>

* Video codec settings

Browser XML Submission Test

Official API Wrappers

PHP

This sample script allows user to enter parameters and send API request for encoding:

<?php
function sendRequest($xml)
{
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, "http://manage.encoding.com/");
	curl_setopt($ch, CURLOPT_POSTFIELDS, "xml=" . urlencode($xml));
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($ch, CURLOPT_HEADER, 0);
	return curl_exec($ch);
} 


// Begin processing User's POST
if(!empty($_POST['source']))
{
	// Preparing XML request
  
	// Main fields
	$req = new SimpleXMLElement('<?xml version="1.0"?><query></query>');
	$req->addChild('userid', MY_ID);
	$req->addChild('userkey', MY_KEY);
	$req->addChild('action', 'AddMedia');
	$req->addChild('source', $_POST['source']);
  
	$formatNode = $req->addChild('format');
	// Format fields
	foreach($_POST['format'] as $property => $value)
	{
		if ($value !== '')
		$formatNode->addChild($property, $value);
	}
  
	// Sending API request
	$res = sendRequest($req->asXML());
  
	try
	{
		// Creating new object from response XML
		$response = new SimpleXMLElement($res);
	  
		// If there are any errors, set error message
		if(isset($response->errors[0]->error[0])) {
			$error = $response->errors[0]->error[0] . '';
		}
		else
		if ($response->message[0]) {
			// If message received, set OK message
			$message = $response->message[0] . '';
		}
	}
	catch(Exception $e)
	{
		// If wrong XML response received
		$error = $e->getMessage();
	}
  
	// Displaying error if any
	if (!empty($error)) {
		echo '<div class="error">' . htmlspecialchars($error) . '</div>';
	}
  
	// Displaying message
	if (!empty($message)) {
		echo '<div class="message">' . htmlspecialchars($message) . '</div>';
	}
	exit;
}
?>

Java

Thanks to Kalpesh Balare from Mediamelon, we have a nice sample script in Java to get you started.

import java.io.*;
import java.net.*;

public class EncodingTest {

	private static int startEncodingWorkflow() {
		// replace ID and key with your own
		String userID = "ID";
		String userKey = "key";
		String mediaID = "1";
		StringBuffer xml = new StringBuffer();
		xml.append("<?xml version='1.0'?>");
		xml.append("<query>");
		xml.append("<userid>"+userID+"</userid>");
		xml.append("<userkey>"+userKey+"</userkey>");
		xml.append("<action>GetMediaInfo</action>");
		xml.append("<mediaid>"+mediaID+"</mediaid>");
		xml.append("</query>");

		URL server = null;

		try {
			String url = "http://manage.encoding.com";
			System.out.println("Connecting to:"+url);
			server = new URL(url);

		} catch (MalformedURLException mfu) {
			mfu.printStackTrace();
			return 0;
		}

		try {
			String sRequest = "xml=" + URLEncoder.encode(xml.toString(), "UTF8");
			System.out.println("Open new connection to tunnel");
			HttpURLConnection urlConnection = (HttpURLConnection) server.openConnection();
			urlConnection.setRequestMethod( "POST" );
			urlConnection.setDoOutput(true);
			urlConnection.setConnectTimeout(60000);
			urlConnection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
			BufferedWriter out = new BufferedWriter( new OutputStreamWriter( urlConnection.getOutputStream() ) );
			out.write(sRequest);
			out.flush();
			out.close();
			urlConnection.connect();
			InputStream is = urlConnection.getInputStream();
			String str = urlConnection.getResponseMessage();
			System.out.println("Response:"+urlConnection.getResponseCode());
			System.out.println("Response:"+urlConnection.getResponseMessage());
			StringBuffer strbuf = new StringBuffer();
			byte[] buffer = new byte[1024 * 4];

			try {
				int n = 0;
				while (-1 != (n = is.read(buffer))) {
					strbuf.append(new String(buffer, 0, n));
				}

				is.close();

			} catch (IOException ioe) {
				ioe.printStackTrace();
			}

			System.out.println(strbuf.toString()); 

		} catch (Exception exp) {
			exp.printStackTrace();
		}

		return 0;
	}

	public static void main (String[] args) {
		startEncodingWorkflow();
	}
}

Cold Fusion

Now supported by Adobe, take a look at our ColdFusion sample script to get you started.

<!-- Building our query -->
<cfsavecontent variable="xml">
<?xml version="1.0"?>
<query>
	<action>AddMedia</action>
	<userid>0</userid>
	<userkey>your_key</userkey>
	<source>http://your.server.tld/some/path/file</source>
	<format>
		<output>3gp</output>
	</format>
	<format>
		<output>wmv</output>
	</format>
	<format>
		<output>flv</output>
	</format>
</query>
</cfsavecontent>

<!-- Setting up the URL to send the request -->
<cfset theURL = "http://manage.encoding.com">

<!-- Sending the request -->
<cfhttp url="#theURL#" charset="utf-8" method="post">
	<cfhttpparam type="formfield" name="xml" value="#xml#">
</cfhttp>

<!-- Getting the result -->
<cfdump var="#cfhttp.fileContent#">

C#

Integrate into desktop applications using this Microsoft C# sample script. Also, see our VBScript sample script.

static string HTTPPost(string sUrl, string sRequest)
{
	HttpWebRequest request = (HttpWebRequest)WebRequest.Create(sUrl);
	request.Method = "POST";
	request.ContentType = "application/x-www-form-urlencoded";
	request.ContentLength = sRequest.Length;
	request.GetRequestStream().Write(Encoding.UTF8.GetBytes(sRequest), 0, sRequest.Length);
	request.GetRequestStream().Close();
	HttpWebResponse response = (HttpWebResponse)request.GetResponse();
	StreamReader reader = new StreamReader(response.GetResponseStream(), Encoding.UTF8);
	string result = reader.ReadToEnd();
	reader.Close();
	return result;
}

static void Main_Encoding(string origin, string destination)
{
	string xml, sUrl, sRequest, result, userID, userKey;
	//put your real userID and userKey below
	userID = "0";
	userKey = "your_key";
	xml = string.Format(
@"<?xml version=""1.0""?>

<query>
<userid>{0}</userid>
<userkey>{1}</userkey>
<action>AddMedia</action>
<source>{2}</source>
<format>
<output>flv</output>
<destination>{3}</destination>
</format>
</query>", userID, userKey, origin, destination);

	sUrl = "http://manage.encoding.com/";
	sRequest = "xml=" + HttpUtility.UrlEncode(xml);
	result = HTTPPost(sUrl, sRequest);
}

static void Main(string[] args)
{
	string origin = "http://yoursite.com/video/movie.avi";
	string destination = "ftp://username:password@yourftphost.com/video/encoded/test.flv";
	Main_Encoding(origin, destination);
}

Unofficial API Wrappers

Zend Framework

Visit the Zend.com community site for the Encoding.com Zend Framework

Ruby

Thanks to Mick Stauga- ard from podcastemachine.com he has released the following Ruby library into the public domain.

Python

Here's a Python wrapper for the Encoding.com API hosted on Github.

VBScript

This sample script allows to get a list of user's media:

Dim xml, sURL, sRequest, result, userID, userKey
	' put your real userID and userKey below
	userID = "0"
	userKey = "your_key"

	xml = "<?xml version="'1.0'"?>" & VbCrLf
	xmlxml = xml & "<query>" & VbCrLf
	xmlxml = xml & "<userid>" & userID & "</userid>" & VbCrLf
	xmlxml = xml & "<userkey>" & userKey & "</userkey>" & VbCrLf
	xmlxml = xml & "<action>" & "GetMediaList" & "</action>" & VbCrLf
	xmlxml = xml & "</query>" & VbCrLf

	sUrl = "http://manage.encoding.com"
	sRequest = "xml=" & xml
	result = HTTPPost(sUrl, sRequest)

	Function HTTPPost(sUrl, sRequest)
		Set oHTTP = CreateObject("Microsoft.XMLHTTP")
		oHTTP.open "POST", sUrl,false
		oHTTP.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
		oHTTP.setRequestHeader "Content-Length", Len(sRequest)
		oHTTP.send sRequest
		HTTPPost = oHTTP.responseText
	End Function

API Main Fields

End Point

To send API requests to Encoding.com, please send HTTP(S) post requests to:
http(s)://manage.encoding.com
All client requests and server responses use the XML or JSON format. Clients must send the HTTP(S) POST request with a single parameter named `xml` or `json` accordingly. The server response will be a normal XML document or a JSON string.

Authentication

UserID

A unique user identifier. This number can be found in the My Account tab of the Client Interface.

UserKey

A user's unique authentication key string. Created automatically when a user is created and can be regenerated at anytime in the My Account tab of the Client Interface.

Action

The action to be performed in the API request.

Action Description
AddMedia Add new media to user's queue. Creates new items in a queue according to formats specified in the XML API request.
AddMediaBenchmark Add new media to user's queue and sets a flag to NOT process automatically after downloading. Format fields can be specified as well. If NotifyURL is set, a notification will be sent after the media is ready for processing.

Note: the media will get 'Ready to process' status only when at least one <format> field is specified. Otherwise, you may retrieve source media information via GetMediaInfo action listed below.
UpdateMedia Replace information about existing media's formats. All old format items will be deleted and the new ones will be added.
ProcessMedia Start encoding the previously downloaded media (ones that have been added with an AddMediaBenchmark action).
CancelMedia Delete specified media and all its items in the queue.
GetMediaList Returns a list of the user's media in the queue.
GetStatus Returns information about a selected user's media and all its items in the queue.
GetMediaInfo Returns video parameters of the specified media when available.
GetMediaInfoEx Returns extended video parameters of the specified media when available.
RestartMedia Complete restart the entire job.
RestartMediaErrors Only retry tasks ended with error.
RestartMediaTask Only restart the specified task (format). Additional parameter <taskid> must be specified.
StopMedia Stop media downloading/processing/uploading. If at least one destination is saved, media will be finished, otherwise it will be stopped.

MediaID

A unique identifier for each media. This field must be specified for the following actions: UpdateMedia, ProcessMedia, CancelMedia, GetMediaInfo, GetStatus.

SourceFile

Source media file. Must be specified only for AddMedia and AddMediaBenchmark actions.
It can be in the following formats:

Source type Description
HTTP

http://[user[:password]@]hostname[:port]/[path]/[filename]

Parameter "?multithread=1" in source URL turns on multithread download

FTP / SFTP

ftp://[user[:password]@]hostname[:port]/[path]/[filename][?passive=yes]

sftp://[user[:password]@]hostname[:port]/[path]/[filename]

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.

Parameter "?multithread=1" in source URL turns on multithread download

Parameter "?disable-epsv" in source URL disables extended passive mode

Amazon Web Services (S3)

http://[bucket].s3.amazonaws.com/[filename]

http://[AWS_KEY:AWS_SECRET@][bucket].s3.amazonaws.com/[filename]

— If you don't specify an AWS key/secret, the object must have READ permission for AWS user
1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869 (or for all users).
See Amazon S3 ACL for details.

— If you need your S3 files to be accessed with your own AWS credentials, add your AWS key/secret to the URL. If you use the Access key and Secret key, they must be URL encoded. For example, if your Key and the Secret are:

1ZG3YAKJ8W0VOA9L7WT6lQT5MsQLirc8owb:SxX/9EhU4M+QarasFelQ0v2M

First, we must URL encode the Secret as it contains special characters: ':','+' and '/'. The URL encoded Secret is now:

lQT5MsQLirc8owb%3ASxX%2F9EhU4M%2BQarasFelQ0v2M

You should NOT encode the colon between Key and Secret nor the '@' after them. So, the destination URL will be:

http://1ZG3YAKJ8W0VOA9L7WT6:lQT5MsQLirc8owb%3ASxX%2F9EhU4M%2BQarasFelQ0v2M@encode.video.s3.amazonaws.com/v/encoded/

Using specific S3 endpoints:

To use specific endpoint replace 's3.amazonaws.com' in your S3 URL with one of the following:

  • us-east-1 — s3-external-1.amazonaws.com
  • us-west-2 — s3-us-west-2.amazonaws.com
  • us-west-1 — s3-us-west-1.amazonaws.com
  • eu-west-1 — s3-eu-west-1.amazonaws.com
  • ap-southeast-1 — s3-ap-southeast-1.amazonaws.com
  • ap-southeast-2 — s3-ap-southeast-2.amazonaws.com
  • ap-northeast-1 — s3-ap-northeast-1.amazonaws.com
  • sa-east-1 — s3-sa-east-1.amazonaws.com

Note:

— Do not forget to URL encode your AWS_SECRET, specifically replacing '/' with '%2F'.

— See Percent-encoding for more details on URLencoding.

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.

Rackspace CloudFiles

http://[RS_USER:RS_KEY@]storage.cloudfiles.com/[path]/[filename]

— Virtual URL for Cloud Files

https://storage4.clouddrive.com/v1/MossoCloudFS_cea19775-aa94-4d78-8da9-1a7b4bbbd548/container_name/file.ext?auth-token=c2633419-7b79-3d58-8417-d63666dddfd5

— Real URL for Cloud Files like this if you were authenticated yourself recently

Aspera Server

Please use such URL if your source is on the Aspera Enterprise Server™ or Aspera Connect Server™

fasp://[user[:password]@]hostname[:port]/[path]/[filename]

Windows Azure Blob

To access to files stored on azure blob storage use next way:

http(s)://[access_key]@[account].blob.core.windows.net/[container]/path

access_key should be urlencoded

OpenStack Cloud Storage

URL for Oracle cloud storage:

http(s)://[user[:password]@]storage.[region].oraclecloud.com/v1/[service-endpoint]/[container]/[object]

Swift tempauth(v1)

swift://[user[:password]@]hostname[:port]/v1/[tenant]/[container]/[object]

Swift identity (v2.0)

swift://[user[:password]@]hostname[:port]/v2.0/[tenant]/[container]/[object]

You can specify several source files within the same API request. All of them will be combined to one file (in sequential order) during the encoding process. You can use different source URLs (HTTP, FTP, S3, CloudFiles) with different media properties (format, frame size, bitrate, codec, etc.) Read more.

Notifications

Notify_format

Can be XML (default) or JSON - defines callback format.

Notify

Can be either an HTTP(S) URL for the script with which the result will be posted, or a mailto: link with email address for which the result info will be sent. This field may be specified for AddMedia and AddMediaBenchmark actions.

Notify_encoding_errors

Can be either an HTTP(S) URL for the script or a mailto: link with email address for which result info will be sent only if media finished with encoding errors.

Notify_upload

Can be either an HTTP(S) URL for the script or a mailto: link with email address for which result info will be sent when media uploaded to the specified destination.
Note: for advanced_hls notify for each stream will be sent

Callback Format

If an 'http(s)://' link is specified in the <notify> part of the <query>, the HTTP POST request will be sent to the specified location. The POST data will contain a single parameter named xml or json (as stated in notify_format parameter) in the following format:

<?xml version="1.0"?>
<result>
    <mediaid>[MediaID]</mediaid>
    <source>[SourceFile]</source>
    <status>[MediaStatus]</status>
    <description>[ ErrorDescription]</description> <!-- Only in case of Status = Error -->
    <format>
        <output>[OutputFormat]</output>
        <destination>[URL]</destination> <!-- Only in case of Status = Finished -->
        <destination_status>[Saved|Error (ErrorDescription)]</destination_status> 
        <destination>[URL_2]</destination>
        <destination_status>[Saved|Error (ErrorDescription)]</destination_status>
        <!-- ... -->
        <destination>[URL_N]</destination>
        <destination_status>[Saved|Error (ErrorDescription)]</destination_status>
        <status>[TaskStatus]</status>
        <description>[ErrorDescription]</description> <!-- Only in case of Status = Error -->
        <suggestion>[ErrorSuggestion]</suggestion> <!-- Only in case of Status = Error -->
    </format>
</result>
Field Description
MediaID

A unique identifier of the media

SourceFile

Media source file URL

MediaStatus

Could be either Finished or Error

OutputFormat

Format of encoded file, as was requested in the query.

DestFile
ThumbDest

Could be one of the following:

  • ftp://[user]:[password]@[server]/[path]/[filename]

  • http://[users.bucket].s3.amazonaws.com/[path]/[filename]

    — the bucket must have WRITE permission for AWS user 1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869

    See Amazon S3 ACL for details OR

  • http://[encoding.bucket].s3.amazonaws.com/[path]/[filename]

    — if destination was not specified in the query.

TaskStatus

Could be either Finished or Error

ErrorDescription

Description of the error if status is Error

ErrorSuggestion

Description of the error if status is Error and we have a suggestion available for this error

Callback Format for notify_upload

<?xml version="1.0"?>
<result>
    <mediaid>[MediaID]</mediaid>
    <taskid>[TaskID]</taskid>
    <destination>[DestinationLink]</destination>
    <status>[DestinationStatus]</status>
</result>
Field Description
MediaID

A unique identifier of the media

TaskID

A unique identifier of the task

DestinationLink

A link to destination where task was uploaded

DestinationStatus

A status of task

 

API Output Format Fields

Output

Output format type. Can be one of the following:

  • flv
  • fl9
  • wmv
  • mov
  • 3gp
  • mp4
  • m4v
  • ipod
  • iphone
  • ipad
  • android
  • ogg
  • webm
  • appletv
  • psp
  • zune
  • mp3
  • wma
  • m4a
  • thumbnail
  • image
  • mpeg1
  • mpeg2 (just experimental feature please use with care, feedback is welcome)
  • iphone_stream
  • ipad_stream
  • muxer
  • wowza
  • wowza_multibitrate
  • wowza_multibitrate_mp4
  • roku_800
  • roku_1200
  • roku_1800
  • roku_2700
  • roku_hls
  • mpegts
  • dnxhd
  • vidly
  • vidly_lite
  • kindle_fire
  • eac3
  • smooth_streaming
  • hds
  • closed_captions
  • ProRes
  • mxf
  • dnxhd_mxf
  • waveform
  • mpeg_dash
  • harmonic

VP6 FLV Output

VP6 (deprecated)

VP6 feature is deprecated and will be automatically converted to the new form. All parameters will be ignored.

If you choose the vp6 codec for flv output, you will have fewer parameter options than if you use the vp6_flix output (see below) and therefore, your XML query will differ:

<format>
    <output>flv</output>
    <video_codec>vp6</video_codec>
    <bitrate></bitrate> <!-- optional -->
    <size></size> <!-- optional -->
    <audio_bitrate>64k</audio_bitrate> <!-- optional -->
    <audio_sample_rate>44100</audio_sample_rate> <!-- optional -->
    <audio_channels_number>2</audio_channels_number> <!-- optional -->
    <framerate></framerate> <!-- optional -->
    <destination></destination> <!-- optional -->
</format>

Note: we strongly recommend using video dimensions that are multiples of 16.

VP6 Flix

To generate vp6 output using the On2 Flix encoder, please use the vp6_flix output format which includes additional optional options:

<format>
    <output>vp6_flix</output>
    <vp6_profile></vp6_profile>
    <noise_reduction></noise_reduction>
    <upct></upct>
    <kfinttype></kfinttype>
    <keyframe></keyframe>
    <sharpness></sharpness>
    <cxmode></cxmode>
</format>
Field Name Allowed Values Default Values
vp6_profile
Encoding profile
1 — VP6_E
2 — VP6_S
1
noise_reduction
Determines the level of noise filtering to apply in the preprocessor.
[0,6]
0 — no preprocessing
6 — extreme preprocessing
Bits per pixel dependent
upct
Parameter for undershoot percentage
0-100 90
kfinttype
Keyframe interval type
1 — MAX KEYFRAMES
2 — FIXED KEYFRAMES
1
keyframe
Keyframe period (in frames)
Non-negative integer 300
sharpness
Controls the sharpness of the image in the output
[0,7] Bits per pixel dependent
cxmode
Compress mode
1 — GOOD
2 — BEST
1

Video Settings

Field Name Allowed Values Default Values
video_codec
Video codec
flv: flv, libx264, vp6
fl9: libx264
wmv, zune: wmv2, msmpeg4
3gp, android: h263, mpeg4, libx264
m4v: mpeg4
ipod, iphone, ipad, appletv, psp: mpeg4, libx264
mp4: mpeg4, libx264, hevc
ogg: libtheora
webm: libvpx
mp3, wma: none
mpeg2: mpeg2video
mpeg1: mpeg1video
mov: mpeg4, libx264, xdcam, dvcpro, dvcpro50, dvcprohd
mpegts: libx264, mpeg2video
mxf: dvcpro, dvcpro50, dvcprohd, xdcamhd422
flv: flv
fl9, ipod, iphone, ipad: libx264
wmv, zune: wmv2
3gp: h263
mp4, m4v,appletv, psp, android, mov: mpeg4
ogg: libtheora
webm: libvpx
mpeg2: mpeg2video
mpeg1: mpeg1video
mpegts: libx264
mxf: xdcamhd422
ftyp
Specify format ftyp
mp42,3gp5 None
size
Video frame size

All: WxH, where W and N are any even integers.
3gp (h263): 128x96, 176x144, 352x288, 704x576, 1408x1152
appletv: 710x480
zune: 320x180, 320x240
vp6: WxH, where W and N are multiple of 16

mxf: 720x480, 960x720, 1280x720, 1280x1080, 1440x1080, 1920x1080

Custom: To match your source aspect ratio, set X value to zero and Y value to your desired height. For example, 0x360 or 0x480.

All: None (any size possible)
3gp: 176x144
iPhone: 480x368
iPad: 1280x720
Android: 800x400
appletv: 710x480
zune: 320x180
psp: 368x192

mxf: None

Note: You can specify only one dimension: either width or height. In this case, set other dimension to 0. (I.e. 640x0).
keep_aspect_ratio
Whether to keep width to height ratio of the original frame size.
yes, no yes
set_aspect_ratio
Display aspect ratio (DAR). When set, the option keep_aspect_ratio will be ignored. The option only works with the following formats: fl9, 3gp, mp4, m4v, ipod, iphone, ipad, android, ogg, webm, appletv, psp, iphone_stream, ipad_stream.
Positive float value or N:M where N and M are any positive integers.
source: display aspect ratio will be copied from source file
yes
bitrate
video bit rate
All: Nk (where N is any non zero integer) All: 512k
3gp: 256k
iOS, Android, PSP: 1024k
maxrate
Maximum allowed video bitrate
N or Nk — where N is any non-zero integer None
minrate
Minimum allowed video bitrate
N or Nk — where N is any non-zero integer None
cbr
Whether to use CBR (Constant bitrate)
yes, no no
framerate
Frame rate
All: any non-zero integer or N/M where N and M are non-zero integers All: none
psp: 30000/1001
framerate_upper_threshold
If source frame rate lower then framerate_upper_threshold, then source frame rate will be used
Any non-zero integer or N/M where N and M are non-zero integers None
Note: If framerate_upper_threshold is specified then framerate parameter will be ignored.
keyframe
Keyframe period, in frames
positive integer 300
force_keyframes
Force keyframes set
mp4, fl9, 3gp, iOS, mov, psp: Either every N frames (when set as single integer) or on specified positions (when set as a comma separated list)
start
Start encoding from (sec or timecode)
non-negative float or timecode None
finish
Finish encoding at (sec or timecode)
positive float or timecode None
Note: Timecode should have following format
HH:MM:SS[:;]FF, where:
HH - hours
MM - minutes
SS - seconds
FF - frames
[:;] - : - non drop-frame, ; - drop-frame;
duration
Duration (sec)
positive integer None
Note: if finish and duration parameters specified simultaneously - duration parameter would be ignored.

 

HEVC video codec

<format>
    <output>mp4</output>
    <video_codec>hevc</video_codec>
    <video_codec_parameters>
        <refresh>1</refresh>
        <rc-lookahead>20</rc-lookahead>
        <b-adapt>2</b-adapt>
        <bframes>4</bframes>
        <b-pyramid>1</b-pyramid>
        <ref>3</ref>
        <ctu>64</ctu>
        <tu-intra-depth>1</tu-intra-depth>
        <tu-inter-depth>1</tu-inter-depth>
        <me>1</me>
        <subme>2</subme>
        <merange>60</merange>
        <max-merge>2</max-merge>
        <rect>1</rect>
        <amp>1</amp>
        <early-skip>0</early-skip>
        <fast-cbf>0</fast-cbf>
        <signhide>1</signhide>
        <lft>1</lft>
        <tskip>0</tskip>
        <sao>1</sao>
        <weightp>1</weightp>
        <tskip-fast>0</tskip-fast>
    </video_codec_parameters>
</format>
Field Name Allowed Values Default Values
Slice decision options
refresh
Intra refresh type
0 — none
1 — CDR
2 — IDR
1
rc-lookahead
Number of frames for frame-type lookahead
an integer less than or equal to 250 and greater than maximum consecutive bframes count 20
b-adapt
Adaptive B frame scheduling
0 — none
1 — fast
2 — full (trellis)
2
bframes
Maximum number of consecutive b-frames
integer from 0 to 16 4
b-pyramid
Use B-frames as references


0 — Disabled
1 — Enabled
1
ref
Max number of L0 references to be allowed
Values: integer from 0 to 16 3
weightp
Enable weighted prediction in P slices
0 — Disabled
1 — Enabled
1
Quad-tree analusis
ctu
Maximum CU size (width and height)
16,32,64 64
tu-intra-depth
Max TU recursive depth for intra CUs
1,2,3,4 1
tu-inter-depth
Max TU recursive depth for inter CUs
1,2,3,4 1
Motion search options
me
Motion search method
0 — dia
1 — hex
2 — umh
3 — star
4 — full
1
subme
Amount of subpel refinement to perform
integer from 0 to 7 (0: least ... 7: most) 2
merange
Motion search range
integer from 0 to 32768 60
max-merge
Maximum number of merge candidates
integer from 1 to 5 2
rect
Rectangual motions partitions Nx2N and 2NxN
0 — Disable
1 — Enable
1
amp
Asymmetric motion partitions (requires rect enabled)
0 — Disable
1 — Enable
1
early-skip
Enable early SKIP detection
0 — Disable
1 — Enable
0
fast-cbf
CBF fast mode
0 — Disable
1 — Enable
0
Rate control
rd
Level of RD in mode decision
0 — Least
1 — Lightweight RDO Analysis
0
signhide
Hide sign bit of one coeff per TU
0 — Disable
1 — Enable
1
Loop filter
lft
Loop filter
0 — Disable
1 — Enable
1
Intra options
tskip
Intra transform skipping
0 — Disable
1 — Enable
0
tskip-fast
Fast intra transform skipping
0 — Disable
1 — Enable
0
Sample Adaptive Offset loop filter
sao
Simple adaptive offset
0 — Disable
1 — Enable
1

Audio Settings

Field Name Allowed Values Default Values
audio_codec

Audio codec

mp3: libmp3lame
m4a: libfaac, dolby_aac, dolby_heaac, dolby_heaacv2
flv: libmp3lame, libfaac, dolby_aac, dolby_heaac, dolby_heaacv2
mp4: libfaac, dolby_aac, dolby_heaac, dolby_heaacv2, ac3
fl9, mp4, m4v, ipod, iphone, ipad, appletv, psp, wowza, roku_*, kindle_fire: libfaac, dolby_aac, dolby_heaac, dolby_heaacv2
mov: libfaac, dolby_aac, dolby_heaac, dolby_heaacv2, eac3
iphone_stream, ipad_stream, wowza_multibitrate, wowza_multibitrate_mp4, roku_hls, smooth_streaming, hds: libfaac, dolby_aac, dolby_heaac, dolby_heaacv2
wmv, wma, zune: wmav2, libmp3lame
ogg, webm: libvorbis
3gp: libamr_nb
android: libamr_nb, libfaac
mpeg2: pcm_s16be, pcm_s16le, ac3
mpeg1: mp2, copy
mpegts: ac3
mov_prores: pcm_s16le, pcm_s24le
mxf: pcm_s16le, pcm_s24le
dnxhd_mxf: pcm_s16le, pcm_s24le
flv, mp3: libmp3lame
fl9, mp4, m4v, ipod, iphone, ipad, appletv, psp, wowza, roku_*, kindle_fire: libfaac
mov: libfaac
iphone_stream, ipad_stream, wowza_multibitrate, wowza_multibitrate_mp4, roku_hls, smooth_streaming, hds: libfaac
wmv, zune: wmav2
ogg, webm: libvorbis
3gp, android: libamr_nb
mpeg2: pcm_s16be
mpeg1: mp2
m4a: libfaac
mov_prores: pcm_s16le
mxf: pcm_s24le
dnxhd_mxf: pcm_s16le
Note: If you specify audio_codec equal to 'copy', the options audio_channels_number, audio_sample_rate, audio_bitrate will be ignored and their values will be copied from your source file.
audio_bitrate

Audio bitrate

Nk - where N is any non-zero integer

3gp: 4.75k, 5.15k, 5.9k, 6.7k, 7.4k, 7.95k, 10.2k, 12.2k
flv, wmv, mp3, wma, zune: 32k, 40k, 48k, 56k, 64k, 80k, 96k, 112k, 128k, 144k, 160k, 192k, 224k, 256k, 320k
ogg, webm: 45k,64k, 80k, 96k, 112k, 128k, 160k, 192k, 224k, 256k, 320k, 500k
All: 64k
3gp, android: 12.2k
ipod, iphone, ipad, psp: 128k
acbr

Whether to use CBR (Constant bitrate) for audio stream. Only for vorbis (Ogg, Webm)

yes, no no
audio_sample_rate

Audio sampling frequency (Hz)

All: any non-zero integer
3gp: 8000
flv, mp3: 11025, 22050, 44100
ogg, webm: 16000, 32000, 44100, 22050, 11025, 192000
wmv, wma, zune: 11025, 22050, 32000, 44100, 48000
mpeg2: 44100, 48000
All: none
mp4: 44100
3gp, android: 8000
flv, mp3, zune, mpeg2: 44100
audio_channels_number

Number of audio channels

All: any non-zero integer
3gp: 1
android: 1, 2
All: 2
3gp, android: 1
audio_volume

Audio volume level, in percent

non-negative integer 100
audio_normalization
This option specifies that a gain should be applied so that the final dialogue normalization value of the audio signal is equal to the specified value.
Non-negative integer from 0 to 100 None
audio_sync
It adjusts the audio stream to match the timestamps, in # of samples per second. 1 is special value that means automatic.
positive integer None
pan
Allow to select and remap audio channels.
output_audio_chanel,input_audio_channel:output_audio_chanel,input_audio_channel
Example: 0,0:1,1
None
audio_minrate
Minimum allowed audio bitrate.
N or Nk — where N is any non-zero integer None
audio_maxrate
Maximum allowed audio bitrate.
N or Nk — where N is any non-zero integer None
audio_bufsize
Rate control buffer size (bits).
N or Nk — where N is any non-zero integer None

 

Destination

You can use multiple <destination> elements within each <format>.

Destination type Description
HTTP

http://[user[:password]@]hostname[:port]/[path]/[filename]

FTP / SFTP

ftp://[user[:password]@]hostname[:port]/[path]/[filename][?passive=yes]

sftp://[user[:password]@]hostname[:port]/[path]/[filename]

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.

Amazon Web Services (S3)
  • http://[bucket].s3.amazonaws.com/[filename][?acl=public-read | authenticated-read]&canonical_id=AWS_CANONICAL_USER_ID

    — If you specify AWS canonical user ID in the URL, FULL_CONTROL on the object will be granted to the specified user.

  • http://[bucket].s3.amazonaws.com/[filename][?acl=public-read | authenticated-read]&content_type=your-own/content-type

    — If you specify Content type, then Amazon will add appropriate Content-type header when the object is accessed via the web.

  • http://[bucket].s3.amazonaws.com/[filename][?acl=public-read | authenticated-read]&content_disposition=attachment[;%20filename="file.ext"]

    — If you specify Content disposition, then Amazon will add appropriate Content-Disposition header when the object is accessed via the web.

  • 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. If you use the Access key and Secret key, they must be URL encoded. For example, if your Key and the Secret are:

    1ZG3YAKJ8W0VOA9L7WT6lQT5MsQLirc8owb:SxX/9EhU4M+QarasFelQ0v2M

    First, we must URL encode the Secret as it contains special characters: ':','+' and '/'. The URL encoded Secret is now:

    lQT5MsQLirc8owb%3ASxX%2F9EhU4M%2BQarasFelQ0v2M

    You should NOT encode the colon between Key and Secret nor the '@' after them. So, the destination URL will be:

    http://1ZG3YAKJ8W0VOA9L7WT6:lQT5MsQLirc8owb%3ASxX%
    2F9EhU4M%2BQarasFelQ0v2M@encode.video.s3.amazonaws.com/v/encoded/

    Note:

    — Do not forget to URL encode your AWS_SECRET, specifically replacing '/' with '%2F'.

    — If you don't specify AWS key/secret, the bucket must have READ and WRITE permissions for AWS user:

    1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869

    — See Amazon S3 ACL for more details.

    — See Percent-encoding for more details on URLencoding.


    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.

  • http://[bucket].s3.amazonaws.com/[filename]?cache_control=[string]

    — cache_control - Can be used to specify caching behavior along the request/reply chain.

  • http://[bucket].s3.amazonaws.com/[filename]?expires=[string]

    — expires - The date and time at which the object is no longer cacheable.

Using specific S3 endpoints:

To use specific endpoint replace 's3.amazonaws.com' in your S3 URL with one of the following:

  • us-east-1 — s3-external-1.amazonaws.com
  • us-west-2 — s3-us-west-2.amazonaws.com
  • us-west-1 — s3-us-west-1.amazonaws.com
  • eu-west-1 — s3-eu-west-1.amazonaws.com
  • ap-southeast-1 — s3-ap-southeast-1.amazonaws.com
  • ap-southeast-2 — s3-ap-southeast-2.amazonaws.com
  • ap-northeast-1 — s3-ap-northeast-1.amazonaws.com
  • sa-east-1 — s3-sa-east-1.amazonaws.com
Rackspace CloudFiles

http://[RS_USER:RS_KEY@]storage.cloudfiles.com/[path]/[filename]

— Virtual URL for Cloud Files

https://storage4.clouddrive.com/v1/MossoCloudFS_cea19775-aa94-4d78-8da9-1a7b4bbbd548/container_name/file.ext?auth-token=c2633419-7b79-3d58-8417-d63666dddfd5

— Real URL for Cloud Files like this if you were authenticated yourself recently

Aspera Server

fasp://[user[:password]@]hostname[:port]/[path]/[filename]

Windows Azure Blob

To access to files stored on azure blob storage use next way:

http(s)://[access_key]@[account].blob.core.windows.net/[container]/path

Also, you can add ?acl=public-read OR ?acl=public-container OR ?acl=private after the filename. This will explicitly set access rights to the container instead of the default settings

access_key should be urlencoded

YouTube

http://[YoutubeLogin]:[YoutubePassword]@youtube.com/?title=[VideoTitle]&category=[VideoCategory]&keywords=[VideoKeywords]&description=[VideoDescription]&acl=[ACL]

[YoutubeLogin] – Login on YouTube (mandatory)
[YoutubePassword] – Password on YouTube (mandatory)
[VideoTitle] – Video title on YouTube (optional, default: filename)
[VideoCategory] – Video category. Allowed values: Film, Autos, Music, Animals, Sports, Travel, Games, People, Comedy, Entertainment, News, Howto, Education, Tech, Nonprofit (optional, default: Film)
[VideoKeywords] – Video keywords on YouTube (optional, default: none)
[VideoDescription] – Video description on YouTube (optional, default: none)
[ACL] – Access Control List to video on YouTube (optional, default: private).

Allowed values:
private – only owner can get access to the video,
public-read – everyone can get access to the video,
unlisted - only users with direct link can get access to the video

You can link you encoding.com account with your YouTube account in "My Account" section of User Interface. In that case you may not specify [YoutubeLogin] and [YoutubePassword].

Akamai NetStorage HTTP API

http://[Key-Name]:[Key]@[Connection-Host]/[Root-Directory]/[Filename]

OpenStack Cloud Storage

URL for Oracle cloud storage:

http(s)://[user[:password]@]storage.[region].oraclecloud.com/v1/[service-endpoint]/[container]/[object]

Swift tempauth(v1)

swift://[user[:password]@]hostname[:port]/v1/[tenant]/[container]/[object]

Swift identity (v2.0)

swift://[user[:password]@]hostname[:port]/v2.0/[tenant]/[container]/[object]

 

Other Format Options

Field Name Allowed Values Default Values
profile
The standard defines various sets of capabilities, which are referred to as profiles, targeting specific classes of applications.
high, main, baseline

mov_prores: hq, std, lt, proxy

fl9, mpeg4, flv: high
mp4, m4v: main
ipod, iphone, ipad, 3gp, appletv, psp: baseline
mov_prores: hq

two_pass
2-pass encoding toggle
yes, no no
two_pass_decoding
Decode to a lossless format prior to encoding to reduce errors.
1 None
bufsize
Rate control buffer size (bits)
N or Nk - where N is any non-zero integer None
rc_init_occupancy
Initial rate control buffer occupancy (bits)
N or Nk - where N is any non-zero integer None
deinterlacing
De-interlacing toggle
yes, no, auto
auto - use de-interlacing if source's scan type is interlaced
auto
force_interlaced
Interlaced encoding type. Only works with MPEG-TS.

mpegts: tff, bff, no

mxf: tff, bff, source, no

mov_prores: tff, bff, source, no

no
add_meta
Add meta data to the file. Only works with FLV.
yes, no All: None
flv: no
hint
Add RTP data (for streaming servers). Only works with MP4.
yes, no All: None
mp4: no
preset
Specify format preset. Only works with WebM.
1 — 2-Pass Best Quality VBR Encoding
2 — 2-Pass Faster VBR Encoding
3 — 2-Pass VBR Encoding for Smooth Playback on Low-end Hardware
4 — 2-Pass CBR Encoding for Limited-bandwidth Streaming
5 — 2-Pass VBR Encoding for Noisy / Low-quality Input Source
6 — 1-Pass Good Quality VBR Encoding
6
bframes 2 [on = IBBPBBP], 0 [off = IPPPPPP] 2
gop sgop [Strict (Locked)], cgop [Closed (Scene Detection)] cgop
luma_spatial
Spatial luma strength.
[0,255] 4
chroma_spatial
Spatial chroma strength.
[0,255] 3
luma_temp
Temporal luma strength.
[0,255] 6
audio_sync
It adjusts the audio stream to match the timestamps, in # of samples per second. 1 is special value that means automatic.
Positive integer None
video_sync
Video sync method.
old — Keep old behavior (for compatibility)
passthrough — Each frame is passed with its timestamp from the demuxer to the muxer
cfr — Frames will be duplicated and dropped to achieve exactly the requested constant framerate
vfr — Frames are passed through with their timestamp or dropped so as to prevent 2 frames from having the same timestamp
auto — Chooses between cfr and vfr depending on muxer capabilities
None
strip_chapters
Strip chapters markers
yes, no no
vidly_hls
Enables HLS format for Vidly Lite URL
yes, no no
vidly_hd
Enables HD button in Vid.ly player. High Definition (720p) videos will be generated.
yes, no no
hard_cbr
Specify HRD information and pack the bitstream to the specified bitrate
yes, no no
pix_format
Pixel format - ability to lock output to YUV420p colorspace
yuv420p, yuv422p, yuvj420p, yuvj422p, source yuv420p
Note: If 'source' specified as value, then <pix_format> won't be added to format options.
best_quality
Best quality mode (very slow) - dnxhd output only
yes, no no
interlaced
dnxhd output only
yes, no no
Note: bitrate for dnxhd output is specified separately and the default is 145m
ftyp
Specify format ftyp.
mp4: mp42, 3gp5 None

 

Turbo and Twin-Turbo Encoding

Field Name Allowed Values Default Values
turbo
Send your job to a higher capacity (more CPU and more RAM) server for faster processing.
yes, no no
twin_turbo
Send your job to a higher capacity encoder and turn on multi-threaded encoding (only applicable for modern video codecs such as h.264, vp8 (webm), theora)
yes, no no
Note: additional encoding bandwidth charges apply. Please view the Turbo Encoding Help Article for more details.

Region

Allow you to specify instance's region where your file should be processed

Option Location
us-east-1
(default)
US (Northern Virginia)
us-west-1 US (Northern California)
us-west-2 US (Oregon)
eu-west-1 EU (Ireland)
ap-southeast-1 Asia Pacific (Singapore)
ap-northeast-1 Asia Pacific (Tokyo)
sa-east-1 South America (Sao Paulo)
oak-private-clive Private Cloud (California)

Brightcove™ Batch Provisioning Integration

Encoding.com has developed a special plug-in that enables Brightcove customers to take advantage of Encoding.com's advanced video encoding features. Utilizing the dozens of encoding controls (custom dimensions, bitrate, framerate, 1/2 pass, deinterlacing, etc.) available via the Encoding.com platform, Brightcove customers can now have complete control over their video transcoding and achieve superior quality without having to make an investment in expensive hardware / software solutions. The plug-in will automatically deliver the encoded video library to the Brightcove customer's account (via the Brightcove™ FTP Batch Provisioning) along with the necessary meta data (media title, description, tags, etc.) and is available via Encoding.com's powerful XML API thus enabling seamless integration into internal media workflows, applications and content management systems.

Composing API request

First, add new elements to the AddMedia XML request:

<?xml version="1.0"?>
<query>
    <action>AddMedia</action>
    <userid>xxx</userid>
    <userkey>xxx</userkey>
    <source>http://yoursite.com/media.mov</source>
    <resend_to>http://manage.encoding.com/third_party/brightcove/add_media.php</resend_to>
    <notify>http://manage.encoding.com/third_party/brightcove/add_manifest.php</notify>
    <title>Your media title</title>
    <description>Short description of the media</description>
    <long_description>
        Put
        Long description
        Of the Media Here
    </long_description>
    <bc_userid>12345</bc_userid>
    <bc_mediaid>12345</bc_mediaid>
    <notify_email>user@mail.com</notify_email>
    <link_title>Link title</link_title>
    <link_url>http://encoding.com</link_url>
    <active>true</active>
    <tag>tag's content</tag>
    <format>
        <output>flv</output>
        <destination>ftp://user:password@ftp.brightcove.com/encoded/media.flv</destination>
    </format>
</query>

This process will trigger our system to re-send the API request with <mediaid> element added to the specified URL. Then, the additional information will be stored and associated with newly added media.

The manifest file format

If the media is encoded successfully, the other script specified in the <notify> element will compose and save XML manifest file with the same name as your first result file, but with extension .xml, and to the same FTP folder as was specified in the first <destination>. The file will have the following format (assume the result video format is FLV):

<?xml version="1.0" encoding="utf-8"?>
<publisher-upload-manifest publisher-id="{bc_userid}" preparer="encoding.com" report-success="TRUE">
    <notify email="{notify_email}"/>
    <asset filename="{result_filename}" refid="{result_filename}-{md5_hash}" size="{file_size}" hash-code="{md5_hash}" type="FLV_FULL"/>
    <title name="{title}" refid="{bc_mediaid}" active="{active}" flash-full-refid="{result_filename}-{md5_hash}">
        <short-description>{description}</short-description>
        <long-description>{long_description}</long-description>
        <related-link-url>{link_url}</related-link-url>
        <related-link-text>{link_title}</related-link-text>
        <rendition-refid>{result_filename}-{md5_hash}</rendition-refid>
        <tag>tag's content</tag>
    </title>
</publisher-upload-manifest>

Where {file_size} and {md5_hash} will be calculated according to the result file. The asset nodes will be added only for the following output values: flv, fl9, thumbnail.

Adding thumbnails

If a request contains a thumbnail generation task, <asset type="THUMBNAIL"> or <asset type="VIDEO_STILL"> will be added to the manifest. The type attribute depends on the resulting image width: if it is less than 200 pixels, the type will be THUMBNAIL, otherwise it will be VIDEO_STILL.
The request:

<query>
    <format>
        <output>flv</output>
        <destination>ftp://user:password@ftp.brightcove.com/encoded/media.flv</destination>
    </format>
    <format>
        <output>thumbnail</output>
        <destination>ftp://user:password@ftp.brightcove.com/encoded/media_thumb.jpg</destination>
    </format>
</query>

The manifest:

<asset filename="media.flv" refid="media.flv-896e665b84fd8b59ba8f5930dc61d21b" size="1689452" hash-code="896e665b84fd8b59ba8f5930dc61d21b" type="FLV_FULL"/>
<asset filename="media_thumb.jpg" refid="media_thumb.jpg-0861874e79d02a9cb17642defad47926" size="29863" hash-code="0861874e79d02a9cb17642defad47926" type="THUMBNAIL"/>
<title name="{title}" refid="{bc_mediaid}" active="TRUE" flash-full-refid=" media.flv-896e665b84fd8b59ba8f5930dc61d21b" thumbnail-refid="media_thumb.jpg-0861874e79d02a9cb17642defad47926">

Selecting title ref-id from multiple records with equal formats

If there are several FLV or THUMNAIL tasks in the single request, the same number of <asset> elements will be added to the XML manifest.
Although, only the first task of each group will reflect to the title's flash-full-refid or thumbnail-refid accordingly. So, if you want certain task's asset to reflect into the title, specify this task first in your XML API request.

Specifying different video's renditions

When you specify video frame size and bitrate in your API request, the additional attributes will be added to the appropriate assets in the manifest file.

The request:

<?xml version="1.0"?>
<query>
    <format>
        <output>flv</output>
        <bitrate>300k</bitrate>
        <size>320x240</size>
    </format>
    <format>
        <output>flv</output>
        <bitrate>750k</bitrate>
        <size>640x480</size>
    </format>
</query>

The manifest:

<asset filename="media1.flv" refid="media1.flv-896e665b84fd8b59ba8f5930dc61d21b" size="1689452" hash-code="896e665b84fd8b59ba8f5930dc61d21b" type="FLV_FULL" frame-width="320" frame-height="240" encoding-rate="300000"/>
<asset filename="media2.flv" refid="media2.flv-90f044322653e205466de79d4534b84f" size="3542788" hash-code="90f044322653e205466de79d4534b84f" type="FLV_FULL" frame-width="640" frame-height="480" encoding-rate="750000"/>
…  
And within the title:
<rendition-refid>media1.flv-896e665b84fd8b59ba8f5930dc61d21b</rendition-refid>
<rendition-refid>media2.flv-90f044322653e205466de79d4534b84f</rendition-refid>

Waveform

Render waveforms from sound files as png images.
Used library: rendersound

<format>
    <output>waveform</output>
    <video_codec>png</video_codec>
    <width>500</width>
    <height>50</height>
    <color>FF0000</color>
    <factor>4</factor>
</format>
Field Name Allowed Values Default Values
width
Width in pixels of output
Integer 500
height
Height in pixels of output
Integer 50
color Color expressed as rgb hex FF0000
factor
Super sampling factor for anti aliasing
Integer 4

Harmonic ProMedia Carbon

The Harmonic ProMedia Carbon transcoding engine is known for delivering the highest quality with support for broadcast formats including Apple ProRes, MPEG2-TS, DNxHD, XDCAM, and DVCPRO. This Harmonic transcoding engine is now available in our cloud infrastructure. All of your existing Harmonic workflow presets can be automated via our API and integrated seamlessly with the Harmonic WFS XML API.

Either <preset_file>, or <preset_guid> should be specified for harmonic output format

Preset GUID

<format>
    <output>harmonic</output>
    <preset_guid>[HarmonicPresetUrl]</preset_guid>
    <destination>[DestinationUrl]</destination> 
</format>
Field Name Allowed Values
preset_guid
Harmonic preset GUID
*GUID of predefined Harmonic preset
GUID from list
You can view the full list of supported preset GUIDs.

Preset file

<format>
    <output>harmonic</output>
    <preset_file>[HarmonicPresetUrl]</preset_file>
    <source_filter_1_file>[FileURL]</source_filter_1_file>
    <destination_filter_0_file>[FileURL]</destination_filter_0_file>
    <destination>[DestinationUrl]</destination> 
</format>
Field Name Allowed Values
preset_file
Harmonic preset file.
*Only first destination module of Harmonic preset file will be used.
Valid URL to Harmonic preset file
source_filter_N_file
Source file for Source filter N in Harmonic preset file, where N is positive integer and equal to Source filter number.
Valid URL
destination_filter_N_file
Source file for Destination filter N in Harmonic preset file, where N is positive integer and equal to Destination filter number.
Valid URL

Source_filter_N_file/destination_filter_N_file parameters should be used only if filter requires sidecar source file as argument. For example, filter "Caption inject from .SCC file", requires sidecar SCC file

Adaptive Bitrate Encoding

Apple's HTTP Live Streaming (HLS)

<format>
    <!-- Format fields -->
    <output>[iphone_stream|ipad_stream]</output>
    <size>[CommaSeparatedList]</size>
    <profile>[CommaSeparatedList]</profile>
    <bitrates>[CommaSeparatedList]</bitrates>
    <framerates>[CommaSeparatedList]</framerates>
    <keyframes>[CommaSeparatedList]</keyframes>
    <segment_duration>[Duration]</segment_duration>
    <pack_files>[yes|no]</pack_files>
    <add_audio_only>[yes|no]</add_audio_only>
    <still_image>[no|each_segment|first_segment]</still_image>
    <still_image_time>[Time]</still_image_time>
    <still_image_size>[Size]</still_image_size>
    <encryption>[yes|no]</encryption>
    <encryption_key>[128bit-key]</encryption_key>
    <encryption_key_file>[SourceURL]</encryption_key_file>
    <segmenter>[auto|v1|v2|v3]</segmenter>
    <!-- Destination fields -->
    <destination>[DestFile]</destination> <!-- REQUIRED -->
</format>
Field Name Allowed Values Default Values
size
Comma separated list of video sizes
One or more valid size values separated by commas iphone_stream: 400x300
ipad_stream: 640x480
profile
Comma separated list of profiles
high, main, baseline baseline
bitrates
Comma separated list of video bitrates
One or more valid bitrate values separated by commas iphone_stream: 600k,400k,200k,110k
ipad_stream: 1200k,800k,600k,400k,200k,110k
framerates
Comma separated list of framerates related to previous parameter
One or more valid framerate values separated by commas iphone_stream: 29.97,29.97,15,10
ipad_stream: 29.97,29.97,29.97,29.97,15,10
keyframes
Comma separated list of keyframe parameters
One or more valid keyframe values separated by commas iphone_stream: 90,90,45,30
ipad_stream: 90,90,90,90,45,30
segment_duration
Segment duration to split media (in seconds)
Non-negative integer 10
pack_files
Whether to pack resulting files to a single tarball
yes, no yes
add_audio_only
Whether to add audio-only stream
yes, no no
still_image
Embed still image in the audio-only stream
no, each_segment, first_segment no
still_image_time
The time from the beginning of segment to capture still image
Non-negative number greater than 0.01 or hh:mm:ss.ms None
still_image_size
The size of the still image
WxH where W and H — positive integers None
encryption
Encrypt TS segements using AES-128
yes, no no
encryption_key
Encryption key
32 hexidecimal characters ([0-9a-f]) None
encryption_key_file
Encryption key file URL
HTTP, FTP, SFTP or S3/CloudFiles URL None
segmenter auto, v1, v2, v3 auto
copy_nielsen_metadata
Copy Nielsen audio watermarks and Nielsen ID3 tags from source
yes, no no

 

Advanced HLS

<?xml version="1.0"?>
<format>
    <output>advanced_hls</output>
    <stream>
        <!-- Video settings params -->
        <profile>[high|main|baseline]</profile>
        <!-- Audio settings params -->
        <!-- Other format params -->
        <!-- Closed Captions params -->
        <!-- Editing features params -->
        <audio_only>[yes|no]</audio_only>
        <still_image>[no|each_segment|first_segment]</still_image>
        <still_image_time>[Time]</still_image_time>
        <still_image_size>[Size]</still_image_size>
    </stream>
    <!-- multiple stream params may be included in advanced_hls output format -->
    <stream>
       <!-- stream params -->
    </stream>
    <!-- Format fields -->
    <segment_duration>[Duration]</segment_duration>
    <pack_files>[yes|no]</pack_files>
    <pack_type>[tar|zip]</pack_type>
    <pack_each_stream>[yes|no]</pack_each_stream>
    <encryption>[yes|no]</encryption>
    <encryption_key>[128bit-key]</encryption_key>
    <encryption_key_file>[SourceURL]</encryption_key_file>
    <copy_nielsen_metadata>[yes|no]</copy_nielsen_metadata>
    <segmenter>[v1|v2|v3]</segmenter>
    <destination>[DestFile]</destination>
</format>
Field Name Allowed Values Default Values
Format params
segment_duration
Segment duration to split media (in seconds)
Non-negative integer 9
pack_files
Whether to pack resulting files to a single archive
yes, no yes
pack_type
Archive type
tar, zip tar
Parameter would be ignored in case of pack_files=no
pack_each_stream
Pack each stream in separate archive
yes, no no
Parameter would be ignored in case of pack_files=no
encryption
Encrypt TS segements using AES-128
yes, no no
encryption_key
Encryption key
32 hexidecimal characters ([0-9a-f]) None
encryption_key_file
link to encryption key file
Valid URL None
copy_nielsen_metadata
Copy Nielsen audio watermarks and Nielsen ID3 tags from source
yes, no none
segmenter
Type of segmenter.
v1 – This is the segmenter bundled with FFMPEG and carries significant overhead (as much as 27% with a 364kbps file or 17.3% with a 864kbps file!), and generated several warnings.
v2 - This is based on HTTP Live Segmenter based tool. It carries with it the same overhead, but generates far fewer warnings.
v3 - his version, we call tsparser, we built in-house from the ground up to be optimized for our cloud infrastructure. This has significantly less overhead (5.8% with a 364kbps file or 3.8% with a 864kbps file), and does not generate any warnings.
v3
Stream params
If no streams was specified, there will be added 9 default streams with params recomended by Apple.
Aceptable params from:
audio_only
Result segments will contain only audio stream
yes, no no
still_image
Embed still image in the audio-only stream
no, each_segment, first_segment no
still_image_time
The time from the beginning of segment to capture still image
Non-negative number greater than 0.01 or hh:mm:ss.ms None
still_image_size
The size of the still image
WxH where W and H — positive integers None
base_name
Custom stream result file name
valid filename None

Adobe's Dynamic Streaming (HDS)

<format>
    <!-- Format fields -->
    <output>hds</output>
    <bitrates>[CommaSeparatedList]</bitrates>
    <sizes>[CommaSeparatedList]</sizes>
    <pack_files>[yes|no]</pack_files>
    <!-- Destination fields -->
    <destination>[DestFile]</destination> <!-- REQUIRED -->
</format>
Field Name Allowed Values Default Values
bitrates
Comma separated list of video bitrates
One or more valid bitrate values separated by commas 300k, 600k, 1200k, 2400k
sizes
Comma separated list of video sizes
One or more valid size values separated by commas None
pack_files
Whether to pack resulting files to a single tarball
yes, no yes

Microsoft's Smooth Streaming (MSS)

<format>
    <!-- Format fields -->
    <output>smooth_streaming</output>
    <bitrates>[CommaSeparatedList]</bitrates>
    <sizes>[CommaSeparatedList]</sizes>
    <pack_files>[yes|no]</pack_files>
    <!-- Destination fields -->
    <destination>[DestFile]</destination> <!-- REQUIRED -->
</format>

Wowza Multi-Bitrate (SMIL)

<format>
    <!-- Format fields -->
    <output>[wowza_multibitrate|wowza_multibitrate_mp4]</output>
    <bitrates>[CommaSeparatedList]</bitrates>
    <sizes>[CommaSeparatedList]</sizes>
    <!-- Destination fields -->
    <destination>[DestFile]</destination> <!-- REQUIRED -->
</format>
Field Name Allowed Values Default Values
output
Output format type
wowza_multibitrate — MOV container
wowza_multibitrate_mp4 — MP4 container
bitrates
Comma separated list of video bitrates
One or more valid bitrate values separated by commas 270k, 570k, 1000k, 1200k, 1400k
sizes
Comma separated list of video sizes
One or more valid size values separated by commas 320x180, 512x288, 720x406, 1024x576, 1080x608

 

Mpeg_dash output format

<format>
    <!-- Format fields -->
    <output>mpeg_dash</output>
    <bitrates>[CommaSeparatedList]</bitrates>
    <sizes>[CommaSeparatedList]</sizes>
    <pack_files>[yes|no]</pack_files>
    <!-- Destination fields -->
    <destination>[DestFile]</destination> <!-- REQUIRED -->
</format>
Field Name Allowed Values Default Values
bitrates
Comma separated list of video bitrates
One or more valid bitrate values separated by commas 270k, 570k, 1000k, 1200k, 1400k
sizes
Comma separated list of video sizes
One or more valid size values separated by commas 320x180,512x288,768x432,1024x576,1152x648
segment_duration
Segment duration to split media (in seconds)
Non-negative integer 10
pack_files
Whether to pack resulting files to a single tarball
yes, no yes

Advanced H.264 Parameters

Could be specified in such way:


    
        25
        40
        
    

The x264 Project has lead the way on H.264 development by introducing many key features. Variance Adaptive Quantization (VAQ) and Rate–Distortion Optimization (RDO) attempt to preserve video quality and motion estimation against the amount of data required to encode the video. Advanced controls include options for GOP structure, keyframing, scene detection, macroblocking, and interframe quantization. Many of these features are discussed in depth on the x264 forums. A list of the x264 flags available to our API follows:

Frame-Type Options

Option Name Allowed Values Default Values
keyint_min
The minimum distance between I-frames.
Integer 25
level
Set of constraints that indicate a degree of required decoder performance for a profile.
Integer
Note: drop the decimal, for example 3.0 is 30, 1.3 is 13
None
sc_threshold
Adjusts the sensitivity of x264's scenecut detection.
Integer 40
bf
B-frames.
Integer 16
b_strategy
Adaptively decides through a low-resolution lookahead the best number of B-frames.
0, 1, 2 1
flags2
Allows B-frames to be kept as references.
+bpyramid, +wpred, +mixed_refs, +dct8×8, -fastpskip/+fastpskip, +aud None
coder
CABAC is the default entropy encoder used by x264.
0, 1 1(CABAC enabled)
refs
This parameter lets one specify how many references can be used, through a maximum of 16.
integer 6
flags
Disable loop filter.
-loop/+loop, -psnr/+psnr +loop (Enabled)
deblockalpha, deblockbeta
One of H.264's main features is the in-loop deblocker, which avoids the problem of blocking artifacts disrupting motion estimation.
Integer 0 (Must have '-flags +loop')

Ratecontrol

Option Name Allowed Values Default Values
cqp
Constant quantizer mode.
Integer None
crf
Constant quality mode (also known as constant ratefactor).
Float None
qmin
Minimum quantizer.
Integer 10
qmax
Maximum quantizer.
Integer 50
qdiff
Set max QP step.
Integer 4
bt
Allowed variance of average bitrate.
Integer None
i_qfactor
Qscale difference between I-frames and P-frames.
Float 0.71
b_qfactor
Qscale difference between P-frames and B-frames.
Float None
chromaoffset
QP difference between chroma and luma.
Integer None
pass 1, 2, 3 None
rc_eq
Ratecontrol equation.
String blurCplx^(1-qComp)
qcomp
QP curve compression: 0.0 => CBR, 1.0 => CQP.
Float 0.60
complexityblur
Reduce fluctuations in QP (before curve compression).
Float 20.0
qblur
Reduce fluctuations in QP (after curve compression).
Float 0.5

Analysis

Option Name Allowed Values Default Values
partitions
One of H.264's most useful features is the ability to choose among many combinations of inter and intra partitions.
+partp8x8, +partp4x4, +partb8x8, +parti8x8, +parti4x4 None
directpred Integer None
flags2
This allows B-frames to use weighted prediction options other than the default. There is no real speed cost for this, so it should always be enabled.
+bpyramid, +wpred, +mixed_refs, +dct8×8, -fastpskip/+fastpskip, –no-fast-pskip/nothing, +aud. +wpred
me_method epzs, hex, umh, full None
me_range
MErange controls the max range of the motion search.
Integer 16
subq
MErange controls the max range of the motion search.
Integer 6
trellis
Trellis chooses the optimal rounding choices for the maximum rate-distortion score, to maximize PSNR relative to bitrate.
0, 1, 2 None

 

Digital Rights Management

FlashAccessDRM

Available for output formats: flv, mp4, hds.

Additional information: http://www.adobe.com/products/adobe-access.html

<format>
  <drm>yes</drm>
  <drm-license-server-url>[License server url]</drm-license-server-url>
  <drm-content-id>[Content ID]</drm-content-id>
  <drm-common-key>[Key file url]</drm-common-key>
  <drm-license-server-cert>[Certificate file url]</drm-license-server-cert>
  <drm-transport-cert>[Certificate file url]</drm-transport-cert>
  <drm-packager-credential>[Credential file url]</drm-packager-credential>
  <drm-credential-pwd>[Password]</drm-credential-pwd>
  <drm-policy-file>[Policy file url]</drm-policy-file>
</format>

KeyOS for PlayReady DRM

Available for output formats: smooth_streaming.

Additional information: http://buydrm.com

<format>
  <playready>yes</playready>
  <playready-apikey>[KeyOS api key]</playready-apikey>
  <playready-profileid>[KeyOS profile id]</playready-profileid>
  <playready-templateid>[KeyOS template id]</playready-templateid>
</format>

Editing Features

Watermarking

Note: Not available for the image output.

<format>
    <!-- Format fields -->
    <logo>
        <logo_source>[LogoURL]</logo_source>
        <logo_x>[LogoLeft]</logo_x>
        <logo_y>[LogoTop]</logo_y>
        <logo_mode>[LogoMode]</logo_mode>
        <logo_threshold>[LogoTreshold]</logo_threshold>
        <logo_transparent>[LogoTransparent]</logo_transparent>
    </logo>
</format>
Field Name Allowed Values Default Values
(required) logo_source
The URL of the logo image. The image format can be GIF, JPG or PNG.
http://[user[:password]@]hostname[:port]/[path]/[filename]
ftp://[user[:password]@]hostname[:port]/[path]/[filename][?passive=yes]
sftp://[user[:password]@]hostname[:port]/[path]/[filename]
None
logo_x
Left offset of logo image
Non-negative integer 10
logo_y
Top offset of logo image
Non-negative integer 10
logo_mode
Video and watermarking picture mixing mode
0: If the mask color matches the threshold, the logo will be transparent and only the video will be shown.
1: If the mask color is lighter or darker than the threshold value, the logo (watermark) will appear.
1
Note: If your logo source is PNG with alpha-channel, set logo_mode equal to 1 to keep transparency.
logo_threshold
Threshold color mask
6-digit hexadecimal 000000—FFFFFF
Examples:
000000 — sets color black to transparent mask
808080 — sets color gray to transparent mask
000000

For more information on how to place a watermark, please see here.

Concatenation

With this feature, you can combine multiple source video files into one file. To use this feature via the User Interface, you can add multiple video sources in the "Add Media" section and they will automatically combine into one file (in sequential order) during the encoding process. To utilize this concatenation feature via the API, you should use several <source> elements in your XML request which will be added sequentially during the encoding process. In addition, you can use different source video URLs / locations (HTTP, FTP, S3, CloudFiles) along with different media properties for each source video (format, frame size, bitrate, codec, etc...). [Read more]
For example:

<?xml version="1.0"?>
<query>
    <userid>[UserID]</userid>
    <userkey>[UserKey]</userkey>
    <action>[Action]</action>
    <mediaid>[MediaID]</mediaid>

    <source>[SourceFile]</source>
    <source>[SourceFile1]</source> <!-- if multiple SourceFile added, they will be concatenated -->
    <!-- Source fields -->
    <source>[SourceFileN]</source>

    <!-- Format fields -->
</query>

Creating Thumbnails

To generate thumbnail images, please specify a separate encoding task with <output>thumbnail</output>

<format>
    <!-- Format fields -->
    <output>thumbnail</output>
    <time>[Time]</time>
    <width>[Width]</width>
    <height>[Size]</height>
    <!-- Destination fields -->
    <destination>[DestFile]</destination>
</format>
Field Name Allowed Values Default Values
time
Timestamp (in seconds, percentage rate or interval) to capture thumbnail
Non-negative number greater than 0.01 or hh:mm:ss.ms or 1-100% percentage rate.
Example 1: use 5! to capture thumbs every 5 seconds.
Example 2: use 5% to capture thumbs at 5%.
5
width
Thumbnail width (in pixels)
Non-negative integer None
height
Thumbnail height (in pixels)
Non-negative integer None
use_vtt
Join resulting thumbnails in single video tooltip thumbnail (VTT)
yes, no no
vtt_line_size
Set the count of thumbnails in line on VTT image
Non-negative integer 4
Notes:
  • If your specified thumbnail width and height are different from your video's aspect ratio, you may get black spaces added to the thumbnail image.
  • If you specify only width or height, the other will be calculated according to your video size.
  • If both width and height are not specified, the thumbnail will result in the same size as your video.
  • JPEG is the only supported image format for thumbnail images.
Thumbnail time in intervals
You can now generate multiple thumbnails in a specified interval using '!'. Thumbnail image files will be named with a number at the end.

 

Video Rotation

Field Name Allowed Values Default Values
rotate
Video files only. Rotate video picture.
def — don't change anything. Video will be rotated according to Rotation meta data parameter, if it exists
0 — don't rotate and ignore Rotation meta data parameter
90 — rotate by 90 degree CW and ignore Rotation meta data parameter
180 — rotate by 180 degree and ignore Rotation meta data parameter
270 — rotate by 270 degree CW and ignore Rotation meta data parameter
def
set_rotate
Set rotation meta-data (MOV only).
0 — don't set anything
90 — rotate by 90 degree CW
180 — rotate by 180 degree
270 — rotate by 270 degree CW
source — keep the source value (if any)
0

Cropping

Field Name Allowed Values Default Values
crop_top
Top crop band size (in pixels)
Even integer None
crop_left
Left crop band size (in pixels)
Even integer None
crop_right
Right crop band size (in pixels)
Even integer None
crop_bottom
Bottom crop band size (in pixels)
Even integer None

Fade In/Out

Field Name Allowed Values Default Values
fade_in
Add fade in effect to audio and video streams.
FadeInStart:FadeInDuration — where both parameters are positive float values
FadeInStart — start of fade in effect (in seconds)
FadeInDuration — duration of fade in effect (in seconds)
None
fade_out
Add fade out effect to audio and video streams.
FadeOutStart:FadeOutDuration — where both parameters are positive float values
FadeOutStart — start of fade out effect (in seconds)
FadeOutDuration — duration of fade out effect (in seconds)
None

Muxing

Note: muxing is supported for only two sources now.
Sample XML to mux video from one source and audio from another:

<?xml version="1.0"?>
<query>
    <action>AddMedia</action>
    <userid>[UserID]</userid>
    <userkey>[UserKey]</userkey>
    <source>[Video source]</source>
    <source>[Audio source]</source>
    <format>
        <output>muxer</output>
        <target>ntsc-dvd</target>
        <maps>0:0,1:0</maps>
    </format>
</query>
Field Name Allowed Values Default Values
maps
Use to extract tracks from different media
file#:track#, file#:track# None
target pal-vcd, pal-svcd, pal-dvd, pal-dv, pal-dv50, ntsc-vcd, ntsc-svcd, ntsc-dvd, ntsc-dv, ntsc-dv50, film-vcd, film-svcd, film-dvd, film-dv, film-dv50 ntsc-dvd

 

Meta Data

Note: Available for the following formats: 3gp, appletv, fl9, iphone, ipod, m4a, mp4, wmv, zune.
Length of metatag value can't be greater than 256 characters.

<format>
    <!-- Format fields -->
    <metadata>
        <title>[Title]</title>
        <copyright>[Copyright]</copyright>
        <author>[Author]</author>
        <description>[Description]</description>
        <album>[Album]</album>
    </metadata>
</format>
Tag Name Description
author Source author
title Title of the media
album Media album
description Media description
copyright Copyright information
copy Copy metatags from the source media

Split Screen

Combine several sources to one split screen video

<?xml version="1.0"?>  
<query>  
    <!-- Main fields -->
    <source>[SourceFile1]</source>
    <!-- ... -->
    <source>[SourceFileN]</source>
	<split_screen>
        <columns>[ColumnsNumber]</columns>
        <rows>[RowsNumber]</rows>
        <padding_left>[PaddingLeftInPx]</padding_left>
        <padding_right>[PaddingRightInPx]</padding_right>
        <padding_bottom>[PaddingBottomInPx]</padding_bottom>
        <padding_top>[PaddingTopInPx]</padding_top>
    </split_screen>
</query>
Field Name Allowed Values Default Values
columns
Number of columns in split screen
non-negative integer Sources count
rows
Number of rows in split screen
non-negative integer 1
padding_top
Padding (in pixels) from top to split screen's main area
non-negative integer 0
padding_right
Padding (in pixels) from right to split screen's main area
non-negative integer 0
padding_bottom
Padding (in pixels) from bottom to split screen's main area
non-negative integer 0
padding_left
Padding (in pixels) from left to split screen's main area
non-negative integer 0

 

Video Overlay

<format>
    <!-- Format fields -->
    <overlay>
        <overlay_source>[Overlay1Source]</overlay_source>
        <overlay_left>[Overlay1PositionXfromLeft]</overlay_left>
        <overlay_right>[Overlay1PositionXfromRight]</overlay_right>
        <overlay_top>[Overlay1PositionYfromTop]</overlay_top>
        <overlay_bottom>[Overlay1PositionYfromBottom]</overlay_bottom>
        <size>[Overlay1Size]</size>
        <overlay_start>[Overlay1StartInSeconds]</overlay_start>
        <overlay_duration>[Overlay1DurationInSeconds]</overlay_duration>
        <keep_audio>[0,1]</keep_audio>
    </overlay>
    <!-- ... -->
    <overlay>
        <overlay_source>[OverlayNSource]</overlay_source>
        <overlay_left>[OverlayNPositionXfromLeft]</overlay_left>
        <overlay_right>[OverlayNPositionXfromRight]</overlay_right>
        <overlay_top>[OverlayNPositionYfromTop]</overlay_top>
        <overlay_bottom>[OverlayNPositionYfromBottom]</overlay_bottom>
        <size>[OverlayNSize]</size>
        <overlay_start>[OverlayNStartInSeconds]</overlay_start>
        <overlay_duration>[OverlayNDurationInSeconds]</overlay_duration>
        <keep_audio>[0,1]</keep_audio>
    </overlay>
</format>
Field Name Allowed Values Default Values
(required)
overlay_source
overlay's source URL
Valid url None
overlay_left
position x of left overlay's side (with starting point from left)
non-negative integer or % from output video width None
overlay_right
position x of right overlay's side(with starting point from right)
non-negative integer or % from output video width None
Note: If overlay_right and overlay_left specified simultaneously - overlay_right would be ignored
overlay_top
position y of top overlay's side (with starting point from top)
non-negative integer or % from output video width None
overlay_bottom
position y of bottom overlay's side (with starting point from bottom)
non-negative integer or % from output video width None
Note: If overlay_bottom and overlay_top specified simultaneously - overlay_bottom would be ignored
size
overlay's size
WxH where W and H - positive integers, or % from result video width None
Note: Size of overlay source can't be greater then size of output media.
overlay_start
overlay's start time (in seconds)
positive float value 0
overlay_duration
overlay's duration (in seconds)
positive float value None
keep_audio
keep overlay's audio
0,1 0

Audio Overlay

<format>
  <audio_overlay>
      <overlay_source>[AudioOverlay1Source]</overlay_source> 
      <overlay_start>[AudioOverlay1Start]</overlay_start> 
      <overlay_duration>[AudioOverlay1Duration]</overlay_duration> 
  </audio_overlay>
  <!-- ... -->
  <audio_overlay>
      <overlay_source>[AudioOverlayNSource]</overlay_source> 
      <overlay_start>[AudioOverlayNStart]</overlay_start> 
      <overlay_duration>[AudioOverlayNDuration]</overlay_duration> 
  </audio_overlay>
</format>
Field Name Allowed Values Default Values
(required)
overlay_source
overlay's source URL
Valid url None
overlay_start
overlay's start time (in seconds)
positive float value 0
overlay_duration
overlay's duration (in seconds)
positive float value 0

 

Text Overlay

<format>
    <!-- Format fields -->
    <text_overlay>
        <text>[Text1]</text>
        <font_source>[Font1Source]</font_source>
        <font_size>[Font1Size]</font_size>
        <font_rotate>[Font1Rotate]</font_rotate>
        <font_color>[Font1Color]</font_color>
        <align_center>[0|1]</align_center>
        <overlay_x>[TextOverlay1PositionX]</overlay_x>
        <overlay_y>[TextOverlay1PositionY]</overlay_y>
        <size>[TextOverlay1Size]</size>
        <overlay_start>[TextOverlay1StartInSeconds]</overlay_start>
        <overlay_duration>[TextOverlay1DurationInSeconds]</overlay_duration>
    </text_overlay>
    <!-- ... -->
    <text_overlay>
        <text>[TextN]</text>
        <font_source>[FontNSource]</font_source>
        <font_size>[FontNSize]</font_size>
        <font_rotate>[FontNRotate]</font_rotate>
        <font_color>[FontNColor]</font_color>
        <align_center>[0|1]</align_center>
        <overlay_x>[TextOverlayNPositionX]</overlay_x>
        <overlay_y>[TextOverlayNPositionY]</overlay_y>
        <size>[TextOverlayNSize]</size>
        <overlay_start>[TextOverlayNStartInSeconds]</overlay_start>
        <overlay_duration>[TextOverlayNDurationInSeconds]</overlay_duration>
    </text_overlay>
</format>
Field Name Allowed Values Default Values
(required)
text
Text for overlay
Text None
(required)
font_source
Font's source URL
Valid url None
font_size
Text font's size
non-negative integer 20
font_rotate
Angle on which text should be rotated
integer 0
font_color
Font color
6-digits hexadecimal 000000-FFFFFF 000000
align_center
Align text by center
0 or 1 0
overlay_x
Overlay's position X
non-negative integer 0
overlay_y
Overlay's position Y
non-negative integer 0
size
Size of the text block
WxH where W and H - positive integers None
overlay_start
Overlay's start time (in seconds)
positive float value 0
overlay_duration
Overlay's duration (in seconds)
positive float value None

 

Image to Image

<format>
    <!-- Format fields -->
    <output>image</output>
    <image_format>jpg</image_format>
    <resize_method>resize</resize_method>
    <size>560x420</size>
    <keep_aspect_ratio>yes</keep_aspect_ratio>
    <quality>75</quality>
    <dpi>72</dpi>
    <sharpen_radius>1</sharpen_radius>
    <sharpen_sigma>0.5</sharpen_sigma>
    <remove_metadata>no</remove_metadata>
    <!-- Destination fields -->
    <destination>[DestFile]</destination>
</format>
Field Name Allowed Values Default Values
(required) image_format
Format of resulting image
jpg, png, gif, tiff jpg
size
Size of resulting image
WxH or Wx0 or 0xH or Wx or xH, where W and H are positive integers None
keep_aspect_ratio
Whether to keep width to height ratio of original picture
yes,no yes
Note: if either width or height is set to 0, keep_aspect_ratio will be yes.
resize_method
How the original picture will be transformed to new size
resize, crop, combine resize
quality
JPEG quality
jpg: 1-100
All: none
80
dpi
Image DPI
71-1200 72
sharpen_radius
Sharpen radius (use 0 in most cases)
0-10 None
sharpen_sigma
Sharpen amount (best are 0.5-1.0)
Float: 0, 0.2-10 0
remove_metadata
Whether to remove image meta data (including EXIF)
yes, no no

Slideshow

If you want to create slideshow from your sources you should specify <slideshow>1</slideshow> in Main Fields.

Now we can support following input formats for slideshow: jpeg, png, mpeg audio, mpeg-4, wave.

If audio file was specified - it would be used as audio stream in output slideshow video. If durations of slideshow and audio stream are different - shortest duration will be used.

By default each slide has duration equal to 3 seconds. If you want to change it, you should add duration parameter to your source.

XML example:

<?xml version="1.0"?>
<query>
  <action>AddMedia</action>
  <userid>*</userid>
  <userkey>*</userkey>
  <source>http://www.example.com/Chrysanthemum.jpg</source>
  <source>http://www.example.com/Desert.jpg?duration=5</source>
  <source>http://www.example.com/Hydrangeas.jpg</source>
  <source>http://www.example.com/Jellyfish.jpg</source>
  <source>http://www.example.com/Koala.jpg</source>
  <source>http://www.example.com/Lighthouse.jpg</source>
  <source>http://www.example.com/Penguins.jpg</source>
  <source>http://www.example.com/Tulips.jpg</source>
  <source>http://www.example.com/music.wav</source>
  <slideshow>1</slideshow>
  <region>us-east-1</region>
  <split_screen/>
  <format>
    <output>mp4</output>
    <bitrate>2000k</bitrate>
  </format>
</query>

Burn-in timecode

To burn in timecode with default parameters specify <burnin_timecode>yes</burnin_timecode> in format fields.

To customize burn in timecode, following parameters can be used (inside <burnin_timecode> ... </burnin_timecode> parameter)

<burnin_timecode>
    <start>00:00:00:00</start>
    <left>0</left>
    <right>0</right>
    <top>0</top>
    <bottom>0</bottom>
</burnin_timecode>
Field Name Allowed Values Default Values
start
start of timecode counter
timecode in format HH:MM:SS[:;]FF
HH - hours
MM - minutes
SS - seconds
FF - frames
[:;] - : - non drop-frame, ; - drop-frame;
00:00:00:00
Note: drop frame can be used only for 29.97 or 59.94 output frame rates
left
position x of left timecode's side (with starting point from left)
non-negative integer none
right
position x of right timecode's side(with starting point from right)
non-negative integer none
Note: if right and left specified simultaneously - right would be ignored
top
position y of top timecode's side (with starting point from top)
non-negative integer none
bottom
position y of bottom timecode's side (with starting point from bottom)
non-negative integer none
Note: if bottom and top specified simultaneously - bottom would be ignored

Closed Captions

Closed Captions

<format>
    <!-- Format fields -->
    <closed_captions>
        <source>[CCSource]</source>
        <copy>[yes|no]</copy>
        <extract>[srt|scc|dfxp]</extract>
        <mux_type>[cea-608|cea-708|timed-text|webvtt|burn-in]</mux_type>
        <language>[LanguageCode]</language>
        <time_offset>[TimeOffset]</time_offset>
    </closed_captions>
</format>
Field Name Allowed Values Default Values
source
URL to Closed Captions file.
Valid URL to Closed Captions file in one of the following formats: SCC, SubRip, DFXP (TTML), SAMI, WebvTT None
copy
If video has Clossed Captions data stored in Timed Text or cea-608/cea-708 tracks, system will try to extract closed captions, and mux them back while encoding. If you want to mux Closed Captions to video in other (than in source video) format, you should specify mux_type.
yes, no no
mux_type
Closed captions mux type

timed-text — Closed Captions would be muxed in video as 3GPP Timed Text track

cea-608 — Closed Captions would be muxed in video as cea-608 track (works only with video codec libx264)

cea-708 — 608 closed captions would be up-converted to 708 closed captions. And both, cea-608 and cea-708 closed captions, would be muxed in video stream

webvtt — webvtt file would be uploaded to same destination as result file (for HLS it would be segmented)

burn-in – SRT video subtitle burn-in

None
language
Set language of 3GPP Timed Text track. Works only for mux_type=timed-text
either ISO 639-1 2-char code, ISO 639-2 3-char code, or the full language name None
extract
If video has Clossed Captions data stored in Timed Text or cea-608/cea-708 tracks, system will try to extract closed captions, and upload them to same destination as result file. If video has multiple text tracks extracted files will have integer suffix.
srt — Closed Captions would be extracted in SubRip format,
scc — Closed Captions would be extracted in Scenarist Closed Captions format
dfxp — Closed Captions would be extracted in DFXP format
None
time_offset
Set time offset for time in CC file
positive or negative integer 0

 

Caption to Caption Conversion

<?xml version="1.0"?>
<query>
    <userid>*</userid>
    <userkey>*</userkey>
    <action>AddMedia</action>
    <source>[CLOSED_CAPTIONS_SOURCE]</source>
    <format>
        <output>closed_captions</output>
        <type>[srt|scc|webvtt|dfxp]</type>
        <strip_formatting>[yes|no]</strip_formatting>
        <time_offset>[TIME_OFFSET]</time_offset>
    </format>
</query>
Field Name Allowed Values Default Values
source
URL to Closed Captions file or video with muxed closed captions.
Valid URL to Closed Captions file (in one of the following formats: SCC, SubRip, DFXP (TTML), SAMI, WebvTT) or video with muxed closed captions (in cea-6/708 or timed-text format) None
type
Convert closed captions to specified type
srt, scc, webvtt or dfxp srt
strip_formatting
Remove all formatting tags (available only for DFXP)
yes, no no
time_offset
Set time offset for time in CC file
positive or negative integer 0

 

Sub Account Management

Sub accounts are only a way of a master account to track encoding bandwidth individually among sub accounts, they are not allowed to change from plan to plan, manage billing information or do any actions rather than to create encoding jobs on their own and access limitted client interface. In order to create/manage sub accounts you should recieve permission from Encoding.com administration (contact us!).

Actions

Action Description
AddSubUser Add new sub user.
AddTrialUser Add new Trial user.
UpdateSubUser Replace information about existing user's data.
DeleteSubUser Delete specified sub user.
GetUserInfo Return information about selected user.
GetSubUsers Return list of all users and all its data.
GetASM Return average system metric information of selected user.
GetStorageSpace Return storage space information of selected user.
GetBandwidthStat Return used encoding traffic of selected user.
GetBandwidthStatGroupDate Return encoding traffic of selected user. The traffic will be grouped by existing's dates.

 

Parameters

Field Description
(required)
UserID
A unique user identifier. Can be taken from user's page.
(required)
UserKey
User's key string. Generated automatically when user is created and can be changed by user.
(required)
Action
The action to be performed.
action_user_id An unique identifier of user.
This field is required for the following actions:
  • UpdateSubUser
  • DeleteSubUser
  • GetUserInfo
  • GetASM
  • GetStorageSpace
  • GetBandwidthStat
  • GetBandwidthStatGroupDate
user_data This data include the registration information (required), and the contact information(optional) about user.
This field is required for the following actions:
  • AddSubUser
  • AddTrialUser
  • UpdateSubUser
Below you can see the required registration fields:
— for AddSubUser action: login, email, password
— for AddTrialUser action: login, email, password, phone, first_name, last_name, company
The optional contact data may be following:
  • phone
  • first_name
  • last_name
  • company
  • city
  • zip
  • country
  • state
  • addres
date_from
date_to
This field may be specified for the GetBandwidthStat and GetBandwidthStatGroupDate actions when you intend to recieve bandwidth's statistic specified interval. The date must be in format: YYYY-MM-DD.

Request XML Format

AddTrialUser action

<?xml version="1.0"?>
<query>
	<!-- Main fields -->
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>addTrialUser</action>
	<user_data>
		<email>[Email]</email>
		<login>[Login]</login>
		<password>[Password]</password>
		<first_name>[FirstName]</first_name>
		<last_name>[LastName]</last_name>
		<phone>[Phone]</phone>
	</user_data>
</query>

AddSubUser action

<?xml version="1.0"?>
<query>
	<!-- Main fields -->
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>AddSubUser</action>
	<user_data>
		<email>[Email]</email>
		<login>[Login]</login>
		<password>[Password]</password>
		<first_name>[FirstName]</first_name>
		<last_name>[LastName]</last_name>
		<phone>[Phone]</phone>
	</user_data>
</query>

UpdateUser action

<?xml version="1.0"?>
<query>
	<!-- Main fields -->
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>UpdateSubUser</action>
	<action_user_id>[ActionUserID]</action_user_id>
	<user_data>
		<email>[New email]</email>
		<phone>[New phone]</phone>
	</user_data>
</query>

DeleteUser action

<?xml version="1.0"?>
<query>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>DeleteSubUser</action>
	<action_user_id>[ActionUserID]</action_user_id>
</query>

GetUserInfo action

<?xml version="1.0"?>
<query>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>GetUserInfo</action>
	<action_user_id>[ActionUserID]</action_user_id>
</query>

GetSubUsers action

<?xml version="1.0"?>
<query>
<!-- Main fields -->
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>getsubusers</action>
</query>

GetASM action

<?xml version="1.0"?>
<query>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>GetASM</action>
	<action_user_id>[ActionUserID]</action_user_id>
</query>

GetStorageSpace action

<?xml version="1.0"?>
<query>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>GetStorageSpace</action>
	<action_user_id>[ActionUserID]</action_user_id>
</query>

GetBandwidthStat action

<?xml version="1.0"?>
<query>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>GetBandwidthStat</action>
	<action_user_id>[ActionUserID]</action_user_id>
	<date_from>[YYYY-MM-DD]</date_from>
	<date_to>[YYYY-MM-DD]</date_to>
</query>

GetBandwidthStatGroupDate action

<?xml version="1.0"?>
<query>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<action>GetBandwidthStatGroupDate</action>
	<action_user_id>[ActionUserID]</action_user_id>
	<date_from>[YYYY-MM-DD]</date_from>
	<date_to>[YYYY-MM-DD]</date_to>
</query>

Response Format

The response for API request can vary depending on action:

AddTrialUser action

<?xml version="1.0"?>
<response>
	<action>addtrialuser</action>
	<status>Success</status>
	<result>
		<plan>Trial 1 GB</plan>
		<user_id>1839</user_id>
		<user_key>f851cae31d705c08a157b8f32f3cc121</user_key>
		<message>The new trial user has been created</message>
	</result>
</response>

AddSubUser action

<?xml version="1.0"?>
<response>
	<action>addsubuser</action>
	<status>Success</status>
	<result>
		<plan>[Plan]</plan>
		<user_id>1840</user_id>
		<user_key>38772a155045fc49a4b9f6d24efee4e6</user_key>
		<message>The new sub user has been created</message>
	</result>
</response>

UpdateUser action

<?xml version="1.0"?>
<response>
	<action>updatesubuser</action>
	<status>Success</status>
	<result>
		<user_id>1800</user_id>
		<message>The user data was updated</message>
		<email>[New Email]</email>
		<country>[New Country]</country>
	</result>
</response>

DeleteSubUser action

<?xml version="1.0"?>
<response>
	<action>deletesubuser</action>
	<status>Success</status>
</response>

GetUserInfo action

<?xml version="1.0"?>
<response>
	<action>getuserinfo</action>
	<status>Success</status>
	<result>
		<user_id>1800</user_id>
		<ID>1800</ID>
		<Login>[Login]</Login>
		<FirstName>[FirstName]</FirstName>
		<LastName>[LastName]</LastName>
		<Email>[Email]</Email>
		<UserKey>[UserKey]</UserKey>
		<Country>[Country]</Country>
		<Phone>[Phone]</Phone>
		<Status>[Status]</Status>
	</result>
</response>

GetSubUsers action

<?xml version="1.0"?>
<response>
	<action>getsubusers</action>
	<status>Success</status>
	<result>
	<user_id>6</user_id>
	<user_0>
		<ID>[UserID]</ID>
		<Login>[Login]</Login>
		<FirstName>[FirstName]</FirstName>
		<LastName>[LastName]</LastName>
		<Email>[Email]</Email>
		<UserKey>[UserKey]</UserKey>
		<Country>[Country]</Country>
		<Phone>[Phone]</Phone>
		<Status>[Status]</Status>
	</user_0>
	<user_1>
		<ID>[UserID]</ID>
		<Login>[Login]</Login>
		<FirstName>[FirstName]</FirstName>
		<LastName>[LastName]</LastName>
		<Email>[Email]</Email>
		<UserKey>[UserKey]</UserKey>
		<Country>[Country]</Country>
		<Phone>[Phone]</Phone>
		<Status>[Status]</Status>
	</user_1>
	<!-- ... -->
    </result>
</response>

GetASM action

<?xml version="1.0"?>
<response>
	<action>getasm</action>
	<status>Success</status>
	<result>
		<user_id>[UserID]</user_id>
		<encoding_success_rate>
			<percentage>100</percentage>
		</encoding_success_rate>
		<queue_time>
			<second>[average queue time in this month]</second>
		</queue_time>
		<processing_time>
			<second>[average processing time in this month]</second>
		</processing_time>
		<connection_speed>
			<kbs>[average connection speed]</kbs>
		</connection_speed>
		<encoding_bandwidth>
			<gb>[average amount of encoding bandwidth]</gb>
		</encoding_bandwidth>
	</result>
</response>

GetStorageSpace action

<?xml version="1.0"?>
<response>
	<action>getstoragespace</action>
	<status>Success</status>
	<result>
		<user_id>[UserID]</user_id>
		<gb>[Storage Space]</gb>
	</result>
</response>

GetBandwidthStat action

<?xml version="1.0"?>
<response>
	<action>getbandwidthstat</action>
	<status>Success</status>
	<result>
		<user_id>[UserID]</user_id>
		<date_from>[Date from]</date_from>
		<date_to>[Date to]</date_to>
		<in>
			<bytes>[amount in bytes]</bytes>
			<gb>[amount in gigabytes]</gb>
		</in>
		<out>
			<bytes>[amount in bytes]</bytes>
			<gb>[amount in gigabytes]</gb>
		</out>
		<turbo>
			<bytes>[amount in bytes]</bytes>
			<gb>[amount in gigabytes]</gb>
		</turbo>
	</result>
</response>

GetBandwidthStatGroupDate action

<?xml version="1.0"?>
<response>
	<action>getbandwidthstatgroupdate</action>
	<status>Success</status>
	<result>
		<user_id>[userID]</user_id>
		<date_date1>
			<in>
				<bytes>[amount in bytes]</bytes>
				<gb>[amount in gigabytes]</gb>
			</in>
			<out>
				<bytes>[amount in bytes]</bytes>
				<gb>[amount in gigabytes]</gb>
			</out>
		</date_date1>
		<date_date2>
			<in>
				<bytes>[amount in bytes]</bytes>
				<gb>[amount in gigabytes]</gb>
			</in>
			<out>
				<bytes>[amount in bytes]</bytes>
				<gb>[amount in gigabytes]</gb>
			</out>
		</date_date2>
		<!-- ... -->
	</result>
</response>

Errors

Error Messages appears in the response if the action was failed.

Error Description
Common errors
No XML No XML query provided in the request.
Wrong XML The XML query provided in the request is not well-formed.
Wrong query format The XML does not contain <query> root element.
Invalid action The Action parameter is empty or is not in the list of allowed actions.
Authentication Errors
Wrong User ID or Key The UserID/UserKey pair was not found.
Add/Update sub users validation Errors
You don't have permission to create trial users You cannot create trial users.
You don't have permission to create sub users You cannot create sub users.
You don't have permission to manage this user You can manage only users who had been created by you.
action_user_id : User not found User with id which you set doesn't exist.
action_user_id : This field is required action_user_id is required field for following actions:
  • UpdateSubUser
  • DeleteSubUser
  • GetUserInfo
  • GetSubUsers
  • GetASM
  • GetStorageSpace
  • GetBandwidthStat
  • GetBandwidthStatGroupDate

 

API Responses

The response for API request can vary depending on the following actions:

AddMedia

<?xml version="1.0"?>
<response>
	<message>Added</message>
	<MediaID>[MediaID]</MediaID>
</response>

GetMediaList

<?xml version="1.0"?>
<response>
	<media>
		<mediafile>["SourceFile"]</mediafile>
		<mediaid>["MediaID"]</mediaid>
		<mediastatus>Closed</mediastatus>
		<createdate>[Date]</createdate>
		<startdate>[Date]</startdate>
		<finishdate>[Date]</finishdate>
	</media>
	<media>
	<!-- ... -->
	</media>
</response>

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

GetStatus

<?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>
		<!-- other format fields -->

		<s3_destination>[TempS3Link]</s3_destination> <!-- optional -->
		<cf_destination>[TempCFLink]</cf_destination> <!-- optional -->
		<destination>[URL]</destination>
		<destination_status>[Saved|Error (ErrorDescription)]</destination_status> 
		<destination>[URL_2]</destination>
		<destination_status>[Saved|Error (ErrorDescription)]</destination_status>
		<!-- ... -->
		<destination>[URL_N]</destination>
		<destination_status>[Saved|Error (ErrorDescription)]</destination_status>
	</format>

	<format>
        <!-- ... -->
	</format>
</response>
Field Name Description
Date is of the format: YYYY-MM-DD HH:MM:SS
FormatFields is a set of fields corresponding to the <format> section of a user's API request
TotalTimeLeft is an estimated time until the media processing will complete
StatusTimeLeft is an estimated time remaining for the media's current status
TotalProgress is an estimated progress for the entire media processing (in percent)
StatusProgress is an estimated progress for the media's current status (in percent)
TempS3Link S3 URL for the encoded file only if the <destination> was empty and result put to S3
TempCFLink CDN URL for the encoded file only if the <destination> was empty and result put to Rackspace CloudFiles
MediaStatus can take the following values: 'New', 'Downloading', 'Ready to process', 'Waiting for encoder', 'Processing', 'Saving', 'Finished', 'Error'.
Status can take the following values: 'New', 'Waiting for encoder', 'Processing', 'Saving', 'Finished', 'Error'.

 

GetStatus (extended)

Used to request the status of several medias in a single request:

Request:

<?xml version="1.0"?>
<query>
	<action>GetStatus</action>
	<userid>[UserID]</userid>
	<userkey>[UserKey]</userkey>
	<extended>yes</extended>
	<mediaid>[CommaSeparatedList]</mediaid>
</query>

Response:

<?xml version="1.0"?>
<response>
	<job>
		<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>
		<filesize>[FileSize]</filesize>
		<processor>[AMAZON | RACKSPACE]</processor>
		<progress>[TotalProgress]</progress>
		<time_left>[TotalTimeLeft]</time_left>

		<format>
			<id>[ID]</id>
			<status>[Status]</status>
			<created>[Date]</created>
			<started>[Date]</started>
			<finished>[Date]</finished>
			<s3_destination>[TempS3Link]</s3_destination> <!-- optional -->
			<cf_destination>[TempCFLink]</cf_destination> <!-- optional -->
			<convertedsize>[FileSize]</convertedsize>
			<time_left>[TotalTimeLeft]</time_left>
			<progress>[TotalProgress]</progress>
			<time_left_current>[StatusTimeLeft]</time_left_current>
			<progress_current>[StatusPorgress]</progress_current>
			<file_size>[FileSize]</file_size>
			<destination>[URL]</destination>
			<destination_status>[Saved|Error (ErrorDescription)]</destination_status> 
			<destination>[URL_2]</destination>
			<destination_status>[Saved|Error (ErrorDescription)]</destination_status>
			<!-- ... -->
			<destination>[URL_N]</destination>
			<destination_status>[Saved|Error (ErrorDescription)]</destination_status>
		</format>

		<format>
	        <!-- ... -->
		</format>
	</job>

	<job>
	<!-- ... -->
	</job>
</response>

GetMediaInfo

<?xml version="1.0"?>
<response>
	<bitrate>1807k</bitrate>
	<duration>6464.83</duration>
	<audio_bitrate>128k</audio_bitrate>
	<video_codec>mpeg4</video_codec>
	<video_bitrate>1679k</video_bitrate>
	<frame_rate>23.98</frame_rate>
	<size>640x352</size>
	<pixel_aspect_ratio>1:1</pixel_aspect_ratio>
	<display_aspect_ratio>20:11</display_aspect_ratio>
	<audio_codec>ac3</audio_codec>
	<audio_sample_rate>48000</audio_sample_rate>
	<audio_channels>2</audio_channels>
</response>

Parameters Description

Field Name Description
bitrate Total bitrate for the media file.
duration Tracks duration in seconds.
pixel_aspect_ratio Pixel's rectangle width/height ratio (1:1 = square pixel).
display_aspect_ratio Video frame's width/height ratio.
audio_channels Number of audio channels (commonly 1, 2 or 5.1).
Note: for each particular media, some parameters can be omitted.

Other Actions

<?xml version="1.0"?>
<response>
	<!-- Message section -->
	<message>[Message]</message>
	<!-- Errors section -->
	<errors>
		<error>[Error]</error>
		<error>[Error]</error>
		<!-- … -->
	</errors>
</response>

API Error Responses

Common Errors

Error Message Description
No XML No XML query provided in the request
Wrong XML The XML query provided in the request is not correctly formatted
Wrong query format The XML does not contain root element
Invalid action The Action parameter is empty, or is not in the list of allowed actions
Wrong user id or key The user ID / user key pair was not found

Media Errors

Error Message Description Actions
Media ID is not indicated The MediaID parameter is omitted in the query UpdateMedia, GetStatus
Wrong source file URL The URL provided in the query does not match a single URL of valid formats AddMedia, UpdateMedia
Source file is not indicated The SourceFile parameter is empty AddMedia, UpdateMedia
Wrong Media ID The media with such ID was not found UpdateMedia, GetStatus

Queue Errors

Error Message Description Actions
No formats specified There is no single <format> element present in the query AddMedia, UpdateMedia
No output format specified The <output> element of the format is omitted or has an empty value AddMedia, UpdateMedia
Output format [Output] is not allowed The <output> element of the format is not in the list of allowed formats AddMedia, UpdateMedia
Wrong destination file URL The URL provided in the query does not match a single URL of valid formats. AddMedia, UpdateMedia
Internal Error Internal program error. A description will follow. All

 

Status API

Encoding.com status API provide ability to get current system status and status history using simple GET request.

Current Status

Request format:
http://status.encoding.com/status.php?format=[xml|json]

Request params:

Field Name Allowed Values Default Values
format
Specify response format
json, xml html

Response format:

<response>
  <status>Current system status</status>
  <status_code>Current system status code.</status_code>
  <incident>Current incident description, if system is not at Ok condition. See description below</incident>
</response>

Where status code is one of the following: ok, encoding_delays, api_out, maintenance

Status history

Request format:
http://status.encoding.com/archive.php?format=[xml|json][&from=0][&limit=10]

Request params:

Field Name Allowed Values Default Values
format
Response format
json, xml html
from
First element in response
integer 0
limit
Number of incidents in response
integer 10

Response format:

<response>
  <paging>
    <total>Total count of incidents</total>
    <from>First element into list</from>
    <limit>Count of elements into list</limit>
  </paging>
  <incidents>
    <incident>Incident #1 description</incident>
    <!-- ... -->
    <incident>Incident #N description</incident>
  </incidents>
</response>

Incident description:

<incident>
  <id>Incident id</id>
  <published>Incident publish date into YYYY-MM-DD HH:MM:SS format in PST timezone</published>
  <name>Incident name</name>
  <status_code>Incident status code</status_code>
  <description>Incident description</description>
  <updates>Incident updates list. Consist of incident update elements.</updates>
  <resolvenote>Incident resolve note. Empty in case incident isn't resolved</resolvenote>
  <resolved>Incident resolve date into YYYY-MM-DD HH:MM:SS format in PST timezone. Empty in case incident isn't resolved</resolved>
</incident>

Where Incident status code one of the following: queue_slow, pc_queue_slow, api_out, deploy

Incident update element:

<update>
  <id>Incident status update id</id>
  <published>Incident status update publish date into YYYY-MM-DD HH:MM:SS format in PST timezone</published>
  <updatetime>Incident status update date into YYYY-MM-DD HH:MM:SS format in PST timezone</updatetime>
  <description>Incident status update description</description>
</update>

Recent API Changes