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 выполняет экспорт в MP4 за один проход архива без формирования временных файлов благодаря индексу архива. Flussonic всегда знает, где хранятся фрагменты архива и какого они размера, поэтому может быстро рассчитать размер экспортируемого файла и записать его в заголовок. Это сокращает время на формирование файла и позволяет начать загрузку практически мгновенно — сначала отправляется заголовок, затем данные.

Warning

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

Чтобы не ждать начала загрузки, попробуйте использовать проигрывание 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-кодирование преобразовывает символы параметров в строке запроса таким образом, чтобы они корректно передавались через Интернет. Для этого используйте параметр --data-urlencode в команде curl как в примере ниже.

curl -u username:password -X POST --data-urlencode "from=1675159800" --data-urlencode "duration=4200" --data-urlencode "path=s3://AWS_ACCESS_ID:AWS_SECRET_KEY@s3.amazonaws.com/bucket/path/to/file.mp4" http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME/dvr/export

Здесь:

  • 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=1675159800&duration=4200&path=/home/example/file.mp4&meta=true"

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

Информация об использовании DVR

Знать информацию об использовании DVR может быть полезно.

В чём ценность этой информации? Для чего она нужна?

  • определение дискового пространства, необходимого для записи и хранения потоков;
  • построение распределений трафика по глубине архива для дальнейшей оптимизации нагрузки на разные серверы.

Ниже указаны метрики, которые вы можете отслеживать. Все они отображаются в файле JSON при вызове события web_request:

Метрика Описание
bytes_from_ram Количество байт прочитанных из памяти и отданных пользователю
bytes_from_dvr_cache Количество байт прочитанных из кэша и отданных пользователю
bytes_from_dvr_disk Количество байт прочитанных с диска и отданных пользователю
bytes_from_dvr_remote Количество байт прочитанных с внешнего DVR-сервера и отданных пользователю
dvr_utc_ms Время начала запрашиваемого фрагмента архива (Unix-время, мс)

Чтобы получить общее количество переданной информации в байтах, необходимо просуммировать значения вышеприведённых метрик (за исключением dvr_utc_ms):

bytes_from_ram + bytes_from_cache + bytes_from_dvr_disk + bytes_from_dvr_remote = общее количество переданных байт.

Для того, чтобы настроить получение значений метрик, необходимо добавить в конфигурационный файл (/etc/flussonic/flussonic.conf) следующие строки:

event_sink example_web_request_logger {
  url http://examplehost:5000/events;
  only event=web_request;
}

где:

  • example_web_request_logger — имя процесса,
  • http://examplehost:5000/events — путь до кастомного обработчика либо до файла журнала.

Теперь когда будет вызываться событие web_request, вам будет отправляться файл JSON со значениями указанных метрик.

Note

Если вы попытаетесь получить значения метрик для потокового вещания, то получите следующие значения: dvr_utc_ms = null, bytes_from_ram = size, bytes_from_cache = 0, bytes_from_dvr_disk = 0, bytes_from_dvr_remote = 0 по той причине, что указанные метрики относятся исключительно к использованию DVR.

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

При вызове команд, доступных пользователям, необходима проверка прав доступа. Это необходимо, чтобы обеспечить безопасный доступ клиентов к данным. Для этого вы можете использовать авторизацию по токену. В примерах ниже мы не будем использовать авторизацию при запросах к 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