From 1ff0cdf6213f7b00f300d5a9d9832c7dd2a940b3 Mon Sep 17 00:00:00 2001
From: Dermot Duffy <dermot.duffy@gmail.com>
Date: Thu, 23 Sep 2021 22:13:47 -0700
Subject: [PATCH] Add documentation for aspect-ratio options.

---
 README.md                      | 38 +++++++++++++++++++++++++++++++++-
 src/localize/languages/en.json |  9 ++++++++
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 13c60eb7..f3ff46a5 100644
--- a/README.md
+++ b/README.md
@@ -87,8 +87,44 @@ lovelace:
 | `menu_mode` | `hidden-top` | The menu mode to show by default. See [menu modes](#menu-modes) below.|
 | `menu_buttons.{frigate, live, clips, snapshots, frigate_ui}` | `true` | Whether or not to show these builtin actions in the card menu. |
 | `controls.nextprev` | `thumbnails` | When viewing media, what kind of controls to show to move to the previous/next media item. Acceptable values: `thumbnails`, `chevrons`, `none` . |
+| `dimensions.aspect_ratio_mode` | `dynamic` | The aspect ratio mode to use. Acceptable values: `dynamic`, `static`, `unconstrained`. See [aspect ratios](#aspect-ratios) below.|
+| `dimensions.aspect_ratio` | `16:9` | The aspect ratio  to use. Acceptable values: `<W>:<H>` or `<W>/<H>`. See [aspect ratios](#aspect-ratios) below.|
 
-### Advanced
+<a name="aspect-ratios"></a>
+
+#### Aspect Ratio
+
+The card can show live cameras, stored events (clip or snapshot) and an event gallery (clips or snapshots). Of these [views](#views), the gallery views have no intrinsic aspect-ratio, whereas the other views have the aspect-ratio of the media.
+
+The card aspect ratio can be changed with the `dimensions.aspect_ratio_mode` and `dimensions.aspect_ratio` appearance options.
+
+If no aspect ratio is specified or available, but one is needed then `16:9` will be used by default.
+
+#### `dimensions.aspect_ratio_mode`:
+
+| Option           | Description                                         |
+| ------------- | --------------------------------------------- |
+| `dynamic` | The aspect-ratio of the card will match the aspect-ratio of the last loaded media. |
+| `static` | A fixed aspect-ratio (as defined by `dimensions.aspect_ratio`) will be applied to all views. |
+| `unconstrained` | No aspect ratio is enforced in any view, the card will expand with the content (may be especially useful for a panel-mode dashboard). |
+
+#### `dimensions.aspect_ratio`:
+
+* `16 / 9` or `16:9`: Default widescreen ratio.
+* `4 / 3` or `4:3`: Default fullscreen ratio.
+* `<W>/<H>` or `<W>:<H>`: Any arbitrary aspect-ratio.
+
+#### Example aspect ratio configuration
+
+Force the aspect-ratio to always be `4:3`:
+
+```yaml
+dimensions:
+  aspect_ratio_mode: dynamic
+  aspect_ratio: '4:3'
+```
+
+### Advanced Options
 
 | Option           | Default | Description                                         |
 | ------------- | - | --------------------------------------------- |
diff --git a/src/localize/languages/en.json b/src/localize/languages/en.json
index a9d75f48..0d8dd53a 100644
--- a/src/localize/languages/en.json
+++ b/src/localize/languages/en.json
@@ -49,6 +49,15 @@
     "chevrons": "Chevrons",
     "none": "None"
   },
+  "dimensions": {
+    "aspect_ratio_mode": "Aspect Ratio Mode",
+    "aspect_ratio": "Default aspect ratio (Optional)"
+  },
+  "aspect_ratio_mode": {
+    "unconstrained": "Unconstrained aspect ratio",
+    "dynamic": "Aspect ratio adjusts to media",
+    "static": "Static aspect ratio"
+  },
   "menu_mode": {
     "none": "No menu",
     "hidden-top": "Hidden Top",