update record and parked car guide

docs/docs/configuration/record.md

@@ -9,6 +9,56 @@ New recording segments are written from the camera stream to cache, they are onl
 
 H265 recordings can be viewed in Chrome 108+, Edge and Safari only. All other browsers require recordings to be encoded with H264.
 
+## Common recording configurations
+
+### Most conservative: Ensure all video is saved
+
+For users deploying Frigate in environments where it is important to have contiguous video stored even if there was no detectable motion, the following config will store all video for 3 days. After 3 days, only video containing motion and overlapping with events will be retained until 30 days have passed.
+
+```yaml
+record:
+  enabled: True
+  retain:
+    days: 3
+    mode: all
+  events:
+    retain:
+      default: 30
+      mode: motion
+```
+
+### Reduced storage: Only saving video when motion is detected
+
+In order to reduce storage requirements, you can adjust your config to only retain video where motion was detected.
+
+```yaml
+record:
+  enabled: True
+  retain:
+    days: 3
+    mode: all
+  events:
+    retain:
+      default: 30
+      mode: motion
+```
+
+### Minimum: Events only
+
+If you only want to retain video that occurs during an event, this config will discard video unless an event is ongoing.
+
+```yaml
+record:
+  enabled: True
+  retain:
+    days: 0
+    mode: all
+  events:
+    retain:
+      default: 30
+      mode: motion
+```
+
 ## Will Frigate delete old recordings if my storage runs out?
 
 As of Frigate 0.12 if there is less than an hour left of storage, the oldest 2 hours of recordings will be deleted.
@@ -57,16 +107,19 @@ This configuration will retain recording segments that overlap with events and h
 Frigate saves from the stream with the `record` role in 10 second segments. These options determine which recording segments are kept for continuous 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 continuous 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.
 
 A configuration example of the above retain modes where all `motion` segments are stored for 7 days and `active objects` are stored for 14 days would be as follows:
+
 ```yaml
 record:
   enabled: True
@@ -78,11 +131,13 @@ record:
       default: 14
       mode: active_objects
 ```
+
 The above configuration example can be added globally or on a per camera basis.
 
 ### Object Specific Retention
 
 You can also set specific retention length for an object type. The below configuration example builds on from above but also specifies that recordings of dogs only need to be kept for 2 days and recordings of cars should be kept for 7 days.
+
 ```yaml
 record:
   enabled: True

docs/docs/configuration/stationary_objects.md

@@ -23,9 +23,9 @@ NOTE: There is no way to disable stationary object tracking with this value.
 
 `threshold` is the number of frames an object needs to remain relatively still before it is considered stationary.
 
-## Avoiding stationary objects
+## Handling stationary objects
 
-In some cases, like a driveway, you may prefer to only have an event when a car is coming & going vs a constant event of it stationary in the driveway. [This docs sections](../guides/stationary_objects.md) explains how to approach that scenario.
+In some cases, like a driveway, you may prefer to only have an event when a car is coming & going vs a constant event of it stationary in the driveway. You can reference [this guide](../guides/parked_cars.md) for recommended approaches.
 
 ## Why does Frigate track stationary objects?
 

docs/docs/guides/parked_cars.md

@@ -0,0 +1,71 @@
+---
+id: parked_cars
+title: Handling parked cars
+---
+
+:::tip
+
+This is an area targeted for improvement in future releases.
+
+:::
+
+Many people use Frigate to detect cars entering their driveway, and they often run into an issue with repeated events of parked cars and/or long running events after the car parks. This can cause Frigate to store more video than desired.
+
+:::caution
+
+It is not recommended to use motion masks to try and eliminate parked cars in your driveway. Motion masks are designed to prevent motion from triggering object detection and will not prevent objects from being detected in the area if motion is detected outside of the motion mask.
+
+:::
+
+## Repeated events of parked cars
+
+To only be notified of cars that enter your driveway from the street, you can create multiple zones that cover your driveway. For cars, you would only notify if `entered_zones` from the events MQTT topic has contains the entrance zone.
+
+See [this example](../configuration/zones.md#restricting-zones-to-specific-objects) from the Zones documentation to see how to restrict zones to certain object types.
+
+![Driveway Zones](/img/driveway_zones-min.png)
+
+To limit snapshots and events, you can list the zone for the entrance of your driveway under `required_zones` in your configuration file.
+
+```yaml
+camera:
+  record:
+    events:
+      required_zones:
+        - zone_2
+  zones:
+    zone_1:
+      coordinates: ... (parking area)
+    zone_2:
+      coordinates: ... (entrance to driveway)
+```
+
+This will only save events if the car entered the entrance zone at any point.
+
+## Long running events
+
+There are a few recommended approaches to avoid excessive storage use due to parked cars. These can be used in combination.
+
+### 1. Use `motion` or `active_objects` mode for event recordings
+
+Leverages [recording settings](../configuration/record.md#what-do-the-different-retain-modes-mean) to avoid excess storage use.
+
+#### Advantages of this approach
+
+For users using `motion` mode for continuous recording, this successfully avoids extra video from being stored for cars parked in view because all motion video is already being saved.
+
+#### Limitations of this approach
+
+For users that only want to record motion during events, long running events will result in all motion being stored as long as the car is in view. You can mitigate this further by using the `active_objects` mode for event recordings, but that may result less video being retained than is desired.
+
+### 2. Use an object mask to prevent detections in the parking zone
+
+Leverages [object filter masks](../configuration/masks.md#object-filter-masks) to prevent detections of cars parked in the driveway.
+
+#### Advantages of this approach
+
+Using this approach, you will get two separate events for when a car enters the driveway, parks in the parking zone, and then later leaves the zone. Using an object mask will ensure that cars parked in the parking zone are not detected and confused with cars driving by on the street as well.
+
+#### Limitations of this approach
+
+This approach will only work for cars that park in the parking zone. Cars that park in other areas will still be tracked as long as they are in view. This will also prevent zone sensors from telling you if a car is parked in the parking zone from working.

docs/docs/guides/stationary_objects.md

@@ -1,43 +0,0 @@
----
-id: stationary_objects
-title: Avoiding stationary objects
----
-
-Many people use Frigate to detect cars entering their driveway, and they often run into an issue with repeated notifications or events of a parked car being repeatedly detected over the course of multiple days (for example if the car is lost at night and detected again the following morning).
-
-You can use zones to restrict events and notifications to objects that have entered specific areas.
-
-:::caution
-
-It is not recommended to use masks to try and eliminate parked cars in your driveway. Masks are designed to prevent motion from triggering object detection and/or to indicate areas that are guaranteed false positives.
-
-Frigate is designed to track objects as they move and over-masking can prevent it from knowing that an object in the current frame is the same as the previous frame. You want Frigate to detect objects everywhere and configure your events and alerts to be based on the location of the object with zones.
-
-:::
-
-:::info
-
-Once a vehicle crosses the entrance into the parking area, that event will stay `In Progress` until it is no longer seen in the frame. Frigate is designed to have an event last as long as an object is visible in the frame, an event being `In Progress` does not mean the event is being constantly recorded. You can define the recording behavior by adjusting the [recording retention settings](../configuration/record.md).
-
-:::
-
-To only be notified of cars that enter your driveway from the street, you could create multiple zones that cover your driveway. For cars, you would only notify if `entered_zones` from the events MQTT topic has more than 1 zone.
-
-See [this example](../configuration/zones.md#restricting-zones-to-specific-objects) from the Zones documentation to see how to restrict zones to certain object types.
-
-![Driveway Zones](/img/driveway_zones-min.png)
-
-To limit snapshots and events, you can list the zone for the entrance of your driveway under `required_zones` in your configuration file. Example below.
-
-```yaml
-camera:
-  record:
-    events:
-      required_zones:
-        - zone_2
-  zones:
-    zone_1:
-      coordinates: ... (parking area)
-    zone_2:
-      coordinates: ... (entrance to driveway)
-```

docs/sidebars.js

@@ -13,7 +13,7 @@ module.exports = {
       "guides/configuring_go2rtc",
       "guides/ha_notifications",
       "guides/ha_network_storage",
-      "guides/stationary_objects",
+      "guides/parked_cars",
       "guides/reverse_proxy",
     ],
     Configuration: {