379
edits
Changes
→EVENT
Клиент - стороннее приложение, которое работает с движком посредством API.
== Общий вид команд Схема работы API==Каждая команда должна состоять Обмен данными с движком происходит по протоколу TCP. Общая схема работы выглядит так:* клиент устанавливает TCP-соединение с движком* клиент и движок обмениваются рукопожатиями* клиент и движок обмениваются сообщениями* одна из строки, завершающейся разделителем \r\nсторон завершает соединение
Ключ <tt>'''CMD'''EnginePath</tt> содержит абсолютный путь к исполняемому файлу движка (tsengine.exe). По умолчанию это <tt>%APPDATA%\TorrentStream\engine\tsengine.exe</tt> - предопределенное название команды
Алгоритм установления соединения (Windows):# считать из реестра ключ <tt>'''param1, param2 ...'''HKEY_CURRENT_USER\Software\TorrentStream\EnginePath</tt> ## если ключ отсутствует - движок не установлен## запомнить путь к исполняемому файлу движка (engine_path) и директории движка (engine_dir)# считать содержимое файла engine_dir/acestream.port и запомнить порт# если данный файл отсутствует - параметры командызапустить движок, разделенные пробеломдождаться создания файла acestream.port и считать его содержимое# установить TCP-соединение на localhost на указанный порт# если не получилось установить соединение - движок не запущен и его нужно запустить# обменяться рукопожатием и начать обмен сообщениями
;''version_code'Примеры асинхронных команд':'''цифровой код версии движка (например, 3003400); клиент должен использовать этот код для сравнения версий движка; код каждой новой версии всегда больше всех кодов предыдущих версий
Если клиент в течение некоторого времени после отправки рукопожатия не получил ответ, соединение необходимо завершить.
Примерный алгоритм приема сообщений выглядит таким образом:* клиент в цикле ждет поступления данных по TCP- соединению* при получении данных они добавляются в буфер* клиент отправляет командупроверяет, есть ли в буфере символы CRLF. Если есть, например "GETPID qwerty 0 0 0" то из буфера вырезается сообщение (строка от начала буфера до символов CRLF) и ждетотправляется в обработчик сообщений* клиент должен учитывать возможность получения нескольких сообщений одновременно (т.е. повторять предыдущий шаг, пока от TS Engine придет ответв буфере не будет символов CRLF)
То же самое должен делаь клиент при закрытии - перед закрытием отослать движку команду <tt>SHUTDOWN</tt>
== ВХОДЯЩИЕ КОМАНДЫ Сообщения==
Исключением являются две команды:
* <tt>LOAD</tt> (сихронная загрузка информации о потоке)
* <tt>GETCID</tt> (получение Content ID для потока)
Мы не рекомендуем использовать синхронную команду <tt>LOAD</tt>, так как она подразумевает блокирование потока на стороне клиента.
Эта команда является устаревшей и вместо нее следует использовать асинхронную версию <tt>LOADASYNC</tt>
Ответ на команду <tt>'''LOAD TORRENT''' GETCID<torrent_url/tt> приходит практически мгновенно, поэтому ее использование не приводит к блокированию. Однако есть одно замечание по использованию данной команды: Команду <developer_idtt> GETCID<affiliate_id/tt> не следует отправлять, если движок находится в состоянии <zone_idtt>starting</tt>
;Синтаксис <tt>LOADASYNC ''request_id''TORRENT ''url'' ''developer_id'' ''affiliate_id'' ''zone_id'' LOADASYNC ''request_id'' INFOHASH ''infohash'' ''developer_id'' ''affiliate_id'' ''zone_id'' LOADASYNC ''request_id'' RAW ''data'' ''developer_id'' ''affiliate_id'' ''zone_id'' LOADASYNC ''request_id'' PID ''content_id''</tt> - случайное целое число - идентификатор запроса LOADASYNC; этот же идентификатор будет отослан клиенту в команде LOADRESP после того,как будет получен список файлов; данный идентификатор служит для того, чтобы клиент в случае отправки нескольких запросов LOAD точно знал, на какой из этих запросов получен ответ
;Параметры* <tt>'''torrent_url'request_id''</tt> : случайное целое число - ссылка на торрент файл (напримеридентификатор запроса LOADASYNC; этот же идентификатор будет отослан клиенту в команде LOADRESP после того, http://sometracker.com/torrent/12345)как будет получен список файлов; данный
идентификатор служит для того, чтобы клиент в случае отправки нескольких запросов LOADASYNC точно знал, на какой из этих запросов получен ответ * <tt>''url'torrent_infohash'</tt>: ссылка на транспортный файл* <tt>''infohash''</tt>: инфохеш транспортного файла* <tt>''data''</tt>: содержимое транспортного файла в кодировке base64* <tt>''content_id''</tt>: идентификатор контента в системе ACE Stream (Content ID)* <tt>''developer_id''</tt> - infohash торрента: код разработчика (если неизвестно, необходимо передавать 0) * <tt>''affiliate_id''</tt>: код партнера (если неизвестно, необходимо передавать 0) * <tt>''zone_id''</tt>: код зоны партнера (если неизвестно, необходимо передавать 0)
;Формат ответа:Ответ приходит в формате JSON со следующими полями:* <tt>''status'player_id'</tt>:** 0 - транспортный файл не содержит аудио/видео файлов** 1 - транспортный файл содержит один аудио/видео файл** 2 - транспортный файл содержит более одного аудио/видео файла** 100 - ошибка получения данных* <tt>''files''</tt> : список файлов/потоков; это массив, каждый элемент в котором состоит из массива из двух элементов: первый - название файла, второй - код плеерапозиция в транспортном файле (эта позиция
должна отправляться в команде <tt>START</tt> для указания, какой именно файл необходимо загружать, если их несколько)* <tt>''infohash'torrent_data'</tt>: инфохеш транспортного файла* <tt>''checksum''</tt> - содержимое торрент-: хешсумма транспортного файла в кодировке base64
:Параметры <tt>''infohash'developer_id'</tt> и <tt>''checksum''</tt> - код разработчика (если неизвестноклиенту нужны для того, необходимо передавать 0)чтобы в дальнейшем получить Content ID с помощью команды <tt>GETCID</tt>
;Пример: <tt>'''zone_id'''</ttnowiki>Загрузить контент по Content ID:>> - код зоны партнера (если неизвестно, необходимо передавать 0)LOADASYNC 126500 PID 1ccf192064ee2d95e91a79f91c6097273d582827
В ответ клиент получает от движка:
<<LOADRESP 126500 {
"status": 1,
"files": [["sintel-1024-surround.mp4", 0]],
"infohash": "5410b27fc567c35c8547e3b69b141215ce3a1fd7",
"checksum": "504275dd71a32d51c63c45ced37807751f5ccfa2"
}</nowiki></tt>
=====<tt style="color: #009;">START</tt>=====
;Версия API
:>= 1
;Описание
:Начать проигрывание указанного контента
;Синтаксис
<tt>START TORRENT ''url'' ''file_indexes'' ''developer_id'' ''affiliate_id'' ''zone_id'' ''stream_id''
START INFOHASH ''infohash'' ''file_indexes'' ''developer_id'' ''affiliate_id'' ''zone_id''
START PID ''content_id'' ''file_indexes''
START RAW ''data'' ''file_indexes'' ''developer_id'' ''affiliate_id'' ''zone_id''
START URL ''direct_url'' ''file_indexes'' ''developer_id'' ''affiliate_id'' ''zone_id''
START EFILE ''efile_url''</tt>
;Параметры* <tt>''url'START TORRENT'</tt>: ссылка на транспортный файл* <tt>''infohash''</tt>: инфохеш транспортного файла* <tt>''content_id''</tt>: идентификатор контента в системе ACE Stream (Content ID)* <tt>''data'' <torrent_url/tt> : содержимое транспортного файла в кодировке base64* <tt>''direct_url''</tt>: прямая http-ссылка на контент (для проигрывания без транспортного файла)* <tt>''efile_url''</tt>: ссылка на acemedia-файл (зашифрованный медиа-файл, который можно воспроизвести с помощью ПО ACE Stream)* <tt>''file_indexes''</tt> : список индексов файлов из торрент-файла, которые необходимо загружать. Индексы файлов клиент получает в сообщении LOADRESP разделенных запятой. Индексы начинаются с нуля и соответствуют списку файлов, который был получен в результате выполнения команды LOAD. Например, если в торрент-файле всего один видео-файл, то необходимо отправлять индекс 0. * <tt>''developer_id''</tt> : код разработчика (если неизвестно, необходимо передавать 0)* <tt>''affiliate_id''</tt> : код партнера (если неизвестно, необходимо передавать 0)* <tt>''zone_id''</tt>: код зоны партнера (если неизвестно, необходимо передавать 0) * <tt>''stream_id''</tt>: номер потока для multi-stream файлов (значение клиент получает из сообщения LOADRESP)
;Примеры: <tt>'''file_indexes'''</ttnowiki> - список индексов файлов из торрент-файла, которые необходимо загружать. Индексы файлов клиент получает Запустить в сообщении LOADRESP разделенных запятой. Индексы начинаются с нуля и соответствуют списку файлов,формате HLS:который был получен в результате выполнения команды LOAD. Например, если в торрент-файле всего один видео-файл, то необходимо отправлять индекс >> START PID 1ccf192064ee2d95e91a79f91c6097273d582827 0.output_format=hls
=====<ttstyle="color: #009;">'''torrent_url'''STOP</tt> - ссылка на торрент файл (например, http=====;Версия API://sometracker.com/torrent/12345)>= 1
;Синтаксис <tt>'''player_id'''STOP</tt> - код плеера
;Пример: <tt>'''direct_url'''<nowiki>>>STOP</nowiki></tt> - прямая ссылка на файл (например, http://somesite.com/files/video.mp4)
=====<ttstyle="color: #009;">'''developer_id'''GETPID</tt>=====;Версия API:1 Эта команда устарела и больше не используется. Вместо нее следует использовать команду <tt>GETCID</tt> - код разработчика (если неизвестно, необходимо передавать 0)
=====<ttstyle="color: #009;">'''affiliate_id'''GETCID</tt> - код партнера (если неизвестно, необходимо передавать 0)=====;Версия API:>= 2
;Синтаксис
<tt>GETCID checksum=''checksum'' infohash=''infohash'' developer=''developer_id'' affiliate=''affiliate_id'' zone=''zone_id''</tt>
;Параметры* <tt>''checksum'GETPID'</tt>: хешсумма транспортного файла (значение клиент из команды LOADRESP)* <tt>''infohash'' <infohash/tt> : инфохеш транспортного файла (значение клиент из команды LOADRESP)* <tt>''developer_id''</tt> : код разработчика (если неизвестно, необходимо передавать 0 либо не передавать данный параметр) * <tt>''affiliate_id''</tt> : код партнера (если неизвестно, необходимо передавать 0 либо не передавать данный параметр) * <tt>''zone_id>''</tt>: код зоны партнера (если неизвестно, необходимо передавать 0 либо не передавать данный параметр)
=====<tt style="color: #009;">GETADURL</tt>=====
;Версия API
:>= 3
;Описание:Запрос к движку на получение ссылки на рекламную страницу. Данную команду могут использовать клиенты, которые имеют возможность отображать встроенный браузер в плеере, для того, чтобы показывать пользователям рекламу перед началом проигрывания контента либо когда пользователь нажимает паузу. Если движок определит, что есть доступная к показу реклама, то после получения этой команды отправит клиенту событие <tt>'''SHUTDOWN'''EVENT showurl</tt>
;Параметры
* <tt>''width''</tt>: ширина видео окна клиента (в пикселях)
* <tt>''height''</tt>: высота видео окна клиента (в пикселях)
* <tt>''infohash''</tt>: infohash текущего контента (значение клиент получает из сообщения LOADRESP)
* <tt>''action''</tt>: описание события, возможные значения:
** <tt>load</tt> - загрузка (клиент загрузился, готов к проигрыванию, но пользователь еще не начала проигрывание)
** <tt>pause</tt> - пользователь нажал паузу
;Примеры <tt>'''STOP'''<nowiki>>>GETADURL width=1328 height=474 infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 action=load>>GETADURL width=1328 height=474 infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 action=pause</nowiki></tt>
;Описание
:Данная команда используется для передачи движку информации о пользователе. Информация передается в формате JSON.
;Синтаксис <tt>USERDATA [{"gender": ''gender_id'DUR'}, {"age": '' <video_url> <duration>age_id''}]</tt>
=====<ttstyle="color: #009;">'''video_url'''SAVE</tt> - ссылка на видео, которая была отправлена клиенту после окончания пребуферизации=====;Версия API:>= 2
;Синтаксис
<tt>SAVE infohash=''infohash'' index=''index'' path=''path''</tt>
;Параметры* <tt>''infohash'PLAYBACK'</tt> - infohash контента, который неободимо сохранить (значение клиент получает из сообщения <tt>EVENT cansave</tt>)* <tt>''index'' <video_url/tt> - индекс файла, который необходимо сохранить (значение клиент получает из сообщения <tt> EVENT cansave<event/tt>)* <tt>''path''</tt>- абсолютный путь к файлу, в который необходимо сохранить контент. Если указанный файл не существует, он будет создан. Если существует, файл будет перезаписан. Путь должен передаваться в виде urlencoded строки в кодировке UTF-8.
;Синтаксис <tt>'''event'''SHUTDOWN</tt> - одно из данных событий:
;Параметры
:name - название опции
:value - значение опции
;Пример: <tt>'''HELLOTS'''<nowiki>>>SETOPTIONS use_stop_notifications=1</nowiki></tt>
=====<tt style="color: #009;">START</tt>=====
;Версия API
:>= 2
;Синтаксис <tt>auth_levelSTART ''url'' [ad=1 [interruptable=1]] [stream=1] [pos=''position'']</tt> - целое число - уровень доступа
;Примеры <tt><nowiki>Начать проигрывание контента по указанной ссылке:<<START http://127.0.0.1 - пользователю доступны расширенные функции:6878/content/5410b27fc567c35c8547e3b69b141215ce3a1fd7/0.628180567194
Начать проигрывание непрерываемого рекламного ролика:
<<START http://127.0.0.1:6878/content/6081f31fe7f1db2ea7183686b46ba382820df574/0.456623456572 ad=1
Начать проигрывание прерываемого рекламного ролика:<tt>'''STATE''' <state_id><START http://127.0.0.1:6878/content/6081f31fe7f1db2ea7183686b46ba382820df574/tt>0.456623456572 ad=1 interruptable=1
Начать проигрывание с середины (50%):
<<START http://127.0.0.1:6878/content/5410b27fc567c35c8547e3b69b141215ce3a1fd7/0.828180567196 pos=50</nowiki></tt>
=====<ttstyle="color: #009;">'''SHUTDOWN'''PAUSE</tt>=====;Версия API:>= 1
;Синтаксис
<tt>PAUSE</tt>
;Пример: <tt>'''PLAYAD''' <video_urlnowiki><<PAUSE</nowiki></tt>
=====<ttstyle="color: #009;">'''PLAYADI''' <video_url>RESUME</tt>=====;Версия API:>= 1
;Синтаксис <tt>'''PLAY'''RESUME</tt> - проигрывание основного видео
;Пример: <tt>'''PLAYADI'''<nowiki><<RESUME</nowiki></tt> - проигрывание прерываемого рекламного ролика (пользователь может перемотать либо пропустить данный рекламный ролик)
=====<tt style="color: #009;">STOP</tt>=====
;Версия API
:>= 1
;Параметры
:нет
;Пример: <tt>'''RESUME'''<nowiki><<STOP</nowiki></tt>
;Описание
:Движок завершил работу
;Синтаксис <tt>'''LOADRESP''' <request_id> <response>SHUTDOWN</tt>
;Пример: <tt>'''request_id'''<nowiki><<SHUTDOWN</nowiki></tt> - идентификатор запроса
====События от клиента к движку==== События <tt>'''status'''DUR</tt> и <tt>PLAYBACK</tt> необходимо отправлять только для VOD- 0: в торренте нет видео файлов, контента (так как live не имеет длительности). Отправка данных событий является обязательной только при воспроизведении рекламных роликов (когда получена команда <tt>START</tt> с параметром ad=1 - в торренте один видео файл, 2 - в торренте более одного видео файла). См. примечание к событию <tt>PLAYBACK</tt>.
=====<ttstyle="color: #009;">'''files'''DUR</tt> - список файлов=====; это массив, каждый элемент в котором состоит из массива из двух элементовВерсия API: первый - название файла, второй - позиция файла в торренте (эта позиция должна отправляться в команде START для указания, какой именно файл необходимо загружать, если их несколько).>= 1
;Синтаксис
<tt>DUR ''video_url'' ''duration''</tt>
;Параметры* <tt>'''INFO'video_url'' <message_id/tt>: ссылка на видео, которая была отправлена клиенту после окончания пребуферизации в команде <tt>START</tt>;* <message_texttt>''duration''</tt>: длительность в миллисекундах
=====<ttstyle="color: #009;">'''message_id'''PLAYBACK</tt> - код сообщения=====;Версия API:>= 1
;Синтаксис
<tt>PLAYBACK ''video_url'' ''event''</tt>
;Параметры
* <tt>''video_url''</tt>: ссылка на видео, которая была отправлена клиенту после окончания пребуферизации в команде <tt>START</tt>
* <tt>''event''</tt>: одно из указанных событий:
** 0: начало проигрывания
** 25: проиграно 25% видео
** 50: проиграно 50% видео
** 75: проиграно 75% видео
** 100: проиграно 100% видео (воспроизведение завершено)
;Пример: <tt>'''STATUS''' <status_stringnowiki>>>PLAYBACK http://127.0.0.1:6878/content/5b5ba8c462f4014d8b57377c97d2e13caee52cdd/0.685119063624 0>>PLAYBACK http://127.0.0.1:6878/content/5b5ba8c462f4014d8b57377c97d2e13caee52cdd/0.685119063624 25>>PLAYBACK http://127.0.0.1:6878/content/5b5ba8c462f4014d8b57377c97d2e13caee52cdd/0.685119063624 50>>PLAYBACK http://127.0.0.1:6878/content/5b5ba8c462f4014d8b57377c97d2e13caee52cdd/0.685119063624 75>>PLAYBACK http://127.0.0.1:6878/content/5b5ba8c462f4014d8b57377c97d2e13caee52cdd/0.685119063624 100</nowiki></tt>
;Синтаксис
<tt>EVENT ''event_name'' [param1=value1 [param2=value2] ...]</tt>
;Примеры <tt>STATUS main:status_string<nowiki>>>EVENT play>>EVENT pause>>EVENT seek position=1487>>EVENT stop</nowiki></tt>
====События от движка к клиенту====
=====<tt style="color: #009;">STATE</tt>=====
;Версия API
:>= 1
;Синтаксис <tt>STATUS main:status_string|ad:status_stringSTATE ''state_id''</tt>
;Параметры
* <tt>''state_id''</tt>: состояние движка:
** 0 (IDLE) - движок ничего не делает
** 1 (PREBUFFERING) - началась пребуферизация
** 2 (DOWNLOADING) - идет загрузка контента в обычном режиме
** 3 (BUFFERING) - началась буферизация
** 4 (COMPLETED) - загрузка контента завершена
** 5 (CHECKING) - выполняется инициализация перед началом загрузки
** 6 (ERROR) - ошибка
;Пример: <tt>'''status_string:'''<nowiki><<STATE 0</nowiki></tt>
;Синтаксис
<tt>STATUS ''status_string''</tt>
Если идет проигрывание основного контента <tt>total_progress;immediate_progress;speed_down;http_speed_down;speed_up;peers;http_peers;downloaded;http_downloaded;uploadedSTATUS main:''status_description''</tt>
Если идет проигрывание рекламного ролика (рекламный ролик и основной контент описываются отдельно; например, рекламный ролик уже полность загружен, а основной контент проходит стадию пребуферизации): <tt>STATUS main:''status_description'total_progress'|ad:''status_description''</tt> - сколько всего закачано по данному файлу
;Возможные значения <tt>''status_description:''</tt>* движок ничего не делает - <tt>'immediate_progress''idle'''</tt>* движок загружает транспортный файл (обрабатывает команду <tt>LOADASYNC</tt> ) - сколько непрерывных данных закачано начиная с текущей позиции <tt>'''loading'''</tt>* движок выполняет предварительную инициализацию воспроизведения (для отображения колдвижок переходит в это состояние после получения команды <tt>START</tt> от клиента) -ва закачанного в бегунке<tt>'''starting'''</tt>* ошибка - <tt>'''err;error_id;error_message'''</tt> (код и описание)* проверка - <tt>'''check;progress'''</tt>* пребуферизация - <tt>'''prebuf;progress;time'''</tt>* контент загружается либо уже полностью загружен - <tt>'''dl'''</tt>* буферизация - <tt>'''buf;progress;time'''</tt>* ожидание достаточной скорости - <tt>'''wait;time'''</tt>
Ко всем <tt>status_string</tt> (кроме <tt>idle, loading, starting, err, check</tt>) добавляются общие данные:
<tt>total_progress;immediate_progress;speed_down;http_speed_down;speed_up;peers;http_peers;downloaded;http_downloaded;uploaded</tt>
* <tt>''total_progress''</tt> - сколько всего закачано по данному файлу
* <tt>''immediate_progress''</tt> - сколько непрерывных данных закачано начиная с текущей позиции (для отображения кол-ва закачанного в бегунке)
* <tt>''speed_down''</tt> - скорость загрузки (Кбайт/с)
* <tt>''http_speed_down''</tt> - скорость загрузки от прямых http-источников (Кбайт/с)
* <tt>''speed_up''</tt> - скороть отдачи (Кбайт/с)
* <tt>''peers''</tt> - количество подсоединенных пиров
* <tt>''http_peers''</tt> - количество подсоединенных прямых http-источников
* <tt>''downloaded''</tt> - объем загруженных данных (байт)
* <tt>''http_downloaded''</tt> - объем загруженных по http данных (байт)
* <tt>''uploaded''</tt> - объем отданных данных (байт)
Все числа передаются как integer.
Все progress принимают значение от 0 до 100.
;Примеры
<tt><nowiki>Движок ничего не делает:
<<STATUS main:idle
Загружается транспортный файл:
<<STATUS main:loading
Инициализация воспроизведения:
<<STATUS main:starting
Пребуферизация 0%, еще нет подсоединенных пиров:
<<STATUS main:prebuf;0;2147483648;0;0;0;0;0;0;0;0;0;0;
Пребуферизация 20%, скорость загрузки 328 Кбайт/с, подсоединено 7 пиров, загружено 5505024 байт:
<<STATUS main:prebuf;20;2723;0;0;328;0;0;7;0;5505024;0;0
Пребуферизация 90%, скорость загрузки 420 Кбайт/с, подсоединено 9 пиров, загружено 11659264байт:
<<STATUS main:prebuf;90;3299;1;0;420;0;0;9;0;11659264;0;0
;Пример трансформации статусов в текстовые сообщения, понятные пользователю <tt>check - Checking Проверка xx% prebuf - Prebuffering Пребуферизация xx% buf - Buffering Буферизация xx% wait - Waiting sufficient download speedОжидание достаточной скорости
err - выводим сообщение об ошибке
loading - Загрузка...
starting - Запуск...
dl, idle - ничего не выводим</tt>
=====<tt style="color: #009;">AUTH</tt>=====
;Версия API
:>= 1
;Синтаксис <tt>AUTH '''EVENT event_name param1_name=param1_value param2_name=param2_value ...'user_auth_level''</tt>
;Параметры не обязательны.* <tt>''user_auth_level''</tt>: уровень доступа пользователя
Пользователь зарегистрирован:
<<AUTH 1</nowiki></tt>
=====<tt style="color: #009;">EVENT getuserdata</tt>=====
;Версия API
:>= 3
;Описание
:Движок запрашивает у клиента данные пользователя (пол и возрастную группу). Такой запрос приходит при попытке что-либо проиграть, если данные о пользователе не были переданы ранее (т.е. фактически при первом после установки просмотре в ответ на команду <tt>START</tt>).
:При получении этого события клиент должен запросить данные у пользователя, затем отправить их движку командой <tt>USERDATA</tt> и начать воспроизведение командой <tt>START</tt>
;Синтаксис
<tt>EVENT getuserdata</tt>
;Параметры
:нет
;Пример:
<tt><nowiki><<EVENT getuserdata</nowiki></tt>
=====<tt style="color: #009;">EVENT cansave</tt>=====
;Версия API
:>= 2
;Описание
:Данное событие информирует клиента о том, что контент может быть сохранен на диске в указанном пользователем месте. Например, при получении данного события клиент может отобразить кнопку "Сохранить" в пользовательском интерфейсе. При нажатии на кнопку пользователь должен будет выбрать, куда сохранять контент, после чего клиент отправит движку команду <tt>SAVE</tt>
;Синтаксис
<tt>EVENT cansave infohash=''infohash'' index=''index'' format=''format''</tt>
;Параметры
* <tt>''infohash''</tt> - infohash контента
* <tt>''index''</tt> - номер файла, который можно сохранить
* <tt>''format''</tt> - формат файла, в котором будет сохранен контент. Возможные значения:
** <tt>plain</tt> - файл будет сохранен в незашифрованном виде
** <tt>encrypted</tt> - файл будет сохранен в зашифрованном виде (файл должен иметь расширение .acemedia). Зашифрованные файлы могут быть воспроизведены только с помощью программного обеспечение ACE Stream (с помощью команды <tt>START EFILE</tt>).
Параметры <tt>''infohash''</tt> и <tt>''index''</tt> клиент может использовать в команде <tt>SAVE</tt>, если пользователь решит сохранить контент.
;Пример:
<tt><nowiki>Доступен для сохранения файл под номером 0, файл может быть сохранен в открытом виде:
<<EVENT cansave infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 index=0 format=plain
Файл может быть сохранен только в зашифрованном виде:
<<EVENT cansave infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 index=0 format=encrypted</nowiki></tt>
=====<tt style="color: #009;">EVENT showurl</tt>=====
;Версия API
:>= 3
;Описание
:Клиент должен отобразить встроенный браузер и загрузить указанную ссылку. В случае, если клиент не имеет встроенного браузера, это событие можно проигнорировать.
;Синтаксис
<tt>EVENT showurl type=''type'' url=''url'' [width=''width''] [height=''height'']</tt>
;Параметры
* <tt>''type''</tt> - тип запроса (причина, по которой движок просит отобразить браузер). Возможные значения:
** <tt>ad</tt>: отобразить рекламу (такой запрос приходит в ответ на команду <tt>GETADURL</tt>)
** <tt>notification</tt>: отобразить пользователю страницу-уведомление. Такой запрос используется в том случае, если пользователя необходимо уведомить о чем-то и уведомление потребует от пользователя каких-либо действий (например, если доступ к контенту открыт только для зарегистрированных пользователей, то клиенту будет отослана ссылка на страницу, на которой пользователь сможет зарегистрироваться). Такие запросы дублируются событием <tt>INFO</tt> для того, чтобы клиенты без встроенного браузера могли отобразить пользователю текстовое уведомление.
* <tt>''url''</tt> - ссылка на страницу, которую необходимо отобразить
* <tt>''width''</tt> - ширина страницы (в пикселях)
* <tt>''height''</tt> - высота страницы (в пикселях)
Если размеры окна браузера, передаваемые в параметрах <tt>width</tt> и <tt>height</tt>, больше размера окна клиента, то клиент должен отобразить браузер на все окно.
Если параметры <tt>width</tt> и <tt>height</tt> отсутствуют либо равны нулю, клиент должен отобразить браузер на все окно.
;Пример:
<tt><nowiki>Показать рекламную страницу с адресом http://ad.example.com в браузере с размером окна 400x250 пикселей:
<<EVENT showurl type=ad url=http://ad.example.com width=400 height=250
Отобразить на все окно браузер со страницой http://www.example.com/notification:
<<EVENT showurl type=notification url=http://www.example.com/notification</nowiki></tt>
=====<tt style="color: #009;">EVENT livepos</tt>=====
Описание скоро будет
=====<tt style="color: #009;">EVENT download_stopped</tt>=====
;Версия движка
:>= 3003600
;Описание
:Данное событие информирует клиента о причине остановки воспроизведения контента
;Синтаксис
<tt>EVENT download_stopped reason=''reason'' option=''option''</tt>
;Параметры
* <tt>''reason''</tt> - причина остановки; возможные значения:
** <tt>missing_option</tt>: не активирована платная опция, необходимая для воспроизведения данного контента
* <tt>''option''</tt> - идентификатор платной опции
;Пример:
<tt><nowiki>Воспроизведение остановлено, так как у пользователя отсутствует активированная платная опция proxyServer:
<<EVENT download_stopped reason=missing_option option=proxyServer</nowiki></tt>
== Примеры ==
<tt>'''(>>'''</tt> - сообщения от клиента к TS Engine, движку <tt>'''<< '''</tt> - сообщения от TS Engine движка к клиенту)'''
Для загрузки содержимого торрента используется асинхронная команда LOADASYNC.
Торрент файл содержит один видео-файл.
рукопожатие
<tt>>>HELLOBGversion=3 <<HELLOTSversion=3.1.1 version_code=3003400 key=5eb1f78f http_port=6878</tt>
клиент готов принимать сообщения
<tt>>>READYkey=123456-fd2a247d83adffed56d82cca150d5fab225f1408</tt>
пользователю доступны расширенные функции
<tt><<AUTH 1</tt>
загрузить торрент по ссылке
<tt>>>LOADASYNC 467763 TORRENT http://rutor.org/download/67346 0 0 0
<<LOADRESP 467763 {"status": 1, "files": <nowiki>[["Prey%202_%20E3%202011%20Official%20Trailer_2.mp4", 0]]</nowiki>, "infohash":
"4c78e1cf0df23b4f5a16a106829ebed710cb52e0"}</tt>
узнать код плеера (например, чтобы показать его пользователю)
<tt>>>GETPID 4c78e1cf0df23b4f5a16a106829ebed710cb52e0 0 0 0
<<##36ae4c89ab45b4010b1461c513da38d007356195</tt>
начать пребуферизацию видео
<tt>>>START TORRENT http://rutor.org/download/67346 0 0 0 0</tt>
идет процесс пребуферизации
<tt><<STATE 1
<<STATUS main:prebuf;0;2147483447;0;0;0;0;0;0;0;0;0;0
пребуферизация завершена, клиент получает ссылку для проигрывания контента
<tt><<PLAY http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974
<<STATE 2</tt>
клиент отправляет длительность контента (~201 секунда)
<tt>>>DUR http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 201964</tt>
клиент информирует о том, что началось проигрывание
<tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 0</tt>
<tt><<STATUS main:dl;0;0;110;0;0;8;0;1622016;0;0
<<STATUS main:dl;0;0;128;0;0;8;0;2965504;0;0
<<STATUS main:dl;0;0;130;0;0;8;0;3129344;0;0</tt>
<tt><<PAUSE
<<STATE 3
буферизация завершена
<tt><<RESUME
<<STATE 2
клиент проиграл 25% контента
<tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 25
<<STATUS main:dl;0;0;141;0;0;8;0;4898816;0;0
клиент проиграл 50% контента
<tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 50
<<STATUS main:dl;0;0;145;0;0;7;0;9404416;0;0</tt>
клиент проиграл 75% контента
<tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 75
<<STATUS main:dl;0;0;146;0;0;7;0;9568256;0;0</tt>
остановить загрузку контента
<tt>>>STOP
<<STATE 0</tt>
разорвать соединение
<tt>>>SHUTDOWN
<<SHUTDOWN</tt>
===Ошибка запуска воспроизведения, отсутствует необходимая платная опция proxyServer===
<div id="example-missing-option-on-start"></div>
В этом примере описана ситуация, когда движок не может начать воспроизведение, так как для этого требуется наличие у пользователя активированной платной опции.
В случае отсутствия платной опции необходимо уведомить пользователя о необходимости приобрести данную опцию. Это может сделать либо клиент, либо движок. Если клиент хочет самостоятельно уведомить пользователя, он должен сообщить движку о готовности получать событие <tt>download_stopped</tt> с помощью команды <tt>SETOPTIONS</tt>. Если клиент этого не сделал, то движок самостоятельно уведомит пользователя (открыв окно либо страницу в браузере).
Первый пример описывает ситуацию, когда клиент не хочет уведомлять пользователя (в этом сценарии уведомление пользователю выдаст движок):
рукопожатие
<tt>>>HELLOBG version=3
<<HELLOTS version=3.1.1 version_code=3003400 key=5eb1f78f http_port=6878
>>READY key=123456-fd2a247d83adffed56d82cca150d5fab225f1408
<<AUTH 5</tt>
старт воспроизведения
<tt>>>START PID c894b23a65d64a0dae2076d2a01ec6bface83b01 0
<<STATE 1
<<STATUS main:starting</tt>
ошибка старта
<tt><<STATE 0
<<STATUS main:idle
<<STATUS main:err;0;You need to buy Proxy Server option to continue</tt>
Второй пример описывает ситуацию, когда клиент хочет уведомлять пользователя:
рукопожатие
<tt>>>HELLOBG version=3
<<HELLOTS version=3.1.1 version_code=3003400 key=5eb1f78f http_port=6878
>>READY key=123456-fd2a247d83adffed56d82cca150d5fab225f1408
<<AUTH 5
>>SETOPTIONS use_stop_notifications=1</tt>
старт воспроизведения
<tt>>>START PID c894b23a65d64a0dae2076d2a01ec6bface83b01 0
<<STATE 1
<<STATUS main:starting</tt>
ошибка старта
<tt><<EVENT download_stopped reason=missing_option option=proxyServer
<<STATE 0
<<STATUS main:idle</tt>
===Воспроизведение прервано, так как отсутствует необходимая платная опция proxyServer===
Этот сценарий отличается от предыдущего тем, что воспроизведение начинается, но через некоторое время после старта останавливается по причине отсутствия платной опции.
рукопожатие
<tt>>>HELLOBG version=3
<<HELLOTS version=3.1.1 version_code=3003400 key=5eb1f78f http_port=6878
>>READY key=123456-fd2a247d83adffed56d82cca150d5fab225f1408
<<AUTH 5
>>SETOPTIONS use_stop_notifications=1</tt>
старт воспроизведения
<tt>>>START PID c894b23a65d64a0dae2076d2a01ec6bface83b01 0
<<STATE 1
<<STATUS main:starting
<<STATUS main:prebuf;0;0;0;0;8;0;0;1;0;16384;0;0
<<START http://127.0.0.1:6878/content/6d12f958332ef0bd258053ba1afd833ddf9b74f9/0.289607197304 stream=1
<<STATE 2</tt>
некоторое время воспроизведения идет без остановки
<tt><<STATUS main:dl;0;0;832;0;0;1;0;2392064;0;0
<<EVENT livepos last=1448977939 live_first=1448976139 pos=1448977939 ↵
first_ts=1448976139 last_ts=1448977939 is_live=1 live_last=1448977939 buffer_pieces=15
<<STATUS main:dl;0;0;1339;0;8;3;0;5242880;0;65536
<<EVENT livepos last=1448977939 live_first=1448976139 pos=1448977939 ↵
first_ts=1448976139 last_ts=1448977939 is_live=1 live_last=1448977939 buffer_pieces=15
<<STATUS main:dl;0;0;1165;0;18;3;0;5767168;0;163840
<<EVENT livepos last=1448977941 live_first=1448976141 pos=1448977941 ↵
first_ts=1448976141 last_ts=1448977941 is_live=1 live_last=1448977941 buffer_pieces=15
<<STATUS main:dl;0;0;396;0;175;4;0;35127296;0;10534912
<<EVENT livepos last=1448978010 live_first=1448976210 pos=1448978010 ↵
first_ts=1448976210 last_ts=1448978010 is_live=1 live_last=1448978010 buffer_pieces=15</tt>
остановка воспроизведения
<tt><<EVENT download_stopped reason=missing_option option=proxyServer
<<STOP
<<STATE 0
<<STATUS main:idle
<<STATUS main:err;0;Download stopped</tt>