Manage DVR With API

Flussonic provides a set of API calls to work with DVR. It allows you to automate the work with DVR in your system. In this article, we will overview the API calls to work with DVR and learn how to use them.

Overview

Flussonic allows you to obtain data about recorded streams and to set up stream recording in the archive. Some calls are available for administrators only, and some are available for end users (with token protection).

For example, only the administrator can change the configuration or save a file locally on the server. End users can request information about a stream, JPEG thumbnails, etc.

Here is the list of available API calls to work with DVR.

Administrator-only commands

• Configure DVR for stream
• Lock DVR range and protect it from deleting by time
• Unlock DVR range and allow deleting by time
• Recorded DVR ranges
• Export DVR segment to MP4 file
• DVR usage data

Information and files available for end users to request

• Requesting JPEG thumbnails
• Generating JPEG thumbnails on demand
• Requesting MP4 video thumbnails
• Exporting MP4 file from DVR

Administrator-only commands

Administrator-only commands must be authorized. The administrator should provide the basic token or bearer token when sending an API request.

Configuring DVR for a stream

To configure DVR for a stream, use the PUT /streamer/api/v3/streams/{name} call passing the desired JSON formatted DVR configuration:

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}}'

To modify the existing DVR configuration for a stream, use the same call:

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

To prevent the record from being purged automatically from the archive, you can lock the record. Locking can be useful for the nPVR (Network Personal Video Recorder) service or just for keeping important recordings.

To enable a DVR lock, use the 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}'

Here:

• 1483971680 — start time in Unix timestamp (seconds)
• 1000 — duration in seconds

You can request a set of locked intervals by using the GET /streamer/api/v3/streams/{name}/dvr/locks call:

curl -u login:password http://FLUSSONIC-IP/flussonic/api/v3/streams/ort/dvr/locks

DVR Unlock

If the record is unlocked, it is automatically deleted according to archive cleanup settings.

To unlock a DVR record, use the Flussonic API: DELETE /streamer/api/v3/streams/{name}/dvr/locks call:

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}'

Here:

• 1483971680 — start time in Unix timestamp (seconds)
• 1000 — duration in seconds

Recorded DVR ranges

Flussonic can provide a list of DVR recorded ranges for a stream (how many intervals with recordings there are, the start of the interval and its duration).

To request a list of DVR recorded ranges, use the GET /streamer/api/v3/streams/{name}/dvr/ranges, where {name} is a stream name:

curl -u login:password http://FLUSSONIC-IP/streamer/api/v3/streams/ort/dvr/ranges

All DVR ranges are in UTC timestamps.

If you need to manually remove a DVR recording in a specified range for a stream, use DELETE /streamer/api/v3/streams/{name}/dvr/ranges, where {name} is a stream 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}'

Export DVR segment to MP4 file

Admin is allowed to export DVR segments to MP4 files and save them on the server disk or to the S3 bucket. To do that, use the 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'

Here

• from=1675159800 — start time in Unix timestamp (seconds)
• duraion=4200 — duration in seconds
• path=/storage/recording1.mp4 — the recording path.

The recording will be saved as recording1.mp4 and stored in the /storage directory on the server disk. Be careful not to overwrite the existing files.

You can also save the metadata with the MP4 file:

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'

The metadata will be stored in the udta.meta.ilst.data atom.

DVR usage data

It may be helpful to track the amount of DVR usage data.

What for?

• Defining the necessary disk size for your task.
• Building traffic distribution by the archive depth for further server load optimization.

There are a few metrics that you can track with the web_request event :

So to get the total amount of transmitted information you have to sum up the values of all the metrics above (except dvr_utc_ms):

bytes_from_ram + bytes_from_cache + bytes_from_dvr_disk + bytes_from_dvr_remote = total number of transmitted bytes.

To get information considering the usage of the DVR, add the following lines to your configuration file (/etc/flussonic/flussonic.conf):

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

where

• example_web_request_logger — the name of the process
• http://examplehost:5000/events — path to the handler or a log file.

So when the web_request event is raised, you will receive a JSON file with all the values of the metrics above.

Information and files available for end users to request

Requests available for end users can be authorized and unauthorized. We recommend always authorizing the requests to make access to the data secure. You can use the token-based authorization.

Requesting JPEG thumbnails

If you have configured thumbnails on your DVR or HTTP thumbnails, Flussonic writes the thumbnails on the disk. You need a thumbnail URL to access a thumbnail. These URLs contain the UTC time of the time frame in the video.

If you do not know the exact time frame to request a thumbnail, you can specify an approximate time frame. For example, you might know from the motion detector that something happened around some point in time, or you might know the necessary moment in time from the timeline of a player.

If no thumbnail at the specified time frame is found, Flussonic returns the thumbnail at the time frame closest to the specified one. Flussonic redirects the request and returns a ready-to-use thumbnail URL.

For example, we request a thumbnail for 2023/01/31 at 1:28:11 PM. No thumbnail is found at this time, but there is one close to this time frame. Flussonic returns Location with the time frame 2023/01/31 1:27:07 PM at which the thumbnail was found. This time frame can be used to get the necessary thumbnail.

To request the JPEG thumbnail of a stream from DVR, use the GET /{name}/{from}.jpg call, where {name} is the stream name and {from} is the time frame (UTC in seconds) after which Flussonic searches for the written JPEG or the closest keyframe to generate a JPEG file from:

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

Generating JPEG thumbnails on demand

Flussonic can generate JPEG on-the-fly. It reduces disk space and disk I/O, but be careful and protect it with authorization because it is not cheap for the CPU.

To get the JPEG thumbnail, use the GET /{name}/{from}-preview.jpg call, where {name} is the stream name and {from} is the UTC time spot (in seconds) after which Flussonic searches for the recorded JPEG or the closest keyframe to generate a JPEG file from:

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...

Requesting MP4 thumbnails

We recommend that you stop using JPEG screenshots and use our video thumbnails. Video thumbnails of DVR are accessible in a similar way as JPEG screenshots. Flussonic corrects your request if no suitable frame is available at the specified time.

To request an MP4 thumbnail for the DVR recorded stream, use the GET /{name}/{from}-preview.mp4 call, where {name} is the stream name and {from} is the UTC time spot (in seconds) after which Flussonic searches for the recorded MP4 or the closest keyframe to return an MP4 file from:

curl -v 'http://FLUSSONIC-IP/ort/1675252800-preview.mp4'
...
< HTTP/1.1 302 Found
< Location: /ort/1675252803-preview.mp4

You will receive an MP4 file consisting of one frame.

Exporting MP4, MPEG-TS file from DVR

To export a DVR video segment as an MP4 file, use the GET /{name}/archive-{from}-{duration}.mp4 call, where

• {name} is the stream name
• {from} is the start time of the DVR window in UTC seconds
• {duration} is the duration of the DVR window in seconds.

Below is the example of a request to Flussonic for exporting a one-hour part of DVR recording as an MP4 file over HTTP:

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...