Add zones friend name (#20761)

* feat: add zones friendly name

* fix: fix the issue where the input field was empty when there was no friendly_name

* chore: fix the issue where the friendly name would replace spaces with underscores

* docs: update zones docs

* Update web/src/components/settings/ZoneEditPane.tsx

Co-authored-by: Josh Hawkins <32435876+hawkeye217@users.noreply.github.com>

* Add friendly_name option for zone configuration

Added optional friendly name for zones in configuration.

* fix: fix the logical error in the null/empty check for the polygons parameter

* fix: remove the toast name for zones will use the friendly_name instead

* docs: remove emoji tips

* revert: revert zones doc ui tips

* Update docs/docs/configuration/zones.md

Co-authored-by: Josh Hawkins <32435876+hawkeye217@users.noreply.github.com>

* Update docs/docs/configuration/zones.md

Co-authored-by: Josh Hawkins <32435876+hawkeye217@users.noreply.github.com>

* Update docs/docs/configuration/zones.md

Co-authored-by: Josh Hawkins <32435876+hawkeye217@users.noreply.github.com>

* feat: add friendly zone names to tracking details and lifecycle item descriptions

* chore: lint fix

* refactor: add friendly zone names to timeline entries and clean up unused code

* refactor: add formatList

---------

Co-authored-by: Josh Hawkins <32435876+hawkeye217@users.noreply.github.com>

docs/docs/configuration/reference.md

@@ -810,6 +810,8 @@ cameras:
       # NOTE: This must be different than any camera names, but can match with another zone on another
       #       camera.
       front_steps:
+        # Optional: A friendly name or descriptive text for the zones
+        friendly_name: ""
         # Required: List of x,y coordinates to define the polygon of the zone.
         # NOTE: Presence in a zone is evaluated only based on the bottom center of the objects bounding box.
         coordinates: 0.033,0.306,0.324,0.138,0.439,0.185,0.042,0.428

docs/docs/configuration/zones.md

@@ -27,6 +27,7 @@ cameras:
           - entire_yard
     zones:
       entire_yard:
+        friendly_name: Entire yard # You can use characters from any language text
         coordinates: ...
 ```
 
@@ -44,8 +45,10 @@ cameras:
           - edge_yard
     zones:
       edge_yard:
+        friendly_name: Edge yard # You can use characters from any language text
         coordinates: ...
       inner_yard:
+        friendly_name: Inner yard # You can use characters from any language text
         coordinates: ...
 ```
 
@@ -59,6 +62,7 @@ cameras:
         - entire_yard
     zones:
       entire_yard:
+        friendly_name: Entire yard
         coordinates: ...
 ```
 
@@ -82,6 +86,7 @@ cameras:
 
 Only car objects can trigger the `front_yard_street` zone and only person can trigger the `entire_yard`. Objects will be tracked for any `person` that enter anywhere in the yard, and for cars only if they enter the street.
 
+
 ### Zone Loitering
 
 Sometimes objects are expected to be passing through a zone, but an object loitering in an area is unexpected. Zones can be configured to have a minimum loitering time after which the object will be considered in the zone.

frigate/config/camera/zone.py

@@ -13,6 +13,9 @@ logger = logging.getLogger(__name__)
 
 
 class ZoneConfig(BaseModel):
+    friendly_name: Optional[str] = Field(
+        None, title="Zone friendly name used in the Frigate UI."
+    )
     filters: dict[str, FilterConfig] = Field(
         default_factory=dict, title="Zone filters."
     )

web/src/components/camera/FriendlyNameLabel.tsx

@@ -2,12 +2,19 @@ import * as React from "react";
 import * as LabelPrimitive from "@radix-ui/react-label";
 import { useCameraFriendlyName } from "@/hooks/use-camera-friendly-name";
 import { CameraConfig } from "@/types/frigateConfig";
+import { useZoneFriendlyName } from "@/hooks/use-zone-friendly-name";
 
 interface CameraNameLabelProps
   extends React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root> {
   camera?: string | CameraConfig;
 }
 
+interface ZoneNameLabelProps
+  extends React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root> {
+  zone: string;
+  camera?: string;
+}
+
 const CameraNameLabel = React.forwardRef<
   React.ElementRef<typeof LabelPrimitive.Root>,
   CameraNameLabelProps
@@ -21,4 +28,17 @@ const CameraNameLabel = React.forwardRef<
 });
 CameraNameLabel.displayName = LabelPrimitive.Root.displayName;
 
-export { CameraNameLabel };
+const ZoneNameLabel = React.forwardRef<
+  React.ElementRef<typeof LabelPrimitive.Root>,
+  ZoneNameLabelProps
+>(({ className, zone, camera, ...props }, ref) => {
+  const displayName = useZoneFriendlyName(zone, camera);
+  return (
+    <LabelPrimitive.Root ref={ref} className={className} {...props}>
+      {displayName}
+    </LabelPrimitive.Root>
+  );
+});
+ZoneNameLabel.displayName = LabelPrimitive.Root.displayName;
+
+export { CameraNameLabel, ZoneNameLabel };

web/src/components/filter/CameraGroupSelector.tsx

@@ -76,7 +76,7 @@ import { CameraStreamingDialog } from "../settings/CameraStreamingDialog";
 import { DialogTrigger } from "@radix-ui/react-dialog";
 import { useStreamingSettings } from "@/context/streaming-settings-provider";
 import { Trans, useTranslation } from "react-i18next";
-import { CameraNameLabel } from "../camera/CameraNameLabel";
+import { CameraNameLabel } from "../camera/FriendlyNameLabel";
 import { useAllowedCameras } from "@/hooks/use-allowed-cameras";
 import { useIsCustomRole } from "@/hooks/use-is-custom-role";
 

web/src/components/filter/CamerasFilterButton.tsx

@@ -190,7 +190,7 @@ export function CamerasFilterContent({
               key={item}
               isChecked={currentCameras?.includes(item) ?? false}
               label={item}
-              isCameraName={true}
+              type={"camera"}
               disabled={
                 mainCamera !== undefined &&
                 currentCameras !== undefined &&

web/src/components/filter/FilterSwitch.tsx

@@ -1,29 +1,39 @@
 import { Switch } from "../ui/switch";
 import { Label } from "../ui/label";
-import { CameraNameLabel } from "../camera/CameraNameLabel";
+import { CameraNameLabel, ZoneNameLabel } from "../camera/FriendlyNameLabel";
 
 type FilterSwitchProps = {
   label: string;
   disabled?: boolean;
   isChecked: boolean;
   isCameraName?: boolean;
+  type?: string;
+  extraValue?: string;
   onCheckedChange: (checked: boolean) => void;
 };
 export default function FilterSwitch({
   label,
   disabled = false,
   isChecked,
-  isCameraName = false,
+  type = "",
+  extraValue = "",
   onCheckedChange,
 }: FilterSwitchProps) {
   return (
     <div className="flex items-center justify-between gap-1">
-      {isCameraName ? (
+      {type === "camera" ? (
         <CameraNameLabel
           className={`mx-2 w-full cursor-pointer text-sm font-medium leading-none text-primary smart-capitalize peer-disabled:cursor-not-allowed peer-disabled:opacity-70 ${disabled ? "text-secondary-foreground" : ""}`}
           htmlFor={label}
           camera={label}
         />
+      ) : type === "zone" ? (
+        <ZoneNameLabel
+          className={`mx-2 w-full cursor-pointer text-sm font-medium leading-none text-primary smart-capitalize peer-disabled:cursor-not-allowed peer-disabled:opacity-70 ${disabled ? "text-secondary-foreground" : ""}`}
+          htmlFor={label}
+          camera={extraValue}
+          zone={label}
+        />
       ) : (
         <Label
           className={`mx-2 w-full cursor-pointer text-primary smart-capitalize ${disabled ? "text-secondary-foreground" : ""}`}

web/src/components/filter/ReviewFilterGroup.tsx

@@ -550,7 +550,8 @@ export function GeneralFilterContent({
               {allZones.map((item) => (
                 <FilterSwitch
                   key={item}
-                  label={item.replaceAll("_", " ")}
+                  label={item}
+                  type={"zone"}
                   isChecked={filter.zones?.includes(item) ?? false}
                   onCheckedChange={(isChecked) => {
                     if (isChecked) {

web/src/components/input/InputWithTags.tsx

@@ -53,7 +53,7 @@ import { FrigateConfig } from "@/types/frigateConfig";
 import { MdImageSearch } from "react-icons/md";
 import { useTranslation } from "react-i18next";
 import { getTranslatedLabel } from "@/utils/i18n";
-import { CameraNameLabel } from "../camera/CameraNameLabel";
+import { CameraNameLabel, ZoneNameLabel } from "../camera/FriendlyNameLabel";
 
 type InputWithTagsProps = {
   inputFocused: boolean;
@@ -831,6 +831,8 @@ export default function InputWithTags({
                               getTranslatedLabel(value)
                             ) : filterType === "cameras" ? (
                               <CameraNameLabel camera={value} />
+                            ) : filterType === "zones" ? (
+                              <ZoneNameLabel zone={value} />
                             ) : (
                               value.replaceAll("_", " ")
                             )}
@@ -934,6 +936,11 @@ export default function InputWithTags({
                         <CameraNameLabel camera={suggestion} />
                         {")"}
                       </>
+                    ) : currentFilterType === "zones" ? (
+                      <>
+                        {suggestion} {" ("} <ZoneNameLabel zone={suggestion} />
+                        {")"}
+                      </>
                     ) : (
                       suggestion
                     )
@@ -943,6 +950,8 @@ export default function InputWithTags({
                       {currentFilterType ? (
                         currentFilterType === "cameras" ? (
                           <CameraNameLabel camera={suggestion} />
+                        ) : currentFilterType === "zones" ? (
+                          <ZoneNameLabel zone={suggestion} />
                         ) : (
                           formatFilterValues(currentFilterType, suggestion)
                         )

web/src/components/menu/LiveContextMenu.tsx

@@ -47,7 +47,7 @@ import {
 import { useTranslation } from "react-i18next";
 import { useDateLocale } from "@/hooks/use-date-locale";
 import { useIsAdmin } from "@/hooks/use-is-admin";
-import { CameraNameLabel } from "../camera/CameraNameLabel";
+import { CameraNameLabel } from "../camera/FriendlyNameLabel";
 
 type LiveContextMenuProps = {
   className?: string;

web/src/components/overlay/CreateRoleDialog.tsx

@@ -25,7 +25,7 @@ import {
 } from "@/components/ui/dialog";
 import { useTranslation } from "react-i18next";
 import { FrigateConfig } from "@/types/frigateConfig";
-import { CameraNameLabel } from "../camera/CameraNameLabel";
+import { CameraNameLabel } from "../camera/FriendlyNameLabel";
 import { isDesktop, isMobile } from "react-device-detect";
 import { cn } from "@/lib/utils";
 import {

web/src/components/overlay/EditRoleCamerasDialog.tsx

@@ -24,7 +24,7 @@ import {
 } from "@/components/ui/dialog";
 import { Trans, useTranslation } from "react-i18next";
 import { FrigateConfig } from "@/types/frigateConfig";
-import { CameraNameLabel } from "@/components/camera/CameraNameLabel";
+import { CameraNameLabel } from "@/components/camera/FriendlyNameLabel";
 
 type EditRoleCamerasOverlayProps = {
   show: boolean;

web/src/components/overlay/MobileCameraDrawer.tsx

@@ -4,7 +4,7 @@ import { Button } from "../ui/button";
 import { FaVideo } from "react-icons/fa";
 import { isMobile } from "react-device-detect";
 import { useTranslation } from "react-i18next";
-import { CameraNameLabel } from "../camera/CameraNameLabel";
+import { CameraNameLabel } from "../camera/FriendlyNameLabel";
 
 type MobileCameraDrawerProps = {
   allCameras: string[];

web/src/components/overlay/ObjectTrackOverlay.tsx

@@ -12,6 +12,7 @@ import { TooltipPortal } from "@radix-ui/react-tooltip";
 import { cn } from "@/lib/utils";
 import { useTranslation } from "react-i18next";
 import { Event } from "@/types/event";
+import { resolveZoneName } from "@/hooks/use-zone-friendly-name";
 
 // Use a small tolerance (10ms) for browsers with seek precision by-design issues
 const TOLERANCE = 0.01;
@@ -114,6 +115,10 @@ export default function ObjectTrackOverlay({
     { revalidateOnFocus: false },
   );
 
+  const getZonesFriendlyNames = (zones: string[], config: FrigateConfig) => {
+    return zones?.map((zone) => resolveZoneName(config, zone)) ?? [];
+  };
+
   const timelineResults = useMemo(() => {
     // Group timeline entries by source_id
     if (!timelineData) return selectedObjectIds.map(() => []);
@@ -127,8 +132,19 @@ export default function ObjectTrackOverlay({
     }
 
     // Return timeline arrays in the same order as selectedObjectIds
-    return selectedObjectIds.map((id) => grouped[id] || []);
+    return selectedObjectIds.map((id) => {
-  }, [selectedObjectIds, timelineData]);
+      const entries = grouped[id] || [];
+      return entries.map((event) => ({
+        ...event,
+        data: {
+          ...event.data,
+          zones_friendly_names: config
+            ? getZonesFriendlyNames(event.data?.zones, config)
+            : [],
+        },
+      }));
+    });
+  }, [selectedObjectIds, timelineData, config]);
 
   const typeColorMap = useMemo(
     () => ({

web/src/components/overlay/detail/ObjectPath.tsx

@@ -8,6 +8,9 @@ import {
 import { TooltipPortal } from "@radix-ui/react-tooltip";
 import { getLifecycleItemDescription } from "@/utils/lifecycleUtil";
 import { useTranslation } from "react-i18next";
+import { resolveZoneName } from "@/hooks/use-zone-friendly-name";
+import { FrigateConfig } from "@/types/frigateConfig";
+import useSWR from "swr";
 
 type ObjectPathProps = {
   positions?: Position[];
@@ -42,16 +45,31 @@ export function ObjectPath({
   visible = true,
 }: ObjectPathProps) {
   const { t } = useTranslation(["views/explore"]);
+  const { data: config } = useSWR<FrigateConfig>("config");
   const getAbsolutePositions = useCallback(() => {
     if (!imgRef.current || !positions) return [];
     const imgRect = imgRef.current.getBoundingClientRect();
-    return positions.map((pos) => ({
+    return positions.map((pos) => {
+      return {
         x: pos.x * imgRect.width,
         y: pos.y * imgRect.height,
         timestamp: pos.timestamp,
-      lifecycle_item: pos.lifecycle_item,
+        lifecycle_item: pos.lifecycle_item?.data?.zones
-    }));
+          ? {
-  }, [positions, imgRef]);
+              ...pos.lifecycle_item,
+              data: {
+                ...pos.lifecycle_item?.data,
+                zones_friendly_names: pos.lifecycle_item?.data.zones.map(
+                  (zone) => {
+                    return resolveZoneName(config, zone);
+                  },
+                ),
+              },
+            }
+          : pos.lifecycle_item,
+      };
+    });
+  }, [imgRef, positions, config]);
 
   const generateStraightPath = useCallback((points: Position[]) => {
     if (!points || points.length < 2) return "";

web/src/components/overlay/detail/SearchDetailDialog.tsx

@@ -80,7 +80,7 @@ import TextEntryDialog from "@/components/overlay/dialog/TextEntryDialog";
 import { Trans, useTranslation } from "react-i18next";
 import { useIsAdmin } from "@/hooks/use-is-admin";
 import { getTranslatedLabel } from "@/utils/i18n";
-import { CameraNameLabel } from "@/components/camera/CameraNameLabel";
+import { CameraNameLabel } from "@/components/camera/FriendlyNameLabel";
 import { DialogPortal } from "@radix-ui/react-dialog";
 import { useDetailStream } from "@/context/detail-stream-context";
 import { PiSlidersHorizontalBold } from "react-icons/pi";

web/src/components/overlay/detail/TrackingDetails.tsx

@@ -23,6 +23,7 @@ import { Link, useNavigate } from "react-router-dom";
 import { getLifecycleItemDescription } from "@/utils/lifecycleUtil";
 import { useTranslation } from "react-i18next";
 import { getTranslatedLabel } from "@/utils/i18n";
+import { resolveZoneName } from "@/hooks/use-zone-friendly-name";
 import { Badge } from "@/components/ui/badge";
 import { HiDotsHorizontal } from "react-icons/hi";
 import axios from "axios";
@@ -73,6 +74,12 @@ export function TrackingDetails({
 
   const { data: config } = useSWR<FrigateConfig>("config");
 
+  eventSequence?.map((event) => {
+    event.data.zones_friendly_names = event.data?.zones?.map((zone) => {
+      return resolveZoneName(config, zone);
+    });
+  });
+
   // Use manualOverride (set when seeking in image mode) if present so
   // lifecycle rows and overlays follow image-mode seeks. Otherwise fall
   // back to currentTime used for video mode.
@@ -713,7 +720,8 @@ function LifecycleIconRow({
                           }}
                         />
                         <span className="smart-capitalize">
-                          {zone.replaceAll("_", " ")}
+                          {item.data?.zones_friendly_names?.[zidx] ??
+                            zone.replaceAll("_", " ")}
                         </span>
                       </Badge>
                     );

web/src/components/overlay/dialog/SearchFilterDialog.tsx

@@ -430,7 +430,8 @@ export function ZoneFilterContent({
               {allZones.map((item) => (
                 <FilterSwitch
                   key={item}
-                  label={item.replaceAll("_", " ")}
+                  label={item}
+                  type={"zone"}
                   isChecked={zones?.includes(item) ?? false}
                   onCheckedChange={(isChecked) => {
                     if (isChecked) {

web/src/components/settings/PolygonCanvas.tsx

@@ -262,13 +262,17 @@ export function PolygonCanvas({
   };
 
   useEffect(() => {
-    if (activePolygonIndex === undefined || !polygons) {
+    if (activePolygonIndex === undefined || !polygons?.length) {
       return;
     }
 
     const updatedPolygons = [...polygons];
     const activePolygon = updatedPolygons[activePolygonIndex];
 
+    if (!activePolygon) {
+      return;
+    }
+
     // add default points order for already completed polygons
     if (!activePolygon.pointsOrder && activePolygon.isFinished) {
       updatedPolygons[activePolygonIndex] = {

web/src/components/settings/PolygonItem.tsx

@@ -179,7 +179,7 @@ export default function PolygonItem({
           if (res.status === 200) {
             toast.success(
               t("masksAndZones.form.polygonDrawing.delete.success", {
-                name: polygon?.name,
+                name: polygon?.friendly_name ?? polygon?.name,
               }),
               {
                 position: "top-center",
@@ -261,7 +261,9 @@ export default function PolygonItem({
               }}
             />
           )}
-          <p className="cursor-default">{polygon.name}</p>
+          <p className="cursor-default">
+            {polygon.friendly_name ?? polygon.name}
+          </p>
         </div>
         <AlertDialog
           open={deleteDialogOpen}
@@ -278,7 +280,7 @@ export default function PolygonItem({
                 ns="views/settings"
                 values={{
                   type: polygon.type.replace("_", " "),
-                  name: polygon.name,
+                  name: polygon.friendly_name ?? polygon.name,
                 }}
               >
                 masksAndZones.form.polygonDrawing.delete.desc

web/src/components/settings/ZoneEditPane.tsx

@@ -34,6 +34,7 @@ import { Link } from "react-router-dom";
 import { LuExternalLink } from "react-icons/lu";
 import { useDocDomain } from "@/hooks/use-doc-domain";
 import { getTranslatedLabel } from "@/utils/i18n";
+import NameAndIdFields from "../input/NameAndIdFields";
 
 type ZoneEditPaneProps = {
   polygons?: Polygon[];
@@ -146,15 +147,37 @@ export default function ZoneEditPane({
               "masksAndZones.form.zoneName.error.mustNotContainPeriod",
             ),
           },
-        )
-        .refine((value: string) => /^[a-zA-Z0-9_-]+$/.test(value), {
-          message: t("masksAndZones.form.zoneName.error.hasIllegalCharacter"),
-        })
-        .refine((value: string) => /[a-zA-Z]/.test(value), {
-          message: t(
-            "masksAndZones.form.zoneName.error.mustHaveAtLeastOneLetter",
         ),
-        }),
+      friendly_name: z
+        .string()
+        .min(2, {
+          message: t(
+            "masksAndZones.form.zoneName.error.mustBeAtLeastTwoCharacters",
+          ),
+        })
+        .refine(
+          (value: string) => {
+            return !cameras.map((cam) => cam.name).includes(value);
+          },
+          {
+            message: t(
+              "masksAndZones.form.zoneName.error.mustNotBeSameWithCamera",
+            ),
+          },
+        )
+        .refine(
+          (value: string) => {
+            const otherPolygonNames =
+              polygons
+                ?.filter((_, index) => index !== activePolygonIndex)
+                .map((polygon) => polygon.name) || [];
+
+            return !otherPolygonNames.includes(value);
+          },
+          {
+            message: t("masksAndZones.form.zoneName.error.alreadyExists"),
+          },
+        ),
       inertia: z.coerce
         .number()
         .min(1, {
@@ -247,6 +270,7 @@ export default function ZoneEditPane({
     mode: "onBlur",
     defaultValues: {
       name: polygon?.name ?? "",
+      friendly_name: polygon?.friendly_name ?? polygon?.name ?? "",
       inertia:
         polygon?.camera &&
         polygon?.name &&
@@ -286,6 +310,7 @@ export default function ZoneEditPane({
     async (
       {
         name: zoneName,
+        friendly_name,
         inertia,
         loitering_time,
         objects: form_objects,
@@ -415,9 +440,14 @@ export default function ZoneEditPane({
         }
       }
 
+      let friendlyNameQuery = "";
+      if (friendly_name) {
+        friendlyNameQuery = `&cameras.${polygon?.camera}.zones.${zoneName}.friendly_name=${encodeURIComponent(friendly_name)}`;
+      }
+
       axios
         .put(
-          `config/set?cameras.${polygon?.camera}.zones.${zoneName}.coordinates=${coordinates}${inertiaQuery}${loiteringTimeQuery}${speedThresholdQuery}${distancesQuery}${objectQueries}${alertQueries}${detectionQueries}`,
+          `config/set?cameras.${polygon?.camera}.zones.${zoneName}.coordinates=${coordinates}${inertiaQuery}${loiteringTimeQuery}${speedThresholdQuery}${distancesQuery}${objectQueries}${friendlyNameQuery}${alertQueries}${detectionQueries}`,
           {
             requires_restart: 0,
             update_topic: `config/cameras/${polygon.camera}/zones`,
@@ -427,7 +457,7 @@ export default function ZoneEditPane({
           if (res.status === 200) {
             toast.success(
               t("masksAndZones.zones.toast.success", {
-                zoneName,
+                zoneName: friendly_name || zoneName,
               }),
               {
                 position: "top-center",
@@ -541,26 +571,16 @@ export default function ZoneEditPane({
 
       <Form {...form}>
         <form onSubmit={form.handleSubmit(onSubmit)} className="mt-2 space-y-6">
-          <FormField
+          <NameAndIdFields
+            type="zone"
             control={form.control}
-            name="name"
+            nameField="friendly_name"
-            render={({ field }) => (
+            idField="name"
-              <FormItem>
+            nameLabel={t("masksAndZones.zones.name.title")}
-                <FormLabel>{t("masksAndZones.zones.name.title")}</FormLabel>
+            nameDescription={t("masksAndZones.zones.name.tips")}
-                <FormControl>
+            placeholderName={t("masksAndZones.zones.name.inputPlaceHolder")}
-                  <Input
-                    className="text-md w-full border border-input bg-background p-2 hover:bg-accent hover:text-accent-foreground dark:[color-scheme:dark]"
-                    placeholder={t("masksAndZones.zones.name.inputPlaceHolder")}
-                    {...field}
-                  />
-                </FormControl>
-                <FormDescription>
-                  {t("masksAndZones.zones.name.tips")}
-                </FormDescription>
-                <FormMessage />
-              </FormItem>
-            )}
           />
+
           <Separator className="my-2 flex bg-secondary" />
           <FormField
             control={form.control}

web/src/components/timeline/DetailStream.tsx

@@ -26,6 +26,7 @@ import { Link } from "react-router-dom";
 import { Switch } from "@/components/ui/switch";
 import { usePersistence } from "@/hooks/use-persistence";
 import { isDesktop } from "react-device-detect";
+import { resolveZoneName } from "@/hooks/use-zone-friendly-name";
 import { PiSlidersHorizontalBold } from "react-icons/pi";
 import { MdAutoAwesome } from "react-icons/md";
 
@@ -793,17 +794,28 @@ function ObjectTimeline({
     },
   ]);
 
+  const { data: config } = useSWR<FrigateConfig>("config");
   const timeline = useMemo(() => {
     if (!fullTimeline) {
       return fullTimeline;
     }
 
-    return fullTimeline.filter(
+    return fullTimeline
+      .filter(
         (t) =>
           t.timestamp >= review.start_time &&
           (review.end_time == undefined || t.timestamp <= review.end_time),
-    );
+      )
-  }, [fullTimeline, review]);
+      .map((event) => ({
+        ...event,
+        data: {
+          ...event.data,
+          zones_friendly_names: event.data?.zones?.map((zone) =>
+            resolveZoneName(config, zone),
+          ),
+        },
+      }));
+  }, [config, fullTimeline, review]);
 
   if (isValidating && (!timeline || timeline.length === 0)) {
     return <ActivityIndicator className="ml-2 size-3" />;

web/src/hooks/use-zone-friendly-name.ts

@@ -0,0 +1,41 @@
+import { FrigateConfig } from "@/types/frigateConfig";
+import { useMemo } from "react";
+import useSWR from "swr";
+
+export function resolveZoneName(
+  config: FrigateConfig | undefined,
+  zoneId: string,
+  cameraId?: string,
+) {
+  if (!config) return String(zoneId).replace(/_/g, " ");
+
+  if (cameraId) {
+    const camera = config.cameras?.[String(cameraId)];
+    const zone = camera?.zones?.[zoneId];
+    return zone?.friendly_name || String(zoneId).replace(/_/g, " ");
+  }
+
+  for (const camKey in config.cameras) {
+    if (!Object.prototype.hasOwnProperty.call(config.cameras, camKey)) continue;
+    const cam = config.cameras[camKey];
+    if (!cam?.zones) continue;
+    if (Object.prototype.hasOwnProperty.call(cam.zones, zoneId)) {
+      const zone = cam.zones[zoneId];
+      return zone?.friendly_name || String(zoneId).replace(/_/g, " ");
+    }
+  }
+
+  // Fallback: return a cleaned-up zoneId string
+  return String(zoneId).replace(/_/g, " ");
+}
+
+export function useZoneFriendlyName(zoneId: string, cameraId?: string): string {
+  const { data: config } = useSWR<FrigateConfig>("config");
+
+  const name = useMemo(
+    () => resolveZoneName(config, zoneId, cameraId),
+    [config, cameraId, zoneId],
+  );
+
+  return name;
+}

web/src/pages/Settings.tsx

@@ -42,7 +42,7 @@ import { useInitialCameraState } from "@/api/ws";
 import { useIsAdmin } from "@/hooks/use-is-admin";
 import { useTranslation } from "react-i18next";
 import TriggerView from "@/views/settings/TriggerView";
-import { CameraNameLabel } from "@/components/camera/CameraNameLabel";
+import { CameraNameLabel } from "@/components/camera/FriendlyNameLabel";
 import {
   Sidebar,
   SidebarContent,
@@ -650,7 +650,7 @@ function CameraSelectButton({
                 key={item.name}
                 isChecked={item.name === selectedCamera}
                 label={item.name}
-                isCameraName={true}
+                type={"camera"}
                 onCheckedChange={(isChecked) => {
                   if (isChecked && (isEnabled || isCameraSettingsPage)) {
                     setSelectedCamera(item.name);

web/src/types/canvas.ts

@@ -11,10 +11,12 @@ export type Polygon = {
   distances: number[];
   isFinished: boolean;
   color: number[];
+  friendly_name?: string;
 };
 
 export type ZoneFormValuesType = {
   name: string;
+  friendly_name: string;
   inertia: number;
   loitering_time: number;
   isFinished: boolean;

web/src/types/frigateConfig.ts

@@ -280,6 +280,7 @@ export interface CameraConfig {
       speed_threshold: number;
       objects: string[];
       color: number[];
+      friendly_name?: string;
     };
   };
 }

web/src/types/timeline.ts

@@ -22,6 +22,7 @@ export type TrackingDetailsSequence = {
     attribute: string;
     attribute_box?: [number, number, number, number];
     zones: string[];
+    zones_friendly_names?: string[];
   };
   class_type: LifecycleClassType;
   source_id: string;

web/src/utils/lifecycleUtil.ts

@@ -1,25 +1,7 @@
 import { TrackingDetailsSequence } from "@/types/timeline";
 import { t } from "i18next";
 import { getTranslatedLabel } from "./i18n";
-import { capitalizeFirstLetter } from "./stringUtil";
+import { capitalizeFirstLetter, formatList } from "./stringUtil";
-
-function formatZonesList(zones: string[]): string {
-  if (zones.length === 0) return "";
-  if (zones.length === 1) return zones[0];
-  if (zones.length === 2) {
-    return t("list.two", {
-      0: zones[0],
-      1: zones[1],
-    });
-  }
-
-  const separatorWithSpace = t("list.separatorWithSpace", { ns: "common" });
-  const allButLast = zones.slice(0, -1).join(separatorWithSpace);
-  return t("list.many", {
-    items: allButLast,
-    last: zones[zones.length - 1],
-  });
-}
 
 export function getLifecycleItemDescription(
   lifecycleItem: TrackingDetailsSequence,
@@ -42,7 +24,9 @@ export function getLifecycleItemDescription(
       return t("trackingDetails.lifecycleItemDesc.entered_zone", {
         ns: "views/explore",
         label,
-        zones: formatZonesList(lifecycleItem.data.zones),
+        zones: formatList(
+          lifecycleItem.data.zones_friendly_names ?? lifecycleItem.data.zones,
+        ),
       });
     case "active":
       return t("trackingDetails.lifecycleItemDesc.active", {

web/src/utils/stringUtil.ts

@@ -1,3 +1,5 @@
+import { t } from "i18next";
+
 export const capitalizeFirstLetter = (text: string): string => {
   return text.charAt(0).toUpperCase() + text.slice(1);
 };
@@ -45,3 +47,29 @@ export function generateFixedHash(name: string, prefix: string = "id"): string {
 export function isValidId(name: string): boolean {
   return /^[a-zA-Z0-9_-]+$/.test(name) && !/^\d+$/.test(name);
 }
+
+/**
+ * Formats a list of strings into a human-readable format with proper localization.
+ * Handles different cases for empty, single-item, two-item, and multi-item lists.
+ *
+ * @param item - The array of strings to format
+ * @returns A formatted string representation of the list
+ */
+export function formatList(item: string[]): string {
+  if (item.length === 0) return "";
+  if (item.length === 1) return item[0];
+  if (item.length === 2) {
+    return t("list.two", {
+      0: item[0],
+      1: item[1],
+      ns: "common",
+    });
+  }
+
+  const separatorWithSpace = t("list.separatorWithSpace", { ns: "common" });
+  const allButLast = item.slice(0, -1).join(separatorWithSpace);
+  return t("list.many", {
+    items: allButLast,
+    last: item[item.length - 1],
+  });
+}

web/src/views/recording/RecordingView.tsx

@@ -63,7 +63,7 @@ import {
   TooltipContent,
   TooltipTrigger,
 } from "@/components/ui/tooltip";
-import { CameraNameLabel } from "@/components/camera/CameraNameLabel";
+import { CameraNameLabel } from "@/components/camera/FriendlyNameLabel";
 import { useAllowedCameras } from "@/hooks/use-allowed-cameras";
 import { DetailStreamProvider } from "@/context/detail-stream-context";
 import { GenAISummaryDialog } from "@/components/overlay/chip/GenAISummaryChip";

web/src/views/settings/AuthenticationView.tsx

@@ -36,7 +36,7 @@ import EditRoleCamerasDialog from "@/components/overlay/EditRoleCamerasDialog";
 import { useTranslation } from "react-i18next";
 import DeleteRoleDialog from "@/components/overlay/DeleteRoleDialog";
 import { Separator } from "@/components/ui/separator";
-import { CameraNameLabel } from "@/components/camera/CameraNameLabel";
+import { CameraNameLabel } from "@/components/camera/FriendlyNameLabel";
 
 type AuthenticationViewProps = {
   section?: "users" | "roles";

web/src/views/settings/CameraManagementView.tsx

@@ -18,7 +18,7 @@ import {
 } from "@/components/ui/select";
 import { IoMdArrowRoundBack } from "react-icons/io";
 import { isDesktop } from "react-device-detect";
-import { CameraNameLabel } from "@/components/camera/CameraNameLabel";
+import { CameraNameLabel } from "@/components/camera/FriendlyNameLabel";
 import { Switch } from "@/components/ui/switch";
 import { Trans } from "react-i18next";
 import { Separator } from "@/components/ui/separator";

web/src/views/settings/CameraSettingsView.tsx

@@ -23,7 +23,6 @@ import { StatusBarMessagesContext } from "@/context/statusbar-provider";
 import axios from "axios";
 import { Link } from "react-router-dom";
 import { LuExternalLink } from "react-icons/lu";
-import { capitalizeFirstLetter } from "@/utils/stringUtil";
 import { MdCircle } from "react-icons/md";
 import { cn } from "@/lib/utils";
 import { Trans, useTranslation } from "react-i18next";
@@ -42,6 +41,8 @@ import CameraWizardDialog from "@/components/settings/CameraWizardDialog";
 import { IoMdArrowRoundBack } from "react-icons/io";
 import { isDesktop } from "react-device-detect";
 import { useCameraFriendlyName } from "@/hooks/use-camera-friendly-name";
+import { resolveZoneName } from "@/hooks/use-zone-friendly-name";
+import { formatList } from "@/utils/stringUtil";
 
 type CameraSettingsViewProps = {
   selectedCamera: string;
@@ -86,40 +87,47 @@ export default function CameraSettingsView({
 
   // zones and labels
 
+  const getZoneName = useCallback(
+    (zoneId: string, cameraId?: string) =>
+      resolveZoneName(config, zoneId, cameraId),
+    [config],
+  );
+
   const zones = useMemo(() => {
     if (cameraConfig) {
       return Object.entries(cameraConfig.zones).map(([name, zoneData]) => ({
         camera: cameraConfig.name,
         name,
+        friendly_name: getZoneName(name, cameraConfig.name),
         objects: zoneData.objects,
         color: zoneData.color,
       }));
     }
-  }, [cameraConfig]);
+  }, [cameraConfig, getZoneName]);
 
   const alertsLabels = useMemo(() => {
     return cameraConfig?.review.alerts.labels
-      ? cameraConfig.review.alerts.labels
+      ? formatList(
-          .map((label) =>
+          cameraConfig.review.alerts.labels.map((label) =>
             getTranslatedLabel(
               label,
               cameraConfig?.audio?.listen?.includes(label) ? "audio" : "object",
             ),
+          ),
         )
-          .join(", ")
       : "";
   }, [cameraConfig]);
 
   const detectionsLabels = useMemo(() => {
     return cameraConfig?.review.detections.labels
-      ? cameraConfig.review.detections.labels
+      ? formatList(
-          .map((label) =>
+          cameraConfig.review.detections.labels.map((label) =>
             getTranslatedLabel(
               label,
               cameraConfig?.audio?.listen?.includes(label) ? "audio" : "object",
             ),
+          ),
         )
-          .join(", ")
       : "";
   }, [cameraConfig]);
 
@@ -526,7 +534,7 @@ export default function CameraSettingsView({
                                           />
                                         </FormControl>
                                         <FormLabel className="font-normal smart-capitalize">
-                                          {zone.name.replaceAll("_", " ")}
+                                          {zone.friendly_name}
                                         </FormLabel>
                                       </FormItem>
                                     )}
@@ -548,14 +556,11 @@ export default function CameraSettingsView({
                                   "cameraReview.reviewClassification.zoneObjectAlertsTips",
                                   {
                                     alertsLabels,
-                                    zone: watchedAlertsZones
+                                    zone: formatList(
-                                      .map((zone) =>
+                                      watchedAlertsZones.map((zone) =>
-                                        capitalizeFirstLetter(zone).replaceAll(
+                                        getZoneName(zone),
-                                          "_",
+                                      ),
-                                          " ",
                                     ),
-                                      )
-                                      .join(", "),
                                     cameraName: selectCameraName,
                                   },
                                 )
@@ -628,7 +633,7 @@ export default function CameraSettingsView({
                                             />
                                           </FormControl>
                                           <FormLabel className="font-normal smart-capitalize">
-                                            {zone.name.replaceAll("_", " ")}
+                                            {zone.friendly_name}
                                           </FormLabel>
                                         </FormItem>
                                       )}
@@ -667,14 +672,11 @@ export default function CameraSettingsView({
                                   i18nKey="cameraReview.reviewClassification.zoneObjectDetectionsTips.text"
                                   values={{
                                     detectionsLabels,
-                                    zone: watchedDetectionsZones
+                                    zone: formatList(
-                                      .map((zone) =>
+                                      watchedDetectionsZones.map((zone) =>
-                                        capitalizeFirstLetter(zone).replaceAll(
+                                        getZoneName(zone),
-                                          "_",
+                                      ),
-                                          " ",
                                     ),
-                                      )
-                                      .join(", "),
                                     cameraName: selectCameraName,
                                   }}
                                   ns="views/settings"
@@ -684,14 +686,11 @@ export default function CameraSettingsView({
                                   i18nKey="cameraReview.reviewClassification.zoneObjectDetectionsTips.notSelectDetections"
                                   values={{
                                     detectionsLabels,
-                                    zone: watchedDetectionsZones
+                                    zone: formatList(
-                                      .map((zone) =>
+                                      watchedDetectionsZones.map((zone) =>
-                                        capitalizeFirstLetter(zone).replaceAll(
+                                        getZoneName(zone),
-                                          "_",
+                                      ),
-                                          " ",
                                     ),
-                                      )
-                                      .join(", "),
                                     cameraName: selectCameraName,
                                   }}
                                   ns="views/settings"

web/src/views/settings/FrigatePlusSettingsView.tsx

@@ -23,7 +23,7 @@ import {
   SelectTrigger,
 } from "@/components/ui/select";
 import { useDocDomain } from "@/hooks/use-doc-domain";
-import { CameraNameLabel } from "@/components/camera/CameraNameLabel";
+import { CameraNameLabel } from "@/components/camera/FriendlyNameLabel";
 
 type FrigatePlusModel = {
   id: string;

web/src/views/settings/MasksAndZonesView.tsx

@@ -229,6 +229,7 @@ export default function MasksAndZonesView({
           typeIndex: index,
           camera: cameraConfig.name,
           name,
+          friendly_name: zoneData.friendly_name,
           objects: zoneData.objects,
           points: interpolatePoints(
             parseCoordinates(zoneData.coordinates),

web/src/views/settings/NotificationsSettingsView.tsx

@@ -45,7 +45,7 @@ import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
 import { Trans, useTranslation } from "react-i18next";
 import { useDateLocale } from "@/hooks/use-date-locale";
 import { useDocDomain } from "@/hooks/use-doc-domain";
-import { CameraNameLabel } from "@/components/camera/CameraNameLabel";
+import { CameraNameLabel } from "@/components/camera/FriendlyNameLabel";
 import { useIsAdmin } from "@/hooks/use-is-admin";
 import { cn } from "@/lib/utils";
 
@@ -476,7 +476,7 @@ export default function NotificationView({
                                   <FilterSwitch
                                     key={camera.name}
                                     label={camera.name}
-                                    isCameraName={true}
+                                    type={"camera"}
                                     isChecked={field.value?.includes(
                                       camera.name,
                                     )}

web/src/views/system/CameraMetrics.tsx

@@ -13,7 +13,7 @@ import {
 } from "@/components/ui/tooltip";
 import useSWR from "swr";
 import { useTranslation } from "react-i18next";
-import { CameraNameLabel } from "@/components/camera/CameraNameLabel";
+import { CameraNameLabel } from "@/components/camera/FriendlyNameLabel";
 import { resolveCameraName } from "@/hooks/use-camera-friendly-name";
 
 type CameraMetricsProps = {