Methods 1.1:startConversion

From Aviberry API

Jump to: navigation, search
Languages Language: 

English  • Русский

Contents
Other methods
Still have a question?


startConversion - method that generates and launches conversion with specified parameters.

Contents

Signature 

string startConversion(
    mixed  source_url,
    mixed  target_url,
    mixed  preset,
    object transform = {},
    object preview = {},
    object callback = {},
    object params = {},
    object data = {}
)

Parameters

source_url

source_url - source video file URL, or URL array.
Type: mixed.
The following URL types are accepted: 

http|https://[user[:password]@]hostname[:port]/[path]/[filename]
ftp://[user[:password]@]hostname[:port]/[path]/[filename]
http://[user:password@]bucket.s3.amazonaws.com/[path]/[filename]
URL should be coded according to standard, i.e. all the special characters should be "percent-encoded".

Possible combinations of types of source_url, target_url and preset parameters

target_url

target_url - converted file URL, or URL array.
Type: mixed.
URL must include converted file name. Not specifying the file name is an error. File name is everything after the last slash /. The following URL types are accepted: 

 ftp://[user[:password]@]hostname[:port]/[path]/filename[.ext]
 http://user:password@bucket.s3.amazonaws.com/[path]/filename[.ext]
 mailto:email
URL should be coded according to standard, i.e. all the special characters should be "percent-encoded".

When using mailto: URL, a message with conversion result and file download link will be sent to the specified email. In this case the name of converted file is not indicated and will be generated automatically. After the conversion completion, aviberry.com service provides 1 day hosting for converted file, during which the file should be downloaded. After that the download link is no longer valid.

mailto: URL cannot be specified if target_url is an URL array. I.e. the email notification is available only for the whole conversion and not for the separate files.

Possible combinations of types of source_url, target_url and preset parameters

preset

preset - mandatory object containing preset settings, or object array.
Type: mixed.

Property Type Description
format_id integer Digital format identifier. Mandatory property.
preset_id integer Format preset identifier. It can be default or custom preset.
preset_data string JSON string that containing custom preset settings.

The full list of formats, default presets and possible preset custom settings see in Formats and Presets section.

Tasks will be proceeded in different ways, depending on specified preset parameter settings.

  • If only format_id is specified, then original file is converted to specified format, and default preset is applied to this format.
  • If only format_id and preset_id properties are specified, then original file is converted to specified format applying specified preset.
  • If all the properties - format_id, preset_id and preset_data - are specified, then original file is converted to specified format using preset custom settings from preset_data; values of settings that were not specified by the user in preset_data are taken from the preset specified in preset_id when possible.
  • If only format_id and preset_data properties are specified, then original file is converted to selected format using only custom preset settings from preset_data; for settings that were not specified by the user, default values are used when possible.


If the only object with preset settings is defined as a preset parameter value, every source file will be converted once using this only preset, and the output of getConversion method will contain a set of output files for this only preset.

If an object array with preset settings is defined as a preset parameter value, every source file will be converted as many times as many presets are defined in array, and the output of getConversion method will contain a set of output files for each defined preset.
This task type is called supertask or superconversion. Each sub-task has its own unique identifier.
When defining multiple presets, target_filename_policy property of param parameter cannot be set in PRESERVE_FILENAME, and in this case will have OVERWRITE_EXTENSION value by default.

Possible combinations of types of source_url, target_url and preset parameters

The following combinations of types of source_url, target_url and preset parameters are available:

  1. source_url - string; target_url - string; preset - object.
    Single source file will be converted to single target file using selected preset.
  2. source_url - string; target_url - string; preset - array.
    Single source file will be converted to all selected presets. There will be several target files created on the basis of specified target_url. The files will differ in extensions only. If there are several files with completely identical names, then an index is added to filenames.
  3. source_url - string; target_url - array; preset - object.
    Single source file will be converted to single target file using selected preset and will be placed to all target files. I.e. all elements of target_url array will contain the same file.
  4. source_url - string; target_url - array; preset - array.
    The result is similar to the case (2), but target files will be placed to all specified target_url. Thus, the output can be saved, e.g., both to S3 and FTP at once.
  5. source_url - array; target_url - string; preset - object.
    All the converted source files will be joined in one target file and converted once to the selected preset. Such pattern is called automatic join. Value of join_source_files property of params parameter in this case is always considered to be set to 1.
  6. source_url - array; target_url - string; preset - array.
    All the converted source files will be joined in one target file (automatic join) and converted to all selected presets. There will be several target files created on the basis of specified target_url. The files will differ in extensions only. If there are several files with completely identical names, then an index is added to filenames.

transform

transform - optional object with transformation settings that will be applied to every source file. Object properties are the actions applied.
Type: object.

Property Type Description
cut string Cuts out specified video fragment.
split string Splits video to fragments of equal duration or size.
сrop string Crops the frame by defined margins.
rotate string Rotates video.
watermark object Applies "watermark" to video.
adjust object Performs general image adjustment.
3d object Converts ordinary video to 3D.


Each of the actions in transformation settings can be omitted. In this case the action will not be applied.
For more details on action parameters, see Transformations section.

preview

preview - optional objects with preview settings.
Type: object.

Property Type Description
width integer Desired width of picture preview in pixels. By default 160 pixels.
height integer Desired height of picture preview in pixels. By default 120 pixels.
resize_method integer Resize method. Default value - 1.
Value Description
0 Stretch. The image will be stretched to meet the new values of width and height
1 Letterbox. Black bars will be added to the image so that it meets the new values of width and height
2 Crop. The image will be cropped to meet the new values of width and height
resize_quality integer Resize quality parameter. Default value - 1.
Value Description
0 Normal (Fast). Works faster, but the quality is worse
1 Best (Slow). Works slower, but the quality is better

Each of the actions in transformation settings can be omitted. In this case the action will not be applied.
Link to picture preview will be available if conversion status is finished (see getProgress method) and is generated as follows: preview_url = target_url + '.jpg'.

callback

callback - optional object with callback function settings that will be called after conversion completion.
Type: object.

Property Type Description
url string API address with callback function
method string Name of callback function to call
protocol string Call protocol. The value should be the "json" string to call via JSON-RPC protocol.
associate_with string API v1.1.1 only. This parameter controls callback invocation conditions. By default - PARENT. Possible values are:
CHILD Called upon completion each child task.
PARENT Called upon completion each parent task.
ALL Called upon completion parent task and each child-task.

There will be done a RPC call of callback[method] method by POST request to the callback[url] address via RPС protocol specified in callback[protocol] parameter.
During the call conversion parameter will be transferred to the method. The parameter will contain information about conversion similar to the information returned via getConversion method.

Example of request sent via JSON-RPC protocol: 

?
POST <URI received from callback[url]> HTTP/1.1
User-Agent: api.aviberry.com
Host: <Hostname received from callback[url]>
Content-Type: application/json
Content-Length: ...

{
    "version" : "1.1",
    "method" : "callback[method]",
    "params" : 
    {
        "conversion" : {...}
    }
}

See also: Example for JSON-RPC server

params

params - optional object with additional method execution parameters. Each object property corresponds to some parameter.
Type: object.

At the moment following properties are defined:

Property Type Description
overwrite_target_file boolean Whether the files in target_url should be overwritten if they already exist. 1 - overwrite, 0 - don't overwrite. By default 0.
join_source_files boolean Whether all the source files should be joined in one file after conversion. 1 - join, 0 - don't join. By default 0.
source_url_encoding string Encoding of transferred source file name. By default UTF-8. For more information on parameter, see the About encodings section.
source_url_check_file_exists boolean 1 - check if the source file exists when creating a task. If the file doesn't exist, then the task is not created.

0 - task is always created. Check is carried out straight before processing.
By default 1.
For local files (path to which is specified via file protocol (file://path/to/file)) the value 0 is always used.

source_filename_encoding string Actual encoding of source file name required to access the file in its file system. By default UTF-8. For more details on the parameter, see the About encodings section.
target_url_encoding string Similar to source_url_encoding, but for target_url. By default UTF-8.
target_url_check_file_exists boolean 1 - check if the path to converted file exists when creating a task. If the path doesn't exist, then the task is not created.

0 - task is always created. Check is carried out straight before processing.
By default 1.
For local files (path to which is specified via file protocol (file://path/to/file)) the value 0 is always used.

target_filename_encoding string Similar to source_filename_encoding, but for target_url. By default UTF-8.
s3_storage_class string Storage class for files located at Amazon S3. Possible values are STANDARD or REDUCED_REDUNDANCY. By default standard.
target_filename_policy string Policy of creating target file names target_url. Possible values are:
PRESERVE_FILENAME Filename remains unchanged. Set by default.
OVERWRITE_EXTENSION If filename has an extension, the extension is overwritten. If not - an extension is added.
APPEND_EXTENSION Adds extension to any filename.

Extensions are listed in Formats and presets section.

priority string Task priority may be specified in an absolute value or in a percentage of the service plan priority.

Minimal absolute priority value is 0 and maximal priority value depends on the service plan by default. Example: '1000', '50%'.

Any parameter can be omitted. In this case default values will be applied.

data

data - optional object with custom data to associate with created conversion.
Type: object.
This object will be returned later on for conversion when received via different methods, for example via getConversion or getConversions methods. In fact, object contains user data in form of key=value matches.

Return value

Return value depends on the currently used API version.

API v1.1

Type: string.
Method call result - identifier of created conversion (conversion_id) that must be used to call other methods.

API v1.1.1

Type: object.
Method call result - object with following properties:

conversion_id

conversion_id - Identifier of created conversion.
Type: string.

child_conversion_id

child_conversion_id - Subtask identifier array. Only used in supertasks, if the preset parameter contains an array of presets
Type: array.

Examples

XML-RPC

preset parameter custom settings 

<?xml version='1.0'?>
<methodCall>
<methodName>startConversion</methodName>
<params>
    <param><value><string>ftp://login:pass@server.com/path/test.avi</string></value></param>
    <param><value><string>mailto:user@mail.ru</string></value></param>
    <param>
        <value>
            <struct>
                <member>
                    <name>format_id</name>
                    <value><int>16505</int></value>
                </member>
                <member>
                    <name>preset_data</name>
                    <value><string>
                    {
                        "VideoCodec":"avc1",
                        "AudioCodec":"mp4a",
                        "Width":"320",
                        "Height":"240",
                        "FrameRate":"25",
                        "VideoSAsInput":false,
                        "PSPMode":false,
                        "ProgressiveDownload":true,
                        "ResizeMethod":"1",
                        "ResizeQuality":"1",
                        "Frequency":"44100","Channels":"2",
                        "VParams":
                        {
                            "H264":
                            {
                                "Profile":4,
                                "Quality":2,
                                "MaxIFrameInterval":25,
                                "MaxBFrameSequence":0,
                                "VBR":true,
                                "AspectRatio":0
                            }
                        },
                        "AParams":
                        {
                            "AAC":
                            {
                                "Profile":"2",
                                "Bitrate":128000,
                                "Quality":"100"
                            }
                        }
                    }
                    </string></value>
                </member>
                <member>
                    <name>preset_id</name>
                    <value><int>-2</int></value>
                </member>
            </struct>
        </value>
    </param>
    <param><value><boolean>0</boolean></value></param>
    <param><value><boolean>0</boolean></value></param>
    <param><value><boolean>0</boolean></value></param>
    <param><value><boolean>0</boolean></value></param>
    <param><value> <struct></struct></value></param>
</params>
</methodCall>

Setting preset value array 

<?xml version='1.0'?>
<methodCall>
<methodName>startConversion</methodName>
<params>
    <param><value><string>ftp://login:pass@server.com/path/test.avi</string></value></param>
    <param><value><string>mailto:user@mail.ru</string></value></param>
    <param>
        <value>
            <array>
                <data>
                    <value>
                        <struct>
                            <member>
                                <name>format_id</name>
                                <value><int>16505</int></value>
                            </member>
                            <member>
                                <name>preset_id</name>
                                <value><int>1480</int></value>
                            </member>
                        </struct>
                    </value>
                    <value>
                        <struct>
                            <member>
                                <name>format_id</name>
                                <value><int>16505</int></value>
                            </member>
                            <member>
                                <name>preset_id</name>
                                <value><int>2744</int></value>
                            </member>
                        </struct>
                    </value>
                </data>
            </array>
        </value>
    </param>
    <param><value><boolean>0</boolean></value></param>
    <param><value><boolean>0</boolean></value></param>
    <param><value><boolean>0</boolean></value></param>
    <param><value><boolean>0</boolean></value></param>
    <param><value> <struct></struct></value></param>
</params>
</methodCall>

Setting source_url and target_url array 

<?xml version='1.0'?>
<methodCall>
<methodName>startConversion</methodName>
<params>
    <param>
        <value>
            <array>
                <data>
                    <value><string>ftp://login:pass@server.com/path/input/test.avi</string></value>
                    <value><string>ftp://login:pass@server.com/path/input/test2.avi</string></value>
                </data>
            </array>
        </value>
    </param>
    <param>
        <value>
            <array>
                <data>
                    <value><string>ftp://login:pass@server1.com/path/output/1/test.avi</string></value>
                    <value><string>ftp://login:pass@server1.com/path/output/1/test.avi</string></value>
                    <value><string>ftp://login:pass@server2.com/path/output/test.avi</string></value>
                </data>
            </array>
        </value>
    </param>
    <param>
        <value>
            <struct>
                <member>
                    <name>format_id</name>
                    <value><int>16505</int></value>
                </member>
                <member>
                    <name>preset_id</name>
                    <value><int>1480</int></value>
                </member>
            </struct>
        </value>
    </param>
    <param><value><boolean>0</boolean></value></param>
    <param><value><boolean>0</boolean></value></param>
    <param><value><boolean>0</boolean></value></param>
    <param><value><boolean>0</boolean></value></param>
    <param><value> <struct></struct></value></param>
</params>
</methodCall>

Specifying preview object settings 

<?xml version='1.0'?>
<methodCall>
<methodName>startConversion</methodName>
<params>
    <param><value><string>ftp://login:pass@server.com/path/test.avi</string></value></param>
    <param><value><string>mailto:user@mail.ru</string></value></param>
    <param>
        <value>
            <struct>
                <member>
                    <name>format_id</name>
                    <value><int>16505</int></value>
                </member>
                <member>
                    <name>preset_id</name>
                    <value><int>1480</int></value>
                </member>
            </struct>
        </value>
    </param>
    <param><value><boolean>0</boolean></value></param>
    <param>
        <value>
                <struct>
                        <member>
                                <name>width</name>
                                <value><int>300</int></value>
                        </member>
                        <member>
                                <name>height</name>
                                <value><int>300</int></value>
                        </member>
                        <member>
                                <name>resize_method</name>
                                <value><int>1</int></value>
                        </member>
                        <member>
                                <name>resize_quality</name>
                                <value><int>1</int></value>
                        </member>
                </struct>
        </value>
    </param>
    <param><value><boolean>0</boolean></value></param>
    <param><value><boolean>0</boolean></value></param>
    <param><value> <struct></struct></value></param>
</params>
</methodCall>

Specifying transform object settings 

<?xml version='1.0'?>
<methodCall>
<methodName>startConversion</methodName>
<params>
    <param><value><string>ftp://login:pass@server.com/path/test.avi</string></value></param>
    <param><value><string>mailto:user@mail.ru</string></value></param>
    <param>
        <value>
            <struct>
                <member>
                    <name>format_id</name>
                    <value><int>16505</int></value>
                </member>
                <member>
                    <name>preset_id</name>
                    <value><int>1480</int></value>
                </member>
            </struct>
        </value>
    </param>
    <param>
        <value>
            <struct>
                <member>
                    <name>split</name>
                    <value><string>10mb</string></value>
                </member>
                <member>
                    <name>3d</name>
                    <value>
                        <struct>
                            <member>
                                <name>Mode</name>
                                <value><string>Anaglyph</string></value>
                            </member>
                            <member>
                                <name>Depth</name>
                                <value><int>-20</int></value>
                            </member>
                            <member>
                                <name>Shift</name>
                                <value><int>10</int></value>
                            </member>
                            <member>
                                <name>Perspective</name>
                                <value><int>40</int></value>
                            </member>
                        </struct>
                    </value>
                </member>
            </struct>
        </value>
    </param>
    <param><value><boolean>0</boolean></value></param>
    <param><value><boolean>0</boolean></value></param>
    <param><value><boolean>0</boolean></value></param>
    <param><value> <struct></struct></value></param>
</params>
</methodCall>

JSON-RPC

Specifying params object settings 

{
	"version":"1.1",
	"method":"startConversion",
	"id":1,
	"params":
	{
		"source_url":"ftp:\/\/server.com\/path\/test.avi",
		"target_url":"ftp:\/\/login:pass@server.com\/path\/test_output.mp4",
		"preset":
		{
			"format_id":"16505",
			"preset_id":"86"
		},
		"callback":[],
		"params":
		{
			"overwrite_target_file":"true",
			"priority":"20",
			"target_filename_policy":"OVERWRITE_EXTENSION"
		}
	}
}

Setting source_url and preset array 

{
	"version":"1.1",
	"method":"startConversion",
	"id":1,
	"params":
	{
		"source_url":["ftp:\/\/server.com\/path\/test1.avi","ftp:\/\/server.com\/path\/test2.avi"],
		"target_url":"ftp:\/\/login:pass@server.com\/path\/test_output.mp4",
		"preset":[
		{
			"format_id":"16505",
			"preset_id":"86"
		},
		{
			"format_id":"16505",
			"preset_id":"2744"
		}],
		"callback":[],
		"params":
		{
			"overwrite_target_file":"true",
			"target_filename_policy":"OVERWRITE_EXTENSION"
		}
	}
}


Contents
Other methods
Still have a question?

Languages Language: 

English  • Русский

Retrieved from "http://api.aviberry.com/Methods_1.1:startConversion"
Views
Personal tools