Methods 1.1:startConversion/ru

From Aviberry API

Jump to: navigation, search

К содержанию
Другие методы
Возникли вопросы?


startConversion - Метод создает и запускает задачу с указанными параметрами.

Contents

Сигнатура 

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

Параметры

source_url

source_url - Ссылка на исходный видеофайл или массив таких ссылок.
Тип: mixed.
Принимаются ссылки вида: 

http|https://[user[:password]@]hostname[:port]/[path]/[filename]
ftp://[user[:password]@]hostname[:port]/[path]/[filename]
http|https://[user:password@]bucket.s3.amazonaws.com/[path]/[filename]
Ссылка должна быть оформлена соответственно стандарту, т.е. все спецсимволы должны быть "percent-encoded".

Возможные сочетания типов параметров source_url, target_url и preset

target_url

target_url - Ссылка, куда необходимо поместить файл, полученный в результате конвертации, или массив таких ссылок.
Тип: mixed.
Ссылка обязательно должна включать имя файла-результата. Если имя не указано, это считается ошибкой. Именем файла считается все, что указано после последнего слеша /. Принимаются ссылки вида: 

 ftp://[user[:password]@]hostname[:port]/[path]/filename[.ext]
 http://user:password@bucket.s3.amazonaws.com/[path]/filename[.ext]
 mailto:email
Ссылка должна быть оформлена соответственно стандарту, т.е. все спецсимволы должны быть "percent-encoded".

При использовании ссылки вида mailto: на указанный email будет отправлено письмо с сообщением о результате конвертации и ссылкой на скачивание файла. Имя файла-результата в данном случае не указывается и будет сформировано автоматически. С момента окончания конвертации сервис aviberry.com в течение 1 суток предоставляет хостинг для файла-результата, в течение которых файл должен быть скачан. По истечении указанного периода ссылка на скачивание станет недействительной.

Ссылка вида mailto: не может быть указана в случае, когда target_url является массивом ссылок. Т.е. отправка уведомления на email может быть задана только для всей конвертации, но не для какого-либо отдельного файла.

Возможные сочетания типов параметров source_url, target_url и preset

preset

preset - Обязательный объект с настройками профиля или массив таких объектов.
Тип: mixed.

Свойство Тип Описание
format_id integer Цифровой идентификатор формата. Обязательное свойство.
preset_id integer Идентификатор профиля, который следует использовать для формата. Профиль может быть или предустановленным, или созданным самим пользователем.
preset_data string Строка JSON, содержащая пользовательские настройки профиля.

Подробный список форматов, стандартных профилей и возможных пользовательских настроек профилей см. в разделе Форматы и профили.

В зависимости от того, какие свойства параметра preset заданы, а какие опущены, задача будет обрабатываться по-разному.

  • Задан только format_id - Используется указанный формат; в качестве профиля будет использован профиль по умолчанию для данного формата.
  • Заданы только format_id и preset_id - Используются указанный формат и профиль.
  • Заданы все свойства - format_id, preset_id и preset_data - Используется указанный формат и пользовательские настройки профиля из preset_data; настройки, значения которых пользователь не указал в preset_data, будут по возможности взяты из указанного в preset_id профиля.
  • Заданы только format_id и preset_data - Используется указанный формат и пользовательские настройки профиля из preset_data; настройки, значения которых пользователь не указал, принимают по возможности значения по умолчанию.


Если в качестве значения параметра preset задан единственный объект с настройками профиля, то каждый исходный файл будет сконвертирован единожды, используя только этот единственный профиль, а результат в выдаче метода getConversion будет содержать набор результирующих файлов для этого единственного профиля.

Если в качестве значения параметра preset задан массив объектов с настройками профилей, то каждый исходный файл будет сконвертирован столько раз, сколько задано профилей в массиве, а результат в выдаче метода getConversion будет содержать набор результирующих файлов для каждого заданного профиля.
Такая задача называется "суперзадачей" или "суперконвертацией". Каждая её подзадача имеет свой уникальный идентификатор.
При задании множественных профилей свойство target_filename_policy параметра params не может быть установлено в PRESERVE_FILENAME и по умолчанию в этом случае будет иметь значение OVERWRITE_EXTENSION.

Возможные сочетания типов параметров source_url, target_url и preset

Возможны следующие сочетания типов параметров source_url, target_url и preset:

  1. source_url - string; target_url - string; preset - object.
    Единственный исходный файл будет конвертирован в единственный файл назначения с выбранным профилем.
  2. source_url - string; target_url - string; preset - array.
    Единственный исходный файл будет конвертирован во все заданные профили. На основе заданного target_url будет сформировано несколько результирующих файлов, различающихся только расширением. Если в результате получаются файлы с полностью одинаковым именем, то к имени добавляется индекс.
  3. source_url - string; target_url - array; preset - object.
    Единственный исходный файл будет сконвертирован один раз с выбранным профилем и помещен во все файлы назначения. Т.е. во всех элементах массива target_url будет содержаться один и тот же файл.
  4. source_url - string; target_url - array; preset - array.
    Результат аналогичен случаю (2), но полученные файлы будут помещены во все заданные target_url. Таким образом, можно, например, сохранить результат сразу и на S3, и на FTP.
  5. source_url - array; target_url - string; preset - object.
    Все исходные файл будут объединены в единственный файл результата и сконвертированы один раз с выбранным профилем. В этом случае значение свойства join_source_files параметра params автоматически устанавливается в 1, т.е. происходит автоматический join.
  6. source_url - array; target_url - string; preset - array.
    Все исходные файл будут объединены (автоматический join) в один файл и сконвертированы во все заданные профили. На основе заданного target_url будет сформировано несколько результирующих файлов, различающихся только расширением. Если в результате получаются файлы с полностью одинаковым именем, то к имени добавляется индекс.

transform

transform - Необязательный объект с настройками трансформаций, которые будут применены к каждому исходному файлу при конвертации в каждый профиль. Свойствами объекта являются конкретно применяемые действия.
Тип: object.

Свойство Тип Описание
cut string Вырезает из видео указанный фрагмент.
split string Разделяет видео на фрагменты равной продолжительности или равного размера.
сrop string Обрезает кадр на указанные отступы.
rotate string Осуществляет поворот видео.
watermark object Накладывает на видео "водяной знак".
adjust object Осуществляет общую корректировку изображения.
3d object Преобразовывает обычное видео в 3D-видео.


Любое из действий в настройках трансформации может быть опущено. В этом случае оно не будет применено.
Более подробно о параметрах действий смотрите в разделе Трансформации.

preview

preview - Необязательный объект с настройками стоп-кадра.
Тип: object.

Свойство Тип Описание
width integer Желаемая ширина картинки preview в пикселях. По умолчанию 160 пикселей.
height integer Желаемая высота картинки preview в пикселях. По умолчанию 120 пикселей.
resize_method integer Метод, используемый для изменения ширины и высоты кадра. Значение по умолчанию - 1.
Значение Описание
0 Stretch. Изображение будет растянуто, чтобы соответствовать новым значениям ширины и высоты
1 Letterbox. Изображение будет дополнено черными полями, чтобы соответствовать новым значениям ширины и высоты
2 Crop. Изображение будет обрезано, чтобы соответствовать новым значениям ширины и высоты
resize_quality integer Качество преобразования к новым значениям ширины и высоты. Значение по умолчанию - 1.
Значение Описание
0 Normal (Fast). Быстрее, но хуже по качеству
1 Best (Slow). Дольше, но лучше по качеству

Любой из параметров может быть опущен. В этом случае будут использованы указанные значения по умолчанию.
Ссылка на стоп-кадр становится доступной при статусе конвертации finished и формируется следующим образом: preview_url = target_url + '.jpg'.

callback

callback - Необязательный объект с настройками функции обратного вызова, которая будет вызвана после завершения конвертации.
Тип: object.

Свойство Тип Описание
url string Адрес API c функцией обратного вызова.
method string Собственно имя функции обратного вызова, которую необходимо вызвать.
protocol string Протокол, по которому необходимо сделать вызов. Значением должна быть строка "json" для вызова по протоколу
associate_with string Только для версии API v1.1.1. Используется для мультизадач. Параметр, отвечающий за то, в каком случае вызывается callback. Значение по умолчанию - PARENT. Может принимать значения:
CHILD Вызывается по завершению каждой подзадачи.
PARENT Вызывается по завершению родительской задачи.
ALL Вызывается по завершению родительской задачи и каждой из подзадач.

После завершения конвертации будет сделан RPC-вызов метода callback[method] с помощью POST-запроса на адрес callback[url] согласно RPС-протоколу, указанному в параметре callback[protocol].
При вызове методу будет передан параметр conversion - информация о конвертации, аналогичная возвращаемой методом getConversion.


Пример запроса, отправляемого по протоколу JSON-RPC: 


POST <URI, полученный из callback[url]> HTTP/1.1
User-Agent: api.aviberry.com
Host: <Имя хоста, полученное из callback[url]>
Content-Type: application/json
Content-Length: ...

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

См. также: Пример JSON-RPC сервера

params

params - Необязательный объект с дополнительными параметрами выполнения метода. Каждое свойство объекта соответствует какому-либо параметру.
Тип: object.

Определены следующие свойства:

Свойство Тип Описание
overwrite_target_file boolean Перезаписывать ли файл или файлы, "скрывающиеся" за target_url, если они уже существуют. 1 - перезаписывать, 0 - не перезаписывать. По умолчанию 0.
join_source_files boolean Следует ли все исходные файлы после конвертации объединить в один файл. 1 - объединять, 0 - не объединять. По умолчанию 0.
source_url_encoding string Кодировка переданного имени файла-источника. По умолчанию UTF-8. Более подробно о параметре смотрите в разделе О кодировках.
source_url_check_file_exists boolean 1 - Проверять существование исходного файла при постановке задачи. Если такой файл не существует, то задача не ставится.

0 - Задача ставится в любом случае. Проверка осуществляется непосредственно перед началом обработки.
По умолчанию 1.
Для локальных файлов (путь до которых указан по file-протоколу (file://path/to/file)) всегда используется значение 0.

source_filename_encoding string Актуальная кодировка имени файла-источника, требуемая для доступа к файлу в его файловой системе. По умолчанию UTF-8. Более подробно о параметре смотрите в разделе О кодировках.
target_url_encoding string Аналогично source_url_encoding, но для target_url. По умолчанию UTF-8.
target_url_check_file_exists boolean 1 - Проверять существование пути до конечного файла при постановке задачи. Если такой путь не существует, то задача не ставится.

0 - Задача ставится в любом случае. Проверка осуществляется непосредственно перед началом обработки.
По умолчанию 1.
Для локальных файлов (путь до которых указан по file-протоколу (file://path/to/file)) всегда используется значение 0.

target_filename_encoding string Аналогично source_filename_encoding, но для target_url. По умолчанию UTF-8.
s3_storage_class string Класс хранилища для файлов, помещаемых на Amazon S3. Возможными значениями являются STANDARD или REDUCED_REDUNDANCY. По умолчанию standard.
target_filename_policy string Политика формирования имен файлов назначения target_url. Возможные значения:
PRESERVE_FILENAME Имя файла остается неизменным. Это значение по умолчанию.
OVERWRITE_EXTENSION Если в имени файла есть расширение, то оно заменяется расширением формата. Если в имени файла расширения нет, то расширение формата добавляется.
APPEND_EXTENSION К имени файла, каким бы оно ни было, просто добавляется расширение формата.

Расширения форматов перечислены в разделе Форматы и профили.

priority string Приоритет задачи. Чем больше значение, тем выше приоритет, тем раньше начнет выполняться задача.

Может задаваться относительное или абсолютное значение.
Относительное значение может меняться от '0%' до '100%'.
Минимальное абсолютное значение - '0'. Максимальное абсолютное значение (соответствующее '100%') зависит от тарифного плана.


Любой из параметров может быть опущен. В этом случае будут использованы указанные значения по умолчанию.

data

data - Необязательный объект с пользовательскими данными, который будет ассоциирован с создаваемой конвертацией.
Тип: object.
Данный объект будет возвращаться в дальнейшем для конвертации при ее получении различными методами, например getConversion или getConversions. Фактически объект содержит пользовательские данные в виде пар ключ=значение.

Возвращаемое значение

Результат вызова метода зависит от используемой версии API.

API v1.1

Тип: string.
Результат вызова метода - идентификатор созданной конвертации (conversion_id), который нужно использовать при вызове других методов.

API v1.1.1

Тип: object.
Результат вызова метода - объект, со следующими свойствами:

conversion_id

conversion_id - Идентификатор задачи.
Тип: string.

child_conversion_id

child_conversion_id - Массив идентификаторов подзадач. Используется только в случае суперзадач, если в качестве значения параметра preset задан не один объект, а массив таких объектов.
Тип: array.

queue

Тип: object.
queue - объект, позволяющий определить, как скоро задача будет отправлена на обработку. Используется только при постановке обычных (не супер) задач. Содержит следующие свойства:

Свойство Тип Описание
tasks_before integer Количество задач в очереди перед текущей задачей.
time_to_shift integer Оценочное время (в секундах), оставшееся до продвижения задачи вперед в очереди.

Нужно учитывать, что позиция задачи в очереди может не только уменьшаться, но и увеличиваться, в случае если приходит задача с более высоким приоритетом, см Сравнение тарифных планов.

Примеры

XML-RPC

Пользовательские настройки параметра preset 

<?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>

Задан массив значений preset

<?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>


Задан массив source_url 

<?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><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><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>

Задан массив target_url 

<?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>
            <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>

Заданы настройки объекта preview

<?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>

Заданы настройки объекта transform

<?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

Заданы свойства объекта params

{
	"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"
		}
	}
}

Заданы массивы значений source_url и preset

{
	"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"
		}
	}
}



К содержанию
Другие методы
Возникли вопросы?

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