Skip to content

Работа с DVR через API

Flussonic предоставляет набор методов для работы с DVR через API. Это позволяет автоматизировать работу с DVR в рамках вашей инфраструктуры. Эта статья посвящена обзору методов API и примерам их использования для управления DVR и работы с ним.

Обзор API-методов для работы с DVR

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

Администратор может изменять настройки архива или сохранить его в виде файла на диск. Пользователи могут запрашивать информацию о потоке, JPEG-скриншоты и т.п.

Ниже вы можете увидеть команды для работы с DVR через API для администраторов и пользователей.

Команды, доступные только администратору

Команды, доступные пользователям

Команды, доступные только администратору

Запросы, доступные только администратору, должны быть авторизованы. Администратору необходимо передать basic-токен или bearer-токен при отправке запроса. В примерах ниже мы будем использовать простую авторизацию с указанием имени пользователя и пароля для входа на сервер Flussonic, разделённых двоеточием, вида username:password.

Настройка DVR для потока

Для настройки DVR для потока используйте запрос Flussonic-API: PUT /streamer/api/v3/streams/{name} и передайте необходимую конфигурацию в формате JSON:

curl -u username:password -X PUT "http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME" \
> -H "Content-Type: application/json" \
> --data '{"dvr": {"root":"/storage","expiration":3600}}'

, где:

  • /storage — директория, где будут храниться записи DVR,
  • 3600 — глубина архива, или период хранения записей, после которого они будут удалены из директории.

Чтобы изменить настройки DVR для потока, используйте такой же запрос:

curl -u username:password -X PUT "http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME" \
> -H "Content-Type: application/json" \
> --data '{"dvr": {"root":"/storage","expiration":172800}}'

, где:

  • /storage — директория, где будут храниться записи DVR,
  • 172800 — глубина архива, или период хранения записей, после которого они удаляются из директории.

Защита участков DVR от удаления

В Flussonic реализован механизм защиты определенных частей архива от автоматического удаления. Для защиты записей используются эпизоды — набор метаданных об участке архива. Информация об эпизодах хранится в Flussonic Central и запрашивается при очистке архива. Flussonic Media Server не удаляет участки архива с эпизодами до тех пор, пока:

Note

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

Чтобы использовать приведенные ниже вызовы API, установите и настройте Flussonic Central.

Note

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

Чтобы создать или обновить эпизод, отправьте в Flussonic Central запрос Central-API: PUT streamer/api/v3/episodes/{episode_id}.

curl -u username:password --request PUT 'http://127.0.0.1:9019/streamer/api/v3/episodes/1' \
-H "Content-Type: application/json" \
--data '{"episode_id": 1,"media": "test-879c595839","opened_at": 1686808712,"updated_at": 1686808712,"closed_at": 1686823112}'

Когда надобность в хранении защищенного участка отпадет, удалите эпизод Central-API: DELETE streamer/api/v3/episodes/{episode_id}.

curl -u username:password --request DELETE 'http://127.0.0.1:9019/streamer/api/v3/episodes/1' \

Note

Обратите внимание, что логин и пароль, которые нужно использовать для авторизации API-запросов к Flussonic Central, отличаются от логина и пароля администратора Flussonic. Логин и пароль Central указаны в файле /etc/central/central.conf. Токен авторизации — это строка username:password, закодированная в base64.

Вы также можете просматривать список имеющихся эпизодов и информацию о конкретном эпизоде. Соответствующие запросы отражены в схеме API.

Фрагменты записей DVR

Flussonic может вернуть список временных интервалов фрагментов записей и информацию о времени начала фрагмента и продолжительности фрагмента в каждом из них.

Чтобы получить список временных интервалов фрагментов записей DVR, используйте запрос Flussonic-API: GET streamer/api/v3/streams/{name}/dvr/ranges, где {name} — имя потока:

curl -u username:password http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME/dvr/ranges

Note

Время в интервалах возвращается в формате Unix-времени.

Если вам необходимо удалить фрагмент архива с определенным интервалом вручную, используйте запрос Flussonic-API: DELETE streamer/api/v3/streams/{name}/dvr/ranges, где {name} — имя потока:

curl -u username:password -X DELETE http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME/dvr/ranges \
> -H 'Content-Type: application/json' \
> --data '{"from":1675326686, "duration":7200}'

, где:

  • 1675326686 — время начала фрагмента архива в формате Unix-времени,
  • 7200 — продолжительности фрагмента в секундах.

Экспорт фрагмента записи архива в виде MP4-файла

Администратор может экспортировать фрагменты архива в виде MP4-файлов и загружать их по ссылке на удаленный компьютер или в хранилище Amazon S3, а также хранить их на диске сервера.

Особенности экспорта в MP4-файл

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

Flussonic Media Server выполняет экспорт в fragmented MP4 за один проход архива без формирования временных файлов благодаря особенностям формата fMP4. Заголовок fMP4-файла не содержит информации о кадрах, поэтому его можно сформировать мгновенно. Сами данные разбиваются на небольшие независимые фрагменты каждый со своим заголовком, где уже содержится информация о кадрах.

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

Note

Есть и другие способы доступа к архиву, кроме скачивания. Попробуйте использовать проигрывание DVR вместо экспорта.

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

Чтобы скачать фрагмент архива в виде MP4-файла, используйте запрос Flussonic-API: POST streamer/api/v3/streams/{name}/dvr/export, где {name} — имя потока.

Обязательные параметры указываются в строке запроса:

  • {from} — время начала фрагмента записи архива в формате Unix-времени.
  • {duration} — продолжительность фрагмента записи в секундах.
  • {path} — путь до MP4-файла на диске сервера или хранилище Amazon S3.

Экспорт фрагмента записи архива в виде MP4-файла на диск сервера

Чтобы экспортировать фрагмент архива в виде MP4-файла и сохранить его на диске сервера, используйте команду ниже:

curl -u username:password -X POST "http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME/dvr/export?from=1675159800&duration=4200&path=/home/example/file.mp4"

Здесь:

  • from=1675159800 — время начала фрагмента записи архива в формате Unix-времени.
  • duration=4200 — продолжительность фрагмента записи в секундах.
  • path=/home/example/file.mp4 — путь до MP4-файла на диске сервера.

Указанный фрагмент архива будет сохранен в виде MP4-файла file.mp4 в каталоге /home/example.

Warning

Будьте осторожны при указании имени файла, чтобы не затереть существующие.

Экспорт фрагмента записи архива в виде MP4-файла в Amazon S3

Чтобы экспортировать фрагмент записи архива в виде MP4-файла и сохранить его в хранилище Amazon S3, используйте следующую команду:

Warning

При формировании ссылки для экспорта фрагмента архива в хранилище Amazon S3 вам необходимо URL-кодирование. URL-кодирование преобразовывает символы параметров в строке запроса таким образом, чтобы они корректно передавались через Интернет.

curl -u username:password -X POST "http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME/dvr/export?from%3D1675159800%26duration%3D4200%26path%3Ds3%3A%2F%2FAWS_ACCESS_ID%3AAWS_SECRET_KEY%40s3.amazonaws.com%2Fbucket%2Fpath%2Fto%2Ffile.mp4"

Здесь:

  • from=1675159800 — время начала фрагмента записи архива в формате Unix-времени.
  • duration=4200 — продолжительность фрагмента записи в секундах.
  • path=s3://AWS_ACCESS_ID:AWS_SECRET_KEY@s3.amazonaws.com/bucket/path/to/file.mp4 — путь до MP4-файла в хранилище Amazon S3 с данными вашей учётной записи: идентификатором ключа доступа AWS_ACCESS_ID и секретным ключом доступа AWS_SECRET_KEY.

Можно также сохранять и метаданные MP4-файла, добавив meta=true в строку запроса:

curl -u username:password -X POST "http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME/dvr/export?from%3D1675159800%26duration%3D4200%26path%3Ds3%3A%2F%2FAWS_ACCESS_ID%3AAWS_SECRET_KEY%40s3.amazonaws.com%2Fbucket%2Fpath%2Fto%2Ffile.mp4%26meta%3Dtrue"

Метаданные будут записаны в атом udta.meta.ilst.data.

Команды, доступные пользователям

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

Получение JPEG-скриншотов из архива по времени UTC

Когда вы включили скриншоты для DVR или по URL, Flussonic начинает создавать и писать скриншоты на диск, а вы можете получать эти скриншоты по специальным URL. Эти URL содержат время того момента, в который был получен скриншот.

Flussonic может находить JPEG-скриншоты с указанием приблизительного момента времени. Например, вы можете узнать из датчика движения, что в районе определённого времени записаны необходимые вам события, или вы можете знать необходимое время, посмотрев его на таймлайне в плеере.

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

Например, запросим скриншот от 31.01.2023 13:28:11. Именно в этот момент времени скриншот записан не был, но есть скриншот в момент времени, близкий к указанному. Flussonic возвращает Location с указанием момента времени, в который был найден скриншот (в нашем примере это 31.01.2023 13:27:07). Это время которое мы можем использовать далее для доступа к JPEG- скриншотом.

Чтобы запросить JPEG-скриншот потока из DVR, используйте запрос Streaming-API: GET /{name}/{from}.jpg, где:

  • {name} — имя потока,
  • {from} — момент времени в формате Unix-времени, после которого Flussonic ищет записанный JPEG-скриншот или ближайший ключевой кадр для генерации JPEG-скриншота.
curl -v 'http://FLUSSONIC-IP/STREAM_NAME/1675171691.jpg'
...
< HTTP/1.1 302 Found
< Connection: keep-alive
< Date: Tue, 31 Jan 2023 13:28:11 GMT
...
< Location: /STREAM_NAME/1675171627.jpg

Генерация JPEG-скриншотов по запросу

Flussonic может создавать JPEG-скриншоты на лету. При этом экономятся ресурсы диска. Нагрузка на процессор будет ощутимая, поэтому защищайте сервер с помощью авторизации доступа. А лучше используйте видео-скриншоты, если нет необходимости именно в JPEG.

Чтобы получить JPEG-скриншот, используйте запрос Streaming-API: GET /{name}/{from}-preview.jpg, где:

  • {name} — имя потока,
  • {from} — момент времени в формате Unix-времени, после которого Flussonic ищет записанный JPEG-скриншот или ближайший ключевой кадр для генерации JPEG-скриншота.
curl -v 'http://192.168.2.3:80/STREAM_NAME/1675179644-preview.jpg'
...
< HTTP/1.1 200 OK
...
< Content-Length: 5738
< Content-Type: image/jpeg
< Last-Modified: Wed, 02-May-2018 07:00:40 GMT
< X-Thumbnail-Utc: 1525244440
...here goes jpeg...

Получение MP4 видео-скриншотов

Мы рекомендуем использовать видео-скриншоты вместо JPEG-скриншотов. Видео-скриншоты архива получают почти так же, как JPEG-скриншоты. Flussonic исправляет URL, если по запрошенному URL нет подходящего кадра для создания скриншота.

Чтобы получить MP4 видео-скриншот из записанного в архив DVR потока, используйте запрос Streaming-API: GET /{name}/{from}-preview.mp4, где:

  • {name} — имя потока,
  • {from} — момент времени в формате Unix-времени, после которого Flussonic ищет записанный MP4-скриншот или ближайший ключевой кадр для возвращения MP4-скриншота.
curl -v 'http://FLUSSONIC-IP/STREAM_NAME/1675252800-preview.mp4'
...
< HTTP/1.1 302 Found
< Location: /STREAM_NAME/1675252803-preview.mp4

Flussonic вернёт MP4-файл, состоящий из одного кадра.

Скачивание фрагмента записи архива в виде файла MP4 или MPEG-TS

Flussonic позволяет скачать фрагмент записи архива DVR в формате файла MP4 или MPEG-TS на свой компьютер.

Чтобы скачать фрагмент архива в виде MP4-файла, используйте запрос Streaming-API: GET {name}/archive-{from}-{duration}.mp4, где:

  • {name} — имя потока,
  • {from} — время начала фрагмента записи в формате Unix-времени,
  • {duration} — продолжительность фрагмента записи в секундах.

Ниже показаны примеры URL для загрузки фрагмента архива потока длиной в один час в:

  • MP4:
http://FLUSSONIC-IP/STREAM_NAME/archive-1525186456-3600.mp4
  • MPEG-TS:
http://FLUSSONIC-IP/STREAM_NAME/archive-1525186456-3600.ts

Вставьте подобную ссылку в браузер и начнётся загрузка файла на компьютер.

Если вам необходимо скачать фрагмент архива с определёнными дорожками, укажите их в параметре filter.tracks в строке запроса:

http://FLUSSONIC-IP/STREAMNAME/archive-1525186456-4200.mp4?filter.tracks=v1a1