feat: Add support for rotating camera streams (#2149)

* Closes #1307
2025-08-23 17:30:53 -07:00
parent 69ae80d6f1
commit 4d4b64232a
25 changed files with 1393 additions and 764 deletions
@@ -135,6 +135,11 @@ cameras:
 | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `aspect_ratio` |         | An optional aspect ratio for media from this camera which will be used in `live` or media viewer related views (e.g. `clip`, `snapshot` and `recording`). Format is the same as the parameter of the same name under the [dimensions block](../dimensions.md) (which controls dimensions for the whole card), e.g. `16 / 9`. |
 | `layout`       |         | How the media should be laid out _within_ the camera dimensions. See below.                                                                                                                                                                                                                                                  |
+| `rotation`     | `0`     | Rotates the camera clockwise by `0`, `90`, `180` or `270` degrees.                                                                                                                                                                                                                                                           |
+
+?> Use of `rotation` causes the browser to rotate the video player, unavoidably _including_ rotating the builtin video controls on the player, which may be distracting or confusing (e.g. upside down controls). Builtin controls can be disabled using the [`live.controls.builtin` parameter](../live.md?id=controls). Rotation is not available in iOS fullscreen, due to the limited fullscreen support offered by that OS.
+
+!> Rotating the camera incurs a rendering performance penalty. Always rotate "upstream" if possible (e.g. in your camera settings).

 ### Layout Configuration

@@ -182,6 +187,15 @@ See [media layout examples](../../examples.md?id=media-layout).

 ![](../../images/media_layout/pan-zoom.png 'Panning and zooming :size=400')

+### Order of Operations
+
+Camera `dimensions` settings are applied in this order:
+
+- `aspect_ratio` defines the aspect ratio of the video player ...
+- ... then `fit`, `position` and `view_box` defines how the media is laid out within that ratio ...
+- ... then `rotation` defines whether the video is rotated ...
+- ... then `zoom` and `pan` define the zoom and pan settings respectively.
+
 ## `ptz`

 Configure the PTZ actions taken for a camera (not to be confused with configuration of the PTZ _controls_, see [Live PTZ Controls](../live.md?id=ptz) or [Media Viewer PTZ Controls](../media-viewer.md?id=ptz)). Manually configured actions override any auto-detected actions.
@@ -437,6 +451,9 @@ cameras:
        - trigger
      disable:
        # Capabilities to selectively disable.
+  - camera_entity: camera.rotated
+    dimensions:
+      rotation: 90
 cameras_global:
  triggers:
    motion: false
@@ -53,6 +53,7 @@ This card supports several menu styles.
 | `none`       | No status bar is shown.                                                                                               |
 | `outside`    | Render the status bar outside the card (i.e. above it if `position` is `top`, or below it if `position` is `bottom`). |
 | `overlay`    | Overlay the status bar over the card contents.                                                                        |
+| `popup`      | Equivalent to `overlay` except the status bar disappears after `popup_seconds`.                                       |

 ## Fully expanded reference