Docs: Update recording docs to include examples of retain modes. (bla…

…keblackshear#2914)

* Update recording docs to include examples of retain modes.

* Minor adjustment

Co-authored-by: Blake Blackshear <[email protected]>

docs/docs/configuration/record.md

@@ -21,4 +21,18 @@ record:
 
 This configuration will retain recording segments that overlap with events and have active tracked objects for 10 days. Because multiple events can reference the same recording segments, this avoids storing duplicate footage for overlapping events and reduces overall storage needs.
 
-When `retain_days` is set to `0`, segments will be deleted from the cache if no events are in progress.
+When `retain -> days` is set to `0`, segments will be deleted from the cache if no events are in progress.
+
+## What do the different retain modes mean?
+
+Frigate saves from the stream with the `record` role in 10 second segments. These options determine which recording segments are kept for 24/7 recording (but can also affect events). 
+
+Let's say you have frigate configured so that your doorbell camera would retain the last **2** days of 24/7 recording. 
+- With the `all` option all 48 hours of those two days would be kept and viewable. 
+- With the `motion` option the only parts of those 48 hours would be segments that frigate detected motion. This is the middle ground option that won't keep all 48 hours, but will likely keep all segments of interest along with the potential for some extra segments.
+- With the `active_objects` option the only segments that would be kept are those where there was a true positive object that was not considered stationary.
+
+The same options are available with events. Let's consider a scenario where you drive up and park in your driveway, go inside, then come back out 4 hours later.
+- With the `all` option all segments for the duration of the event would be saved for the event. This event would have 4 hours of footage.
+- With the `motion` option all segments for the duration of the event with motion would be saved. This means any segment where a car drove by in the street, person walked by, lighting changed, etc. would be saved. 
+- With the `active_objects` it would only keep segments where the object was active. In this case the only segments that would be saved would be the ones where the car was driving up, you going inside, you coming outside, and the car driving away. Essentially reducing the 4 hours to a minute or two of event footage.