Skip to content

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

Information and files available for end users to request

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:

Note

If you delete the stream with episodes or the episodes database becomes unavailable, Flussonic keeps the archive sections with episodes till the episode_expiration period ends to protect these files from being suddenly deleted.

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

Note

You can use your own configuration backend instead of Flussonic Central to manage the episodes, see Managing episodes.

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

Note

Note that username and password that you should use for authorizing API requests to Flussonic Central are not the same as Flussonic's username and password. Check Central's credentials in /etc/central/central.conf. The auth token is base64-encoded string username:password.

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

Note

All DVR ranges are returned in UTC timestamps.

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.

Note

There are other ways to access the archive besides downloading. Try DVR playback instead of export.

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.

Warning

Be careful not to overwrite the existing files.

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:

Warning

You should URL encode the query parameters when creating a URL to export a DVR segment to the Amazon S3 storage. URL encoding converts the query parameters so that they can be processed correctly when transmitted over the Internet.

curl -u username:password -X POST "http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME/dvr/export?from%3D1675159800%26duration%3D4200%26path%3Ds3%3A%2F%2FAWS_ACCESS_ID%3AAWS_SECRET_KEY%40s3.amazonaws.com%2Fbucket%2Fpath%2Fto%2Ffile.mp4"

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%3D1675159800%26duration%3D4200%26path%3Ds3%3A%2F%2FAWS_ACCESS_ID%3AAWS_SECRET_KEY%40s3.amazonaws.com%2Fbucket%2Fpath%2Fto%2Ffile.mp4%26meta%3Dtrue"

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

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