Difference between revisions of "Engine API"

Latest revision as of 11:18, 3 September 2018

Общие понятия

ACE Stream Engine (далее - "движок") - приложение, которое обеспечивает весь функционал системы ACE Stream. Данное приложение работает в фоновом режиме и имеет минимальный графический интерфейс для изменения различных настроек.

ACE Stream Engine API (далее - API) - программный интерфейс, позволяющий сторонним приложениям работать с движком. Под сторонними приложениями, как правило, подразумеваются медиа плееры, работающие с системой ACE Stream.

Клиент - стороннее приложение, которое работает с движком посредством API.

Схема работы API

Обмен данными с движком происходит по протоколу TCP. Общая схема работы выглядит так:

клиент устанавливает TCP-соединение с движком
клиент и движок обмениваются рукопожатиями
клиент и движок обмениваются сообщениями
одна из сторон завершает соединение

Установление соединения

Для установления соединения клиент должен знать порт, на котором работает API движка. Методы определения порта зависят от операционной системы, на которой запущен движок.

На Linux используется фиксированный порт: 62062

На Windows используется динамический порт. Движок после запуска создает файл acestream.port в директории, в которой находится сам движок (файл tsengine.exe), и записывает в данный файл порт, на котором работает API. Для того, чтобы узнать порт, клиент должен прочитать указанный файл. Отсутствие данного файла указывает на то, что движок в не запущен. Путь к папке, в которую устанавливается движок, можно считать из реестра:

HKEY_CURRENT_USER\Software\TorrentStream\EnginePath

Ключ EnginePath содержит абсолютный путь к исполняемому файлу движка (tsengine.exe). По умолчанию это %APPDATA%\TorrentStream\engine\tsengine.exe

Алгоритм установления соединения (Windows):

считать из реестра ключ HKEY_CURRENT_USER\Software\TorrentStream\EnginePath
1. если ключ отсутствует - движок не установлен
2. запомнить путь к исполняемому файлу движка (engine_path) и директории движка (engine_dir)
считать содержимое файла engine_dir/acestream.port и запомнить порт
если данный файл отсутствует - запустить движок, дождаться создания файла acestream.port и считать его содержимое
установить TCP-соединение на localhost на указанный порт
если не получилось установить соединение - движок не запущен и его нужно запустить
обменяться рукопожатием и начать обмен сообщениями

Алгоритм установления соединения (Linux):

установить TCP-соединение на localhost на порт 62062
если не получилось установить соединение - движок не запущен и его нужно запустить (/usr/bin/acestreamengine-client-gtk)
обменяться рукопожатием и начать обмен сообщениями

Рукопожатие

После установления соединения клиент и движок должны обменяться рукопожатием:

клиент отсылает сообщение

HELLOBG version=api_version

движок отсылает в ответ

HELLOTS version=engine_version version_code=version_code key=request_key http_port=http_port

Каждое сообщение должно завершаться символами перевода строки CRLF (\r\n)

api_version: версия API, которую поддерживает клиент. Этот параметр служит для поддержки обратной совместимости новых версий движка со старыми клиентами. Если клиент не указал версию, по умолчанию используется версия 1. Для всех сообщений API в документации указано, начиная с какой версии они поддерживаются.

Текущая версия API - 3

engine_version: версия движка (например, 2.0.8)

version_code: цифровой код версии движка (например, 3003400); клиент должен использовать этот код для сравнения версий движка; код каждой новой версии всегда больше всех кодов предыдущих версий

request_key: используется для авторизации клиента с помощью ключа продукта

http_port: порт, на котором работает встроенный HTTP сервер движка

Если клиент в течение некоторого времени после отправки рукопожатия не получил ответ, соединение необходимо завершить.

После получения команды HELLOTS от движка клиент должен отослать такую команду:

READY key=response_key

Формирование response_key описано здесь.

Обмен сообщениями

Каждое сообщение представляет собой ASCII-строку, которая завершается символами перевода строки CRLF (\r\n)

Примерный алгоритм приема сообщений выглядит таким образом:

клиент в цикле ждет поступления данных по TCP-соединению
при получении данных они добавляются в буфер
клиент проверяет, есть ли в буфере символы CRLF. Если есть, то из буфера вырезается сообщение (строка от начала буфера до символов CRLF) и отправляется в обработчик сообщений
клиент должен учитывать возможность получения нескольких сообщений одновременно (т.е. повторять предыдущий шаг, пока в буфере не будет символов CRLF)

Завершение соединения

Движок при завершении работы отправляет команду SHUTDOWN и закрывает сокет. При получении данной команды клиент должен прекратить обработку команд и закрыть свой сокет.

То же самое должен делаь клиент при закрытии - перед закрытием отослать движку команду SHUTDOWN

Сообщения

Типы сообщений

Все сообщения условно делятся на две группы: команды и события.

Команды подразумевают выполнение какого-либо действия от принимающей стороны. Например, командой START клиент просит движок начать пребуферизацию указанного контента.

События носят информационный характер. Например, событие STATUS информирует клиента о статусе загрузки (идет ли в данный момент пребуферизация, буферизация, какая скорость загрузки и т.д.)

Синхронные команды

Практически все команды являются асинхронными, т.е. не предполагают наличие ответа от другой стороны.

Исключением являются две команды:

LOAD (сихронная загрузка информации о потоке)
GETCID (получение Content ID для потока)

Для этих команд есть понятие ответа на команду. Ответ передается в виде строки, которая начинается на ##.

Алгоритм обработки синхронных команд такой:

клиент отправляет движку синхронную команду (например, GETCID 4c78e1cf0df23b4f5a16a106829ebed710cb52e0 0 0 0) и ждет данных от движка
когда от движка приходят данные, клиент проверяет, начинается ли полученный ответ на ## (например, ##36ae4c89ab45b4010b1461c513da38d007356195)
если это так, то строка от символов ## до CRLF является ответом на синхронную команду (причем ответ может быть пустой, т.е. выглядеть так: ##)
если нет, значит ответ на команду не может быть получен

Мы не рекомендуем использовать синхронную команду LOAD, так как она подразумевает блокирование потока на стороне клиента.
Эта команда является устаревшей и вместо нее следует использовать асинхронную версию LOADASYNC

Ответ на команду GETCID приходит практически мгновенно, поэтому ее использование не приводит к блокированию. Однако есть одно замечание по использованию данной команды:

Команду GETCID не следует отправлять, если движок находится в состоянии starting

Список сообщений

В примерах сообщения от клиента к движку отмечены >>, от движка к клиенту - <<

Команды от клиента к движку

`READY`

Версия API: >= 1

Описание: Информирует движок о том, что клиент готов принимать команды. Это должна быть первая команда после рукопожатия.

Синтаксис

READY

Параметры: нет

Пример

>>READY

`LOADASYNC`

Версия API: >= 1

Описание: Получить описание контента по идентификатору. Идентификатором может быть content id, ссылка на транспортный файл (.torrent, .acelive), инфохеш транспортного файла и т.п. Описание представляет

собой список названий файлов либо потоков, которые содержатся в транспортном файле. Основное назначение этой команды - возможность сформировать и показать пользователю плейлист.

Синтаксис

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

Параметры

request_id: случайное целое число - идентификатор запроса LOADASYNC; этот же идентификатор будет отослан клиенту в команде LOADRESP после того,как будет получен список файлов; данный

идентификатор служит для того, чтобы клиент в случае отправки нескольких запросов LOADASYNC точно знал, на какой из этих запросов получен ответ

url: ссылка на транспортный файл
infohash: инфохеш транспортного файла
data: содержимое транспортного файла в кодировке base64
content_id: идентификатор контента в системе ACE Stream (Content ID)
developer_id: код разработчика (если неизвестно, необходимо передавать 0)
affiliate_id: код партнера (если неизвестно, необходимо передавать 0)
zone_id: код зоны партнера (если неизвестно, необходимо передавать 0)

Формат ответа: Ответ приходит в формате JSON со следующими полями:

status:
- 0 - транспортный файл не содержит аудио/видео файлов
- 1 - транспортный файл содержит один аудио/видео файл
- 2 - транспортный файл содержит более одного аудио/видео файла
- 100 - ошибка получения данных
files: список файлов/потоков; это массив, каждый элемент в котором состоит из массива из двух элементов: первый - название файла, второй - позиция в транспортном файле (эта позиция

должна отправляться в команде START для указания, какой именно файл необходимо загружать, если их несколько)

infohash: инфохеш транспортного файла
checksum: хешсумма транспортного файла

Параметры infohash и checksum клиенту нужны для того, чтобы в дальнейшем получить Content ID с помощью команды GETCID

Названия файлов возвращаются в виде urlencoded строк в кодировке UTF-8

Пример

Загрузить контент по Content ID:
>>LOADASYNC 126500 PID 1ccf192064ee2d95e91a79f91c6097273d582827

В ответ клиент получает от движка:
<<LOADRESP 126500 {
  "status": 1,
  "files": [["sintel-1024-surround.mp4", 0]],
  "infohash": "5410b27fc567c35c8547e3b69b141215ce3a1fd7",
  "checksum": "504275dd71a32d51c63c45ced37807751f5ccfa2"
}

`START`

Версия API: >= 1

Описание: Начать проигрывание указанного контента

Синтаксис

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

Параметры

url: ссылка на транспортный файл
infohash: инфохеш транспортного файла
content_id: идентификатор контента в системе ACE Stream (Content ID)
data: содержимое транспортного файла в кодировке base64
direct_url: прямая http-ссылка на контент (для проигрывания без транспортного файла)
efile_url: ссылка на acemedia-файл (зашифрованный медиа-файл, который можно воспроизвести с помощью ПО ACE Stream)
file_indexes: список индексов файлов из торрент-файла, которые необходимо загружать. Индексы файлов клиент получает в сообщении LOADRESP разделенных запятой. Индексы начинаются с нуля и соответствуют списку файлов, который был получен в результате выполнения команды LOAD. Например, если в торрент-файле всего один видео-файл, то необходимо отправлять индекс 0.
developer_id: код разработчика (если неизвестно, необходимо передавать 0)
affiliate_id: код партнера (если неизвестно, необходимо передавать 0)
zone_id: код зоны партнера (если неизвестно, необходимо передавать 0)
stream_id: номер потока для multi-stream файлов (значение клиент получает из сообщения LOADRESP)

Если необходимо в параметрах передать ссылку на файл, который находится в локальной файловой системе, следует использовать формат file:///path/to/file.

Примеры

Начать проигрывание по ссылке на транспортный файл:
>>START TORRENT http://rutor.org/download/67346 0 0 0 0

Начать проигрывание по Content ID:
START PID 1ccf192064ee2d95e91a79f91c6097273d582827 0

Начать проигрывание acemedia-файла c:\acestream\test.acemedia:
START EFILE file%3A%2F%2F%2Fc%3A%5Cacestream%5Ctest.acemedia

Настройки транскодирования

Начиная с версии 3.1.5 есть возможность задавать формат вывода потока и параметры транскодирования аудио.

output_format=hls|http: формат вывода потока
transcode_audio=0|1: транскодировать все аудио в AAC
transcode_mp3=0|1: транскодировать MP3 (данная опция применима только если transcode_audio=1)
transcode_ac3=0|1: транскодировать только AC3 в AAC (данная опция применима только если transcode_audio=0)

В версии 3.1.5 данные настройки касаются только live-потоков.

Если оригинал потока вещается в формате HLS, то формат вывода будет HLS независимо от настроек.

Настройки транскодирования аудио влияют только на выдачу в формате HLS (по HTTP всегда выдается оригинальный поток)

Если настройки формата вывода или транскодирования не передаются в команде START, то используются настройки, заданные пользователем на движке

Примеры

Запустить в формате HLS:
>> START PID 1ccf192064ee2d95e91a79f91c6097273d582827 0 output_format=hls

Запустить в формате HLS, транскодировать все аудио-кодеки в AAC:
>> START PID 1ccf192064ee2d95e91a79f91c6097273d582827 0 output_format=hls transcode_audio=1 transcode_mp3=1

Запустить в формате HLS, транскодировать все аудио-кодеки, кроме MP3, в AAC:
>> START PID 1ccf192064ee2d95e91a79f91c6097273d582827 0 output_format=hls transcode_audio=1 transcode_mp3=0

`STOP`

Версия API: >= 1

Описание: Остановить воспроизведение и загрузку

Синтаксис

STOP

Параметры: нет

Пример

>>STOP

`GETPID`

Версия API: 1

Эта команда устарела и больше не используется. Вместо нее следует использовать команду GETCID

`GETCID`

Версия API: >= 2

Описание: Получение кода плеера по набору параметров. Эта команда является синхронной командой (см.ниже). В ответ отправляется код плеера, либо пустая строка, если код плеера не может быть получен

Синтаксис

GETCID checksum=checksum infohash=infohash developer=developer_id affiliate=affiliate_id zone=zone_id

Параметры

checksum: хешсумма транспортного файла (значение клиент из команды LOADRESP)
infohash: инфохеш транспортного файла (значение клиент из команды LOADRESP)
developer_id: код разработчика (если неизвестно, необходимо передавать 0 либо не передавать данный параметр)
affiliate_id: код партнера (если неизвестно, необходимо передавать 0 либо не передавать данный параметр)
zone_id: код зоны партнера (если неизвестно, необходимо передавать 0 либо не передавать данный параметр)

Пример

>>GETCID infohash=bc57456ca38b365477e07fa7e912693a7adc57da checksum=888e9891f82a045ea639256b468041fb8c9ac315 developer=0 affiliate=0 zone=0
<<##68dba76ad7d0b9992581bf72f7835a0de4f84234

`GETADURL`

Версия API: >= 3

Описание: Запрос к движку на получение ссылки на рекламную страницу. Данную команду могут использовать клиенты, которые имеют возможность отображать встроенный браузер в плеере, для того, чтобы показывать пользователям рекламу перед началом проигрывания контента либо когда пользователь нажимает паузу. Если движок определит, что есть доступная к показу реклама, то после получения этой команды отправит клиенту событие EVENT showurl

Синтаксис

GETADURL width=width height=height infohash=infohash action=action

Параметры

width: ширина видео окна клиента (в пикселях)
height: высота видео окна клиента (в пикселях)
infohash: infohash текущего контента (значение клиент получает из сообщения LOADRESP)
action: описание события, возможные значения:
- load - загрузка (клиент загрузился, готов к проигрыванию, но пользователь еще не начала проигрывание)
- pause - пользователь нажал паузу

Примеры

>>GETADURL width=1328 height=474 infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 action=load
>>GETADURL width=1328 height=474 infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 action=pause

`USERDATA`

Версия API: >= 3

Описание: Данная команда используется для передачи движку информации о пользователе. Информация передается в формате JSON.

Синтаксис

USERDATA [{"gender": gender_id}, {"age": age_id}]

Параметры

gender_id: пол пользователя. Возможные значения:
- 1 - мужчина
- 2 - женщина
age_id: возрастная группа пользователя. Возможные значения:
- 1 - младше 13 лет
- 2 - 13-17
- 3 - 18-24
- 4 - 25-34
- 5 - 35-44
- 6 - 45-54
- 7 - 55-64
- 8 - старше 64

Пример

мужчина, от 18 до 24 лет:
>>USERDATA [{"gender": 1}, {"age": 3}]

`SAVE`

Версия API: >= 2

Описание: Сохранить контент в указанном месте.

Синтаксис

SAVE infohash=infohash index=index path=path

Параметры

infohash - infohash контента, который неободимо сохранить (значение клиент получает из сообщения EVENT cansave)
index - индекс файла, который необходимо сохранить (значение клиент получает из сообщения EVENT cansave)
path - абсолютный путь к файлу, в который необходимо сохранить контент. Если указанный файл не существует, он будет создан. Если существует, файл будет перезаписан. Путь должен передаваться в виде urlencoded строки в кодировке UTF-8.

Пример

Сохранить файл с индексом 0 в папку d:\media под названием sintel-1024-surround.mp4
>>SAVE infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 index=0 path=D%3A%2Fmedia%2Fsintel-1024-surround.mp4

`LIVESEEK`

Описание скоро будет

`SHUTDOWN`

Версия API: >= 1

Описание: Клиент завершил работу

Синтаксис

SHUTDOWN

Параметры: нет

Пример

>>SHUTDOWN

`SETOPTIONS`

Версия движка: >= 3003600

Описание: Сообщить движку о наборе опций, которые поддерживает клиент

Синтаксис

SETOPTIONS name1=value1 [name2=value2 ...]

Параметры: name - название опции; value - значение опции

Список опций: use_stop_notifications - клиент хочет получать от движка событие download_stopped с причиной остановки во время проигрывания

Пример

>>SETOPTIONS use_stop_notifications=1

Команды от движка к клиенту

`PLAY, PLAYAD, PLAYADI`

Версия API: 1

Эти команды устарели и больше не используется. Вместо них следует использовать команду START

`START`

Версия API: >= 2

Описание: Начать прогрывание контента. Эта команда отправляется после завершения пребуферизации. Движок отсылает плееру http-ссылку, по которой плеер может начать проигрывание контента. Данная ссылка

обрабатывается http-серверов, встроенным в движок.

Синтаксис

START url [ad=1 [interruptable=1]] [stream=1] [pos=position]

Параметры

url: ссылка для проигрывания
ad=1: флаг, указывающий на то, что ссылка url ведет на рекламный видеоролик, который клиент должен проиграть перед началом воспроизведения основного контента
interruptable=1: флаг, указывающий на то, что должен проиграться прерываемый рекламный ролик
stream=1: флаг, указывающий на то, что проигрываемый контент является живой трансляцией (Live Stream).
position: целое число от 0 до 100, которое указывает с какой позиции клиент должен начать проигрывание (например, position=50 означает, что клиент должен начать проигрывание с

позиции 50%, т.е. с середины контента)

Примеры

Начать проигрывание контента по указанной ссылке:
<<START http://127.0.0.1:6878/content/5410b27fc567c35c8547e3b69b141215ce3a1fd7/0.628180567194

Начать проигрывание непрерываемого рекламного ролика:
<<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%):
<<START http://127.0.0.1:6878/content/5410b27fc567c35c8547e3b69b141215ce3a1fd7/0.828180567196 pos=50

`PAUSE`

Версия API: >= 1

Описание: Движок начал буферизацию, клиент по возможности должен остановиться на паузу до получения команды RESUME

Синтаксис

PAUSE

Параметры: нет

Пример

<<PAUSE

`RESUME`

Версия API: >= 1

Описание: Движок завершил буферизацию, клиент может продолжить воспроизведение.

Синтаксис

RESUME

Параметры: нет

Пример

<<RESUME

`STOP`

Версия API: >= 1

Описание: Клиент должен остановить воспроизведение контента

Синтаксис

STOP

Параметры: нет

Пример

<<STOP

`SHUTDOWN`

Версия API: >= 1

Описание: Движок завершил работу

Синтаксис

SHUTDOWN

Параметры: нет

Пример

<<SHUTDOWN

События от клиента к движку

События DUR и PLAYBACK необходимо отправлять только для VOD-контента (так как live не имеет длительности).

Отправка данных событий является обязательной только при воспроизведении рекламных роликов (когда получена команда START с параметром ad=1). См. примечание к событию PLAYBACK.

При воспроизведении обычных VOD клиент не обязан отправлять данные события.

`DUR`

Версия API: >= 1

Описание: Сообщить движку о длительности контента, который в данный момент проигрывается клиентом. Данная команда должна отправлять сразу после того, как клиент определил длительность контента.

Синтаксис

DUR video_url duration

Параметры

video_url: ссылка на видео, которая была отправлена клиенту после окончания пребуферизации в команде START
duration: длительность в миллисекундах

Пример

Клиент определить длительность контента: 3780 секунд:
>>DUR http://127.0.0.1:6878/content/5b5ba8c462f4014d8b57377c97d2e13caee52cdd/0.685119063624 3780000

`PLAYBACK`

Версия API: >= 1

Описание: Сообщить движку о прогрессе проигранного контента (сколько процентов проигралось).; Данная команда особенно важна, когда идет прогрывание рекламных роликов - переход к основному контенту происходит только после того, как движок получил команду PLAYBACK 100 (т.е. после того, как клиент полностью проиграл рекламный ролик)

Синтаксис

PLAYBACK video_url event

Параметры

video_url: ссылка на видео, которая была отправлена клиенту после окончания пребуферизации в команде START
event: одно из указанных событий:
- 0: начало проигрывания
- 25: проиграно 25% видео
- 50: проиграно 50% видео
- 75: проиграно 75% видео
- 100: проиграно 100% видео (воспроизведение завершено)

Пример

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

`EVENT`

Версия API: >= 3

Описание: Отправка событий движку. С помощью этого сообщения клиент может отправлять движку события, касающиеся действий пользователя относительно воспроизведения контента (поставил на паузу, перемотал и т.п.). Отправка данных событий не обязательна - клиент может их не отправлять при отсутствии технический возможности.

Синтаксис

EVENT event_name [param1=value1 [param2=value2] ...]

Параметры

event_name: название события. Возможные значения:
- play - начало воспроизведения либо продолжение после паузы
- pause - пользователь поставил воспроизведение на паузу
- stop - остановка воспроизведения
- seek - пользователь осуществил перемотку. Для этого события необходимо отправлять параметр position, в котором указывается позиция в секундах

Примеры

>>EVENT play
>>EVENT pause
>>EVENT seek position=1487
>>EVENT stop

События от движка к клиенту

`STATE`

Версия API: >= 1

Описание: Информация о текущем статусе движка

Синтаксис

STATE state_id

Параметры

state_id: состояние движка:
- 0 (IDLE) - движок ничего не делает
- 1 (PREBUFFERING) - началась пребуферизация
- 2 (DOWNLOADING) - идет загрузка контента в обычном режиме
- 3 (BUFFERING) - началась буферизация
- 4 (COMPLETED) - загрузка контента завершена
- 5 (CHECKING) - выполняется инициализация перед началом загрузки
- 6 (ERROR) - ошибка

Пример

<<STATE 0

`INFO`

Версия API: >= 1

Описание: Отобразить текстовое сообщение пользователю.

Синтаксис

INFO message_id;message_text

Параметры

message_id: числовой идентификатор сообщения
- 1: сообщение "На данный момент нет активных пиров" (отправляется в том случае, если в течение минуты после начала загрузки не удалось найти ни одного пира)
- 2: сообщение "Рекламный блок" (отправляется после начала воспроизведения рекламного ролика).
- 3: сообщение "Основной контент" (отправляется после начала воспроизведения основного контента).
- 0: другое сообщение (текст сообщения берется из параметра message_text)
message_text: текст сообщения, которое необходимо отобразить

Пример

<<INFO 1;Cannot find active peers
<<INFO 2;Advertising video
<<INFO 3;Main content
<<INFO 0;Display some message

`STATUS`

Версия API: >= 1

Описание: Данное сообщение отправляется периодически для информирования клиента о текущем статусе загрузки контента. Основное назначение этого сообщение - дать клиенту возможность отображать пользователю о том, что сейчас происходит на движке.

Синтаксис

STATUS status_string

Параметры

status_string - строка описанного ниже формата

Если идет проигрывание основного контента

STATUS main:status_description

Если идет проигрывание рекламного ролика (рекламный ролик и основной контент описываются отдельно; например, рекламный ролик уже полность загружен, а основной контент проходит стадию пребуферизации):

STATUS main:status_description|ad:status_description

Возможные значения status_description:

движок ничего не делает - idle
движок загружает транспортный файл (обрабатывает команду LOADASYNC) - loading
движок выполняет предварительную инициализацию воспроизведения (движок переходит в это состояние после получения команды START от клиента) - starting
ошибка - err;error_id;error_message (код и описание)
проверка - check;progress
пребуферизация - prebuf;progress;time
контент загружается либо уже полностью загружен - dl
буферизация - buf;progress;time
ожидание достаточной скорости - wait;time

Ко всем status_string (кроме idle, loading, starting, err, check) добавляются общие данные:

total_progress;immediate_progress;speed_down;http_speed_down;speed_up;peers;http_peers;downloaded;http_downloaded;uploaded

total_progress - сколько всего закачано по данному файлу
immediate_progress - сколько непрерывных данных закачано начиная с текущей позиции (для отображения кол-ва закачанного в бегунке)
speed_down - скорость загрузки (Кбайт/с)
http_speed_down - скорость загрузки от прямых http-источников (Кбайт/с)
speed_up - скороть отдачи (Кбайт/с)
peers - количество подсоединенных пиров
http_peers - количество подсоединенных прямых http-источников
downloaded - объем загруженных данных (байт)
http_downloaded - объем загруженных по http данных (байт)
uploaded - объем отданных данных (байт)

Все числа передаются как integer.

Все progress принимают значение от 0 до 100.

Примеры

Движок ничего не делает:
<<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

Идет загрузка контента, загружен 1%, скорость загрузки 442 Кбайт/с, подсоединено 10 пиров, загружено 13920256:
<<STATUS main:dl;1;0;442;0;0;10;0;13920256;0;0

Рекламный ролик полность загружен и воспроизводится, основной контент пребуферизируется (20%):
<<STATUS main:prebuf;20;2723;0;0;328;0;0;7;0;5505024;0;0|ad:dl;100;0;0;0;0;0;0;13920256;0;0

Пример трансформации статусов в текстовые сообщения, понятные пользователю

check - Проверка xx%
prebuf - Пребуферизация xx%
buf - Буферизация xx%
wait - Ожидание достаточной скорости
err - выводим сообщение об ошибке
loading - Загрузка...
starting - Запуск...
dl, idle - ничего не выводим

`AUTH`

Версия API: >= 1

Описание: Уровень доступа пользователя

Синтаксис

AUTH user_auth_level

Параметры

user_auth_level: уровень доступа пользователя

Пример

Пользователь не зарегистрирован:
<<AUTH 0

Пользователь зарегистрирован:
<<AUTH 1

`EVENT getuserdata`

Версия API: >= 3

Описание: Движок запрашивает у клиента данные пользователя (пол и возрастную группу). Такой запрос приходит при попытке что-либо проиграть, если данные о пользователе не были переданы ранее (т.е. фактически при первом после установки просмотре в ответ на команду START).; При получении этого события клиент должен запросить данные у пользователя, затем отправить их движку командой USERDATA и начать воспроизведение командой START

Синтаксис

EVENT getuserdata

Параметры: нет

Пример

<<EVENT getuserdata

`EVENT cansave`

Версия API: >= 2

Описание: Данное событие информирует клиента о том, что контент может быть сохранен на диске в указанном пользователем месте. Например, при получении данного события клиент может отобразить кнопку "Сохранить" в пользовательском интерфейсе. При нажатии на кнопку пользователь должен будет выбрать, куда сохранять контент, после чего клиент отправит движку команду SAVE

Синтаксис

EVENT cansave infohash=infohash index=index format=format

Параметры

infohash - infohash контента
index - номер файла, который можно сохранить
format - формат файла, в котором будет сохранен контент. Возможные значения:
- plain - файл будет сохранен в незашифрованном виде
- encrypted - файл будет сохранен в зашифрованном виде (файл должен иметь расширение .acemedia). Зашифрованные файлы могут быть воспроизведены только с помощью программного обеспечение ACE Stream (с помощью команды START EFILE).

Параметры infohash и index клиент может использовать в команде SAVE, если пользователь решит сохранить контент.

Пример

Доступен для сохранения файл под номером 0, файл может быть сохранен в открытом виде:
<<EVENT cansave infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 index=0 format=plain

Файл может быть сохранен только в зашифрованном виде:
<<EVENT cansave infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 index=0 format=encrypted

`EVENT showurl`

Версия API: >= 3

Описание: Клиент должен отобразить встроенный браузер и загрузить указанную ссылку. В случае, если клиент не имеет встроенного браузера, это событие можно проигнорировать.

Синтаксис

EVENT showurl type=type url=url [width=width] [height=height]

Параметры

type - тип запроса (причина, по которой движок просит отобразить браузер). Возможные значения:
- ad: отобразить рекламу (такой запрос приходит в ответ на команду GETADURL)
- notification: отобразить пользователю страницу-уведомление. Такой запрос используется в том случае, если пользователя необходимо уведомить о чем-то и уведомление потребует от пользователя каких-либо действий (например, если доступ к контенту открыт только для зарегистрированных пользователей, то клиенту будет отослана ссылка на страницу, на которой пользователь сможет зарегистрироваться). Такие запросы дублируются событием INFO для того, чтобы клиенты без встроенного браузера могли отобразить пользователю текстовое уведомление.
url - ссылка на страницу, которую необходимо отобразить
width - ширина страницы (в пикселях)
height - высота страницы (в пикселях)

Если размеры окна браузера, передаваемые в параметрах width и height, больше размера окна клиента, то клиент должен отобразить браузер на все окно.

Если параметры width и height отсутствуют либо равны нулю, клиент должен отобразить браузер на все окно.

Пример

Показать рекламную страницу с адресом 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

`EVENT livepos`

Описание скоро будет

`EVENT download_stopped`

Версия движка: >= 3003600

Описание: Данное событие информирует клиента о причине остановки воспроизведения контента

Синтаксис

EVENT download_stopped reason=reason option=option

Параметры

reason - причина остановки; возможные значения:
- missing_option: не активирована платная опция, необходимая для воспроизведения данного контента
option - идентификатор платной опции

Пример

Воспроизведение остановлено, так как у пользователя отсутствует активированная платная опция proxyServer:
<<EVENT download_stopped reason=missing_option option=proxyServer

Примеры

>> - сообщения от клиента к движку

<< - сообщения от движка к клиенту

Проигрывание торрент-файла по ссылке без рекламных роликов

(необходимость проигрывания рекламных роликов определяет движок).

Для загрузки содержимого торрента используется асинхронная команда LOADASYNC.

Торрент файл содержит один видео-файл.

рукопожатие

>>HELLOBG version=3
<<HELLOTS version=3.1.1 version_code=3003400 key=5eb1f78f http_port=6878

клиент готов принимать сообщения

>>READY key=123456-fd2a247d83adffed56d82cca150d5fab225f1408

пользователю доступны расширенные функции

<<AUTH 1

загрузить торрент по ссылке

>>LOADASYNC 467763 TORRENT http://rutor.org/download/67346 0 0 0
<<LOADRESP 467763 {"status": 1, "files": [["Prey%202_%20E3%202011%20Official%20Trailer_2.mp4", 0]], "infohash":  
"4c78e1cf0df23b4f5a16a106829ebed710cb52e0"}

узнать код плеера (например, чтобы показать его пользователю)

>>GETPID 4c78e1cf0df23b4f5a16a106829ebed710cb52e0 0 0 0
<<##36ae4c89ab45b4010b1461c513da38d007356195

начать пребуферизацию видео

>>START TORRENT http://rutor.org/download/67346 0 0 0 0

идет процесс пребуферизации

<<STATE 1
<<STATUS main:prebuf;0;2147483447;0;0;0;0;0;0;0;0;0;0
<<STATUS main:prebuf;0;2132;0;0;29;0;0;8;0;131072;0;0
<<STATUS main:prebuf;8;942;0;0;60;0;0;9;0;393216;0;0
<<STATUS main:prebuf;50;591;0;0;87;0;0;8;0;835584;0;0
<<STATUS main:prebuf;75;497;0;0;98;0;0;8;0;1146880;0;0
<<STATUS main:prebuf;91;448;0;0;105;0;0;8;0;1441792;0;0

пребуферизация завершена, клиент получает ссылку для проигрывания контента

<<PLAY http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974
<<STATE 2

клиент отправляет длительность контента (~201 секунда)

>>DUR http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 201964

клиент информирует о том, что началось проигрывание

>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 0

движок загружает контент

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

движку недостаточно данных для проигрывания, начинает буферизация

<<PAUSE
<<STATE 3
<<STATUS main:buf;0;315;0;0;130;0;0;8;0;3260416;0;0
<<STATUS main:buf;90;299;0;0;133;0;0;8;0;3866624;0;0
<<STATUS main:buf;90;278;0;0;138;0;0;8;0;4390912;0;0

буферизация завершена

<<RESUME
<<STATE 2
<<STATUS main:dl;0;0;141;0;0;8;0;4898816;0;0

клиент проиграл 25% контента

>>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
<<STATUS main:dl;0;0;146;0;0;7;0;8388608;0;0

клиент проиграл 50% контента

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

клиент проиграл 75% контента

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

остановить загрузку контента

>>STOP
<<STATE 0

разорвать соединение

>>SHUTDOWN
<<SHUTDOWN

Ошибка запуска воспроизведения, отсутствует необходимая платная опция proxyServer

В этом примере описана ситуация, когда движок не может начать воспроизведение, так как для этого требуется наличие у пользователя активированной платной опции.

В случае отсутствия платной опции необходимо уведомить пользователя о необходимости приобрести данную опцию. Это может сделать либо клиент, либо движок. Если клиент хочет самостоятельно уведомить пользователя, он должен сообщить движку о готовности получать событие download_stopped с помощью команды SETOPTIONS. Если клиент этого не сделал, то движок самостоятельно уведомит пользователя (открыв окно либо страницу в браузере).

Первый пример описывает ситуацию, когда клиент не хочет уведомлять пользователя (в этом сценарии уведомление пользователю выдаст движок):

рукопожатие

>>HELLOBG version=3
<<HELLOTS version=3.1.1 version_code=3003400 key=5eb1f78f http_port=6878
>>READY key=123456-fd2a247d83adffed56d82cca150d5fab225f1408
<<AUTH 5

старт воспроизведения

>>START PID c894b23a65d64a0dae2076d2a01ec6bface83b01 0
<<STATE 1
<<STATUS main:starting

ошибка старта

<<STATE 0
<<STATUS main:idle
<<STATUS main:err;0;You need to buy Proxy Server option to continue

Второй пример описывает ситуацию, когда клиент хочет уведомлять пользователя:

рукопожатие

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

старт воспроизведения

>>START PID c894b23a65d64a0dae2076d2a01ec6bface83b01 0
<<STATE 1
<<STATUS main:starting

ошибка старта

<<EVENT download_stopped reason=missing_option option=proxyServer
<<STATE 0
<<STATUS main:idle

Воспроизведение прервано, так как отсутствует необходимая платная опция proxyServer

Этот сценарий отличается от предыдущего тем, что воспроизведение начинается, но через некоторое время после старта останавливается по причине отсутствия платной опции.

рукопожатие

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

старт воспроизведения

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

некоторое время воспроизведения идет без остановки

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

остановка воспроизведения

<<EVENT download_stopped reason=missing_option option=proxyServer
<<STOP
<<STATE 0
<<STATUS main:idle
<<STATUS main:err;0;Download stopped

@@ Line 1: / Line 1: @@
-'''Обмен данными с TS Engine происходит по протоколу TCP.'''
+==Общие понятия==
+ACE Stream Engine (далее - "движок") - приложение, которое обеспечивает весь функционал системы ACE Stream. Данное приложение работает в фоновом режиме и имеет минимальный графический интерфейс для изменения различных настроек.
-'''По умолчанию TS Engine принимает входящие соединения на порт 62062.'''
+ACE Stream Engine API (далее - API) - программный интерфейс, позволяющий сторонним приложениям работать с движком. Под сторонними приложениями, как правило, подразумеваются медиа плееры, работающие с системой ACE Stream.
+Клиент - стороннее приложение, которое работает с движком посредством API.
-== Общий вид команд ==
+==Схема работы API==
-Каждая команда должна состоять из строки, завершающейся разделителем \r\n
+Обмен данными с движком происходит по протоколу TCP. Общая схема работы выглядит так:
+* клиент устанавливает TCP-соединение с движком
+* клиент и движок обмениваются рукопожатиями
+* клиент и движок обмениваются сообщениями
+* одна из сторон завершает соединение
-Большинство команд имеют такой вид:
+===Установление соединения===
+Для установления соединения клиент должен знать порт, на котором работает API движка. Методы определения порта зависят от операционной системы, на которой запущен движок.
-<tt>'''CMD [param1] [param2] ...'''</tt>
+На Linux используется фиксированный порт: 62062
-где
+На Windows используется динамический порт. Движок после запуска создает файл acestream.port в директории, в которой находится сам движок (файл tsengine.exe), и записывает в данный файл порт, на котором работает API. Для того, чтобы узнать порт, клиент должен прочитать указанный файл. Отсутствие данного файла указывает на то, что движок в не запущен. Путь к папке, в которую устанавливается движок, можно считать из реестра:
+ <tt>HKEY_CURRENT_USER\Software\TorrentStream\EnginePath</tt>
-<tt>'''CMD'''</tt> - предопределенное название команды
+Ключ <tt>EnginePath</tt> содержит абсолютный путь к исполняемому файлу движка (tsengine.exe). По умолчанию это <tt>%APPDATA%\TorrentStream\engine\tsengine.exe</tt>
-<tt>'''param1, param2 ...'''</tt> - параметры команды, разделенные пробелом
+Алгоритм установления соединения (Windows):
+# считать из реестра ключ <tt>HKEY_CURRENT_USER\Software\TorrentStream\EnginePath</tt>
+## если ключ отсутствует - движок не установлен
+## запомнить путь к исполняемому файлу движка (engine_path) и директории движка (engine_dir)
+# считать содержимое файла engine_dir/acestream.port и запомнить порт
+# если данный файл отсутствует - запустить движок, дождаться создания файла acestream.port и считать его содержимое
+# установить TCP-соединение на localhost на указанный порт
+# если не получилось установить соединение - движок не запущен и его нужно запустить
+# обменяться рукопожатием и начать обмен сообщениями
-== ТИПЫ КОМАНД ==
+Алгоритм установления соединения (Linux):
+# установить TCP-соединение на localhost на порт 62062
+# если не получилось установить соединение - движок не запущен и его нужно запустить (<tt>/usr/bin/acestreamengine-client-gtk</tt>)
+# обменяться рукопожатием и начать обмен сообщениями
-Все команды делятся на входящие и исходящие.
+===Рукопожатие===
+После установления соединения клиент и движок должны обменяться рукопожатием:
+* клиент отсылает сообщение
+ <tt>HELLOBG version=''api_version''</tt>
+* движок отсылает в ответ
+ <tt>HELLOTS version=''engine_version'' version_code=''version_code'' key=''request_key'' http_port=''http_port''</tt>
-Входящие команды отправляются от клиента к TS Engine. Клиентом является любое программное
+Каждое сообщение должно завершаться символами перевода строки CRLF (\r\n)
-обеспечение, которое использует функционал TS Engine. С помощью входящих команд клиент
-управляет работой TS Engine.
-Исходящие команды отправляются от TS Engine к клиенту. Данный тип команд используется для
+;''api_version''
-информирования клиента о работе TS Engine.
+: версия API, которую поддерживает клиент. Этот параметр служит для поддержки обратной совместимости новых версий движка со старыми клиентами. Если клиент не указал версию, по умолчанию используется версия 1. Для всех сообщений API в документации указано, начиная с какой версии они поддерживаются.
+ Текущая версия API - 3
-== СИНХРОННЫЕ КОМАНДЫ ==
+;''engine_version''
+: версия движка (например, 2.0.8)
-Большинство входящих команд выполняются асинхронно, т.е. для таких команд нет понятия "ответ на команду".
+;''version_code''
+: цифровой код версии движка (например, 3003400); клиент должен использовать этот код для сравнения версий движка; код каждой новой версии всегда больше всех кодов предыдущих версий
-'''Примеры асинхронных команд:'''
+;''request_key''
+:используется для авторизации клиента с помощью [[Product key|ключа продукта]]
-- клиент отправляет LOADASYNC, после загрузки содержимого TS Engine отправляет LOADRESP через некоторое время
+;''http_port''
+:порт, на котором работает встроенный HTTP сервер движка
-- клиент отправляет START, после окончания пребуферизации TS Engine отправляет PLAY
+Если клиент в течение некоторого времени после отправки рукопожатия не получил ответ, соединение необходимо завершить.
+После получения команды <tt>HELLOTS</tt> от движка клиент должен отослать такую команду:
+ <tt>READY key=''response_key''</tt>
-Но есть также команды, которые выполняются синхронно, в режиме "запрос-ответ". На данный момент таких команд две: '''LOAD''' и '''GETPID'''.
+Формирование <tt>response_key</tt> описано [[Product_key|здесь]].
-Синхронная команда предполагает ответ, который отправляется от TS Engine к клиенту в виде строки, начинающейся на ##.
+===Обмен сообщениями===
+Каждое сообщение представляет собой ASCII-строку, которая завершается символами перевода строки <tt>CRLF</tt> (<tt>\r\n</tt>)
-Обработка синхронных команд со стороны клиента должна выглядеть таким образом:
+Примерный алгоритм приема сообщений выглядит таким образом:
+* клиент в цикле ждет поступления данных по TCP-соединению
+* при получении данных они добавляются в буфер
+* клиент проверяет, есть ли в буфере символы CRLF. Если есть, то из буфера вырезается сообщение (строка от начала буфера до символов CRLF) и отправляется в обработчик сообщений
+* клиент должен учитывать возможность получения нескольких сообщений одновременно (т.е. повторять предыдущий шаг, пока в буфере не будет символов CRLF)
-- клиент отправляет команду, например "GETPID qwerty 0 0 0" и ждет, пока от TS Engine придет ответ
+===Завершение соединения===
+Движок при завершении работы отправляет команду <tt>SHUTDOWN</tt> и закрывает сокет. При получении данной команды клиент должен прекратить обработку команд и закрыть свой сокет.
-- если от TS Engine получено сообщение, которое начинается на ##, то данное сообщение считается ответом на синхронную команду  (например, ##12345)
+То же самое должен делаь клиент при закрытии - перед закрытием отослать движку команду <tt>SHUTDOWN</tt>
+==Сообщения==
-== ВХОДЯЩИЕ КОМАНДЫ ==
+===Типы сообщений===
+Все сообщения условно делятся на две группы: команды и события.
-<tt>'''HELLOBG'''</tt>
+Команды подразумевают выполнение какого-либо действия от принимающей стороны. Например, командой <tt>START</tt> клиент просит движок начать пребуферизацию указанного контента.
-Используется в рамках процедуры "рукопожатия" между клиентом и TS Engine.
+События носят информационный характер. Например, событие <tt>STATUS</tt> информирует клиента о статусе загрузки (идет ли в данный момент пребуферизация, буферизация, какая скорость загрузки и т.д.)
-Эта команда должна быть отправлена клиентом сразу после установления tcp-соединения с TS Engine.
+===Синхронные команды===
+Практически все команды являются асинхронными, т.е. не предполагают наличие ответа от другой стороны.
-Соединение с TS Engine считается успешным после того, как клиент получил от TS Engine ответ на "рукопожатие" - команду HELLOTS
+Исключением являются две команды:
+* <tt>LOAD</tt> (сихронная загрузка информации о потоке)
+* <tt>GETCID</tt> (получение Content ID для потока)
+Для этих команд есть понятие ответа на команду. Ответ передается в виде строки, которая начинается на ##.
-<tt>'''READY'''</tt>
+Алгоритм обработки синхронных команд такой:
+* клиент отправляет движку синхронную команду (например, <tt>GETCID 4c78e1cf0df23b4f5a16a106829ebed710cb52e0 0 0 0</tt>) и ждет данных от движка
+* когда от движка приходят данные, клиент проверяет, начинается ли полученный ответ на ## (например, <tt>##36ae4c89ab45b4010b1461c513da38d007356195</tt>)
+* если это так, то строка от символов ## до CRLF является ответом на синхронную команду (причем ответ может быть пустой, т.е. выглядеть так: <tt>##</tt>)
+* если нет, значит ответ на команду не может быть получен
-Информирует TS Engine о том, что клиент готов принимать исходящие команды
+ Мы не рекомендуем использовать синхронную команду <tt>LOAD</tt>, так как она подразумевает блокирование потока на стороне клиента.
+ Эта команда является устаревшей и вместо нее следует использовать асинхронную версию <tt>LOADASYNC</tt>
+Ответ на команду <tt>GETCID</tt> приходит практически мгновенно, поэтому ее использование не приводит к блокированию. Однако есть одно замечание по использованию данной команды:
+ Команду <tt>GETCID</tt> не следует отправлять, если движок находится в состоянии <tt>starting</tt>
-<tt>'''LOAD TORRENT''' <torrent_url> <developer_id> <affiliate_id> <zone_id>
+===Список сообщений===
+В примерах сообщения от клиента к движку отмечены >>, от движка к клиенту - <<
-'''LOAD INFOHASH''' <torrent_infohash> <developer_id> <affiliate_id> <zone_id>
+====Команды от клиента к движку====
-'''LOAD PID''' <player_id>
+=====<tt style="color: #009;">READY</tt>=====
+;Версия API
+:>= 1
-'''LOAD RAW''' <torrent_data> <developer_id> <affiliate_id> <zone_id>
+;Описание
+:Информирует движок о том, что клиент готов принимать команды. Это должна быть первая команда после рукопожатия.
-'''LOADASYNC''' <request_id> '''TORRENT''' <torrent_url> <developer_id> <affiliate_id> <zone_id>
+;Синтаксис
+ <tt>READY</tt>
-'''LOADASYNC''' <request_id> '''INFOHASH''' <torrent_infohash> <developer_id> <affiliate_id> <zone_id>
+;Параметры
+:нет
-'''LOADASYNC''' <request_id> '''PID''' <player_id>
+;Пример:
+ <tt><nowiki>>>READY</nowiki></tt>
-'''LOADASYNC''' <request_id> '''RAW''' <torrent_data> <developer_id> <affiliate_id> <zone_id></tt>
+=====<tt style="color: #009;">LOADASYNC</tt>=====
+;Версия API
+:>= 1
-Данные команды выполняют загрузку содержимого торрент-файла и используются для того, чтобы клиент мог получить список названий
+;Описание
-файлов в интересующем торрент-файле. Команды LOAD выполняются синхронно, команды LOADASYNC - асинхронно (ответ приходит в исходящей команде LOADRESP).
+:Получить описание контента по идентификатору. Идентификатором может быть content id, ссылка на транспортный файл (.torrent, .acelive), инфохеш транспортного файла и т.п. Описание представляет
-Более предпочтительным методом является асинхронная загрузка.
+собой список названий файлов либо потоков, которые содержатся в транспортном файле. Основное назначение этой команды - возможность сформировать и показать пользователю плейлист.
-'''Параметры:'''
+;Синтаксис
+ <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 точно знал, на какой из этих запросов получен ответ
+;Параметры
+* <tt>''request_id''</tt>: случайное целое число - идентификатор запроса LOADASYNC; этот же идентификатор будет отослан клиенту в команде LOADRESP после того,как будет получен список файлов; данный
-<tt>'''torrent_url'''</tt> - ссылка на торрент файл (например, http://sometracker.com/torrent/12345)
+идентификатор служит для того, чтобы клиент в случае отправки нескольких запросов LOADASYNC точно знал, на какой из этих запросов получен ответ
+* <tt>''url''</tt>: ссылка на транспортный файл
+* <tt>''infohash''</tt>: инфохеш транспортного файла
+* <tt>''data''</tt>: содержимое транспортного файла в кодировке base64
+* <tt>''content_id''</tt>: идентификатор контента в системе ACE Stream (Content ID)
+* <tt>''developer_id''</tt>: код разработчика (если неизвестно, необходимо передавать 0)
+* <tt>''affiliate_id''</tt>: код партнера (если неизвестно, необходимо передавать 0)
+* <tt>''zone_id''</tt>: код зоны партнера (если неизвестно, необходимо передавать 0)
-<tt>'''torrent_infohash'''</tt> - infohash торрента
+;Формат ответа
+:Ответ приходит в формате JSON со следующими полями:
+* <tt>''status''</tt>:
+** 0 - транспортный файл не содержит аудио/видео файлов
+** 1 - транспортный файл содержит один аудио/видео файл
+** 2 - транспортный файл содержит более одного аудио/видео файла
+** 100 - ошибка получения данных
+* <tt>''files''</tt>: список файлов/потоков; это массив, каждый элемент в котором состоит из массива из двух элементов: первый - название файла, второй - позиция в транспортном файле (эта позиция
-<tt>'''player_id'''</tt> - код плеера
+должна отправляться в команде <tt>START</tt> для указания, какой именно файл необходимо загружать, если их несколько)
+* <tt>''infohash''</tt>: инфохеш транспортного файла
+* <tt>''checksum''</tt>: хешсумма транспортного файла
-<tt>'''torrent_data'''</tt> - содержимое торрент-файла в кодировке base64
+:Параметры <tt>''infohash''</tt> и <tt>''checksum''</tt> клиенту нужны для того, чтобы в дальнейшем получить Content ID с помощью команды <tt>GETCID</tt>
-<tt>'''developer_id'''</tt> - код разработчика (если неизвестно, необходимо передавать 0)
+:Названия файлов возвращаются в виде urlencoded строк в кодировке UTF-8
-<tt>'''affiliate_id'''</tt> - код партнера (если неизвестно, необходимо передавать 0)
+;Пример:
+ <tt><nowiki>Загрузить контент по Content ID:
+>>LOADASYNC 126500 PID 1ccf192064ee2d95e91a79f91c6097273d582827
-<tt>'''zone_id'''</tt> - код зоны партнера (если неизвестно, необходимо передавать 0)
+В ответ клиент получает от движка:
+<<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_url> <file_indexes> <developer_id> <affiliate_id> <zone_id>
+;Примеры:
+ <tt><nowiki>Начать проигрывание по ссылке на транспортный файл:
+>>START TORRENT http://rutor.org/download/67346 0 0 0 0
-'''START INFOHASH''' <torrent_infohash> <file_indexes> <developer_id> <affiliate_id> <zone_id>
+Начать проигрывание по Content ID:
+START PID 1ccf192064ee2d95e91a79f91c6097273d582827 0
-'''START PID''' <player_id> <file_indexes>
+Начать проигрывание acemedia-файла c:\acestream\test.acemedia:
+START EFILE file%3A%2F%2F%2Fc%3A%5Cacestream%5Ctest.acemedia
+</nowiki></tt>
-'''START RAW''' <torrent_data> <file_indexes> <developer_id> <affiliate_id> <zone_id>
+======<span id="transcode_settings"></span>Настройки транскодирования======
+Начиная с версии 3.1.5 есть возможность задавать формат вывода потока и параметры транскодирования аудио.
+* <tt>''output_format=hls|http''</tt>: формат вывода потока
+* <tt>''transcode_audio=0|1''</tt>: транскодировать все аудио в AAC
+* <tt>''transcode_mp3=0|1''</tt>: транскодировать MP3 (данная опция применима только если transcode_audio=1)
+* <tt>''transcode_ac3=0|1''</tt>: транскодировать только AC3 в AAC (данная опция применима только если transcode_audio=0)
-'''START URL''' <direct_url> <file_indexes> <developer_id> <affiliate_id> <zone_id>)</tt>
+:В версии 3.1.5 данные настройки касаются только live-потоков.
+:Если оригинал потока вещается в формате HLS, то формат вывода будет HLS независимо от настроек.
+:Настройки транскодирования аудио влияют только на выдачу в формате HLS (по HTTP всегда выдается оригинальный поток)
+:Если настройки формата вывода или транскодирования не передаются в команде <tt>START</tt>, то используются настройки, заданные пользователем на движке
-Данные команды используются для начала загрузки определенного файла из торрент-файла либо для начала загрузки файла по прямой ссылке (START URL)
+;Примеры:
+ <tt><nowiki>Запустить в формате HLS:
+>> START PID 1ccf192064ee2d95e91a79f91c6097273d582827 0 output_format=hls
-'''Параметры:'''
+Запустить в формате HLS, транскодировать все аудио-кодеки в AAC:
+>> START PID 1ccf192064ee2d95e91a79f91c6097273d582827 0 output_format=hls transcode_audio=1 transcode_mp3=1
-<tt>'''file_indexes'''</tt> - список индексов файлов из торрент-файла, которые необходимо загружать. Индексы файлов клиент получает в сообщении LOADRESP разделенных запятой. Индексы начинаются с нуля и соответствуют списку файлов,
+Запустить в формате HLS, транскодировать все аудио-кодеки, кроме MP3, в AAC:
-который был получен в результате выполнения команды LOAD. Например, если в торрент-файле всего один видео-файл, то необходимо отправлять индекс 0.
+>> START PID 1ccf192064ee2d95e91a79f91c6097273d582827 0 output_format=hls transcode_audio=1 transcode_mp3=0
+</nowiki></tt>
-Если в торренте пять видео-файлов и необходимо начать проигрывание первого, но при это загружать остальные, то отправляется 0,1,2,3,4.
+=====<tt style="color: #009;">STOP</tt>=====
+;Версия API
+:>= 1
-Если нужно проиграть третий файл, и не загружать другие, отправляется 2.
+;Описание
+:Остановить воспроизведение и загрузку
-<tt>'''torrent_url'''</tt> - ссылка на торрент файл (например, http://sometracker.com/torrent/12345)
+;Синтаксис
+ <tt>STOP</tt>
-<tt>'''torrent_infohash'''</tt> - infohash торрента
+;Параметры
+:нет
-<tt>'''player_id'''</tt> - код плеера
+;Пример:
+ <tt><nowiki>>>STOP</nowiki></tt>
-<tt>'''torrent_data'''</tt> - содержимое торрент-файла в кодировке base64
+=====<tt style="color: #009;">GETPID</tt>=====
+;Версия API
+:1
+ Эта команда устарела и больше не используется. Вместо нее следует использовать команду <tt>GETCID</tt>
-<tt>'''direct_url'''</tt> - прямая ссылка на файл (например, http://somesite.com/files/video.mp4)
+=====<tt style="color: #009;">GETCID</tt>=====
+;Версия API
+:>= 2
-<tt>'''developer_id'''</tt> - код разработчика (если неизвестно, необходимо передавать 0)
+;Описание
+:Получение кода плеера по набору параметров. Эта команда является синхронной командой (см.ниже). В ответ отправляется код плеера, либо пустая строка, если код плеера не может быть получен
-<tt>'''affiliate_id'''</tt> - код партнера (если неизвестно, необходимо передавать 0)
+;Синтаксис
+ <tt>GETCID checksum=''checksum'' infohash=''infohash'' developer=''developer_id'' affiliate=''affiliate_id'' zone=''zone_id''</tt>
-<tt>'''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>
-<tt>'''GETPID''' <infohash> <developer_id> <affiliate_id> <zone_id></tt>
+=====<tt style="color: #009;">GETADURL</tt>=====
+;Версия API
+:>= 3
-Получение кода плеера по набору параметров. Эта команда является синхронной командой (см.ниже). В ответ отправляется код плеера, либо пустая строка, если код плеера не может быть получен
+;Описание
+:Запрос к движку на получение ссылки на рекламную страницу. Данную команду могут использовать клиенты, которые имеют возможность отображать встроенный браузер в плеере, для того, чтобы показывать пользователям рекламу перед началом проигрывания контента либо когда пользователь нажимает паузу. Если движок определит, что есть доступная к показу реклама, то после получения этой команды отправит клиенту событие <tt>EVENT showurl</tt>
+;Синтаксис
+ <tt>GETADURL width=''width'' height=''height'' infohash=''infohash'' action=''action''</tt>
-<tt>'''SHUTDOWN'''</tt>
+;Параметры
+* <tt>''width''</tt>: ширина видео окна клиента (в пикселях)
+* <tt>''height''</tt>: высота видео окна клиента (в пикселях)
+* <tt>''infohash''</tt>: infohash текущего контента (значение клиент получает из сообщения LOADRESP)
+* <tt>''action''</tt>: описание события, возможные значения:
+** <tt>load</tt> - загрузка (клиент загрузился, готов к проигрыванию, но пользователь еще не начала проигрывание)
+** <tt>pause</tt> - пользователь нажал паузу
-Закрыть соединение с клиентом.
+;Примеры
+ <tt><nowiki>>>GETADURL width=1328 height=474 infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 action=load
+>>GETADURL width=1328 height=474 infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 action=pause
+</nowiki></tt>
+=====<tt style="color: #009;">USERDATA</tt>=====
+;Версия API
+:>= 3
-<tt>'''STOP'''</tt>
+;Описание
+:Данная команда используется для передачи движку информации о пользователе. Информация передается в формате JSON.
-Остановить загрузку файла, который загружается в данный момент.
+;Синтаксис
+ <tt>USERDATA [{"gender": ''gender_id''}, {"age": ''age_id''}]</tt>
+;Параметры
+* <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_url> <duration></tt>
+;Пример:
+ <tt><nowiki>мужчина, от 18 до 24 лет:
+>>USERDATA [{"gender": 1}, {"age": 3}]</nowiki></tt>
-Сообщить TS Engine о длительности видео-файла, который в данный момент проигрывается клиентом.
+=====<tt style="color: #009;">SAVE</tt>=====
-Данная команда должна отправлять сразу после того, как клиент определил длительность контента.
+;Версия API
+:>= 2
-'''Параметры:'''
+;Описание
+:Сохранить контент в указанном месте.
-<tt>'''video_url'''</tt> - ссылка на видео, которая была отправлена клиенту после окончания пребуферизации
+;Синтаксис
+ <tt>SAVE infohash=''infohash'' index=''index'' path=''path''</tt>
-<tt>'''duration'''</tt> - длительность в миллисекундах
+;Параметры
+* <tt>''infohash''</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>
-<tt>'''PLAYBACK''' <video_url> <event></tt>
+=====<tt style="color: #009;">LIVESEEK</tt>=====
+Описание скоро будет
-Сообщить TS Engine о процентном соотношении проигранного видео
+=====<tt style="color: #009;">SHUTDOWN</tt>=====
+;Версия API
+:>= 1
-Данная команда особенно важна, когда идет прогрывание рекламных роликов - переход к основному видео происходит только после того,
+;Описание
-как TS Engine получил команду PLAYBACK 100 (т.е. после того, как клиент полность проиграл рекламный ролик)
+:Клиент завершил работу
-'''Параметры:'''
+;Синтаксис
+ <tt>SHUTDOWN</tt>
-<tt>'''video_url'''</tt> - ссылка на видео, которая была отправлена клиенту после окончания пребуферизации
+;Параметры
+:нет
-<tt>'''event'''</tt> - одно из данных событий:
+;Пример:
+ <tt><nowiki>>>SHUTDOWN</nowiki></tt>
-- начало проигрывания
+=====<tt style="color: #009;">SETOPTIONS</tt>=====
+;Версия движка
+:>= 3003600
-- проиграно 25% видео
+;Описание
+:Сообщить движку о наборе опций, которые поддерживает клиент
-- проиграно 50% видео
+;Синтаксис
+ <tt>SETOPTIONS name1=value1 [name2=value2 ...]</tt>
-- проиграно 75% видео
+;Параметры
+:name - название опции
+:value - значение опции
-- проиграно 100% видео
+;Список опций
+:use_stop_notifications - клиент хочет получать от движка событие download_stopped с причиной остановки во время проигрывания
+;Пример:
+ <tt><nowiki>>>SETOPTIONS use_stop_notifications=1</nowiki></tt>
-== ИСХОДЯЩИЕ КОМАНДЫ ==
+====Команды от движка к клиенту====
+=====<tt style="color: #009;">PLAY, PLAYAD, PLAYADI</tt>=====
+;Версия API
+:1
+ Эти команды устарели и больше не используется. Вместо них следует использовать команду <tt>START</tt>
-<tt>'''HELLOTS'''</tt>
+=====<tt style="color: #009;">START</tt>=====
+;Версия API
+:>= 2
-ответная команда в рамках процедуры рукопожатия
+;Описание
+:Начать прогрывание контента. Эта команда отправляется после завершения пребуферизации. Движок отсылает плееру http-ссылку, по которой плеер может начать проигрывание контента. Данная ссылка
+обрабатывается http-серверов, встроенным в движок.
-<tt>'''AUTH''' <auth_level></tt>
+;Синтаксис
+ <tt>START ''url'' [ad=1 [interruptable=1]] [stream=1] [pos=''position'']</tt>
-Уровень доступа пользователя
+;Параметры
+* <tt>''url''</tt>: ссылка для проигрывания
+* <tt>''ad=1''</tt>: флаг, указывающий на то, что ссылка <tt>''url''</tt> ведет на рекламный видеоролик, который клиент должен проиграть перед началом воспроизведения основного контента
+* <tt>''interruptable=1''</tt>: флаг, указывающий на то, что должен проиграться прерываемый рекламный ролик
+* <tt>''stream=1''</tt>: флаг, указывающий на то, что проигрываемый контент является живой трансляцией (Live Stream).
+* <tt>''position''</tt>: целое число от 0 до 100, которое указывает с какой позиции клиент должен начать проигрывание (например, position=50 означает, что клиент должен начать проигрывание с
-<tt>auth_level</tt> - целое число - уровень доступа
+позиции 50%, т.е. с середины контента)
-На данный момент возможны два значения уровня доступа:
+;Примеры
+ <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
-- пользователю доступны расширенные функции
+Начать проигрывание прерываемого рекламного ролика:
+<<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
-<tt>'''STATE''' <state_id></tt>
+Начать проигрывание с середины (50%):
+<<START http://127.0.0.1:6878/content/5410b27fc567c35c8547e3b69b141215ce3a1fd7/0.828180567196 pos=50</nowiki></tt>
-Информация о текущем статусе TS Engine
+=====<tt style="color: #009;">PAUSE</tt>=====
+;Версия API
+:>= 1
+;Описание
+:Движок начал буферизацию, клиент по возможности должен остановиться на паузу до получения команды <tt>RESUME</tt>
-<tt>'''SHUTDOWN'''</tt>
+;Синтаксис
+ <tt>PAUSE</tt>
-TS Engine завершил работу
+;Параметры
+:нет
+;Пример:
+ <tt><nowiki><<PAUSE</nowiki></tt>
-<tt>'''PLAY''' <video_url></tt>
+=====<tt style="color: #009;">RESUME</tt>=====
+;Версия API
+:>= 1
-<tt>'''PLAYAD''' <video_url></tt>
+;Описание
+:Движок завершил буферизацию, клиент может продолжить воспроизведение.
-<tt>'''PLAYADI''' <video_url></tt>
+;Синтаксис
+ <tt>RESUME</tt>
-Начать проигрывание видео по ссылке video_url (данная ссылка ведет на http-сервер, встроенный в TS Engine).
+;Параметры
+:нет
-<tt>'''PLAY'''</tt> - проигрывание основного видео
+;Пример:
+ <tt><nowiki><<RESUME</nowiki></tt>
-<tt>'''PLAYAD'''</tt> - проигрывание непрерываемого рекламного ролика (пользователь не может перемотать либо пропустить данный рекламный ролик)
+=====<tt style="color: #009;">STOP</tt>=====
+;Версия API
+:>= 1
-<tt>'''PLAYADI'''</tt> - проигрывание прерываемого рекламного ролика (пользователь может перемотать либо пропустить данный рекламный ролик)
+;Описание
+:Клиент должен остановить воспроизведение контента
+;Синтаксис
+ <tt>STOP</tt>
-<tt>'''PAUSE'''</tt>
+;Параметры
+:нет
-TS Engine начал буферизацию, так как недостаточно данных для проигрывания видео без остановки
+;Пример:
+ <tt><nowiki><<STOP</nowiki></tt>
+=====<tt style="color: #009;">SHUTDOWN</tt>=====
+;Версия API
+:>= 1
-<tt>'''RESUME'''</tt>
+;Описание
+:Движок завершил работу
-TS Engine завершил буферизацию
+;Синтаксис
+ <tt>SHUTDOWN</tt>
+;Параметры
+:нет
-<tt>'''LOADRESP''' <request_id> <response></tt>
+;Пример:
+ <tt><nowiki><<SHUTDOWN</nowiki></tt>
-Ответ на команду LOAD
-<tt>'''request_id'''</tt> - идентификатор запроса
+====События от клиента к движку====
-<tt>'''response'''</tt> - список файлов в формате json в такого вида:
+События <tt>DUR</tt> и <tt>PLAYBACK</tt> необходимо отправлять только для VOD-контента (так как live не имеет длительности).
- {
-  "status": 1,
-  "infohash": "abcd1234",
-  "files": [
-    ["file1.mp4", 0],
-    ["file2.avi", 1],
-    ["file3.mkv", 5]
-  ]
- }
-<tt>'''status'''</tt> - 0: в торренте нет видео файлов, 1 - в торренте один видео файл, 2 - в торренте более одного видео файла
+Отправка данных событий является обязательной только при воспроизведении рекламных роликов (когда получена команда <tt>START</tt> с параметром ad=1). См. примечание к событию <tt>PLAYBACK</tt>.
-<tt>'''infohash'''</tt> - infohash торрента
+При воспроизведении обычных VOD клиент не обязан отправлять данные события.
-<tt>'''files'''</tt> - список файлов; это массив, каждый элемент в котором состоит из массива из двух элементов: первый - название файла, второй - позиция файла в торренте (эта позиция должна отправляться в команде START для указания, какой именно файл необходимо загружать, если их несколько).
+=====<tt style="color: #009;">DUR</tt>=====
+;Версия API
+:>= 1
-Имена файлов передаются в кодировке UTF-8 в urlencoded виде.
+;Описание
+:Сообщить движку о длительности контента, который в данный момент проигрывается клиентом. Данная команда должна отправлять сразу после того, как клиент определил длительность контента.
+;Синтаксис
+ <tt>DUR ''video_url'' ''duration''</tt>
-<tt>'''INFO''' <message_id>;<message_text></tt>
+;Параметры
+* <tt>''video_url''</tt>: ссылка на видео, которая была отправлена клиенту после окончания пребуферизации в команде <tt>START</tt>
+* <tt>''duration''</tt>: длительность в миллисекундах
-Информационное сообщение
+;Пример:
+ <tt><nowiki>Клиент определить длительность контента: 3780 секунд:
+>>DUR http://127.0.0.1:6878/content/5b5ba8c462f4014d8b57377c97d2e13caee52cdd/0.685119063624 3780000</nowiki></tt>
-<tt>'''message_id'''</tt> - код сообщения
+=====<tt style="color: #009;">PLAYBACK</tt>=====
+;Версия API
+:>= 1
-<tt>'''message_text'''</tt> - текст сообщения
+;Описание
+:Сообщить движку о прогрессе проигранного контента (сколько процентов проигралось).
+:Данная команда особенно важна, когда идет прогрывание рекламных роликов - переход к основному контенту происходит только после того, как движок получил команду PLAYBACK 100 (т.е. после того, как клиент полностью проиграл рекламный ролик)
+;Синтаксис
+ <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_string></tt>
+;Пример:
+ <tt><nowiki>>>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 style="color: #009;">EVENT</tt>=====
+;Версия API
+:>= 3
-<tt>'''status_string'''</tt> - строка описанного ниже формата
+;Описание
+:Отправка событий движку. С помощью этого сообщения клиент может отправлять движку события, касающиеся действий пользователя относительно воспроизведения контента (поставил на паузу, перемотал и т.п.). Отправка данных событий не обязательна - клиент может их не отправлять при отсутствии технический возможности.
+;Синтаксис
+ <tt>EVENT ''event_name'' [param1=value1 [param2=value2] ...]</tt>
-Если идет проигрывание основного контента
+;Параметры
+* <tt>''event_name''</tt>: название события. Возможные значения:
+** <tt>play</tt> - начало воспроизведения либо продолжение после паузы
+** <tt>pause</tt> - пользователь поставил воспроизведение на паузу
+** <tt>stop</tt> - остановка воспроизведения
+** <tt>seek</tt> - пользователь осуществил перемотку. Для этого события необходимо отправлять параметр <tt>position</tt>, в котором указывается позиция в секундах
-  <tt>STATUS main:status_string</tt>
+;Примеры
+  <tt><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_string</tt>
+;Синтаксис
+  <tt>STATE ''state_id''</tt>
+;Параметры
+* <tt>''state_id''</tt>: состояние движка:
+** 0 (IDLE) - движок ничего не делает
+** 1 (PREBUFFERING) - началась пребуферизация
+** 2 (DOWNLOADING) - идет загрузка контента в обычном режиме
+** 3 (BUFFERING) - началась буферизация
+** 4 (COMPLETED) - загрузка контента завершена
+** 5 (CHECKING) - выполняется инициализация перед началом загрузки
+** 6 (ERROR) - ошибка
-<tt>'''status_string:'''</tt>
+;Пример:
+ <tt><nowiki><<STATE 0</nowiki></tt>
-TS Engine ничего не делает - <tt>'''idle'''</tt>
+=====<tt style="color: #009;">INFO</tt>=====
+;Версия API
+:>= 1
-ошибка - <tt>'''err;error_id;error_message'''</tt> (код и описание)
+;Описание
+:Отобразить текстовое сообщение пользователю.
-проверка - <tt>'''check;progress'''</tt>
+;Синтаксис
+ <tt>INFO ''message_id'';''message_text''</tt>
-пребуферизация - <tt>'''prebuf;progress;time'''</tt>
+;Параметры
+* <tt>''message_id''</tt>: числовой идентификатор сообщения
+** 1: сообщение "На данный момент нет активных пиров" (отправляется в том случае, если в течение минуты после начала загрузки не удалось найти ни одного пира)
+** 2: сообщение "Рекламный блок" (отправляется после начала воспроизведения рекламного ролика).
+** 3: сообщение "Основной контент" (отправляется после начала воспроизведения основного контента).
+** 0: другое сообщение (текст сообщения берется из параметра <tt>''message_text''</tt>)
+* <tt>''message_text''</tt>: текст сообщения, которое необходимо отобразить
-закачка - <tt>'''dl'''</tt>
+;Пример:
+ <tt><nowiki><<INFO 1;Cannot find active peers
+<<INFO 2;Advertising video
+<<INFO 3;Main content
+<<INFO 0;Display some message</nowiki></tt>
-буферизация - <tt>'''buf;progress;time'''</tt>
+=====<tt style="color: #009;">STATUS</tt>=====
+;Версия API
+:>= 1
-ожидание достаточной скорости - <tt>'''wait;time'''</tt>
+;Описание
+:Данное сообщение отправляется периодически для информирования клиента о текущем статусе загрузки контента. Основное назначение этого сообщение - дать клиенту возможность отображать пользователю о том, что сейчас происходит на движке.
+;Синтаксис
+ <tt>STATUS ''status_string''</tt>
-Ко всем <tt>status_string</tt> (кроме <tt>idle, err, check</tt>) добавляются общие данные:
+;Параметры
+* <tt>''status_string''</tt> - строка описанного ниже формата
-  <tt>total_progress;immediate_progress;speed_down;http_speed_down;speed_up;peers;http_peers;downloaded;http_downloaded;uploaded</tt>
+Если идет проигрывание основного контента
+  <tt>STATUS main:''status_description''</tt>
+Если идет проигрывание рекламного ролика (рекламный ролик и основной контент описываются отдельно; например, рекламный ролик уже полность загружен, а основной контент проходит стадию пребуферизации):
+ <tt>STATUS main:''status_description''|ad:''status_description''</tt>
-<tt>'''total_progress'''</tt> - сколько всего закачано по данному файлу
+;Возможные значения <tt>''status_description:''</tt>
+* движок ничего не делает - <tt>'''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'''</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.
@@ Line 334: / Line 687: @@
 Все 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
-'''Примеры:'''
+Идет загрузка контента, загружен 1%, скорость загрузки 442 Кбайт/с, подсоединено 10 пиров, загружено 13920256:
- <tt>STATUS main:prebuf;45;30|ad:buf;69
+<<STATUS main:dl;1;0;442;0;0;10;0;13920256;0;0
- STATUS main:dl|ad:dl</tt>
-'''Пример трансформация статусов в текстовые сообщения, понятные пользователю:'''
+Рекламный ролик полность загружен и воспроизводится, основной контент пребуферизируется (20%):
+<<STATUS main:prebuf;20;2723;0;0;328;0;0;7;0;5505024;0;0|ad:dl;100;0;0;0;0;0;0;13920256;0;0</nowiki></tt>
-  <tt>check - Checking xx%
+;Пример трансформации статусов в текстовые сообщения, понятные пользователю
-  prebuf - Prebuffering xx%
+  <tt>check - Проверка xx%
-  buf - Buffering xx%
+  prebuf - Пребуферизация xx%
-  wait - Waiting sufficient download speed
+  buf - Буферизация xx%
+  wait - Ожидание достаточной скорости
   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>=====
+Описание скоро будет
-<tt>'''EVENT event_name param1_name=param1_value param2_name=param2_value ...'''</tt>
+=====<tt style="color: #009;">EVENT download_stopped</tt>=====
+;Версия движка
+:>= 3003600
-Параметры не обязательны.
+;Описание
+:Данное событие информирует клиента о причине остановки воспроизведения контента
-Значения параметров - <tt>'''urlencoded utf-8'''</tt>
+;Синтаксис
+ <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>
 == Примеры ==
-'''(>> - сообщения от клиента к TS Engine, << - сообщения от TS Engine к клиенту)'''
+<tt>'''>>'''</tt> - сообщения от клиента к движку
+<tt>'''<<'''</tt> - сообщения от движка к клиенту
-) Проигрывание торрент-файла по ссылке без рекламных роликов (необходимость проигрывания рекламных роликов определяет TS Engine).
+===Проигрывание торрент-файла по ссылке без рекламных роликов===
+(необходимость проигрывания рекламных роликов определяет движок).
 Для загрузки содержимого торрента используется асинхронная команда LOADASYNC.
 Торрент файл содержит один видео-файл.
 рукопожатие
+  <tt>>>HELLOBG version=3
-  <tt>>>HELLOBG
+  <<HELLOTS version=3.1.1 version_code=3003400 key=5eb1f78f http_port=6878</tt>
-  <<HELLOTS</tt>
 клиент готов принимать сообщения
+  <tt>>>READY key=123456-fd2a247d83adffed56d82cca150d5fab225f1408</tt>
-  <tt>>>READY</tt>
 пользователю доступны расширенные функции
   <tt><<AUTH 1</tt>
 загрузить торрент по ссылке
   <tt>>>LOADASYNC 467763 TORRENT http://rutor.org/download/67346 0 0 0
-  <<LOADRESP 467763 {"status": 1, "files": [["Prey%202_%20E3%202011%20Official%20Trailer_2.mp4", 0]], "infohash":
+  <<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
@@ Line 410: / Line 882: @@
 пребуферизация завершена, клиент получает ссылку для проигрывания контента
   <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>
-TS Engine загружает контент
+движок загружает контент
   <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>
-TS Engine недостаточно данных для проигрывания, начинает буферизация
+движку недостаточно данных для проигрывания, начинает буферизация
   <tt><<PAUSE
   <<STATE 3
@@ Line 437: / Line 904: @@
 буферизация завершена
   <tt><<RESUME
   <<STATE 2
@@ Line 443: / Line 909: @@
 клиент проиграл 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
@@ Line 449: / Line 914: @@
 клиент проиграл 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 &crarr;
+         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 &crarr;
+         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 &crarr;
+         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 &crarr;
+         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>

Difference between revisions of "Engine API"

Latest revision as of 11:18, 3 September 2018

Contents

Общие понятия

Схема работы API

Установление соединения

Рукопожатие

Обмен сообщениями

Завершение соединения

Сообщения

Типы сообщений

Синхронные команды

Список сообщений

Команды от клиента к движку

READY

LOADASYNC

START

Настройки транскодирования

STOP

GETPID

GETCID

GETADURL

USERDATA

SAVE

LIVESEEK

SHUTDOWN

SETOPTIONS

Команды от движка к клиенту

PLAY, PLAYAD, PLAYADI

START

PAUSE

RESUME

STOP

SHUTDOWN

События от клиента к движку

DUR

PLAYBACK

EVENT

События от движка к клиенту

STATE

INFO

STATUS

AUTH

EVENT getuserdata

EVENT cansave

EVENT showurl

EVENT livepos

EVENT download_stopped

Примеры

Проигрывание торрент-файла по ссылке без рекламных роликов

Ошибка запуска воспроизведения, отсутствует необходимая платная опция proxyServer

Воспроизведение прервано, так как отсутствует необходимая платная опция proxyServer

Navigation menu

Search

`READY`

`LOADASYNC`

`START`

`STOP`

`GETPID`

`GETCID`

`GETADURL`

`USERDATA`

`SAVE`

`LIVESEEK`

`SHUTDOWN`

`SETOPTIONS`

`PLAY, PLAYAD, PLAYADI`

`START`

`PAUSE`

`RESUME`

`STOP`

`SHUTDOWN`

`DUR`

`PLAYBACK`

`EVENT`

`STATE`

`INFO`

`STATUS`

`AUTH`

`EVENT getuserdata`

`EVENT cansave`

`EVENT showurl`

`EVENT livepos`

`EVENT download_stopped`