Skip to content

Archive segment export

A segment of the recorded archive downloads as a single MP4 file that opens in regular players, for example VLC. The file is assembled from the archive at request time; nothing has to be prepared in advance.

Export works only for streams with recording enabled (dvr).

Export URL

http://server/streaming/v/<stream>/archive-<from>-<duration>.mp4
  • from — segment start, UTC in seconds;
  • duration — segment duration in seconds.

For example, archive-1789546139-600.mp4 is ten minutes of archive starting at the given moment.

If the stream requires authorization, pass the token the same way as for archive playback, for example ?token=<token> — see Authorization.

Track selection

Without parameters the file gets all video and audio tracks of the segment. Select tracks with the filter.tracks parameter:

http://server/streaming/v/<stream>/archive-<from>-<duration>.mp4?filter.tracks=v1a1

Tracks are named as in playlists: v1, v2 are video, a1 is audio. If no video track ends up in the file, it is served as audio/mp4.

Subtitles and service tracks are not supported in export yet; a request for such a track is rejected with 422.

What goes into the file

  • Start — the file starts at the key frame at or before the requested moment, so it can be a few seconds longer than requested. If the start falls into a recording gap, the file starts at the first key frame after the gap.
  • Recording gaps — are joined: the file holds only recorded time and may be shorter than the requested segment.
  • Stream parameter change — if track parameters changed within the segment, for example the camera resolution, the file ends at the change.

The server suggests the file name in the Content-Disposition header: <stream>_<YYYY-MM-DD>_<HH-MM-SS>Z_<seconds>s.mp4. The time in the name is UTC, the duration is the actually recorded one.

The file size is known before downloading: a HEAD request to the same URL returns Content-Length without the file itself.

Settings

Limits are set in the server dvr section:

dvr:
  root: /storage
  export_max_duration_secs: 10800   # maximum duration of one export, seconds
  export_max_concurrent: 4          # how many exports run at the same time
Parameter Default Description
export_max_duration_secs 10800 (3 hours) a longer request is rejected with 422 before the archive is read
export_max_concurrent 4 a request over the limit gets 503 with a Retry-After header

Zero is not allowed.

Server responses

Code When
200 the file is being served
404 there is no recording in the segment
422 the request cannot be fulfilled; the reason is named in the response body
503 the maximum number of exports is already running; retry after Retry-After seconds
401, 403 authorization failed; 403 is also returned for an encrypted stream

Reasons for 422:

  • duration over the limit export_max_duration_secs;
  • a missing track is named, or a track with no recording in the segment;
  • subtitles are requested, or a service track;
  • duration is now — export "up to the current moment" is not supported;

Statistics

Export counters are served together with the process metrics (/streamer/api-v4/runtime/metrics, see Monitoring):

  • archive_export_requests_total — number of exports;
  • archive_export_recorded_secs_total — recorded seconds exported;
  • archive_export_bytes_total — bytes exported;
  • archive_export_failures_total — refusals labeled with reason.

What's next