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.

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 commands to work with DVR through the API.

Administrator-only commands¶

• Configure DVR for stream
• Protecting DVR sections from deletion
• 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
• Download the DVR segment to MP4 or MPEG-TS file to a local computer

Administrator-only commands¶

Administrator-only commands must be authorized. The administrator should provide the basic token or bearer token when sending an API request. In the examples below we will be passing user credentials to access the Flussonic server — username and password — divided by a colon username:password to authorize the requests.

Configuring DVR for a stream¶

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

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

Here:

• /storage — directory where the DVR recordings will be stored
• 3600 — archive depth, or the retention period after which the DVR recordings are removed from the directory

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

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

Here:

• /storage — directory where the DVR recordings will be stored.
• 172800 — archive depth, or the retention period after which the DVR recordings are removed from the directory.

Protecting DVR sections from deletion¶

Flussonic allows you to protect certain parts of the archive from automatic deletion. The episodes mechanism is used for that; an episode is a set of metadata about an archive section. All data about the episodes is stored in Flussonic Central and requested when it's time for archive cleanup. Flussonic Media Server doesn't delete archive sections with corresponding episodes, unless:

• Disk space reaches its limit in bytes or percentage.
• Episode expires.

To use the below API requests, install and configure Flussonic Central.

To create or update an episode, send the Central-API: PUT streamer/api/v3/episodes/{episode_id} request to Flussonic Central.

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

When it is no longer necessary to keep the protected archive recording, delete the episode with 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' \

You can also view a list of episodes and information about a specific episode. The corresponding requests are provided in the API schema.

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 Flussonic-API: GET streamer/api/v3/streams/{name}/dvr/ranges, where {name} is a stream name:

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

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

Here:

• 1675326686 — start time in Unix time
• 7200 — duration in seconds

Export DVR segment to MP4 file¶

Admin is allowed to export DVR segments to MP4 files and upload them to a remote location, directly to the server hard drive or the Amazon S3 bucket.

MP4 export solution¶

The main problem when exporting an archive to a file of any format is that you need to specify file size in the file header. There are several solutions to this problem, for example, a software can create a temporary file on disk or make two passes through the archive (locate the fragments on the first pass and create a file on the second).

Flussonic Media Server exports the archive to fragmented MP4 in one pass without any temporary files thanks to the features of fMP4 format. The header of an fMP4 file does not contain information about frames, so it can be generated instantly. The data itself is divided into small independent fragments, each with its own header which contains information about the frames.

Thus, loading of the exported fragment begins immediately, even if the file has not yet been generated or even recorded. And if the export is interrupted, for example due to a disconnection, the already downloaded part of the file can still be viewed.

Export DVR segment to MP4 file via a URL¶

To do that, use the Flussonic-API: POST streamer/api/v3/streams/{name}/dvr/export, where {name} is the stream name.

Required parameters:

• {from} — start time of the DVR segment in Unix time
• {duration} — duration of the DVR segment in seconds
• {path} — path to the MP4 file on the server hard drive or Amazon S3 storage

are specified in the query string.

Export DVR segment to MP4 file on the server hard drive¶

To export a DVR segment to an MP4 file and upload it directly to the server hard drive, use the following command in the terminal:

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"

Here:

• from=1675159800 — start time of the DVR segment in Unix time

• duration=4200 — duration of the DVR segment in seconds

  Note

  If duration is more than 10800 seconds (3 hours), file generation may take several minutes because Flussonic have to collect all the required archive fragments from the disks.

• path=/home/example/file.mp4 — path to the MP4 file on the server hard drive

The recording will be exported as file.mp4 and uploaded directly to the /home/example directory on the server hard drive.

Export DVR segment to MP4 file to Amazon S3¶

To export a DVR segment to an MP4 file and upload it directly to the Amazon S3 bucket, use the command below:

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

Here:

• from=1675159800 — start time of the DVR segment in Unix time

• duration=4200 — duration of the DVR segment in seconds

  Note

  If you specify rather large value for {duration}, for example greater than 10800 seconds (3 hours), it may take several minutes for the download to start. This is because Flussonic have to prepare the file for export by collecting all the required archive fragments from the disks. This process may take a long time when there are a lot of fragments.

• path=s3://AWS_ACCESS_ID:AWS_SECRET_KEY@s3.amazonaws.com/bucket/path/to/file.mp4 — path to the MP4 file in the Amazon S3 bucket with security credentials: AWS_ACCESS_ID access key ID and AWS_SECRET_KEY secret access key.

You can also save the metadata with the MP4 file by adding the meta=true to the query string:

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"

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 the 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. In the examples below we will not be authorizing the requests.

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 Streaming-API: GET /{name}/{from}.jpg call, where

• {name} — stream name
• {from} — Unix timestamp after which Flussonic searches for the written JPEG or the closest keyframe to generate a JPEG file from

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

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 Streaming-API: GET /{name}/{from}-preview.jpg call, where

• {name} — stream name
• {from} — Unix timestamp 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/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...

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 Streaming-API: GET /{name}/{from}-preview.mp4 call, where

• {name} — stream name
• {from} — Unix timestamp after which Flussonic searches for the recorded MP4 or the closest keyframe to return an MP4 file from

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

You will receive an MP4 file consisting of one frame.

Download the DVR segment to MP4 or MPEG-TS file to a local computer¶

Flussonic allows you to download a DVR segment to MPEG-TS or MP4 file to your local computer.

To download a DVR segment to MP4 file, use the Streaming-API: GET {name}/archive-{from}-{duration}.mp4 call, where

• {name} — stream name
• {from} — start time of the DVR segment in Unix time
• {duration} — duration of the DVR segment in seconds

Here are the URLs to download a one-hour DVR segment of a stream to an:

• MP4 file:

http://FLUSSONIC-IP/STREAM_NAME/archive-1525186456-3600.mp4

• MPEG-TS file:

http://FLUSSONIC-IP/STREAM_NAME/archive-1525186456-3600.ts

Opening such a URL in a web browser prompts a file to download on your local computer.

If you need to download a DVR segment with certain tracks only, specify them in the filter.tracks parameter in the query string:

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