379
edits
Changes
→EVENT
==Общие понятия==
ACE Stream Engine (далее - "движок") - приложение, которое обеспечивает весь функционал системы ACE Stream. Данное приложение работает в фоновом режиме и имеет минимальный графический интерфейс для изменения различных настроек.
Клиент - стороннее приложение, которое работает с движком посредством API.
На Linux используется фиксированный порт: 62062
На Windows используется динамический порт. Движок после запуска создает файл acestream.port в директории, в которой находится сам движок (файл tsengine.exe), и записывает в данный файл порт, на котором работает API. Для того, чтобы узнать порт, клиент должен прочитать указанный файл. Отсутствие данного файла указывает на то, что движок в не запущен. Путь к папке, в которую устанавливается движок, можно считать из реестра: <tt>HKEY_CURRENT_USER\Software\TorrentStream\EnginePath</tt>
Алгоритм установления соединения (Windows):
После установления соединения клиент и движок должны обменяться рукопожатием:
* клиент отсылает сообщение
<tt>HELLOBG version=''api_version''<api_version/tt>
* движок отсылает в ответ
<tt>HELLOTS version=''engine_version'' version_code=''version_code'' key=''request_key'' http_port=''http_port''<engine_version/tt>
Каждое сообщение должна должно завершаться символами перевода строки CRLF (\r\n)
;<''api_version>'': версия API, которую поддерживает клиент. Этот параметр служит для поддержки обратной совместимости новых версий движка со старыми клиентами. Текущая версия API - 3. Если клиент не указал версию, по умолчанию используется версия 1. Для всех сообщений API в документации указано, начиная с какой версии они поддерживаются.
: версия движка (например, 2.0.8)
;''version_code''
: цифровой код версии движка (например, 3003400); клиент должен использовать этот код для сравнения версий движка; код каждой новой версии всегда больше всех кодов предыдущих версий
;''request_key''
:используется для авторизации клиента с помощью [[Product key|ключа продукта]]
;''http_port''
:порт, на котором работает встроенный HTTP сервер движка
Если клиент в течение некоторого времени после отправки рукопожатия не получил ответ, соединение необходимо завершить.
После получения команды <tt>HELLOTS</tt> от движка клиент должен отослать такую команду:
<tt>READY key=''response_key''</tt>
Формирование <tt>response_key</tt> описано [[Product_key|здесь]].
===Обмен сообщениями===
Каждое сообщение представляет собой ASCII-строку, которая завершается символами перевода строки <tt>CRLF </tt> (<tt>\r\n</tt>)
Примерный алгоритм приема сообщений выглядит таким образом:
* клиент должен учитывать возможность получения нескольких сообщений одновременно (т.е. повторять предыдущий шаг, пока в буфере не будет символов CRLF)
===Завершение соединения===
Движок при завершении работы отправляет команду <tt>SHUTDOWN</tt> и закрывает сокет. При получении данной команды клиент должен прекратить обработку команд и закрыть свой сокет.
* если нет, значит ответ на команду не может быть получен
Мы не рекомендуем использовать синхронную команду <tt>LOAD</tt>, так как она подразумевает блокирование потока на стороне клиента. Эта команда является устаревшей и вместо нее следует использовать асинхронную версию <tt>LOADASYNC</tt>
Ответ на команду <tt>GETCID</tt> приходит практически мгновенно, поэтому ее использование не приводит к блокированию. Однако есть одно замечание по использованию данной команды:
Начать проигрывание acemedia-файла c:\acestream\test.acemedia:
START EFILE file%3A%2F%2F%2Fc%3A%5Cacestream%5Ctest.acemedia
</nowiki></tt>
======<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)
:В версии 3.1.5 данные настройки касаются только live-потоков.
:Если оригинал потока вещается в формате HLS, то формат вывода будет HLS независимо от настроек.
:Настройки транскодирования аудио влияют только на выдачу в формате HLS (по HTTP всегда выдается оригинальный поток)
:Если настройки формата вывода или транскодирования не передаются в команде <tt>START</tt>, то используются настройки, заданные пользователем на движке
;Примеры:
<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
Запустить в формате HLS, транскодировать все аудио-кодеки, кроме MP3, в AAC:
>> START PID 1ccf192064ee2d95e91a79f91c6097273d582827 0 output_format=hls transcode_audio=1 transcode_mp3=0
</nowiki></tt>
;Параметры
* <tt>''infohash''</tt> - infohash контента, который неободимо сохранить (значение клиент получает из сообщения LOADRESP<tt>EVENT cansave</tt>)* <tt>''index''</tt> - индекс файла, который необходимо сохранить (значение клиент получает из сообщения LOADRESP<tt>EVENT cansave</tt>)
* <tt>''path''</tt> - абсолютный путь к файлу, в который необходимо сохранить контент. Если указанный файл не существует, он будет создан. Если существует, файл будет перезаписан. Путь должен передаваться в виде urlencoded строки в кодировке UTF-8.
;Пример:
<tt><nowiki>>>SHUTDOWN</nowiki></tt>
=====<tt style="color: #009;">SETOPTIONS</tt>=====
;Версия движка
:>= 3003600
;Описание
:Сообщить движку о наборе опций, которые поддерживает клиент
;Синтаксис
<tt>SETOPTIONS name1=value1 [name2=value2 ...]</tt>
;Параметры
:name - название опции
:value - значение опции
;Список опций
:use_stop_notifications - клиент хочет получать от движка событие download_stopped с причиной остановки во время проигрывания
;Пример:
<tt><nowiki>>>SETOPTIONS use_stop_notifications=1</nowiki></tt>
====Команды от движка к клиенту====
====События от клиента к движку====
События <tt>DUR</tt> и <tt>PLAYBACK</tt> необходимо отправлять только для VOD-контента (так как live не имеет длительности).
Отправка данных событий является обязательной только при воспроизведении рекламных роликов (когда получена команда <tt>START</tt> с параметром ad=1). См. примечание к событию <tt>PLAYBACK</tt>.
При воспроизведении обычных VOD клиент не обязан отправлять данные события.
=====<tt style="color: #009;">DUR</tt>=====
;Описание
:Сообщить движку о прогрессе проигранного контента (сколько процентов проигралось).
:Данная команда особенно важна, когда идет прогрывание рекламных роликов - переход к основному контенту происходит только после того, как движок получил команду PLAYBACK 100 (т.е. после того, как клиент полность полностью проиграл рекламный ролик)
;Синтаксис
;Описание
:Отправка событий движку. С помощью этого сообщения клиент может отправлять движку события, касающиеся действий пользователя относительно воспроизведения контента (поставил на паузу, перемотал и т.п.). Отправка данных событий не обязательна - клиент может их не отправлять при отсутствии технический возможности.
;Синтаксис
<tt><nowiki><<STATE 0</nowiki></tt>
=====<tt style="color: #009;">STATUSINFO</tt>=====
;Версия API
:>= 1
;Описание
:Отобразить текстовое сообщение пользователю.
;Синтаксис
<tt>STATUS INFO ''status_stringmessage_id'';''message_text''</tt>
;Пример: <tt>'''status_string'''<nowiki><<INFO 1;Cannot find active peers<<INFO 2;Advertising video<<INFO 3;Main content<<INFO 0;Display some message</nowiki></tt> - строка описанного ниже формата
=====<tt style="color: #009;">STATUS</tt>=====
;Версия API
:>= 1
;Синтаксис <tt>STATUS main:''status_string''</tt>
;Параметры
* <tt>''status_string''</tt> - строка описанного ниже формата
Если идет проигрывание рекламного роликаосновного контента <tt>STATUS main:''status_description''</tt>
Если идет проигрывание рекламного ролика (рекламный ролик и основной контент описываются отдельно; например, рекламный ролик уже полность загружен, а основной контент проходит стадию пребуферизации): <tt>STATUS main:status_string''status_description''|ad:status_string''status_description''</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>'''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>
Пребуферизация 20%, скорость загрузки 328 Кбайт/с, подсоединено 7 пиров, загружено 5505024 байт:
<<STATUS main:prebuf;20;2723;0;0;328;0;0;7;0;5505024;0;0
Рекламный ролик полность загружен и воспроизводится, основной контент пребуферизируется (20%):<tt<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>'''total_progress'''</tt> - сколько всего закачано по данному файлу
err - выводим сообщение об ошибке
loading - Загрузка...
starting - Запуск...
dl, idle - ничего не выводим</tt>
<<AUTH 1</nowiki></tt>
=====<tt style="color: #009;">EVENTgetuserdata</tt>=====;Версия API:>= 3 ;Описание:Движок запрашивает у клиента данные пользователя (пол и возрастную группу). Такой запрос приходит при попытке что-либо проиграть, если данные о пользователе не были переданы ранее (т.е. фактически при первом после установки просмотре в ответ на команду <tt>START</tt>).:При получении этого события клиент должен запросить данные у пользователя, затем отправить их движку командой <tt>USERDATA</tt> и начать воспроизведение командой <tt>START</tt> ;Синтаксис <tt>EVENT getuserdata</tt> ;Параметры:нет ;Пример: <tt><nowiki><<EVENT getuserdata</nowiki></tt> =====<tt style="color: #009;">EVENT cansave</tt>=====;Версия API:>= 2 ;Описание:Данное событие информирует клиента о том, что контент может быть сохранен на диске в указанном пользователем месте. Например, при получении данного события клиент может отобразить кнопку "Сохранить" в пользовательском интерфейсе. При нажатии на кнопку пользователь должен будет выбрать, куда сохранять контент, после чего клиент отправит движку команду <tt>SAVE</tt> ;Синтаксис <tt>EVENT cansave infohash=''infohash'' index=''index'' format=''format''</tt> ;Параметры* <tt>''infohash''</tt> - infohash контента* <tt>''index''</tt> - номер файла, который можно сохранить* <tt>''format''</tt> - формат файла, в котором будет сохранен контент. Возможные значения:** <tt>plain</tt> - файл будет сохранен в незашифрованном виде** <tt>encrypted</tt> - файл будет сохранен в зашифрованном виде (файл должен иметь расширение .acemedia). Зашифрованные файлы могут быть воспроизведены только с помощью программного обеспечение ACE Stream (с помощью команды <tt>START EFILE</tt>). Параметры <tt>''infohash''</tt> и <tt>''index''</tt> клиент может использовать в команде <tt>SAVE</tt>, если пользователь решит сохранить контент. ;Пример: <tt><nowiki>Доступен для сохранения файл под номером 0, файл может быть сохранен в открытом виде:<<EVENT cansave infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 index=0 format=plain Файл может быть сохранен только в зашифрованном виде:<<EVENT cansave infohash=5410b27fc567c35c8547e3b69b141215ce3a1fd7 index=0 format=encrypted</nowiki></tt> =====<tt style="color: #009;">EVENT showurl</tt>=====;Версия API:>= 3 ;Описание:Клиент должен отобразить встроенный браузер и загрузить указанную ссылку. В случае, если клиент не имеет встроенного браузера, это событие можно проигнорировать. ;Синтаксис <tt>EVENT showurl type=''type'' url=''url'' [width=''width''] [height=''height'']</tt> ;Параметры* <tt>''type''</tt> - тип запроса (причина, по которой движок просит отобразить браузер). Возможные значения:** <tt>ad</tt>: отобразить рекламу (такой запрос приходит в ответ на команду <tt>GETADURL</tt>)** <tt>notification</tt>: отобразить пользователю страницу-уведомление. Такой запрос используется в том случае, если пользователя необходимо уведомить о чем-то и уведомление потребует от пользователя каких-либо действий (например, если доступ к контенту открыт только для зарегистрированных пользователей, то клиенту будет отослана ссылка на страницу, на которой пользователь сможет зарегистрироваться). Такие запросы дублируются событием <tt>INFO</tt> для того, чтобы клиенты без встроенного браузера могли отобразить пользователю текстовое уведомление.* <tt>''url''</tt> - ссылка на страницу, которую необходимо отобразить* <tt>''width''</tt> - ширина страницы (в пикселях)* <tt>''height''</tt> - высота страницы (в пикселях) Если размеры окна браузера, передаваемые в параметрах <tt>width</tt> и <tt>height</tt>, больше размера окна клиента, то клиент должен отобразить браузер на все окно. Если параметры <tt>width</tt> и <tt>height</tt> отсутствуют либо равны нулю, клиент должен отобразить браузер на все окно. ;Пример: <tt><nowiki>Показать рекламную страницу с адресом http://ad.example.com в браузере с размером окна 400x250 пикселей:<<EVENT showurl type=ad url=http://ad.example.com width=400 height=250 Отобразить на все окно браузер со страницой http://www.example.com/notification:<<EVENT showurl type=notification url=http://www.example.com/notification</nowiki></tt> =====<tt style="color: #009;">EVENT livepos</tt>=====
Описание скоро будет
=====<tt style="color: #009;">EVENT download_stopped</tt>=====
;Версия движка
:>= 3003600
;Описание
:Данное событие информирует клиента о причине остановки воспроизведения контента
;Синтаксис
<tt>EVENT download_stopped reason=''reason'' option=''option''</tt>
;Параметры
* <tt>''reason''</tt> - причина остановки; возможные значения:
** <tt>missing_option</tt>: не активирована платная опция, необходимая для воспроизведения данного контента
* <tt>''option''</tt> - идентификатор платной опции
;Пример:
<tt><nowiki>Воспроизведение остановлено, так как у пользователя отсутствует активированная платная опция proxyServer:
<<EVENT download_stopped reason=missing_option option=proxyServer</nowiki></tt>
== Примеры ==
Для загрузки содержимого торрента используется асинхронная команда LOADASYNC.
Торрент файл содержит один видео-файл.
рукопожатие
<tt>>>HELLOBGversion=3 <<HELLOTSversion=3.1.1 version_code=3003400 key=5eb1f78f http_port=6878</tt>
клиент готов принимать сообщения
<tt>>>READYkey=123456-fd2a247d83adffed56d82cca150d5fab225f1408</tt>
пользователю доступны расширенные функции
<tt><<AUTH 1</tt>
загрузить торрент по ссылке
<tt>>>LOADASYNC 467763 TORRENT http://rutor.org/download/67346 0 0 0
<<LOADRESP 467763 {"status": 1, "files": <nowiki>[["Prey%202_%20E3%202011%20Official%20Trailer_2.mp4", 0]]</nowiki>, "infohash":
узнать код плеера (например, чтобы показать его пользователю)
<tt>>>GETPID 4c78e1cf0df23b4f5a16a106829ebed710cb52e0 0 0 0
<<##36ae4c89ab45b4010b1461c513da38d007356195</tt>
начать пребуферизацию видео
<tt>>>START TORRENT http://rutor.org/download/67346 0 0 0 0</tt>
идет процесс пребуферизации
<tt><<STATE 1
<<STATUS main:prebuf;0;2147483447;0;0;0;0;0;0;0;0;0;0
пребуферизация завершена, клиент получает ссылку для проигрывания контента
<tt><<PLAY http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974
<<STATE 2</tt>
клиент отправляет длительность контента (~201 секунда)
<tt>>>DUR http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 201964</tt>
клиент информирует о том, что началось проигрывание
<tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 0</tt>
движок загружает контент
<tt><<STATUS main:dl;0;0;110;0;0;8;0;1622016;0;0
<<STATUS main:dl;0;0;128;0;0;8;0;2965504;0;0
движку недостаточно данных для проигрывания, начинает буферизация
<tt><<PAUSE
<<STATE 3
буферизация завершена
<tt><<RESUME
<<STATE 2
клиент проиграл 25% контента
<tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 25
<<STATUS main:dl;0;0;141;0;0;8;0;4898816;0;0
клиент проиграл 50% контента
<tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 50
<<STATUS main:dl;0;0;145;0;0;7;0;9404416;0;0</tt>
клиент проиграл 75% контента
<tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 75
<<STATUS main:dl;0;0;146;0;0;7;0;9568256;0;0</tt>
остановить загрузку контента
<tt>>>STOP
<<STATE 0</tt>
разорвать соединение
<tt>>>SHUTDOWN
<<SHUTDOWN</tt>
===Ошибка запуска воспроизведения, отсутствует необходимая платная опция proxyServer===
<div id="example-missing-option-on-start"></div>
В этом примере описана ситуация, когда движок не может начать воспроизведение, так как для этого требуется наличие у пользователя активированной платной опции.
В случае отсутствия платной опции необходимо уведомить пользователя о необходимости приобрести данную опцию. Это может сделать либо клиент, либо движок. Если клиент хочет самостоятельно уведомить пользователя, он должен сообщить движку о готовности получать событие <tt>download_stopped</tt> с помощью команды <tt>SETOPTIONS</tt>. Если клиент этого не сделал, то движок самостоятельно уведомит пользователя (открыв окно либо страницу в браузере).
Первый пример описывает ситуацию, когда клиент не хочет уведомлять пользователя (в этом сценарии уведомление пользователю выдаст движок):
рукопожатие
<tt>>>HELLOBG version=3
<<HELLOTS version=3.1.1 version_code=3003400 key=5eb1f78f http_port=6878
>>READY key=123456-fd2a247d83adffed56d82cca150d5fab225f1408
<<AUTH 5</tt>
старт воспроизведения
<tt>>>START PID c894b23a65d64a0dae2076d2a01ec6bface83b01 0
<<STATE 1
<<STATUS main:starting</tt>
ошибка старта
<tt><<STATE 0
<<STATUS main:idle
<<STATUS main:err;0;You need to buy Proxy Server option to continue</tt>
Второй пример описывает ситуацию, когда клиент хочет уведомлять пользователя:
рукопожатие
<tt>>>HELLOBG version=3
<<HELLOTS version=3.1.1 version_code=3003400 key=5eb1f78f http_port=6878
>>READY key=123456-fd2a247d83adffed56d82cca150d5fab225f1408
<<AUTH 5
>>SETOPTIONS use_stop_notifications=1</tt>
старт воспроизведения
<tt>>>START PID c894b23a65d64a0dae2076d2a01ec6bface83b01 0
<<STATE 1
<<STATUS main:starting</tt>
ошибка старта
<tt><<EVENT download_stopped reason=missing_option option=proxyServer
<<STATE 0
<<STATUS main:idle</tt>
===Воспроизведение прервано, так как отсутствует необходимая платная опция proxyServer===
Этот сценарий отличается от предыдущего тем, что воспроизведение начинается, но через некоторое время после старта останавливается по причине отсутствия платной опции.
рукопожатие
<tt>>>HELLOBG version=3
<<HELLOTS version=3.1.1 version_code=3003400 key=5eb1f78f http_port=6878
>>READY key=123456-fd2a247d83adffed56d82cca150d5fab225f1408
<<AUTH 5
>>SETOPTIONS use_stop_notifications=1</tt>
старт воспроизведения
<tt>>>START PID c894b23a65d64a0dae2076d2a01ec6bface83b01 0
<<STATE 1
<<STATUS main:starting
<<STATUS main:prebuf;0;0;0;0;8;0;0;1;0;16384;0;0
<<START http://127.0.0.1:6878/content/6d12f958332ef0bd258053ba1afd833ddf9b74f9/0.289607197304 stream=1
<<STATE 2</tt>
некоторое время воспроизведения идет без остановки
<tt><<STATUS main:dl;0;0;832;0;0;1;0;2392064;0;0
<<EVENT livepos last=1448977939 live_first=1448976139 pos=1448977939 ↵
first_ts=1448976139 last_ts=1448977939 is_live=1 live_last=1448977939 buffer_pieces=15
<<STATUS main:dl;0;0;1339;0;8;3;0;5242880;0;65536
<<EVENT livepos last=1448977939 live_first=1448976139 pos=1448977939 ↵
first_ts=1448976139 last_ts=1448977939 is_live=1 live_last=1448977939 buffer_pieces=15
<<STATUS main:dl;0;0;1165;0;18;3;0;5767168;0;163840
<<EVENT livepos last=1448977941 live_first=1448976141 pos=1448977941 ↵
first_ts=1448976141 last_ts=1448977941 is_live=1 live_last=1448977941 buffer_pieces=15
<<STATUS main:dl;0;0;396;0;175;4;0;35127296;0;10534912
<<EVENT livepos last=1448978010 live_first=1448976210 pos=1448978010 ↵
first_ts=1448976210 last_ts=1448978010 is_live=1 live_last=1448978010 buffer_pieces=15</tt>
остановка воспроизведения
<tt><<EVENT download_stopped reason=missing_option option=proxyServer
<<STOP
<<STATE 0
<<STATUS main:idle
<<STATUS main:err;0;Download stopped</tt>
