retina-record

Command-line application to record MP4 video from RTSP cameras.

Documentation and repository at github.com/strawlab/retina-record.

Features

• Does not transcode video from the camera but streams the already-encoded H264 video directly to an .mp4 file. Consequently, CPU usage is minimal.
• Stores additional timing data inline in the .mp4 file. See "Timing data" below.
• Based on the retina Rust crate to support H264 RTSP cameras. This is the same library underlying Moonfire NVR.
• Written in pure Rust.

Timing data

retina-record saves additional timing data during recording. This allows best-effort reconstruction of the timing of individual camera frames and synchronizing videos from multiple cameras. The overall philosophy is to log, in a lossless manner, the timing information sent from the camera as well as the nanosecond-specified time at which retina-record received the data. If the camera has a good internal clock (e.g. because it is using a well behaved NTP client), the timestamps from the camera alone should be sufficient to reconstruct quite precisely (see below for details about "quite precisely") when images were acquired. Alternatively, if the camera's internal clock is not as ideal, the timestamps saved by retina-record can be used to align the data under the assumptions that network delays are insignificant and that the clock of the PC on which retina-record runs is reliable. Furthermore, supported by the partial redundancy of these data types, more sophisticated time reconstruction approaches can be implemented on videos recorded with retina-record. These data are saved in the H264 video track in the MP4 file using Supplemental Enhancement Information (SEI).

Frame timing data

Each frame is stored with its "RTP timestamp" from the camera and the "receive timestamp" from retina-record. The formal description of the data saved in the H264 stream as Supplemental Enhancement Information (SEI) is at strawlab.org/89H.

Sender report timing data

Occasional (every few seconds) sender reports from the camera with additional NTP timestamps are stored alongside RTP and receive timestamps. The formal description of the data saved in the H264 stream as Supplemental Enhancement Information (SEI) is at strawlab.org/o8B.

The NTP timestamps are in the 64-bit NTP timestamp format and thus theoretically have nanosecond-level precision. Practically, this depends on the quality of the internal clock on the camera.

Installing

1. Install rust
2. Run cargo install retina-record --locked.

Running

Here is an example command-line to record from a camera to the file output.mp4. This will run until Ctrl-C is used to stop the program. You will need to update the URL for your camera and presumably the password and output filename.

retina-record --url rtsp://192.168.1.32/cam1/onvif-h264 --username admin --password secret-password output.mp4