Skip to content

Archive export

A segment of the recorded archive downloads as a single MP4 file that opens in ordinary players, for example VLC. The file is assembled from the archive at request time: nothing has to be prepared in advance, and the export takes no disk space.

Export works for a stream with recording enabled. Only MP4 is exported: the station does not assemble a MPEG-TS file, and a .ts request is refused with 422.

Export URL

http://<station-address>/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.

The station answers GET with the file and HEAD with its headers only. Probing the address with HEAD before downloading is worth doing: Content-Length arrives without the body, so the file size is known in advance. GET and HEAD have the same outcomes: a refusal the download would give is visible on the probe already.

Track selection

Without parameters the file gets all the video and audio tracks of the segment. The tracks you need are selected with the filter.tracks parameter:

http://<station-address>/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 do not go into the export: they break the classic-container compatibility the container was chosen for. A request for such a track is refused.

What goes into the file

  • Start — the file starts at the keyframe 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 keyframe after the gap;
  • recording gaps — are joined: the file holds only recorded time and may be shorter than the requested segment;
  • a change of track parameters — if parameters changed within the segment, resolution for instance, the file ends at the change. The cut is common to all tracks: otherwise the picture would end in the middle of the sound.

The station 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 rather than the width of the selection: the name must not lie about the contents.

Limits

Two limits live in the archive settings of the machine and survive a restart: they change by applying the configuration, not by restarting.

  • export_max_duration_secs — the maximum duration of one export, in seconds. 10800 by default — three hours, which is also what the timeline allows to be selected by default;
  • export_max_concurrent — how many exports the station runs at the same time. 4 by default.

A request longer than the ceiling is refused with 422 before the archive is read. A request over the number of concurrent ones gets 503 with a Retry-After header: retrying after the named number of seconds loses nothing, the work had not started.

Zero is not allowed. The duration ceiling cuts one export but not their number: dozens at once put the disk on the shelf, and the station is writing at the same time.

Server responses

Code When
200 the file is being served
403 the stream is encrypted: the classic export carries no encryption
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

Reasons for 422:

  • duration over the ceiling export_max_duration_secs;
  • a missing track is named — either the stream has no such track or it has no recording in the segment;
  • subtitles or a service track are requested;
  • the container is not MP4 — the extension in the address is another one;
  • the packing parameter is not compat — only the classic MP4 is exported;
  • filter.tracks is not a track selector;
  • duration is given as now — export "up to the current moment" is not supported: between the probe and the download the archive edge moves, and the announced length would diverge from the body.

If the delivery breaks off after the headers — a failed disk, say — the response ends as an incomplete transfer: curl reports a broken connection, the browser marks the download as failed. A file that arrived whole contains the whole segment.

Counters

Export is counted together with the rest of the process metrics (see Monitoring):

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

Refusals caused by the client and by the station are kept apart deliberately: an invalid request is not a sign of breakage, and nobody should be woken over it.

What next