Работа с DVR через API
Flussonic предоставляет набор методов для работы с DVR через API. Это позволяет автоматизировать работу с DVR в рамках вашей инфраструктуры. Эта статья посвящена обзору методов API и примерам их использования для управления DVR и работы с ним.
Обзор API-методов для работы с DVR
Flussonic позволяет получать данные о записанном потоке, настраивать запись архива и т.д. Часть команд доступна только администратору, а другая часть доступна также и пользователям (с использованием защиты с помощью токенов).
Администратор может изменять настройки архива или сохранить его в виде файла на диск. Пользователи могут запрашивать информацию о потоке, JPEG-скриншоты и т.п.
Ниже приведены команды для работы с DVR через API для администраторов и пользователей.
Команды, доступные только администратору
- Настроить DVR для потока
- Заблокировать запись в интервале времени интервал с целью защиты от удаления
- Разблокировать запись в интервале времени, чтобы ее можно было удалить
- Фрагменты записей DVR
- Сохранение фрагмента записи архива в виде MP4-файла
- Информация об использовании DVR
Команды, доступные пользователям
- Получение JPEG-скриншотов из архива по времени UTC
- Генерация JPEG-скриншотов по запросу
- Получение видео-скриншотов
- Экспорт архива в MP4
Команды, доступные только администратору
Запросы, доступные только администратору, должны быть авторизованы. Администратору необходимо передать basic-токен или bearer-токен при отправке запроса.
Настройка DVR для потока
Для настройки DVR для потока используйте запрос PUT /streamer/api/v3/streams/{name} и передайте необходимую конфигурацию в формате JSON:
curl -u login:password -X PUT "http://FLUSSONIC-IP/streamer/api/v3/streams/ort" \
> -H "Content-Type: application/json" \
> --data '{"dvr": {"root":"/storage","expiration":3600}}'
Чтобы изменить настройки DVR для потока, используйте такой же запрос:
curl -u login:password -X PUT "http://FLUSSONIC-IP/streamer/api/v3/streams/ort" \
> -H "Content-Type: application/json" \
> --data '{"dvr": {"root":"/storage","expiration":172800}}'
DVR Lock
Вы можете заблокировать запись, чтобы защитить её от автоматического удаления из архива. Это может быть полезно для организации услуги nPVR (Network Personal Video Recorder) или для сохранения важных данных.
Чтобы включить блокировку записи, используйте запрос POST /streamer/api/v3/streams/{name}/dvr/locks:
curl -u login:password -X POST "http://FLUSSONIC-IP/streamer/api/v3/streams/ort/dvr/locks" \
> -H "Content-Type: application/json" \
> --data '{"from": 1483971680, "duration": 1000}'
Здесь:
1483971680— время начала интервала в Unix timestamp (в секундах),1000— продолжительность в секундах.
Note
Если для архива настроена опция copy для копирования записи, например, на Amazon S3, то /api/dvr/lock не работает.
Вы можете получить список заблокированных записей с помощью запроса GET /streamer/api/v3/streams/{name}/dvr/locks:
curl -u login:password http://FLUSSONIC-IP/flussonic/api/v3/streams/ort/dvr/locks
DVR Unlock
Если запись разблокировать, то она будет автоматически удалена в соответствии с настройками очистки архива.
Чтобы разблокировать запись, используйте запрос DELETE /streamer/api/v3/streams/{name}/dvr/locks:
curl -u login:password -X DELETE "http://FLUSSONIC-IP/streamer/api/v3/streams/ort/dvr/locks" \
> -H "Content-Type: application/json" \
> --data '{"from": 1483971680, "duration": 1000}'
Здесь:
1483971680— время начала в Unix timestamp (в секундах),1000— продолжительность в секундах.
Фрагменты записей DVR
Flussonic может вернуть список временных интервалов фрагментов записей и информацию о времени начала фрагмента и продолжительности фрагмента в каждом из них.
Чтобы получить список временных интервалов фрагментов записей DVR, используйте запрос GET /streamer/api/v3/streams/{name}/dvr/ranges, где {name} — имя потока:
curl -u login:password http://FLUSSONIC-IP/streamer/api/v3/streams/ort/dvr/ranges
Время указано в UTC timestamp.
Если вам необходимо удалить фрагмент архива с определенным интервалом вручную, используйте запрос DELETE /streamer/api/v3/streams/{name}/dvr/ranges, где {name} — имя потока:
curl -u login:password -X DELETE http://FLUSSONIC-IP/streamer/api/v3/streams/ort/dvr/ranges \
> -H 'Content-Type: application/json' \
> --data '{"from":1675326686, "duration":7200}'
Сохранение фрагмента записи архива в виде MP4-файла
Администратор может экспортировать фрагменты архива в виде MP4-файлов и хранить их на локальном диске на сервере или в бакете S3. Чтобы скачать фрагмент архива в виде MP4-файла, используйте запрос POST /streamer/api/v3/streams/{name}/dvr/export:
curl -u login:password -X POST 'http://FLUSSONIC-IP/streamer/api/v3/streams/ort/dvr/export?from=1675159800&duration=4200&path=/storage/recording1.mp4'
Здесь:
from=1675159800— время начала в Unix timestamp,duraion=4200— продолжительность в секундах,path=/storage/recording1.mp4— путь до файла с сохранённой записью.
Указанный фрагмент архива будет сохранен в виде MP4-файла recording1.mp4 в каталоге /storage. Будьте осторожны при указании имени файла, чтобы не затереть существующие файлы.
Можно также сохранять и метаданные MP4-файла:
curl -u login:password -X POST 'http://FLUSSONIC-IP/streamer/api/v3/streams/ort/dvr/export?from=1675159800&duration=4200&path=/storage/recording1.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-время, время по UTC, в мс) |
Чтобы получить общее количество переданной информации в байтах, необходимо просуммировать значения вышеприведённых метрик (за исключением 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.
Команды, доступные пользователям
При вызове команд, доступных пользователям, необходима проверка прав доступа. Это необходимо, чтобы обеспечить безопасный доступ клиентов к данным. Вы можете использовать авторизацию по токену.
Получение 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, используйте запрос GET /{name}/{from}.jpg, где {name} — имя потока, а {from} — момент времени в UTC (в секундах), после которого Flussonic ищет записанный JPEG-скриншот или ближайший ключевой кадр для генерации JPEG-скриншота:
curl -v 'http://FLUSSONIC-IP/ort/1675171691.jpg'
...
< HTTP/1.1 302 Found
< Connection: keep-alive
< Date: Tue, 31 Jan 2023 13:28:11 GMT
...
< Location: /ort/1675171627.jpg
Генерация JPEG-скриншотов по запросу
Flussonic может создавать JPEG-скриншоты на лету. При этом экономятся ресурсы диска. Нагрузка на процессор будет ощутимая, поэтому защищайте сервер с помощью авторизации доступа. А лучше используйте видео-скриншоты, если нет необходимости именно в JPEG.
Чтобы получить JPEG-скриншот, используйте запрос GET /{name}/{from}-preview.jpg, где {name} — имя потока, а {from} — момент времени в UTC (в секундах), после которого Flussonic ищет записанный JPEG-скриншот или ближайший ключевой кадр для генерации JPEG-скриншота:
curl -v 'http://192.168.2.3:80/ort/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 потока, используйте запрос GET /{name}/{from}-preview.mp4, где {name} — имя потока, а {from} — момент времени (в секундах UTC), после которого Flussonic ищет записанный MP4-скриншот или ближайший ключевой кадр для возвращения MP4-скриншота:
curl -v 'http://FLUSSONIC-IP/ort/1675252800-preview.mp4'
...
< HTTP/1.1 302 Found
< Location: /ort/1675252803-preview.mp4
Flussonic вернёт MP4-файл, состоящий из одного кадра.
Экспорт части архива в MP4
Чтобы экспортировать часть архива DVR как MP4-файл, используйте запрос GET /{name}/archive-{from}-{duration}.mp4, где
{name}— имя потока,{from}— момент начала сегмента записи (в секундах UTC),{duration}— продолжительность сегмента записи (в секундах UTC).
Ниже показан пример запроса к Flussonic на получение части архива длиной в 1 час в качестве MP4-файла по сети:
curl -v http://FLUSSONIC-IP/ort/archive-1525186456-3600.mp4
...
< HTTP/1.1 200 OK
< Content-Type: video/mp4
< X-Session: a666873ba918d02f81f9b39e336906d85bdbac20
< Content-Disposition: attachment; filename=ort_1525186456_3600.mp4
..
< X-Prepare-Percent: 70
< X-Prepare-Percent: 80
< Content-Length: 81773187
< X-Prepare-Time: 27487
...here goes the mp4 file...