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 на указанный порт# если не получилось установить соединение - движок не запущен и его нужно запустить# обменяться рукопожатием и начать обмен сообщениями
Текущая версия API - 3
;''request_key'Примеры асинхронных команд':'''используется для авторизации клиента с помощью [[Product key|ключа продукта]]
После получения команды <tt>HELLOTS</tt> от движка клиент должен отослать такую команду:
<tt>READY key=''response_key''</tt>
То же самое должен делаь клиент при закрытии - если от TS Engine получено сообщение, которое начинается на ##, то данное сообщение считается ответом на синхронную перед закрытием отослать движку команду (например, ##12345)<tt>SHUTDOWN</tt>
==Сообщения==
== ВХОДЯЩИЕ КОМАНДЫ =Типы сообщений===Все сообщения условно делятся на две группы: команды и события.
Команды подразумевают выполнение какого-либо действия от принимающей стороны. Например, командой <tt>'''HELLOBG'''START</tt>клиент просит движок начать пребуферизацию указанного контента.
Для этих команд есть понятие ответа на команду. Ответ передается в виде строки, которая начинается на ##.
Алгоритм обработки синхронных команд такой:* клиент отправляет движку синхронную команду (например, <tt>'''READY'''GETCID 4c78e1cf0df23b4f5a16a106829ebed710cb52e0 0 0 0</tt>) и ждет данных от движка* когда от движка приходят данные, клиент проверяет, начинается ли полученный ответ на ## (например, <tt>##36ae4c89ab45b4010b1461c513da38d007356195</tt>)* если это так, то строка от символов ## до CRLF является ответом на синхронную команду (причем ответ может быть пустой, т.е. выглядеть так: <tt>##</tt>)* если нет, значит ответ на команду не может быть получен
Ответ на команду <tt>GETCID</tt> приходит практически мгновенно, поэтому ее использование не приводит к блокированию. Однако есть одно замечание по использованию данной команды:
Команду <tt>GETCID</tt> не следует отправлять, если движок находится в состоянии <tt>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>
;Параметры* <tt>'''request_id'''</tt> - : случайное целое число - идентификатор запроса LOADASYNC; этот же идентификатор будет отослан клиенту в команде LOADRESP после того,как будет получен список файлов; данный идентификатор служит для того, чтобы клиент в случае отправки нескольких запросов LOAD точно знал, на какой из этих запросов получен ответ
идентификатор служит для того, чтобы клиент в случае отправки нескольких запросов LOADASYNC точно знал, на какой из этих запросов получен ответ * <tt>'''torrent_url'url''</tt> - : ссылка на торрент транспортный файл (например, http* <tt>''infohash''</tt>: инфохеш транспортного файла* <tt>''data''</tt>:содержимое транспортного файла в кодировке base64* <tt>''content_id''</tt>: идентификатор контента в системе ACE Stream (Content ID)* <tt>''developer_id''</sometracker.comtt>: код разработчика (если неизвестно, необходимо передавать 0) * <tt>''affiliate_id''</torrenttt>: код партнера (если неизвестно, необходимо передавать 0) * <tt>''zone_id''</12345tt>: код зоны партнера (если неизвестно, необходимо передавать 0)
;Формат ответа:Ответ приходит в формате JSON со следующими полями:* <tt>''status'torrent_infohash'</tt>:** 0 - транспортный файл не содержит аудио/видео файлов** 1 - транспортный файл содержит один аудио/видео файл** 2 - транспортный файл содержит более одного аудио/видео файла** 100 - ошибка получения данных* <tt>''files''</tt> : список файлов/потоков; это массив, каждый элемент в котором состоит из массива из двух элементов: первый - название файла, второй - infohash торрентапозиция в транспортном файле (эта позиция
должна отправляться в команде <tt>START</tt> для указания, какой именно файл необходимо загружать, если их несколько)* <tt>''infohash''</tt>: инфохеш транспортного файла* <tt>'player_id'checksum''</tt> - код плеера: хешсумма транспортного файла
:Параметры <tt>''infohash'torrent_data'</tt> и <tt>''checksum''</tt> - содержимое торрент-файла клиенту нужны для того, чтобы в кодировке base64дальнейшем получить Content ID с помощью команды <tt>GETCID</tt>
;Пример: <tt>'''affiliate_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''</tt> : ссылка на транспортный файл* <tt>''infohash''</tt>: инфохеш транспортного файла* <tt>''content_id''</tt>: идентификатор контента в системе ACE Stream (Content ID)* <tt>''data''</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)
Если необходимо в параметрах передать ссылку на файл, который находится в локальной файловой системе, следует использовать формат file:///path/to/file.
;Примеры: <tt>'''START TORRENT''' <torrent_urlnowiki> <file_indexesНачать проигрывание по ссылке на транспортный файл:> <developer_id> <affiliate_id> <zone_id>START TORRENT http://rutor.org/download/67346 0 0 0 0
======<span id="transcode_settings"></span>Настройки транскодирования======Начиная с версии 3.1.5 есть возможность задавать формат вывода потока и параметры транскодирования аудио. * <tt>''output_format=hls|http''</tt>: формат вывода потока* <tt>'START RAW'transcode_audio=0|1'' <torrent_data/tt> : транскодировать все аудио в AAC* <file_indexestt> ''transcode_mp3=0|1''<developer_id/tt> : транскодировать MP3 (данная опция применима только если transcode_audio=1)* <affiliate_idtt> ''transcode_ac3=0|1''<zone_id/tt>: транскодировать только AC3 в AAC (данная опция применима только если transcode_audio=0)
Запустить в формате HLS, транскодировать все аудио-кодеки, кроме MP3, в AAC:>> START PID 1ccf192064ee2d95e91a79f91c6097273d582827 0 output_format=hls transcode_audio=1 transcode_mp3=0<tt/nowiki>'''file_indexes'''</tt> - список индексов файлов из торрент-файла, которые необходимо загружать. Индексы файлов клиент получает в сообщении LOADRESP разделенных запятой. Индексы начинаются с нуля и соответствуют списку файлов,который был получен в результате выполнения команды LOAD. Например, если в торрент-файле всего один видео-файл, то необходимо отправлять индекс 0.
;Синтаксис <tt>'''torrent_url'''STOP</tt> - ссылка на торрент файл (например, http://sometracker.com/torrent/12345)
;Пример: <tt>'''player_id'''<nowiki>>>STOP</nowiki></tt> - код плеера
=====<ttstyle="color: #009;">'''torrent_data'''GETPID</tt>=====;Версия API:1 Эта команда устарела и больше не используется. Вместо нее следует использовать команду <tt>GETCID</tt> - содержимое торрент-файла в кодировке base64
=====<ttstyle="color: #009;">'''direct_url'''GETCID</tt> - прямая ссылка на файл (например, http=====;Версия API://somesite.com/files/video.mp4)>= 2
;Синтаксис <tt>GETCID checksum=''checksum'' infohash=''infohash'' developer=''developer_id'' affiliate=''affiliate_id'' zone=''zone_id''</tt> - код партнера (если неизвестно, необходимо передавать 0)
;Параметры* <tt>''checksum''</tt>: хешсумма транспортного файла (значение клиент из команды LOADRESP)* <tt>''infohash''</tt>: инфохеш транспортного файла (значение клиент из команды LOADRESP)* <tt>''developer_id''</tt>: код разработчика (если неизвестно, необходимо передавать 0 либо не передавать данный параметр) * <tt>''affiliate_id''</tt>: код партнера (если неизвестно, необходимо передавать 0 либо не передавать данный параметр) * <tt>''zone_id'''</tt> - : код зоны партнера (если неизвестно, необходимо передавать 0либо не передавать данный параметр)
;Пример:
<tt><nowiki>>>GETCID infohash=bc57456ca38b365477e07fa7e912693a7adc57da checksum=888e9891f82a045ea639256b468041fb8c9ac315 developer=0 affiliate=0 zone=0
<<##68dba76ad7d0b9992581bf72f7835a0de4f84234</nowiki></tt>
=====<ttstyle="color: #009;">'''GETPID''' <infohash> <developer_id> <affiliate_id> <zone_id>GETADURL</tt>=====;Версия API:>= 3
;Синтаксис
<tt>GETADURL width=''width'' height=''height'' infohash=''infohash'' action=''action''</tt>
;Параметры* <tt>''width'SHUTDOWN'</tt>: ширина видео окна клиента (в пикселях)* <tt>''height''</tt>: высота видео окна клиента (в пикселях)* <tt>''infohash''</tt>: infohash текущего контента (значение клиент получает из сообщения LOADRESP)* <tt>''action''</tt>: описание события, возможные значения:** <tt>load</tt> - загрузка (клиент загрузился, готов к проигрыванию, но пользователь еще не начала проигрывание)** <tt>pause</tt> - пользователь нажал паузу
=====<tt style="color: #009;">USERDATA</tt>=====
;Версия API
:>= 3
;Параметры
* <tt>''gender_id''</tt>: пол пользователя. Возможные значения:
** 1 - мужчина
** 2 - женщина
* <tt>''age_id''</tt>: возрастная группа пользователя. Возможные значения:
** 1 - младше 13 лет
** 2 - 13-17
** 3 - 18-24
** 4 - 25-34
** 5 - 35-44
** 6 - 45-54
** 7 - 55-64
** 8 - старше 64
;Пример: <tt>'''DUR''' <video_urlnowiki> мужчина, от 18 до 24 лет:>>USERDATA [{"gender": 1}, {"age": 3}]<duration/nowiki></tt>
;Синтаксис <tt>SAVE infohash=''infohash'video_url'index=''index'' path=''path''</tt> - ссылка на видео, которая была отправлена клиенту после окончания пребуферизации
;Параметры* <tt>''infohash'duration'</tt> - infohash контента, который неободимо сохранить (значение клиент получает из сообщения <tt>EVENT cansave</tt>)* <tt>''index''</tt> - длительность индекс файла, который необходимо сохранить (значение клиент получает из сообщения <tt>EVENT cansave</tt>)* <tt>''path''</tt> - абсолютный путь к файлу, в который необходимо сохранить контент. Если указанный файл не существует, он будет создан. Если существует, файл будет перезаписан. Путь должен передаваться в виде urlencoded строки в миллисекундахкодировке UTF-8.
;Пример:
<tt><nowiki>Сохранить файл с индексом 0 в папку d:\media под названием sintel-1024-surround.mp4
>>SAVE infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 index=0 path=D%3A%2Fmedia%2Fsintel-1024-surround.mp4</nowiki></tt>
=====<ttstyle="color: #009;">'''PLAYBACK''' <video_url> <event>LIVESEEK</tt>=====Описание скоро будет
;Пример: <tt>'''event'''<nowiki>>>SHUTDOWN</nowiki></tt> - одно из данных событий:
;Пример:
<tt><nowiki>>>SETOPTIONS use_stop_notifications=1</nowiki></tt>
== ИСХОДЯЩИЕ КОМАНДЫ ==Команды от движка к клиенту=========<tt style="color: #009;">PLAY, PLAYAD, PLAYADI</tt>=====;Версия API:1 Эти команды устарели и больше не используется. Вместо них следует использовать команду <tt>START</tt>
=====<ttstyle="color: #009;">'''HELLOTS'''START</tt>=====;Версия API:>= 2
обрабатывается http-серверов, встроенным в движок.
;Синтаксис <tt>START ''url'AUTH'[ad=1 [interruptable=1]] [stream=1] [pos='' <auth_level>position'']</tt>
Начать проигрывание непрерываемого рекламного ролика:<<START http://127.0.0.1:6878/content/6081f31fe7f1db2ea7183686b46ba382820df574/0 - пользователю не доступны расширенные функции (перемотка и проигрывание файлов из торрента с несколькими видео-файлами).456623456572 ad=1
Начать проигрывание прерываемого рекламного ролика:<<START http://127.0.0.1:6878/content/6081f31fe7f1db2ea7183686b46ba382820df574/0.456623456572 ad=1 interruptable=1 - пользователю доступны расширенные функции
Начать проигрывание live:
<<START http://127.0.0.1:6878/content/553b7d4cfec8974752d386844cb67e0ee64eae05/0.728180367195 stream=1
Начать проигрывание с середины (50%):<tt>'''STATE''' <state_idSTART http://127.0.0.1:6878/content/5410b27fc567c35c8547e3b69b141215ce3a1fd7/0.828180567196 pos=50</nowiki></tt>
;Описание
:Движок начал буферизацию, клиент по возможности должен остановиться на паузу до получения команды <tt>RESUME</tt>
;Синтаксис <tt>'''SHUTDOWN'''PAUSE</tt>
;Пример:
<tt><nowiki><<PAUSE</nowiki></tt>
=====<ttstyle="color: #009;">'''PLAY''' <video_url>RESUME</tt>=====;Версия API:>= 1
;Синтаксис <tt>'''PLAYADI''' <video_url>RESUME</tt>
;Пример: <tt>'''PLAY'''<nowiki><<RESUME</nowiki></tt> - проигрывание основного видео
=====<ttstyle="color: #009;">'''PLAYAD'''STOP</tt> - проигрывание непрерываемого рекламного ролика (пользователь не может перемотать либо пропустить данный рекламный ролик)=====;Версия API:>= 1
;Синтаксис
<tt>STOP</tt>
=====<tt style="color: #009;">SHUTDOWN</tt>=====
;Версия API
:>= 1
;Параметры
:нет
;Пример: <tt>'''LOADRESP''' <request_idnowiki> <response<SHUTDOWN</nowiki></tt>
События <tt>'''response'''DUR</tt> и <tt>PLAYBACK</tt> необходимо отправлять только для VOD- список файлов в формате json в такого вида: { "status": 1, "infohash": "abcd1234", "files": [ ["file1.mp4", 0], ["file2.avi", 1], ["file3контента (так как live не имеет длительности).mkv", 5] ] }
Отправка данных событий является обязательной только при воспроизведении рекламных роликов (когда получена команда <tt>'''status'''START</tt> - 0: в торренте нет видео файлов, с параметром 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_progressSTATUS main:''status_description''</tt> Если идет проигрывание рекламного ролика (рекламный ролик и основной контент описываются отдельно;immediate_progress;speed_down;http_speed_down;speed_up;peers;http_peers;downloaded;http_downloaded;uploadedнапример, рекламный ролик уже полность загружен, а основной контент проходит стадию пребуферизации): <tt>STATUS main:''status_description''|ad:''status_description''</tt>
;Возможные значения <tt>''status_description:''</tt>* движок ничего не делает - <tt>'total_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>'''immediate_progress'''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 ''user_auth_level''</tt>
;Параметры
* <tt>''user_auth_level''</tt>: уровень доступа пользователя
;Пример:
<tt><nowiki>Пользователь не зарегистрирован:
<<AUTH 0
Пользователь зарегистрирован:
<<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>=====Описание скоро будет
=====<ttstyle="color: #009;">'''EVENT event_name param1_name=param1_value param2_name=param2_value ...'''download_stopped</tt>=====;Версия движка:>= 3003600
;Параметры
* <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>
