Merge 7a22963e6d into ea131e1663

Resolve conflicts in the export pipeline where dev's job-queue refactor
met master's chapter-metadata and security work.

- Unify chapter support under ChaptersEnum (none / recording_segments /
  review_items); the realtime stream-copy export selects the per-segment
  or per-review-item builder by the camera's configured mode. Thread
  chapters through ExportRecordingsBody -> _build_export_job -> ExportJob
  -> RecordingExporter.
- Keep master's creation_time/comment export metadata and fix a
  video_path duplication the textual merge introduced in the preview
  command.
- Move the chapters request field to ExportRecordingsBody (the single
  export endpoint) where it is actually honored.

Restore security fixes the automatic merge would have reverted:
- frigate/util/services.py: restore the #23493 rename to the public
  is_go2rtc_arbitrary_exec_allowed so create_config.py's dynamic-source
  exec guard imports and runs (the merge otherwise left a broken import).
- Preserve the export image-path ".." traversal check inside
  _sanitize_existing_image, applied to single/custom/batch exports.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docker/main/rootfs/usr/local/go2rtc/create_config.py

@@ -15,12 +15,24 @@ from frigate.const import (
 )
 from frigate.ffmpeg_presets import parse_preset_hardware_acceleration_encode
 from frigate.util.config import find_config_file, resolve_ffmpeg_path
-from frigate.util.services import is_restricted_go2rtc_source
+from frigate.util.services import (
+    is_go2rtc_arbitrary_exec_allowed,
+    is_restricted_go2rtc_source,
+)
 
 sys.path.remove("/opt/frigate")
 
 yaml = YAML()
 
+FRIGATE_ENV_VARS = {k: v for k, v in os.environ.items() if k.startswith("FRIGATE_")}
+# read docker secret files as env vars too
+if os.path.isdir("/run/secrets"):
+    for secret_file in os.listdir("/run/secrets"):
+        if secret_file.startswith("FRIGATE_"):
+            FRIGATE_ENV_VARS[secret_file] = (
+                Path(os.path.join("/run/secrets", secret_file)).read_text().strip()
+            )
+
 config_file = find_config_file()
 
 try:
@@ -100,7 +112,7 @@ for name in list(go2rtc_config.get("streams", {})):
 
     if isinstance(stream, str):
         try:
-            formatted_stream = substitute_frigate_vars(stream)
+            formatted_stream = stream.format(**FRIGATE_ENV_VARS)
             if is_restricted_go2rtc_source(formatted_stream):
                 print(
                     f"[ERROR] Stream '{name}' uses a restricted source (echo/expr/exec) which is disabled by default for security. "
@@ -119,7 +131,7 @@ for name in list(go2rtc_config.get("streams", {})):
         filtered_streams = []
         for i, stream_item in enumerate(stream):
             try:
-                formatted_stream = substitute_frigate_vars(stream_item)
+                formatted_stream = stream_item.format(**FRIGATE_ENV_VARS)
                 if is_restricted_go2rtc_source(formatted_stream):
                     print(
                         f"[ERROR] Stream '{name}' item {i + 1} uses a restricted source (echo/expr/exec) which is disabled by default for security. "
@@ -143,6 +155,20 @@ for name in list(go2rtc_config.get("streams", {})):
             )
             del go2rtc_config["streams"][name]
 
+    elif isinstance(stream, dict):
+        # The map form ({"url": ...}) lets go2rtc resolve the source
+        # recursively, so it is effectively a dynamic way to generate the URL
+        # for a stream. That can only be backed by an exec source, so it cannot
+        # be allowed unless arbitrary exec is explicitly enabled. When it is
+        # enabled, leave the map untouched for go2rtc to resolve.
+        if not is_go2rtc_arbitrary_exec_allowed():
+            print(
+                f"[ERROR] Stream '{name}' uses a dynamic source format which is disabled by default for security. "
+                f"Set GO2RTC_ALLOW_ARBITRARY_EXEC=true to enable arbitrary exec sources."
+            )
+            del go2rtc_config["streams"][name]
+            continue
+
 # add birdseye restream stream if enabled
 if config.get("birdseye", {}).get("restream", False):
     birdseye: dict[str, Any] = config.get("birdseye")

docs/docs/configuration/masks.md

@@ -7,6 +7,8 @@ import ConfigTabs from "@site/src/components/ConfigTabs";
 import TabItem from "@theme/TabItem";
 import NavPath from "@site/src/components/NavPath";
 
+Frigate has two kinds of masks: motion masks and object filter masks. Both are narrow tools for fine-tuning, **not for hiding an area from Frigate**. Masks should be used sparingly; in most cases where users reach for one, a [zone](zones.md) with `required_zones` is the right tool instead. See [Which tool do I need?](#which-tool-do-i-need) and [Common mistakes](#common-mistakes) below if you're new to Frigate's mask behavior.
+
 ## Motion masks
 
 Motion masks are used to prevent unwanted types of motion from triggering detection. Try watching the Debug feed (Settings --> Debug) with `Motion Boxes` enabled to see what may be regularly detected as motion. For example, you want to mask out your timestamp, the sky, rooftops, etc. Keep in mind that this mask only prevents motion from being detected and does not prevent objects from being detected if object detection was started due to motion in unmasked areas. Motion is also used during object tracking to refine the object detection area in the next frame. _Over-masking will make it more difficult for objects to be tracked._
@@ -21,7 +23,16 @@ Object filter masks can be used to filter out stubborn false positives in fixed
 
 ![object mask](/img/bottom-center-mask.jpg)
 
-## Creating masks
+## Which tool do I need?
+
+| What you're trying to do                                                                                                       | Recommended tool                                                                                            | How it works                                                                                                                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Don't get alerts or recordings for activity in an area (e.g., the sidewalk in front of your house)                             | A [zone](zones.md) combined with `review.alerts.required_zones` (and/or `review.detections.required_zones`) | Frigate keeps detecting and tracking activity in the area, but a review item is only created once the bottom-center of an object's bounding box enters a required zone.                     |
+| Stop a stubborn false positive at a specific fixed spot (e.g., a tree base that keeps being detected as a person)              | An **object filter mask** for that object type                                                              | Any detection of that object type whose bounding-box bottom-center lands inside the mask is treated as a false positive and discarded.                                                      |
+| Ignore motion in an area that obviously isn't an object of interest (e.g., the camera timestamp, sky, flags, treetops swaying) | A **motion mask**                                                                                           | Motion inside the mask is ignored when deciding whether to run object detection. Objects can still be detected in a motion masked area if motion elsewhere in the frame triggers detection. |
+| Stop tracking an object type altogether on this camera (e.g., you never care about cats)                                       | Remove the object from the camera's [`objects.track`](objects.md) list                                      | Frigate skips this object type entirely on this camera, regardless of where it appears.                                                                                                     |
+
+## Using the mask creator
 
 <ConfigTabs>
 <TabItem value="ui">
@@ -124,3 +135,14 @@ This is what `required_zones` are for. You should define a zone (remember this i
 > Maybe my specific situation just warrants this. I've just been having a hard time understanding the relevance of this information - it seems to be that it's exactly what would be expected when "masking out" an area of ANY image.
 
 That may be the case for you. Frigate will definitely work harder tracking people on the sidewalk to make sure it doesn't miss anyone who steps foot on your stoop. The trade off with the way you have it now is slower recognition of objects and potential misses. That may be acceptable based on your needs. Also, if your resolution is low enough on the detect stream, your regions may already be so big that they grab the entire object anyway.
+
+## Common mistakes
+
+**"I added a motion mask to ignore my driveway/sidewalk."**
+A motion mask doesn't hide an area from Frigate. Objects can still be detected and tracked inside a masked area. The mask only stops motion _in that area_ from triggering object detection. If you want activity on the sidewalk to never produce a review item, define a [zone](zones.md) over the area you DO care about (your stoop, your driveway) and add it to `review.alerts.required_zones`. Frigate will still see people on the sidewalk, but it won't create an alert until they cross into the zone.
+
+**"I added an object filter mask because I don't care about cars in my yard."**
+Object filter masks are for stubborn false positives at fixed locations, not for filtering whole areas or whole object types. If you only want alerts when a car enters the driveway, use a [zone](zones.md) with `required_zones`. If you don't care about a whole object type on this camera, remove it from [`objects.track`](objects.md).
+
+**"I masked everything except a thin strip on my stoop."**
+Heavy masking hurts tracking. Frigate uses motion near a tracked object's previous bounding box to decide where to look in the next frame; with most of the frame masked, an object walking from an unmasked area into a masked one effectively disappears and gets picked up as a "new" object when it reappears. For example: someone walks down your sidewalk, stops under a tree (masked area) to tie their shoe, then continues. Frigate sees that as two separate people and can create two separate review items. Because Frigate needs several consecutive frames above the confidence threshold to commit to a detection, each re-appearance can also delay or miss alerts. Use `required_zones` for "only alert me about this spot" and leave the surrounding area unmasked so tracking stays intact.

docs/docs/troubleshooting/faqs.md

@@ -124,3 +124,19 @@ cameras:
       width: 1280
       height: 720
 ```
+
+### Why does Frigate keep creating new events for my parked car?
+
+Stationary tracking is designed to _prevent_ this — a parked car should stay one tracked object and not generate new events. If you're getting repeated events for the same car, it's likely that Frigate is losing the tracked object and re-detecting it as a new one.
+
+Open one of the events in Explore → **Tracking Details**. If the detection scores are low (< 70% or so), the model isn't confident the parked car is a car. This is common with the free [COCO-trained](https://cocodataset.org/#explore) object detection models on steep/top-down angles, partially occluded cars, foliage, or low-light footage. When detections fall below `min_score` for too many frames the tracker loses the object, and the next confident frame creates a brand new one.
+
+What helps:
+
+- **Improve the view** — even a small angle change that gets more of the car visible could lift scores enough to stabilize tracking.
+- **Use a more accurate model** — switching from `mobiledet` to `yolov9`, or stepping up to a larger variant like `yolov9-s` over `yolov9-t`, can help (at the cost of inference time, and still on the COCO dataset). The biggest gains usually come from fine-tuning a model on images from your own cameras so it learns your specific scene. [Frigate+](https://frigate.video/plus) is a paid option that does this - models are trained on security-camera footage and can be fine-tuned on images you submit from your own setup.
+- **Don't set `detect -> stationary -> max_frames` for `car`** — it artificially ends tracking and forces re-detection as a new object. See [Stationary Objects](../configuration/stationary_objects.md).
+- **Restrict alerts to the areas you care about** with `required_zones` — see [Zones](../configuration/zones.md#restricting-alerts-and-detections-to-specific-zones). Make sure those zones use the default `loitering_time: 0` unless you specifically want the review item to stay open until the car leaves.
+- **Filter impossible locations** with [object filter masks](../configuration/masks.md#object-filter-masks) if cars are being detected on rooftops, treetops, etc.
+
+See [Object Filters](../configuration/object_filters.md) for more on tuning `min_score` and `threshold` — note that raising them too high will make this exact problem worse.

docs/static/frigate-api.yaml

@@ -7393,6 +7393,13 @@ components:
       required:
         - value
       title: CameraSetBody
+    ChaptersEnum:
+      type: string
+      enum:
+        - none
+        - recording_segments
+        - review_items
+      title: ChaptersEnum
     ChatCompletionRequest:
       properties:
         messages:
@@ -8119,6 +8126,13 @@ components:
             - type: 'null'
           title: Export case ID
           description: ID of the export case to assign this export to
+        chapters:
+          anyOf:
+            - $ref: '#/components/schemas/ChaptersEnum'
+            - type: 'null'
+          title: Chapter mode
+          description: Optional chapter metadata to embed in the export. When 
+            omitted, the camera's configured export chapter mode is used.
       type: object
       title: ExportRecordingsBody
     ExportRecordingsCustomBody:

frigate/api/camera.py

@@ -147,6 +147,19 @@ def go2rtc_camera_stream(request: Request, stream_name: str):
 )
 def go2rtc_add_stream(request: Request, stream_name: str, src: str = ""):
     """Add or update a go2rtc stream configuration."""
+    if src and is_restricted_go2rtc_source(src):
+        logger.warning(
+            "Rejected go2rtc stream '%s' with restricted source type (echo/expr/exec)",
+            stream_name,
+        )
+        return JSONResponse(
+            content={
+                "success": False,
+                "message": "Restricted stream source type",
+            },
+            status_code=400,
+        )
+
     try:
         params = {"name": stream_name}
         if src:
@@ -637,6 +650,32 @@ async def _connect_onvif_camera(
     raise first_error
 
 
+def _supports_continuous_pan_tilt(nodes) -> bool:
+    """Whether any PTZ node advertises continuous pan/tilt velocity.
+
+    The web UI's directional controls issue ContinuousMove with a PanTilt
+    velocity, so continuous pan/tilt is what makes those controls usable. This
+    is intentionally narrower than ptz_supported, which is true for any device
+    exposing the ONVIF PTZ service - including zoom/focus-only varifocal lenses.
+    """
+    for node in nodes or []:
+        spaces = getattr(node, "SupportedPTZSpaces", None) or (
+            node.get("SupportedPTZSpaces") if isinstance(node, dict) else None
+        )
+        if spaces is None:
+            continue
+
+        continuous = getattr(spaces, "ContinuousPanTiltVelocitySpace", None) or (
+            spaces.get("ContinuousPanTiltVelocitySpace")
+            if isinstance(spaces, dict)
+            else None
+        )
+        if continuous:
+            return True
+
+    return False
+
+
 @router.get(
     "/onvif/probe",
     dependencies=[Depends(require_role(["admin"]))],
@@ -794,6 +833,7 @@ async def onvif_probe(
 
         # Check PTZ support and capabilities
         ptz_supported = False
+        pan_tilt_supported = False
         presets_count = 0
         autotrack_supported = False
 
@@ -827,6 +867,15 @@ async def onvif_probe(
                     logger.debug(f"Failed to get presets: {e}")
                     presets_count = 0
 
+            # Check for real (continuous) pan/tilt, which the UI controls need
+            if ptz_supported:
+                try:
+                    nodes = await ptz_service.GetNodes()
+                    pan_tilt_supported = _supports_continuous_pan_tilt(nodes)
+                    logger.debug(f"Continuous pan/tilt supported: {pan_tilt_supported}")
+                except Exception as e:
+                    logger.debug(f"Failed to read PTZ nodes for pan/tilt support: {e}")
+
             # Check for autotracking support - requires both FOV relative movement and MoveStatus
             if ptz_supported and first_profile_token and ptz_config_token:
                 # First check for FOV relative movement support
@@ -946,6 +995,7 @@ async def onvif_probe(
             "firmware_version": device_info["firmware_version"],
             "profiles_count": profiles_count,
             "ptz_supported": ptz_supported,
+            "pan_tilt_supported": pan_tilt_supported,
             "presets_count": presets_count,
             "autotrack_supported": autotrack_supported,
         }

frigate/api/defs/request/export_recordings_body.py

@@ -3,7 +3,10 @@ from typing import Optional, Union
 from pydantic import BaseModel, Field
 from pydantic.json_schema import SkipJsonSchema
 
-from frigate.record.export import PlaybackSourceEnum
+from frigate.record.export import (
+    ChaptersEnum,
+    PlaybackSourceEnum,
+)
 
 
 class ExportRecordingsBody(BaseModel):
@@ -18,6 +21,14 @@ class ExportRecordingsBody(BaseModel):
         max_length=30,
         description="ID of the export case to assign this export to",
     )
+    chapters: Optional[ChaptersEnum] = Field(
+        default=None,
+        title="Chapter mode",
+        description=(
+            "Optional chapter metadata to embed in the export. When omitted, "
+            "the camera's configured export chapter mode is used."
+        ),
+    )
 
 
 class ExportRecordingsCustomBody(BaseModel):

frigate/api/export.py

@@ -68,6 +68,7 @@ from frigate.jobs.export import (
 from frigate.models import Export, ExportCase, Previews, Recordings
 from frigate.record.export import (
     DEFAULT_TIME_LAPSE_FFMPEG_ARGS,
+    ChaptersEnum,
     PlaybackSourceEnum,
     validate_ffmpeg_args,
 )
@@ -128,6 +129,15 @@ def _validate_export_case(export_case_id: Optional[str]) -> Optional[JSONRespons
 def _sanitize_existing_image(
     image_path: Optional[str],
 ) -> tuple[Optional[str], Optional[JSONResponse]]:
+    # sanitize_filepath normalizes "\" to "/" but leaves ".." intact, so a path
+    # like "clips\..\..\etc/passwd" passes the CLIPS_DIR prefix check yet still
+    # escapes the directory once resolved. A valid snapshot path never uses "..".
+    if image_path and ".." in image_path:
+        return None, JSONResponse(
+            content={"success": False, "message": "Invalid image path"},
+            status_code=400,
+        )
+
     existing_image = sanitize_filepath(image_path) if image_path else None
 
     if existing_image and not existing_image.startswith(CLIPS_DIR):
@@ -254,6 +264,7 @@ def _build_export_job(
     ffmpeg_input_args: Optional[str] = None,
     ffmpeg_output_args: Optional[str] = None,
     cpu_fallback: bool = False,
+    chapters: Optional[ChaptersEnum] = None,
 ) -> ExportJob:
     return ExportJob(
         id=_generate_export_id(camera_name),
@@ -267,6 +278,7 @@ def _build_export_job(
         ffmpeg_input_args=ffmpeg_input_args,
         ffmpeg_output_args=ffmpeg_output_args,
         cpu_fallback=cpu_fallback,
+        chapters=chapters,
     )
 
 
@@ -725,6 +737,9 @@ def export_recordings_batch(
             sanitized_images[index],
             PlaybackSourceEnum.recordings,
             export_case_id,
+            chapters=request.app.frigate_config.cameras[
+                item.camera
+            ].record.export.chapters,
         )
         try:
             start_export_job(request.app.frigate_config, export_job)
@@ -803,6 +818,14 @@ def export_recording(
 
     export_case_id = body.export_case_id
 
+    # a chapters value in the request body overrides the camera's export config
+    camera_config = request.app.frigate_config.cameras[camera_name]
+    chapters = (
+        body.chapters
+        if body.chapters is not None
+        else camera_config.record.export.chapters
+    )
+
     # Attaching to an existing case requires admin. Single-export for
     # cameras the user can access is otherwise non-admin; we only gate
     # the case-attachment side effect.
@@ -839,6 +862,7 @@ def export_recording(
         existing_image,
         playback_source,
         export_case_id,
+        chapters=chapters,
     )
     try:
         start_export_job(request.app.frigate_config, export_job)

frigate/api/media.py

@@ -60,6 +60,19 @@ logger = logging.getLogger(__name__)
 router = APIRouter(tags=[Tags.media])
 
 
+def _resolve_cache_age(max_cache_age: int) -> int:
+    """Return max_cache_age as an int.
+
+    When a media handler is invoked directly by another handler instead of
+    through its route, FastAPI doesn't resolve the Query() default and
+    max_cache_age arrives as the Query object; fall back to its int default.
+    """
+    if isinstance(max_cache_age, int):
+        return max_cache_age
+
+    return max_cache_age.default
+
+
 @router.get("/{camera_name}", dependencies=[Depends(require_camera_access)])
 async def mjpeg_feed(
     request: Request,
@@ -413,7 +426,9 @@ async def submit_recording_snapshot_to_plus(
             )
 
         nd = cv2.imdecode(np.frombuffer(image_data, dtype=np.int8), cv2.IMREAD_COLOR)
-        request.app.frigate_config.plus_api.upload_image(nd, camera_name)
+        await asyncio.to_thread(
+            request.app.frigate_config.plus_api.upload_image, nd, camera_name
+        )
 
         return JSONResponse(
             content={
@@ -936,7 +951,7 @@ async def event_thumbnail(
         thumbnail_bytes,
         media_type=extension.get_mime_type(),
         headers={
-            "Cache-Control": f"private, max-age={max_cache_age}"
+            "Cache-Control": f"private, max-age={_resolve_cache_age(max_cache_age)}"
             if event_complete
             else "no-store",
         },
@@ -1270,14 +1285,14 @@ async def event_preview(request: Request, event_id: str):
     end_ts = start_ts + (
         min(event.end_time - event.start_time, 20) if event.end_time else 20
     )
-    return preview_gif(request, event.camera, start_ts, end_ts)
+    return await preview_gif(request, event.camera, start_ts, end_ts)
 
 
 @router.get(
     "/{camera_name}/start/{start_ts}/end/{end_ts}/preview.gif",
     dependencies=[Depends(require_camera_access)],
 )
-def preview_gif(
+async def preview_gif(
     request: Request,
     camera_name: str,
     start_ts: float,
@@ -1340,7 +1355,8 @@ def preview_gif(
             "-",
         ]
 
-        process = sp.run(
+        process = await asyncio.to_thread(
+            sp.run,
             ffmpeg_cmd,
             capture_output=True,
         )
@@ -1419,7 +1435,8 @@ def preview_gif(
             "-",
         ]
 
-        process = sp.run(
+        process = await asyncio.to_thread(
+            sp.run,
             ffmpeg_cmd,
             input=str.encode("\n".join(selected_previews)),
             capture_output=True,
@@ -1438,7 +1455,7 @@ def preview_gif(
         gif_bytes,
         media_type="image/gif",
         headers={
-            "Cache-Control": f"private, max-age={max_cache_age}",
+            "Cache-Control": f"private, max-age={_resolve_cache_age(max_cache_age)}",
             "Content-Type": "image/gif",
         },
     )
@@ -1448,7 +1465,7 @@ def preview_gif(
     "/{camera_name}/start/{start_ts}/end/{end_ts}/preview.mp4",
     dependencies=[Depends(require_camera_access)],
 )
-def preview_mp4(
+async def preview_mp4(
     request: Request,
     camera_name: str,
     start_ts: float,
@@ -1528,7 +1545,8 @@ def preview_mp4(
             path,
         ]
 
-        process = sp.run(
+        process = await asyncio.to_thread(
+            sp.run,
             ffmpeg_cmd,
             capture_output=True,
         )
@@ -1604,7 +1622,8 @@ def preview_mp4(
             path,
         ]
 
-        process = sp.run(
+        process = await asyncio.to_thread(
+            sp.run,
             ffmpeg_cmd,
             input=str.encode("\n".join(selected_previews)),
             capture_output=True,
@@ -1619,7 +1638,7 @@ def preview_mp4(
 
     headers = {
         "Content-Description": "File Transfer",
-        "Cache-Control": f"private, max-age={max_cache_age}",
+        "Cache-Control": f"private, max-age={_resolve_cache_age(max_cache_age)}",
         "Content-Type": "video/mp4",
         "Content-Length": str(os.path.getsize(path)),
         # nginx: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ignore_headers
@@ -1657,9 +1676,9 @@ async def review_preview(
     )
 
     if format == "gif":
-        return preview_gif(request, review.camera, start_ts, end_ts)
+        return await preview_gif(request, review.camera, start_ts, end_ts)
     else:
-        return preview_mp4(request, review.camera, start_ts, end_ts)
+        return await preview_mp4(request, review.camera, start_ts, end_ts)
 
 
 @router.get(

frigate/comms/ws.py

@@ -72,11 +72,16 @@ _WS_VIEWER_TOPICS = frozenset(
     }
 )
 
+# Camera-scoped command topics a camera-authorized (non-admin) user may send.
+_WS_CAMERA_COMMAND_TOPICS = frozenset({"ptz"})
+
 
 def _check_ws_authorization(
     topic: str,
     role_header: str | None,
     separator: str,
+    roles_config: dict[str, list[str]] | None = None,
+    camera_names: set[str] | None = None,
 ) -> bool:
     """Check if a WebSocket message is authorized.
 
@@ -84,6 +89,10 @@ def _check_ws_authorization(
         topic: The message topic.
         role_header: The HTTP_REMOTE_ROLE header value, or None.
         separator: The role separator character from proxy config.
+        roles_config: The auth.roles mapping (role -> allowed cameras), used to
+            authorize camera-scoped commands for non-admin users.
+        camera_names: All configured camera names, used to resolve a role's
+            allowed cameras.
 
     Returns:
         True if authorized, False if blocked.
@@ -93,16 +102,33 @@ def _check_ws_authorization(
         return False
 
     # No role header: default to viewer (fail-closed)
-    if role_header is None:
-        return topic in _WS_VIEWER_TOPICS
+    roles = [r.strip() for r in role_header.split(separator)] if role_header else []
 
-    # Check if any role is admin
-    roles = [r.strip() for r in role_header.split(separator)]
+    # Admin can send anything
     if "admin" in roles:
         return True
 
-    # Non-admin: only viewer topics allowed
-    return topic in _WS_VIEWER_TOPICS
+    # Read-only topics any authenticated user can send
+    if topic in _WS_VIEWER_TOPICS:
+        return True
+
+    # Camera-scoped command like "<camera>/ptz": allow when the user's role(s)
+    # grant access to that camera.
+    parts = topic.split("/")
+    if (
+        roles_config is not None
+        and len(parts) == 2
+        and parts[1] in _WS_CAMERA_COMMAND_TOPICS
+    ):
+        allowed: set[str] = set()
+        # No role header maps to the default viewer role (e.g. proxy-only setups)
+        for role in roles or ["viewer"]:
+            allowed.update(
+                User.get_allowed_cameras(role, roles_config, camera_names or set())
+            )
+        return parts[0] in allowed
+
+    return False
 
 
 # ---- Outbound filtering ---------------------------------------------------
@@ -449,6 +475,8 @@ class WebSocketClient(Communicator):
         class _WebSocketHandler(WebSocket):
             receiver = self._dispatcher
             role_separator = self.config.proxy.separator or ","
+            roles_config = self.config.auth.roles
+            camera_names = set(self.config.cameras.keys())
 
             def received_message(self, message: WebSocket.received_message) -> None:  # type: ignore[name-defined]
                 try:
@@ -470,7 +498,11 @@ class WebSocketClient(Communicator):
                     self.environ.get("HTTP_REMOTE_ROLE") if self.environ else None
                 )
                 if self.environ is not None and not _check_ws_authorization(
-                    topic, role_header, self.role_separator
+                    topic,
+                    role_header,
+                    self.role_separator,
+                    self.roles_config,
+                    self.camera_names,
                 ):
                     logger.warning(
                         "Blocked unauthorized WebSocket message: topic=%s, role=%s",

frigate/config/camera/record.py

@@ -9,6 +9,7 @@ from frigate.review.types import SeverityEnum
 from ..base import FrigateBaseModel
 
 __all__ = [
+    "ChaptersEnum",
     "RecordConfig",
     "RecordExportConfig",
     "RecordPreviewConfig",
@@ -86,6 +87,12 @@ class RecordPreviewConfig(FrigateBaseModel):
     )
 
 
+class ChaptersEnum(str, Enum):
+    none = "none"
+    recording_segments = "recording_segments"
+    review_items = "review_items"
+
+
 class RecordExportConfig(FrigateBaseModel):
     hwaccel_args: Union[str, list[str]] = Field(
         default="auto",
@@ -98,6 +105,10 @@ class RecordExportConfig(FrigateBaseModel):
         title="Maximum concurrent exports",
         description="Maximum number of export jobs to process at the same time.",
     )
+    chapters: ChaptersEnum = Field(
+        default=ChaptersEnum.review_items,
+        title="Chapter metadata to embed in exported recordings",
+    )
 
 
 class RecordConfig(FrigateBaseModel):

frigate/jobs/export.py

@@ -13,6 +13,7 @@ from peewee import DoesNotExist
 
 from frigate.comms.inter_process import InterProcessRequestor
 from frigate.config import FrigateConfig
+from frigate.config.camera.record import ChaptersEnum
 from frigate.const import UPDATE_JOB_STATE
 from frigate.jobs.job import Job
 from frigate.models import Export
@@ -55,6 +56,7 @@ class ExportJob(Job):
     ffmpeg_input_args: Optional[str] = None
     ffmpeg_output_args: Optional[str] = None
     cpu_fallback: bool = False
+    chapters: Optional[ChaptersEnum] = None
     current_step: str = "queued"
     progress_percent: float = 0.0
 
@@ -343,6 +345,7 @@ class ExportJobManager:
             job.ffmpeg_input_args,
             job.ffmpeg_output_args,
             job.cpu_fallback,
+            job.chapters,
             on_progress=self._make_progress_callback(job),
         )
 

frigate/ptz/onvif.py

@@ -72,7 +72,11 @@ class OnvifController:
         self.config_subscriber = CameraConfigUpdateSubscriber(
             self.config,
             self.config.cameras,
-            [CameraConfigUpdateEnum.onvif],
+            [
+                CameraConfigUpdateEnum.onvif,
+                CameraConfigUpdateEnum.add,
+                CameraConfigUpdateEnum.remove,
+            ],
         )
 
         asyncio.run_coroutine_threadsafe(self._init_cameras(), self.loop)
@@ -101,6 +105,16 @@ class OnvifController:
                     if update_type == CameraConfigUpdateEnum.onvif.name:
                         for cam_name in cameras:
                             await self._reinit_camera(cam_name)
+                    elif update_type == CameraConfigUpdateEnum.add.name:
+                        # a camera added at runtime only needs ONVIF set up if
+                        # it actually has an onvif host configured
+                        for cam_name in cameras:
+                            cam = self.config.cameras.get(cam_name)
+                            if cam and cam.onvif.host:
+                                await self._reinit_camera(cam_name)
+                    elif update_type == CameraConfigUpdateEnum.remove.name:
+                        for cam_name in cameras:
+                            await self._remove_camera(cam_name)
             except Exception:
                 logger.error("Error checking for ONVIF config updates")
 
@@ -113,6 +127,18 @@ class OnvifController:
             except Exception:
                 logger.debug(f"Error closing ONVIF session for {cam_name}")
 
+    async def _remove_camera(self, cam_name: str) -> None:
+        """Tear down the ONVIF session for a camera removed at runtime."""
+        if cam_name not in self.cams and cam_name not in self.camera_configs:
+            return
+
+        logger.debug(f"Tearing down ONVIF for {cam_name} after camera removal")
+        await self._close_camera(cam_name)
+        self.cams.pop(cam_name, None)
+        self.camera_configs.pop(cam_name, None)
+        self.failed_cams.pop(cam_name, None)
+        self.status_locks.pop(cam_name, None)
+
     async def _reinit_camera(self, cam_name: str) -> None:
         """Re-initialize a camera after config change."""
         logger.info(f"Re-initializing ONVIF for {cam_name} due to config change")

frigate/record/export.py

@@ -17,6 +17,7 @@ import pytz  # type: ignore[import-untyped]
 from peewee import DoesNotExist
 
 from frigate.config import FfmpegConfig, FrigateConfig
+from frigate.config.camera.record import ChaptersEnum
 from frigate.const import (
     CACHE_DIR,
     CLIPS_DIR,
@@ -217,6 +218,7 @@ class RecordingExporter(threading.Thread):
         ffmpeg_input_args: Optional[str] = None,
         ffmpeg_output_args: Optional[str] = None,
         cpu_fallback: bool = False,
+        chapters: Optional[ChaptersEnum] = None,
         on_progress: Optional[Callable[[str, float], None]] = None,
     ) -> None:
         super().__init__()
@@ -232,6 +234,7 @@ class RecordingExporter(threading.Thread):
         self.ffmpeg_input_args = ffmpeg_input_args
         self.ffmpeg_output_args = ffmpeg_output_args
         self.cpu_fallback = cpu_fallback
+        self.chapters = chapters
         self.on_progress = on_progress
 
         # ensure export thumb dir
@@ -509,6 +512,74 @@ class RecordingExporter(threading.Thread):
 
         return meta_path
 
+    def _build_recording_segment_chapter_metadata_file(
+        self, recordings: list
+    ) -> Optional[str]:
+        """Write an FFmpeg metadata file with one chapter per recording segment.
+
+        Each chapter's title is the segment's wallclock start time in
+        strict ISO 8601 form so a viewer can map any point in the
+        export's playback timeline back to real-world time without
+        OCR-ing a burnt-in timestamp. Chapter offsets are computed in
+        *output time*: the VOD endpoint concatenates recording clips
+        back-to-back, so wall-clock gaps between recordings collapse in
+        the produced video. Returns ``None`` when there are no
+        recordings or every segment is empty after clipping.
+        """
+        if not recordings:
+            return None
+
+        tz_name = self.config.ui.timezone
+        tz: Optional[datetime.tzinfo] = None
+        if tz_name:
+            try:
+                tz = pytz.timezone(tz_name)
+            except pytz.UnknownTimeZoneError:
+                tz = None
+        if tz is None:
+            tz = datetime.timezone.utc
+
+        chapter_blocks: list[str] = []
+        output_offset_ms = 0
+        for rec in recordings:
+            clipped_start = max(float(rec.start_time), float(self.start_time))
+            clipped_end = min(float(rec.end_time), float(self.end_time))
+            if clipped_end <= clipped_start:
+                continue
+
+            duration_ms = int(round((clipped_end - clipped_start) * 1000))
+            if duration_ms <= 0:
+                continue
+
+            title = datetime.datetime.fromtimestamp(clipped_start, tz=tz).isoformat(
+                timespec="seconds"
+            )
+            chapter_blocks.append(
+                "[CHAPTER]\n"
+                "TIMEBASE=1/1000\n"
+                f"START={output_offset_ms}\n"
+                f"END={output_offset_ms + duration_ms}\n"
+                f"title={title}"
+            )
+            output_offset_ms += duration_ms
+
+        if not chapter_blocks:
+            return None
+
+        meta_path = self._chapter_metadata_path()
+        try:
+            with open(meta_path, "w", encoding="utf-8") as f:
+                f.write(";FFMETADATA1\n")
+                f.write("\n".join(chapter_blocks))
+                f.write("\n")
+        except OSError:
+            logger.exception(
+                "Failed to write chapter metadata file for export %s", self.export_id
+            )
+            return None
+
+        return meta_path
+
     def save_thumbnail(self, id: str) -> str:
         thumb_path = os.path.join(CLIPS_DIR, f"export/{id}.webp")
 
@@ -672,7 +743,18 @@ class RecordingExporter(threading.Thread):
                 )
             ).split(" ")
         else:
-            chapters_path = self._build_chapter_metadata_file(recordings)
+            # Realtime/stream-copy export. Embed chapter metadata according to
+            # the camera's configured chapter mode: per-recording-segment
+            # timestamps or per-review-item titles.
+            if self.chapters == ChaptersEnum.recording_segments:
+                chapters_path = self._build_recording_segment_chapter_metadata_file(
+                    recordings
+                )
+            elif self.chapters == ChaptersEnum.review_items:
+                chapters_path = self._build_chapter_metadata_file(recordings)
+            else:
+                chapters_path = None
+
             chapter_args = (
                 f" -i {chapters_path} -map 0 -dn -map_metadata 1"
                 if chapters_path
@@ -684,7 +766,19 @@ class RecordingExporter(threading.Thread):
 
         # add metadata
         title = f"Frigate Recording for {self.camera}, {self.get_datetime_from_timestamp(self.start_time)} - {self.get_datetime_from_timestamp(self.end_time)}"
-        ffmpeg_cmd.extend(["-metadata", f"title={title}"])
+        creation_time = datetime.datetime.fromtimestamp(
+            self.start_time, tz=datetime.timezone.utc
+        ).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+        ffmpeg_cmd.extend(
+            [
+                "-metadata",
+                f"title={title}",
+                "-metadata",
+                f"creation_time={creation_time}",
+                "-metadata",
+                f"comment=Camera: {self.camera}",
+            ]
+        )
 
         ffmpeg_cmd.append(video_path)
 
@@ -770,18 +864,32 @@ class RecordingExporter(threading.Thread):
                     self.config.ffmpeg.ffmpeg_path,
                     hwaccel_args,
                     f"{self.ffmpeg_input_args} {TIMELAPSE_DATA_INPUT_ARGS} {ffmpeg_input}".strip(),
-                    f"{self.ffmpeg_output_args} -movflags +faststart {video_path}".strip(),
+                    f"{self.ffmpeg_output_args} -movflags +faststart".strip(),
                     EncodeTypeEnum.timelapse,
                 )
             ).split(" ")
         else:
             ffmpeg_cmd = (
-                f"{self.config.ffmpeg.ffmpeg_path} -hide_banner {ffmpeg_input} {codec} -movflags +faststart {video_path}"
+                f"{self.config.ffmpeg.ffmpeg_path} -hide_banner {ffmpeg_input} {codec} -movflags +faststart"
             ).split(" ")
 
         # add metadata
         title = f"Frigate Preview for {self.camera}, {self.get_datetime_from_timestamp(self.start_time)} - {self.get_datetime_from_timestamp(self.end_time)}"
-        ffmpeg_cmd.extend(["-metadata", f"title={title}"])
+        creation_time = datetime.datetime.fromtimestamp(
+            self.start_time, tz=datetime.timezone.utc
+        ).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+        ffmpeg_cmd.extend(
+            [
+                "-metadata",
+                f"title={title}",
+                "-metadata",
+                f"creation_time={creation_time}",
+                "-metadata",
+                f"comment=Camera: {self.camera}",
+            ]
+        )
+
+        ffmpeg_cmd.append(video_path)
 
         return ffmpeg_cmd, playlist_lines
 

frigate/record/maintainer.py

@@ -650,6 +650,8 @@ class RecordingMaintainer(threading.Thread):
                     "copy",
                     "-movflags",
                     "+faststart",
+                    "-metadata",
+                    f"creation_time={start_time.strftime('%Y-%m-%dT%H:%M:%S.%fZ')}",
                     file_path,
                     stderr=asyncio.subprocess.PIPE,
                     stdout=asyncio.subprocess.DEVNULL,

frigate/test/test_ws_auth.py

@@ -11,6 +11,16 @@ class TestCheckWsAuthorization(unittest.TestCase):
 
     DEFAULT_SEPARATOR = ","
 
+    # admin/viewer are reserved and always map to all cameras (empty list);
+    # custom roles map to a specific set of cameras.
+    ROLES_CONFIG = {
+        "admin": [],
+        "viewer": [],
+        "yard": ["front_door", "backyard"],
+        "garage_only": ["garage"],
+    }
+    CAMERA_NAMES = {"front_door", "backyard", "garage"}
+
     # --- IPC topic blocking (unconditional, regardless of role) ---
 
     def test_ipc_topic_blocked_for_admin(self):
@@ -161,6 +171,124 @@ class TestCheckWsAuthorization(unittest.TestCase):
             _check_ws_authorization("onConnect", None, self.DEFAULT_SEPARATOR)
         )
 
+    # --- Camera-scoped PTZ access (non-admin with camera access) ---
+
+    def test_viewer_can_ptz_camera_with_access(self):
+        # viewer maps to all cameras, so PTZ is allowed
+        self.assertTrue(
+            _check_ws_authorization(
+                "front_door/ptz",
+                "viewer",
+                self.DEFAULT_SEPARATOR,
+                self.ROLES_CONFIG,
+                self.CAMERA_NAMES,
+            )
+        )
+
+    def test_custom_role_can_ptz_assigned_camera(self):
+        self.assertTrue(
+            _check_ws_authorization(
+                "front_door/ptz",
+                "yard",
+                self.DEFAULT_SEPARATOR,
+                self.ROLES_CONFIG,
+                self.CAMERA_NAMES,
+            )
+        )
+
+    def test_custom_role_blocked_from_ptz_unassigned_camera(self):
+        self.assertFalse(
+            _check_ws_authorization(
+                "garage/ptz",
+                "yard",
+                self.DEFAULT_SEPARATOR,
+                self.ROLES_CONFIG,
+                self.CAMERA_NAMES,
+            )
+        )
+
+    def test_multiple_roles_union_camera_access_for_ptz(self):
+        # "yard" covers front_door/backyard, "garage_only" covers garage
+        self.assertTrue(
+            _check_ws_authorization(
+                "garage/ptz",
+                "yard,garage_only",
+                self.DEFAULT_SEPARATOR,
+                self.ROLES_CONFIG,
+                self.CAMERA_NAMES,
+            )
+        )
+
+    def test_unknown_role_blocked_from_ptz(self):
+        self.assertFalse(
+            _check_ws_authorization(
+                "front_door/ptz",
+                "nonexistent",
+                self.DEFAULT_SEPARATOR,
+                self.ROLES_CONFIG,
+                self.CAMERA_NAMES,
+            )
+        )
+
+    def test_no_role_header_treated_as_viewer_for_ptz(self):
+        # proxy-only / auth-disabled setups default to the viewer role
+        self.assertTrue(
+            _check_ws_authorization(
+                "front_door/ptz",
+                None,
+                self.DEFAULT_SEPARATOR,
+                self.ROLES_CONFIG,
+                self.CAMERA_NAMES,
+            )
+        )
+
+    def test_camera_access_does_not_grant_set_commands(self):
+        # camera access enables PTZ only, not config-changing "set" commands
+        self.assertFalse(
+            _check_ws_authorization(
+                "front_door/detect/set",
+                "yard",
+                self.DEFAULT_SEPARATOR,
+                self.ROLES_CONFIG,
+                self.CAMERA_NAMES,
+            )
+        )
+
+    def test_ptz_autotracker_stays_admin_only(self):
+        # ptz_autotracker is a config toggle, not a live-view action
+        self.assertFalse(
+            _check_ws_authorization(
+                "front_door/ptz_autotracker/set",
+                "viewer",
+                self.DEFAULT_SEPARATOR,
+                self.ROLES_CONFIG,
+                self.CAMERA_NAMES,
+            )
+        )
+
+    def test_admin_can_ptz_any_camera_with_config(self):
+        self.assertTrue(
+            _check_ws_authorization(
+                "garage/ptz",
+                "admin",
+                self.DEFAULT_SEPARATOR,
+                self.ROLES_CONFIG,
+                self.CAMERA_NAMES,
+            )
+        )
+
+    def test_ipc_topic_still_blocked_with_camera_access(self):
+        # IPC topics are blocked unconditionally, even with camera access
+        self.assertFalse(
+            _check_ws_authorization(
+                UPDATE_CAMERA_ACTIVITY,
+                "viewer",
+                self.DEFAULT_SEPARATOR,
+                self.ROLES_CONFIG,
+                self.CAMERA_NAMES,
+            )
+        )
+
 
 if __name__ == "__main__":
     unittest.main()

frigate/util/services.py

@@ -790,7 +790,7 @@ def get_hailo_temps() -> dict[str, float]:
     return temps
 
 
-def _go2rtc_arbitrary_exec_allowed() -> bool:
+def is_go2rtc_arbitrary_exec_allowed() -> bool:
     """Read the GO2RTC_ALLOW_ARBITRARY_EXEC override from env, docker
     secrets, or the Home Assistant add-on options file."""
     raw: Optional[str] = None
@@ -822,7 +822,7 @@ def is_restricted_go2rtc_source(stream_source: str) -> bool:
     and the GO2RTC_ALLOW_ARBITRARY_EXEC override is not set."""
     if not stream_source.strip().startswith(("echo:", "expr:", "exec:")):
         return False
-    return not _go2rtc_arbitrary_exec_allowed()
+    return not is_go2rtc_arbitrary_exec_allowed()
 
 
 def ffprobe_stream(ffmpeg, path: str, detailed: bool = False) -> sp.CompletedProcess:

web/e2e/specs/settings/camera-wizard-ptz.spec.ts

@@ -0,0 +1,187 @@
+/**
+ * Add-camera wizard — PTZ controls pane.
+ *
+ * The pane lives on Step 3 (Stream Configuration) and only appears when the
+ * ONVIF probe from Step 2 reported `ptz_supported`. These tests drive the
+ * wizard to Step 3 with a mocked probe and assert the pane's contract:
+ *   1. Visible + enabled when the probe reports PTZ, with the connection
+ *      fields collapsed by default and pre-filled once expanded.
+ *   2. Toggling the switch off hides the disclosure and its fields.
+ *   3. Clearing the host shows the validation warning and blocks "Next".
+ *   4. Absent entirely when the probe reports no PTZ support.
+ *
+ * The save path (writing the `onvif` section to config/set) runs through
+ * Step 4's live-validation flow, which registers go2rtc streams and renders
+ * MSE previews that are unreliable in headless Chromium. Consistent with
+ * clone-camera.spec.ts, that assertion is deferred to manual QA; the logic is
+ * covered by the Step 4 -> parent handleSave wiring.
+ */
+
+import { test, expect } from "../../fixtures/frigate-test";
+import type { Page, Locator } from "@playwright/test";
+
+const PTZ_PROBE = {
+  success: true,
+  host: "192.168.1.100",
+  port: 80,
+  manufacturer: "Acme",
+  model: "PTZ-1",
+  firmware_version: "1.0",
+  profiles_count: 1,
+  ptz_supported: true,
+  pan_tilt_supported: true,
+  presets_count: 2,
+  autotrack_supported: false,
+  rtsp_candidates: [
+    {
+      source: "GetStreamUri",
+      profile_token: "profile_1",
+      uri: "rtsp://admin:pw@192.168.1.100:554/stream1",
+    },
+  ],
+};
+
+async function mockProbe(page: Page, probe: object) {
+  await page.route("**/api/onvif/probe**", (route) =>
+    route.fulfill({ json: probe }),
+  );
+}
+
+/** Open the wizard and drive Step 1 -> Step 2 -> Step 3. */
+async function gotoStep3(page: Page, host = "192.168.1.100") {
+  await page.getByRole("button", { name: /Add New Camera/i }).click();
+  const dialog = page.getByRole("dialog");
+  await expect(dialog).toBeVisible();
+
+  // Step 1: name + host (probe mode is the default), then Continue.
+  await dialog.getByPlaceholder(/front_door/i).fill("ptz_test_camera");
+  await dialog.getByPlaceholder("192.168.1.100").fill(host);
+  await dialog.getByRole("button", { name: /^Continue$/i }).click();
+
+  // Step 2: the probe auto-runs on mount; once candidates exist, Next enables.
+  const next = dialog.getByRole("button", { name: /^Next$/i });
+  await expect(next).toBeEnabled({ timeout: 10_000 });
+  await next.click();
+
+  // Step 3 is the stream-configuration step; key off a stable control rather
+  // than the description text (which has been reworded).
+  await expect(
+    dialog.getByRole("button", { name: /Add Another Stream/i }),
+  ).toBeVisible();
+  return dialog;
+}
+
+/** The PTZ enable switch (scoped to the PTZ card header row). */
+function ptzSwitch(dialog: Locator) {
+  return dialog
+    .locator("div.justify-between", { hasText: "Enable PTZ Controls" })
+    .getByRole("switch");
+}
+
+/** Expand the (collapsed-by-default) ONVIF connection-detail fields. */
+async function expandOnvifDetails(dialog: Locator) {
+  await dialog
+    .getByRole("button", { name: /ONVIF connection details/i })
+    .click();
+}
+
+test.describe("Camera wizard PTZ pane @medium @mobile", () => {
+  test.beforeEach(async ({ frigateApp }) => {
+    // not in the default mock; unmocked it 500s and trips the error collector
+    await frigateApp.page.route("**/api/config/raw_paths", (route) =>
+      route.fulfill({ json: {} }),
+    );
+    await frigateApp.goto("/settings?page=cameraManagement");
+    await expect(
+      frigateApp.page.getByRole("heading", { name: /Manage Cameras/i }),
+    ).toBeVisible();
+  });
+
+  test("shows an enabled PTZ pane with collapsed, pre-filled fields", async ({
+    frigateApp,
+  }) => {
+    await mockProbe(frigateApp.page, PTZ_PROBE);
+    const dialog = await gotoStep3(frigateApp.page);
+
+    // Card is present with the detected note and the switch defaults on.
+    await expect(
+      dialog.getByText("Enable PTZ Controls", { exact: true }),
+    ).toBeVisible();
+    await expect(
+      dialog.getByText(/PTZ support has been detected via ONVIF/i),
+    ).toBeVisible();
+    await expect(ptzSwitch(dialog)).toBeChecked();
+
+    // Connection fields are collapsed by default.
+    await expect(dialog.getByPlaceholder("192.168.1.100")).toHaveCount(0);
+
+    // Expanding reveals the host pre-filled from the probe.
+    await expandOnvifDetails(dialog);
+    await expect(dialog.getByPlaceholder("192.168.1.100")).toHaveValue(
+      "192.168.1.100",
+    );
+  });
+
+  test("toggling the switch off hides the disclosure and fields", async ({
+    frigateApp,
+  }) => {
+    await mockProbe(frigateApp.page, PTZ_PROBE);
+    const dialog = await gotoStep3(frigateApp.page);
+
+    await expandOnvifDetails(dialog);
+    await expect(dialog.getByPlaceholder("192.168.1.100")).toBeVisible();
+
+    await ptzSwitch(dialog).click();
+
+    await expect(dialog.getByPlaceholder("192.168.1.100")).toHaveCount(0);
+    await expect(
+      dialog.getByRole("button", { name: /ONVIF connection details/i }),
+    ).toHaveCount(0);
+  });
+
+  test("clearing the host shows the warning and blocks Next", async ({
+    frigateApp,
+  }) => {
+    await mockProbe(frigateApp.page, PTZ_PROBE);
+    const dialog = await gotoStep3(frigateApp.page);
+
+    await expandOnvifDetails(dialog);
+    await dialog.getByPlaceholder("192.168.1.100").fill("");
+
+    await expect(
+      dialog.getByText(/An ONVIF host and port are required/i),
+    ).toBeVisible();
+    await expect(
+      dialog.getByRole("button", { name: /^Next$/i }),
+    ).toBeDisabled();
+  });
+
+  test("shows the pane but leaves the switch off without continuous pan/tilt", async ({
+    frigateApp,
+  }) => {
+    // e.g. a varifocal camera: PTZ service present, but zoom/focus only
+    await mockProbe(frigateApp.page, {
+      ...PTZ_PROBE,
+      pan_tilt_supported: false,
+    });
+    const dialog = await gotoStep3(frigateApp.page);
+
+    await expect(
+      dialog.getByText("Enable PTZ Controls", { exact: true }),
+    ).toBeVisible();
+    await expect(ptzSwitch(dialog)).not.toBeChecked();
+    // with the switch off, the connection fields are not shown
+    await expect(dialog.getByPlaceholder("192.168.1.100")).toHaveCount(0);
+  });
+
+  test("hides the PTZ pane when the probe reports no PTZ support", async ({
+    frigateApp,
+  }) => {
+    await mockProbe(frigateApp.page, { ...PTZ_PROBE, ptz_supported: false });
+    const dialog = await gotoStep3(frigateApp.page);
+
+    await expect(
+      dialog.getByText("Enable PTZ Controls", { exact: true }),
+    ).toHaveCount(0);
+  });
+});

web/public/locales/en/components/dialog.json

@@ -24,6 +24,9 @@
         },
         "state": {
           "submitted": "Submitted"
+        },
+        "toast": {
+          "error": "Failed to submit to Frigate+. Please check your network connection and try again."
         }
       }
     },

web/public/locales/en/config/cameras.json

@@ -493,6 +493,9 @@
       "max_concurrent": {
         "label": "Maximum concurrent exports",
         "description": "Maximum number of export jobs to process at the same time."
+      },
+      "chapters": {
+        "label": "Chapter metadata to embed in exported recordings"
       }
     },
     "preview": {

web/public/locales/en/config/global.json

@@ -1035,6 +1035,9 @@
       "max_concurrent": {
         "label": "Maximum concurrent exports",
         "description": "Maximum number of export jobs to process at the same time."
+      },
+      "chapters": {
+        "label": "Chapter metadata to embed in exported recordings"
       }
     },
     "preview": {

web/public/locales/en/views/settings.json

@@ -364,7 +364,7 @@
       }
     },
     "step3": {
-      "description": "Configure stream roles and add additional streams for your camera.",
+      "description": "Configure features, stream roles, and add additional streams for your camera.",
       "streamsTitle": "Camera Streams",
       "addStream": "Add Stream",
       "addAnotherStream": "Add Another Stream",
@@ -403,6 +403,16 @@
       "featuresPopover": {
         "title": "Stream Features",
         "description": "Use go2rtc restreaming to reduce connections to your camera."
+      },
+      "ptz": {
+        "title": "Enable PTZ Controls",
+        "detectedNote": "PTZ support has been detected via ONVIF. If this is a PTZ camera, enabling this option will allow you to control the camera's pan/tilt/zoom functions from the UI.",
+        "connectionDetails": "ONVIF connection details",
+        "host": "ONVIF Host",
+        "port": "ONVIF Port",
+        "username": "ONVIF Username",
+        "password": "ONVIF Password",
+        "hostRequiredWarning": "An ONVIF host and port are required when PTZ controls are enabled."
       }
     },
     "step4": {

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

@@ -1251,30 +1251,42 @@ function ObjectDetailsTab({
         return;
       }
 
-      falsePositive
-        ? axios.put(`events/${search.id}/false_positive`)
-        : axios.post(`events/${search.id}/plus`, {
-            include_annotation: 1,
-          });
+      try {
+        const resp = falsePositive
+          ? await axios.put(`events/${search.id}/false_positive`)
+          : await axios.post(`events/${search.id}/plus`, {
+              include_annotation: 1,
+            });
 
-      setState("submitted");
-      setSearch({ ...search, plus_id: "new_upload" });
-      mutate(
-        (key) => isEventsKey(key),
-        (currentData: SearchResult[][] | SearchResult[] | undefined) =>
-          mapSearchResults(currentData, (event) =>
-            event.id === search.id
-              ? { ...event, plus_id: "new_upload" }
-              : event,
-          ),
-        {
-          optimisticData: true,
-          rollbackOnError: true,
-          revalidate: false,
-        },
-      );
+        if (resp.status !== 200 || !resp.data?.success) {
+          throw new Error();
+        }
+
+        setState("submitted");
+        setSearch({ ...search, plus_id: "new_upload" });
+        mutate(
+          (key) => isEventsKey(key),
+          (currentData: SearchResult[][] | SearchResult[] | undefined) =>
+            mapSearchResults(currentData, (event) =>
+              event.id === search.id
+                ? { ...event, plus_id: "new_upload" }
+                : event,
+            ),
+          {
+            optimisticData: true,
+            rollbackOnError: true,
+            revalidate: false,
+          },
+        );
+      } catch {
+        setState("reviewing");
+        toast.error(
+          t("explore.plus.review.toast.error", { ns: "components/dialog" }),
+          { position: "top-center" },
+        );
+      }
     },
-    [search, mutate, mapSearchResults, setSearch, isEventsKey],
+    [search, mutate, mapSearchResults, setSearch, isEventsKey, t],
   );
 
   const popoverContainerRef = useRef<HTMLDivElement | null>(null);

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

@@ -1225,11 +1225,15 @@ function LifecycleIconRow({
                       <DropdownMenuItem
                         className="cursor-pointer"
                         onSelect={async () => {
-                          const resp = await axios.post(
-                            `/${item.camera}/plus/${item.timestamp + annotationOffset / 1000}`,
-                          );
+                          try {
+                            const resp = await axios.post(
+                              `/${item.camera}/plus/${item.timestamp + annotationOffset / 1000}`,
+                            );
+
+                            if (resp.status !== 200) {
+                              throw new Error();
+                            }
 
-                          if (resp && resp.status == 200) {
                             toast.success(
                               t("toast.success.submittedFrigatePlus", {
                                 ns: "components/player",
@@ -1238,8 +1242,8 @@ function LifecycleIconRow({
                                 position: "top-center",
                               },
                             );
-                          } else {
-                            toast.success(
+                          } catch {
+                            toast.error(
                               t("toast.error.submitFrigatePlusFailed", {
                                 ns: "components/player",
                               }),

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

@@ -10,6 +10,7 @@ import { isDesktop, isMobile, isSafari } from "react-device-detect";
 import { cn } from "@/lib/utils";
 import { useCallback, useEffect, useState } from "react";
 import axios from "axios";
+import { toast } from "sonner";
 import { useTranslation, Trans } from "react-i18next";
 import { Button } from "@/components/ui/button";
 import ActivityIndicator from "@/components/indicators/activity-indicator";
@@ -48,13 +49,28 @@ export function FrigatePlusDialog({
   const onSubmitToPlus = useCallback(
     async (falsePositive: boolean) => {
       if (!upload) return;
-      falsePositive
-        ? axios.put(`events/${upload.id}/false_positive`)
-        : axios.post(`events/${upload.id}/plus`, { include_annotation: 1 });
-      setState("submitted");
-      onEventUploaded();
+
+      try {
+        const resp = falsePositive
+          ? await axios.put(`events/${upload.id}/false_positive`)
+          : await axios.post(`events/${upload.id}/plus`, {
+              include_annotation: 1,
+            });
+
+        if (resp.status !== 200 || !resp.data?.success) {
+          throw new Error();
+        }
+
+        setState("submitted");
+        onEventUploaded();
+      } catch {
+        setState("reviewing");
+        toast.error(t("explore.plus.review.toast.error"), {
+          position: "top-center",
+        });
+      }
     },
-    [upload, onEventUploaded],
+    [upload, onEventUploaded, t],
   );
 
   const [imgRef, imgLoaded, onImgLoad] = useImageLoaded();

web/src/components/settings/CameraWizardDialog.tsx

@@ -115,13 +115,19 @@ export default function CameraWizardDialog({
       case 1:
         // Step 2: Can proceed if at least one stream exists (from probe or manual test)
         return (state.wizardData.streams?.length ?? 0) > 0;
-      case 2:
-        // Step 3: Can proceed if at least one stream has 'detect' role
-        return !!(
+      case 2: {
+        // Step 3: requires a detect stream; if PTZ is enabled, also require
+        // ONVIF host + port (fields are pre-filled but the user may clear them)
+        const hasDetect = !!(
           state.wizardData.streams?.some((stream) =>
             stream.roles.includes("detect"),
           ) ?? false
         );
+        const onvif = state.wizardData.onvif;
+        const onvifOk =
+          !onvif?.enabled || (!!onvif.host?.trim() && !!onvif.port);
+        return hasDetect && onvifOk;
+      }
       case 3:
         // Step 4: Always can proceed from final step (save will be handled there)
         return true;
@@ -241,6 +247,20 @@ export default function CameraWizardDialog({
         });
       }
 
+      // Write the ONVIF section when PTZ controls are enabled
+      if (wizardData.onvif?.enabled && wizardData.onvif.host.trim()) {
+        configData.cameras[finalCameraName].onvif = {
+          host: wizardData.onvif.host.trim(),
+          port: wizardData.onvif.port,
+          ...(wizardData.onvif.user?.trim() && {
+            user: wizardData.onvif.user.trim(),
+          }),
+          ...(wizardData.onvif.password && {
+            password: wizardData.onvif.password,
+          }),
+        };
+      }
+
       const requestBody: ConfigSetBody = {
         requires_restart: 1,
         config_data: configData,

web/src/components/settings/wizard/Step2ProbeOrSnapshot.tsx

@@ -204,6 +204,7 @@ export default function Step2ProbeOrSnapshot({
           .map((c: { uri: string }) => c.uri);
         onUpdate({
           probeMode: true,
+          probeResult: response.data,
           probeCandidates: candidateUris,
           candidateTests: {},
         });

web/src/components/settings/wizard/Step3StreamConfig.tsx

@@ -3,7 +3,7 @@ import { Card, CardContent } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
 import { Switch } from "@/components/ui/switch";
 import { useTranslation } from "react-i18next";
-import { useState, useCallback, useMemo } from "react";
+import { useState, useCallback, useMemo, useEffect } from "react";
 import { LuPlus, LuTrash2, LuX } from "react-icons/lu";
 import ActivityIndicator from "@/components/indicators/activity-indicator";
 import axios from "axios";
@@ -32,6 +32,10 @@ import {
   LuExternalLink,
   LuCheck,
   LuChevronsUpDown,
+  LuChevronDown,
+  LuChevronRight,
+  LuEye,
+  LuEyeOff,
 } from "react-icons/lu";
 import { Link } from "react-router-dom";
 import { useDocDomain } from "@/hooks/use-doc-domain";
@@ -44,6 +48,11 @@ import {
   CommandItem,
   CommandList,
 } from "@/components/ui/command";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@/components/ui/collapsible";
 
 type Step3StreamConfigProps = {
   wizardData: Partial<WizardFormData>;
@@ -64,6 +73,53 @@ export default function Step3StreamConfig({
   const { getLocaleDocUrl } = useDocDomain();
   const [testingStreams, setTestingStreams] = useState<Set<string>>(new Set());
   const [openCombobox, setOpenCombobox] = useState<string | null>(null);
+  const [showOnvifPassword, setShowOnvifPassword] = useState(false);
+  const [onvifDetailsOpen, setOnvifDetailsOpen] = useState(false);
+
+  const onvif = wizardData.onvif;
+  const ptzSupported = wizardData.probeResult?.ptz_supported === true;
+  const panTiltSupported = wizardData.probeResult?.pan_tilt_supported === true;
+  const onvifInvalid = !!onvif?.enabled && (!onvif.host?.trim() || !onvif.port);
+
+  // Seed the PTZ pane once from the successful ONVIF probe
+  useEffect(() => {
+    // run only on first entry and never clobber a user's later toggle-off or edits
+    if (ptzSupported && wizardData.onvif === undefined) {
+      onUpdate({
+        onvif: {
+          enabled: panTiltSupported,
+          host: wizardData.host ?? "",
+          port: wizardData.onvifPort ?? 8000,
+          user: wizardData.username ?? "",
+          password: wizardData.password ?? "",
+        },
+      });
+    }
+  }, [
+    ptzSupported,
+    panTiltSupported,
+    wizardData.onvif,
+    wizardData.host,
+    wizardData.onvifPort,
+    wizardData.username,
+    wizardData.password,
+    onUpdate,
+  ]);
+
+  const updateOnvif = useCallback(
+    (updates: Partial<NonNullable<WizardFormData["onvif"]>>) => {
+      onUpdate({
+        onvif: {
+          enabled: false,
+          host: "",
+          port: 8000,
+          ...wizardData.onvif,
+          ...updates,
+        },
+      });
+    },
+    [onUpdate, wizardData.onvif],
+  );
 
   const streams = useMemo(() => wizardData.streams || [], [wizardData.streams]);
 
@@ -725,12 +781,136 @@ export default function Step3StreamConfig({
         </Button>
       </div>
 
+      {ptzSupported && (
+        <Card className="bg-secondary text-primary">
+          <CardContent className="space-y-2 p-4">
+            <div className="flex items-center justify-between gap-4">
+              <div className="space-y-1">
+                <h4 className="font-medium">
+                  {t("cameraWizard.step3.ptz.title")}
+                </h4>
+                <p className="text-xs text-muted-foreground">
+                  {t("cameraWizard.step3.ptz.detectedNote")}
+                </p>
+              </div>
+              <Switch
+                checked={onvif?.enabled ?? false}
+                onCheckedChange={(checked) => updateOnvif({ enabled: checked })}
+              />
+            </div>
+
+            {onvif?.enabled && (
+              <Collapsible
+                open={onvifDetailsOpen || onvifInvalid}
+                onOpenChange={setOnvifDetailsOpen}
+              >
+                <CollapsibleTrigger asChild>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="sm"
+                    className="w-full justify-start gap-2 pl-0 hover:bg-transparent"
+                  >
+                    {onvifDetailsOpen || onvifInvalid ? (
+                      <LuChevronDown className="size-4" />
+                    ) : (
+                      <LuChevronRight className="size-4" />
+                    )}
+                    {t("cameraWizard.step3.ptz.connectionDetails")}
+                  </Button>
+                </CollapsibleTrigger>
+                <CollapsibleContent className="mt-2 space-y-4 rounded-lg bg-background p-3">
+                  <div className="space-y-2">
+                    <Label className="text-sm font-medium text-primary-variant">
+                      {t("cameraWizard.step3.ptz.host")}
+                    </Label>
+                    <Input
+                      value={onvif.host}
+                      onChange={(e) => updateOnvif({ host: e.target.value })}
+                      className="h-8"
+                      placeholder="192.168.1.100"
+                    />
+                  </div>
+
+                  <div className="space-y-2">
+                    <Label className="text-sm font-medium text-primary-variant">
+                      {t("cameraWizard.step3.ptz.port")}
+                    </Label>
+                    <Input
+                      type="text"
+                      inputMode="numeric"
+                      value={onvif.port || ""}
+                      onChange={(e) => {
+                        const parsed = parseInt(e.target.value, 10);
+                        updateOnvif({ port: isNaN(parsed) ? 0 : parsed });
+                      }}
+                      className="h-8"
+                      placeholder="8000"
+                    />
+                  </div>
+
+                  <div className="space-y-2">
+                    <Label className="text-sm font-medium text-primary-variant">
+                      {t("cameraWizard.step3.ptz.username")}
+                    </Label>
+                    <Input
+                      value={onvif.user ?? ""}
+                      onChange={(e) => updateOnvif({ user: e.target.value })}
+                      className="h-8"
+                      placeholder={t("cameraWizard.step1.usernamePlaceholder")}
+                    />
+                  </div>
+
+                  <div className="space-y-2">
+                    <Label className="text-sm font-medium text-primary-variant">
+                      {t("cameraWizard.step3.ptz.password")}
+                    </Label>
+                    <div className="relative">
+                      <Input
+                        type={showOnvifPassword ? "text" : "password"}
+                        value={onvif.password ?? ""}
+                        onChange={(e) =>
+                          updateOnvif({ password: e.target.value })
+                        }
+                        className="h-8 pr-10"
+                        placeholder={t(
+                          "cameraWizard.step1.passwordPlaceholder",
+                        )}
+                      />
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="sm"
+                        className="absolute right-0 top-0 h-full px-3 py-2 hover:bg-transparent"
+                        onClick={() => setShowOnvifPassword((s) => !s)}
+                      >
+                        {showOnvifPassword ? (
+                          <LuEyeOff className="size-4" />
+                        ) : (
+                          <LuEye className="size-4" />
+                        )}
+                      </Button>
+                    </div>
+                  </div>
+                </CollapsibleContent>
+              </Collapsible>
+            )}
+          </CardContent>
+        </Card>
+      )}
+
       {!hasDetectRole && (
         <div className="rounded-lg border border-danger/50 p-3 text-sm text-danger">
           {t("cameraWizard.step3.detectRoleWarning")}
         </div>
       )}
 
+      {onvifInvalid && (
+        <div className="rounded-lg border border-danger/50 p-3 text-sm text-danger">
+          {t("cameraWizard.step3.ptz.hostRequiredWarning")}
+        </div>
+      )}
+
       <div className="flex flex-col-reverse gap-2 pt-6 sm:flex-row sm:justify-end">
         {onBack && (
           <Button type="button" onClick={onBack} className="sm:flex-1">

web/src/components/settings/wizard/Step4Validation.tsx

@@ -268,6 +268,7 @@ export default function Step4Validation({
       customUrl: wizardData.customUrl,
       streams: wizardData.streams,
       hasBackchannel: wizardData.hasBackchannel,
+      onvif: wizardData.onvif,
     };
 
     onSave(configData);

web/src/hooks/use-deferred-stream-metadata.ts

@@ -5,7 +5,8 @@ import { LiveStreamMetadata } from "@/types/live";
 
 const FETCH_TIMEOUT_MS = 10000;
 const DEFER_DELAY_MS = 2000;
-const EMPTY_METADATA: { [key: string]: LiveStreamMetadata } = {};
+const emptyObject: Readonly<{ [key: string]: LiveStreamMetadata }> =
+  Object.freeze({});
 
 /**
  * Hook that fetches go2rtc stream metadata with deferred loading.
@@ -78,7 +79,7 @@ export default function useDeferredStreamMetadata(streamNames: string[]) {
     return metadata;
   }, []);
 
-  const { data: metadata = EMPTY_METADATA } = useSWR<{
+  const { data: metadata = emptyObject } = useSWR<{
     [key: string]: LiveStreamMetadata;
   }>(swrKey, fetcher, {
     revalidateOnFocus: false,

web/src/types/cameraWizard.ts

@@ -119,6 +119,13 @@ export type WizardFormData = {
   probeCandidates?: string[]; // candidate URLs from probe
   candidateTests?: CandidateTestMap; // test results for candidates
   hasBackchannel?: boolean; // true if camera supports backchannel audio
+  onvif?: {
+    enabled: boolean;
+    host: string;
+    port: number;
+    user?: string;
+    password?: string;
+  };
 };
 
 // API Response Types
@@ -169,6 +176,12 @@ export type CameraConfigData = {
       live?: {
         streams: Record<string, string>;
       };
+      onvif?: {
+        host: string;
+        port: number;
+        user?: string;
+        password?: string;
+      };
     };
   };
   go2rtc?: {
@@ -199,6 +212,7 @@ export type OnvifProbeResponse = {
   firmware_version?: string;
   profiles_count?: number;
   ptz_supported?: boolean;
+  pan_tilt_supported?: boolean;
   presets_count?: number;
   autotrack_supported?: boolean;
   move_status_supported?: boolean;