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

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

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

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

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

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

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

• Настроить DVR для потока
• Защита участков DVR от удаления
• Фрагменты записей DVR
• Экспорт фрагмента записи архива в виде MP4-файла
• Информация об использовании DVR

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

• Получение JPEG-скриншотов из архива по времени UTC
• Генерация JPEG-скриншотов по запросу
• Получение видео-скриншотов
• Скачивание фрагмента записи архива в виде файла MP4 или MPEG-TS

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

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

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

Для настройки DVR для потока используйте запрос 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 не удаляет участки архива с эпизодами до тех пор, пока:

• На диске не становится критически мало места в байтах или процентах.
• Глубина записи эпизода не превышает своего предела episodes_expiration.

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

Чтобы создать или обновить эпизод, отправьте в Flussonic Central запрос 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}'

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

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

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

Подробнее об использовании API Flussonic Central читайте в статье Flussonic Central API.

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

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

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

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

Если вам необходимо удалить фрагмент архива с определенным интервалом вручную, используйте запрос 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-файла, используйте запрос 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.

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

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

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:

Чтобы получить общее количество переданной информации в байтах, необходимо просуммировать значения вышеприведённых метрик (за исключением 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 со значениями указанных метрик.

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

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