/mobile : Получение перекодированного видео в формате MJPEG🔗
GET /mobile : Получение перекодированного видео в формате MJPEG🔗
Доступно во всех типах лицензий.
Важно
Во всех примерах указан локальный хост (localhost). При отправке реальных запросов замените его на адрес и порт сервера, на который отправляете запрос.
Примечание
Доступно получение ответа в формате JSON.
При обращении к ресурсу video сервер Macroscop возвращает видео в исходном (полученном от камеры) формате. Для некоторых приложений и непроизводительных устройств декодирование видео в формате H.264 или отображение MJPEG-видео в оригинальном разрешении может составить проблему.
Для таких случаев Macroscop способен отдавать видео- и аудиопотоки, перекодированные силами мобильного сервера. Получение перекодированных потоков возможно с использованием запроса к ресурсу mobile.
Формат запроса🔗
Такие запросы в общем виде имеют следующий формат:
{Протокол}://{Сервер}:{Порт}/mobile?login={Логин}&password={Пароль}&channelid={Канал}&{Параметр}={Значение параметра}
Где:
Параметр |
Значение по умолчанию |
Описание |
|---|---|---|
Протокол |
http |
Сетевой протокол, выбранный для взаимодействия с сервером Macroscop. По умолчанию используется http, доступность https определяется настройками сервера |
Сервер |
— |
Доменное имя или IP адрес сервера Macroscop |
Порт |
8080 |
Сетевой порт, соответствующий выбранному Протоколу. Порты по умолчанию: 8080 для http; 18080 для https |
Логин |
— |
Имя пользователя Macroscop, от имени которого будет выполняться запрос. Пользователь должен обладать правами доступа к каналам, функциям и возможностям системы, к которым обращается в рамках запроса |
Пароль |
— |
md5-хэш пароля пользователя Macroscop. Если пароль для пользователя не задан, параметр можно оставить пустым или не указывать в запросе |
Канал |
— |
Уникальный идентификатор канала. Может быть получен при выполнении запроса Получение конфигурации системы |
Параметр |
— |
Дополнительный параметр, уточняющий сам запрос или ответ на него. В зависимости от запроса может быть допустимо применение нескольких дополнительных параметров одновременно |
Значение параметра |
— |
Значение применённого дополнительного параметра |
Предупреждение
В случае неправильного логина или пароля будет возвращена ошибка 401 (Unauthorized).
Дополнительные параметры запроса🔗
Параметр |
Значение по умолчанию |
Описание |
|---|---|---|
channel |
— |
Имя канала. Может быть получено в интерфейсе приложений и при выполнении запроса Получение конфигурации системы. Обязательный параметр, если не используется channelid или channelnum |
channelid |
— |
Уникальный идентификатор канала. Может быть получен при выполнении запроса Получение конфигурации системы. Обязательный параметр, если не используется channel или channelnum |
channelnum |
— |
Номер канала в действующей конфигурации. Выясняется путём ручного пересчёта каналов в ответе на запрос Получение конфигурации системы. Обязательный параметр, если не используется channel или channelid |
sound |
off |
Флаг получения видео- и аудиоданных канала в рамках одного соединения. Возможные значения: on – включить получение звука, off – выключить. При sound=on сервер возвращает звуковые кадры в формате G.711U, чередуя их в потоке данных с видеокадрами. Опциональный параметр |
streamtype |
Main |
Параметр, указывающий поток для получения кадров. Допустимые значения: Main — поток Основной; Alternative — поток Дополнительный 1; SecondAlternative — поток Дополнительный 2; ThirdAlternative — поток Дополнительный 3. Доступность указанных значений зависит от настроек канала |
soundformat |
g711u |
Указание формата для перекодирования потока аудио. Возможные значения: pcm, g711u, g711a, aac. Опциональный параметр |
fps |
Частота потока мобильного сервера |
Желаемая частота кадров в секунду. Фактическая частота может отличаться от запрошенной, т.к. зависит от множества параметров. Максимальная частота ограничена настройками перекодированного потока для мобильного сервера. Опциональный параметр |
oneframeonly |
false |
Флаг запроса одиночного кадра с последующим завершением соединения. Может использоваться как альтернатива запросу site. Возможные значения: true, false. Опциональный параметр |
resolutionx |
Значение Плохого качества |
Желаемая ширина кадра. Используется для подбора наиболее подходящего уровня качества для перекодированного потока. Опциональный параметр |
resolutiony |
Значение Плохого качества |
Желаемая высота кадра. Используется для подбора наиболее подходящего уровня качества для перекодированного потока. Опциональный параметр |
mode |
realtime |
Параметр, определяющий режим потока для передачи кадров. Допустимые значения: realtime (поток реального времени), archive (архив). При применении параметра mode=archive необходимо также задать параметр starttime. Опциональный параметр |
starttime |
— |
Параметр, указывающий время в архиве, для которого необходимо передать кадры. Данный параметр состоит из комбинации даты и UTC-времени в формате DD.MM.YYYY hh:mm:ss или DD.MM.YYYY hh:mm:ss.fff. Обязательный параметр при mode=archive |
speed |
1 |
Параметр, определяющий скорость воспроизведения потока. Допустимые значения: от 0.1 до 20. Опциональный параметр, применяется только при mode=archive |
withcontenttype |
false |
Параметр, определяющий необходимость указать в ответе от сервера заголовок с типом передаваемых данных. Допустимые значения: true, false. Опциональный параметр |
Примечание
При работе с запросом mobile необходимо учитывать, что под термином «поток» могут пониматься сразу две сущности:
Исходный поток видео
Перекодированный мобильным сервером поток
Под исходным потоком в данном случае понимается поток, получаемый от камеры сервером Macroscop под названием Основной (Main), Дополнительный 1 (Alternative), Дополнительный 2 (SecondAlternative) или Дополнительный 3 (ThirdAlternative). Такой поток выступает в качестве источника кадров для перекодирования мобильным сервером и указывается в параметре streamtype.
Под перекодированным потоком понимается тот же исходный поток, но уже преобразованный мобильным сервером в соответствии с собственными настройками. Именно его передаёт сервер в ответ на запрос.
Примечание
Запрос mobile для передачи потоков использует механизмы перекодирования мобильного сервера. В связи с этим получаемый поток подчиняется ограничениям, накладываемым настройками мобильного сервера.
Мобильный сервер предоставляет возможность задать до трёх уровней качества перекодируемого потока: Плохого, Среднего и Хорошего. Для каждого уровня качества можно задать собственные настройки разрешения кадра и их частоту в потоке. Для исходных потоков форматов H.264, H.265, MPEG4 и MxPEG также можно задать перекодирование с использованием только опорных кадров.
При выполнении запроса mobile сервер автоматически выбирает наиболее близкий к указанным значениям уровень качества и применяет настройки этого уровня к перекодируемому потоку: разрешение уровня в качестве разрешения потока, частота кадров уровня в качестве максимальной частоты кадров потока.
Пример 1:
Запрос включает в себя параметры resolutionx=720, resolutiony=500 и fps=20. Ближайший по параметрам уровень качества Среднее имеет разрешение 640x480 и fps=10. Полученный перекодированный поток будет полностью соответствовать уровню качества Среднее.
Пример 2:
Запрос включает в себя параметры resolutionx=600, resolutiony=460 и fps=5. Ближайшим по параметрам уровнем качества вновь является Среднее с теми же настройками. Полученный перекодированный поток в таком случае будет иметь разрешение 640x480 и fps=5.
Узнать действующие настройки мобильного сервера можно с помощью запроса на Получение конфигурации системы – параметры перекодирования перечислены в разделе MobileServerInfo.
Изменить настройки мобильного сервера можно в разделе Мобильные устройства настроек сервера в приложении Macroscop Конфигуратор.
Предупреждение
Мобильный сервер использует одни и те же настройки для передачи потоков в мобильные приложения, в веб-клиент и в ответ на запрос mobile. Изменение настроек мобильного сервера может негативно повлиять на других пользователей системы.
Мобильный сервер имеет дополнительные настройки прав доступа пользователей. Пользователю, отправляющему запрос, должно быть предоставлено право на Подключение из мобильных приложений и веб-клиента.
Узнать действующие настройки права можно с помощью запроса на Получение конфигурации системы – параметр CanGetTranscodedVideoFromMobileServer раздела UserGroup.
Изменить настройки прав можно в разделе Пользователи приложения Macroscop Конфигуратор.
Примечание
Параметры channel, channelnum и channelid являются взаимозаменяемыми, в связи с чем запрос должен содержать только один из них.
Параметр channel передаёт в качестве значения имя канала в том виде, как оно представлено в действующей конфигурации. В случае существования в конфигурации нескольких каналов с одинаковым именем или при изменении имени канала в конфигурации могут возникнуть коллизии и ошибки из-за некорректного значения параметра, соответственно.
Параметр channelnum передаёт в качестве значения порядковый номер канала в списке всех каналов действующей конфигурации. Использование данного параметра может вызвать трудности при работе с крупными системами. Помимо этого, порядковый номер канала может измениться при перемещении и удалении каналов из действующей конфигурации.
Параметр channelid передаёт в качестве значения уникальный идентификатор канала (GUID), генерирующийся при создании канала и остающийся неизменным на протяжении всего времени существования канала в конфигурации.
Во избежание возможных проблем с выполнением запросов рекомендуется использовать для указания канала параметр channelid.
Примечание
Все примеры запросов ниже составлены с использованием параметра channelid.
Разделение даты и времени осуществляется кодом («%20»).
Примеры запроса🔗
Пример запроса 1:
GET http://localhost:8080/mobile?login=root&password=&channelid=706c4691-3d90-41e3-8789-76eb9810648f
В ответ сервер начнёт передачу потока в соответствии с настройками самого низкого уровня качества из настроенных.
Пример запроса 2:
GET http://localhost:8080/mobile?login=root&password=&channelid=706c4691-3d90-41e3-8789-76eb9810648f&resolutiony=480&sound=on
В ответ сервер автоматически определит наиболее близкий по значениям настроек уровень качества и начнёт передачу потока в соответствии с его настройками.
Пример запроса 3:
GET http://localhost:8080/mobile?login=root&password=&channelid=706c4691-3d90-41e3-8789-76eb9810648f&resolutiony=480&oneframeonly=true&mode=archive&=starttime=01.01.2023%2000:00:01
В ответ сервер автоматически определит наиболее близкий по значениям настроек уровень качества и выполнит передачу одиночного кадра из архива, снятого 01 января 2023 года в 00:00:01, после чего завершит сеанс передачи.
Примечание
Если планируется воспроизводить получаемый перекодированный поток в браузере, необходимо задать для параметра withcontenttype значение true.