GStreamer pre-record element - User Guide
| GStreamer pre-record element |
|---|
|
| Overview |
| User Guide |
| Getting Started |
| Examples |
| Contact Us |
GstPreRecord
The GstPreRecord element is a filter that prerecords data continuously into a FIFO. You can set the FIFO size in milliseconds based on the amount of pre-recorded data you want to keep. When pre-recording, the pre-record element doesn't pass any buffer downstream. After the FIFO is filled, the oldest data in the FIFO is released as new data is added. When you want to start recording, you can trigger the pre-record element and it will pass the data in the FIFO downstream while adding new data to the end of the FIFO buffer so no data is lost. Eventually, the FIFO will be completely drained and the element will act as a pass-through. When the pipeline is stopped, the pre-record process can be repeated.
Figure 1 shows a typical GStreamer pipeline configuration including the GstPreRecord element on it. As soon as the user changes the buffering property in the element to FALSE, the FIFO will be released and pre-saved buffers will be sent downstream. The element will start buffering again as long as the user sets the buffering property to TRUE.
GstPreRecordSink
The GstPreRecordSink element has exactly the same mechanism as the GstPreRecord, except by the fact it is a sink element instead of a filter, which means it is the last element on a pipeline and it is mainly designed for file recording, as seen in Figure 2.
Differences and similarities between GstPreRecord and GstPreRecordSink elements are as follows. You can reference Figure 3 with a timing diagram about each element functionality:
- Both elements start by buffering the incoming video within a pre-record window (green).
- When an event occurs and triggers the prerecord (Ttrigger), both elements use the video data saved within the pre-record window.
- In the case of the GstPreRecord element, it will start sending the pre-record window data downstream, plus any future video (blue) and it won't stop sending it until you set its property to buffering again. When this happens, no more buffers are sent downstream.
- For the GstPreRecordSink element, when the trigger happens, it automatically creates an MP4 video file (because it is a sink element) with the data in the pre-record window plus the data in the post-record window. Both the pre- and pos-record window sizes can be defined.
Recording File name
The recorded file can use any of the following macros for different files identification:
Y = year m = month d = day H = hour M = minute S = seconds z = numeric time zone
For example, by using location pattern recording_%Y-%m-%d_%H:%M:%S%z.mp4, you can get files such as:
recording_2021-11-22_17:17:23-0600.mp4 recording_2021-11-22_17:22:34-0600.mp4 recording_2021-11-22_17:46:01-0600.mp4
Multiple triggers
The GstPreRecordSink element can react differently to consecutive triggers.
- If a consecutive trigger happens within the post-record window, the file length will be increased by another post-record size. Figure 4 shows this case.
- If a consecutive trigger happens out of the post-record region, a new file is generated. Note that in this case, the length of the pre-record data saved to disk will depend on the difference in time between the last Tpost and the next Ttrigger event. Figure 5 shows this case.
- If the user wants to limit the length of the recorded file to a max value when consecutive triggers happen, the max-buf-time property can be used. If consecutive triggers happen but the recording file reaches the max-buf-time value, the prerecordsink will close the file and start a new one, in order to respect the max value set by the user. Figure 6 shows this case.
Extended Post buffering time
By default, the post-trigger time is the same as the pre-buffering time. However, users can control and change this setting by modifying the post-rec-time property. Its default value is equal to buf-time, but it can be less or more than buf-time, depending on user's needs.