Flussonic Media Server documentation

DVR API

Overview Anchor Anchor x2

Flussonic provides the HTTP API for accessing DVR – for obtaining data about recorded streams and for setting up recording in archive. Some actions are available for administrator only and some also for end users (with token protection).

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

Here goes the list of available HTTP API calls.

Administrator-only commands

Information available for end users to request

Configuring DVR on a stream Anchor Anchor x2

To configure DVR, you'll need to send administrator's login and password and pass the text representation of a dvr line in the Flussonic configuration file:

curl -u flussonic:pass --data 'stream ort { dvr /storage 2d; }' http://192.168.2.3:8080/flussonic/api/modify_config

Alternatively, you can use SQL API to create DVR on a stream by means of SQL queries.

To modify the configuration of DVR, use a similar call:

curl -u flussonic:pass --data 'stream ort { dvr_offline /storage 20d; }' http://192.168.2.3:8080/flussonic/api/modify_config

Stop DVR recording Anchor Anchor x2

curl -u flussonic:pass --data '' http://192.168.2.3:8080/flussonic/api/dvr_disable/ort

This stops recording DVR on a running stream ort. If a stream will be restarted, it will continue recording DVR.

Start DVR recording Anchor Anchor x2

curl -u flussonic:pass --data '' http://192.168.2.3:8080/flussonic/api/dvr_enable/ort

This starts recording DVR on the running stream ort. If a stream was configured as dvr_offline or api call dvr_disable was called before, this call will enable recording. If stream will be restarted, its recording status will switch to default specified in config.

DVR Lock Anchor Anchor x2

You can lock record to revert autodelete it from archive. This can be useful for the organization user nPVR or save important records.

curl -u flussonic:letmein! --data '{"stream":"ort","from":1483971680,"duration":1000}' http://192.168.2.3:8080/flussonic/api/dvr/lock

Where:

  • 1483971680 — start time in Unix timestamp;
  • 1000 — duration in seconds.

You can request locks from API by using an URL like this:

curl http://192.168.2.3:8080/ort/recording_status.json?from=1483970680\&to=now\&request=ranges,locks
[{"stream":"ort","ranges":[{"duration":3687,"from":1483970675},{"duration":56758,"from":1483974376},{"duration":332,"from":1484031143}],"locks":[{"duration":1004,"from":1483971680}]}]

DVR Unlock Anchor Anchor x2

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

curl -u flussonic:letmein! --data '{"stream":"ort","from":1483971680,"duration":1000}' http://192.168.2.3:8080/flussonic/api/dvr/unlock

Where:

  • 1483971680 — start time in Unix timestamp;
  • 1000 — duration in seconds.

Saving archive to MP4 Anchor Anchor x2

Admin is allowed to export MP4 from DVR and save it immediately on server disk without network transfer.

curl -u flussonic:letmein! --data '' http://192.168.2.3:8080/ort/save-mp4-1350274200-4200?file=/storage/recording1.mp4

Where:

  • 1483971680 — start time in Unix timestamp;
  • 1000 — duration in seconds.

This will save directly to file /storage/recording1.mp4

Be careful not to overwrite existing files.

It is possible to pass metadata to save to MP4 file:

curl -u flussonic:letmein! --data 'some opaque value' http://192.168.2.3:8080/ort/save-mp4-1350274200-4200?file=/storage/recording1.mp4&meta=true

Opaque metadata will be stored to the udta.meta.ilst.data atom.

Total recorded range Anchor Anchor x2

It is possible to ask Flussonic: what is the total recorded range, where is the beginning and the end of record:
$ curl http://192.168.2.3:8080/ort/recording_status.json
{"ort":{"from":1525186456,"to":1526910900}}

All times here are UTC timestamps.

Recorded status report Anchor Anchor x2

You can ask Flussonic what time ranges are recorded on the disk:

curl -v 'http://192.168.2.3:8080/ort/recording_status.json?from=1525186456'
...
< HTTP/1.1 200 OK
...
< Server: Flussonic
< X-Route-Time: 83
< X-Run-Time: 3391
< Content-Type: application/json

[{"stream":"ort","warning":"too_big_range","ranges":[{"duration":28800,"from":1525183200},{"duration":7200,"from":1525219200},{"duration":3600,"from":1525233600},{"duration":10800,"from":1525240800},{"duration":43200,"from":1525255200},{"duration":7200,"from":1525309200},{"duration":39600,"from":1525323600},{"duration":7200,"from":1525377600},{"duration":3600,"from":1525392000},{"duration":3600,"from":1525402800}

Here you get a forced brief response. Take a look at "warning":"too_big_range". It happens because the request did not have the force_detailed option and the total range from from to now is longer than 4 days.

The idea is that usually you do not need to have precise information about continuous recorded periods when you request several days and more. The usage of such precise information is limited. That's why Flussonic sends you information that is not precise, but cheap to obtain.

If you still want to request a very detailed information for a very long period of time, add the force_detailed option:

curl -v 'http://192.168.2.3:8080/ort/recording_status.json?from=1525186456&request=ranges,force_detailed'
...
< HTTP/1.1 200 OK
...
< Server: Flussonic
< X-Route-Time: 83
< X-Run-Time: 174210
< Content-Type: application/json

[{"stream":"ort","ranges":[{"duration":24179,"from":1525186456},{"duration":4788,"from":1525221374},{"duration":0,"from":1525236971},{"duration":131,"from":1525244207},{"duration":2018,"from":1525244378},{"duration":656,"from":1525246742},{"duration":0,"from":1525249845},{"duration":1169,"from":1525249848},{"duration":27216,"from":1525257917},{"duration":10177,"from":1525285203},{"duration":0,"from":1525296286},{"duration":151,"from":1525311266},{"duration":314,"from":1525311872},{"duration":2359,"from":1525312194},{"duration":7,"from":1525325359},{"duration":0,"from":1525328402},{"duration":533,"from":1525328405},{"duration":
...

You can see that the warning disappeared but the total runtime is 50 times longer.

Why you might not need precise information:

If you want to draw a timeline, then on a 1920px wide screen the duration of a week means that 1 pixel is responsible for about 5 minutes. One hour will be about 10-11 pixels wide. No need to spend 50 times more on server to draw UI more precise in these 10 pixels.

If you request short duration, it will be easier:

curl -v 'http://192.168.2.3:8080/ort/recording_status.json?from=1525186456&to=1525272856&request=ranges'
...
< HTTP/1.1 200 OK
...
< Server: Flussonic
< X-Route-Time: 83
< X-Run-Time: 20723
< Content-Type: application/json

[{"stream":"ort","ranges":[{"duration":24179,"from":1525186456},{"duration":4788,"from":1525221374},{"duration":0,"from":1525236971},{"duration":131,"from":1525244207},{"duration":2018,"from":1525244378},{"duration":656,"from":1525246742},{"duration":0,"from":1525249845},{"duration":1169,"from":1525249848},{"duration":14941,"from":1525257917}]}]

It takes more time than brief information, but less than a full request.

The request parameter

You can specify the following values in the request parameter:

  • ranges — returns the list of continuous recorded periods in DVR. This information may change if your Flussonic is right now replicating information from some source.
  • brief_thumbnails — returns the list of UTC of screenshots saved in DVR. We don't recommend to use it anymore, because it is better to use approximate GMT time to request JPEG thumbnails — read later on this page.
  • force_detailed — forces sending explicit and precise information even on very long time range.
  • hour_bitmap — sends brief recorded information as a large string with bit map of recorded hours. It is the most compact way to fetch estimated DVR information. Not working if ranges is specified.
  • locks — asks for the list of DVR locks.
  • motion_log — requests events from motion detector.

To get various data in one request, specify these values separated by comma, for example, request=ranges,hour_bitmap.

Motion detector marks Anchor Anchor x2

Motion detector marks the start and end time of an event received.

You can request when motion started and for how long it lasted by using recording_status.json with the parameter request=motion_log. With the from and to parameters specify the time period you are interested in.

curl http://192.168.2.3:8080/cam_office/recording_status.json?from=1528144663&to=1528148263&request=motion_log

[{"stream":"cam10","motion_log":[{"data":{"duration":42,"start":1528145203},"subtype":"range","type":"motion"}]}]

Requesting JPEG screenshots by GMT time Anchor Anchor x2

If you have configured thumbnails on your DVR or HTTP thumbnails, Flussonic writes the thumbnails on the disk, and you can access them by special URLs. These URLs contain the GMT time of a moment in video.

Flussonic allows finding JPEG thumbnails by an approximate time. For example, you might know from the motion detector that something happened around some point in time or you might know the necessary time from the timeline in a player.

It is resource-intensive to get the exact GMT time for each screenshot because it requires getting the list of screenshots with UTC time and converting it to GMT. Flussonic helps you here - it can find the nearest GMT time to the time that you specify when a thumbnail was created.

So, in this API, Flussonic corrects your request if you do not know the exact URL of a thumbnail, and returns a ready-to-use exact URL.

For example, we request a screenshot by this time: 2018/05/02/06/59/38. At this time no thumbnail was created, but there is one near it. Flussonic returns Location with the correct time 2018/05/02/07/00/40, which we use to get a screenshot:

curl -v 'http://192.168.2.3:8080/ort/2018/05/02/06/59/38.jpg'
...
< HTTP/1.1 302 Found
< Location: /ort/2018/05/02/07/00/40.jpg

curl -v 'http://192.168.2.3:8080/ort/2018/05/02/07/00/40.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...

Generating JPEG screenshots on demand Anchor Anchor x2

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

curl -v 'http://192.168.2.3:8080/ort/2018/05/02/07/00/40-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 video screenshots Anchor Anchor x2

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

curl -v 'http://192.168.2.3:8080/ort/2018/05/02/06/59/38-preview.mp4'
...
< HTTP/1.1 302 Found
< Location: /ort/2018/05/02/07/00/40-preview.mp4

curl -v 'http://192.168.2.3:8080/ort/2018/05/02/07/00/40-preview.mp4'
...
< HTTP/1.1 200 OK
...
< Content-Length: 8756
< Content-Type: vide/mp4
< Last-Modified: Wed, 02-May-2018 07:00:40 GMT
< X-Thumbnail-Utc: 1525244440

You will receive an MP4 file consisting of one frame.

Exporting MP4, MPEG-TS file from DVR Anchor Anchor x2

Example of a request to Flussonic for sending a part of one hour of DVR as an MP4 file over HTTP:

curl -v http://192.168.2.3:8080/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 big mp4...