Update instructions

README.md

@@ -26,6 +26,97 @@ Installing this theme adds 28 different themes:
 - `ios-dark-mode-dark-blue`
 - `...` and versions with the `-alternative` suffix
 
+---
+
+## **🖼️ Backgrounds: Remote vs Local**
+
+As of version **3.0.0**, we have introduced an alternative to Base64-encoded background images to boost performance.
+
+By default, iOS Themes now use **remote background images** hosted on GitHub for faster caching and loading times. However, for users that prefer to host images locally on their Home Assistant setup (or in environments with poor internet connectivity), `-alternative` versions of the themes are available, which use locally hosted background images.
+
+### **Remote Backgrounds (Default)**
+
+- The default themes use background images stored in our GitHub repository.
+- To switch to the default themes, no configuration beyond the installation steps is necessary.
+
+### **Local Backgrounds (Alternative Versions)**
+
+For the alternative themes, you will need to **download the images and store them locally** in your Home Assistant's `/config/www/ios-themes` directory. Home Assistant automatically serves files from the `www` folder under `/local/`.
+
+---
+
+<details>
+<summary>📥 How to Download Backgrounds for Local Use (Alternative Themes)</summary>
+
+### **Step-by-Step Local Background Setup**:
+
+To use locally hosted background images, follow the instructions below.
+
+1. **Create the necessary directory**:
+   Open a terminal (or SSH into your Home Assistant setup) and run the following command to ensure the correct folder structure is in place:
+   ```bash
+   mkdir -p /config/www/ios-themes
+   ```
+
+2. **Download the background images**:
+   Download the required background images using `wget` commands. This will store them in the `/config/www/ios-themes` folder.
+
+   For example:
+   ```bash
+   # Dark Blue background
+   wget -O /config/www/ios-themes/homekit-bg-dark-blue.jpg https://raw.githubusercontent.com/basnijholt/lovelace-ios-themes/master/themes/homekit-bg-dark-blue.jpg
+
+   # Light Blue background
+   wget -O /config/www/ios-themes/homekit-bg-dark-blue.jpg https://raw.githubusercontent.com/basnijholt/lovelace-ios-themes/master/themes/homekit-bg-light-blue.jpg
+
+   # Add more backgrounds as needed for other themes
+   ```
+
+   Repeat the command for all the backgrounds you need (ensure to replace `dark-blue.jpg` with the appropriate background name from the themes you're using).
+
+3. **Switch to the alternative theme**:
+   In your Home Assistant profile settings, select the **alternative version** of the theme you want to use.  
+   Example: `ios-dark-mode-dark-blue-alternative`
+
+   **Important:** For images hosted locally, the background paths in the theme are referenced as `/local/ios-themes/...`.
+
+---
+
+### **Command Summary for Downloading Backgrounds**:
+
+Here are commands to download all available backgrounds:
+
+```bash
+# Dark Blue
+wget -O /config/www/ios-themes/homekit-bg-dark-blue.jpg https://raw.githubusercontent.com/basnijholt/lovelace-ios-themes/master/themes/homekit-bg-dark-blue.jpg
+
+# Light Blue
+wget -O /config/www/ios-themes/homekit-bg-light-blue.jpg https://raw.githubusercontent.com/basnijholt/lovelace-ios-themes/master/themes/homekit-bg-light-blue.jpg
+
+# Dark Green
+wget -O /config/www/ios-themes/homekit-bg-dark-green.jpg https://raw.githubusercontent.com/basnijholt/lovelace-ios-themes/master/themes/homekit-bg-dark-green.jpg
+
+# Light Green
+wget -O /config/www/ios-themes/homekit-bg-light-green.jpg https://raw.githubusercontent.com/basnijholt/lovelace-ios-themes/master/themes/homekit-bg-light-green.jpg
+
+# Orange
+wget -O /config/www/ios-themes/homekit-bg-orange.jpg https://raw.githubusercontent.com/basnijholt/lovelace-ios-themes/master/themes/homekit-bg-orange.jpg
+
+# Blue Red
+wget -O /config/www/ios-themes/homekit-bg-blue-red.jpg https://raw.githubusercontent.com/basnijholt/lovelace-ios-themes/master/themes/homekit-bg-blue-red.jpg
+
+# Red
+wget -O /config/www/ios-themes/homekit-bg-red.jpg https://raw.githubusercontent.com/basnijholt/lovelace-ios-themes/master/themes/homekit-bg-red.jpg
+```
+
+---
+
+After placing the images in the `/config/www/ios-themes/` directory, reload your Home Assistant theme settings (or restart Home Assistant) and enjoy using the responsive, locally hosted backgrounds!
+
+</details>
+
+---
+
 ## Screenshots
 
 Screenshots of [my](https://github.com/basnijholt) Home-Assistant instance, [see the config files here :octocat:](https://github.com/basnijholt/home-assistant-config/).

create-themes.py

@@ -6,10 +6,9 @@
 
 import jinja2
 import yaml
-from PIL import Image
-from PIL import ImageColor
+from PIL import Image, ImageColor
 
-with open("settings-light-dark.yaml", "r") as f:
+with open("settings-light-dark.yaml") as f:
     all_settings = yaml.safe_load(f)
 
 COMMIT = "a37376d918fcfe4785be99910dc9a7200ac37da9"
@@ -30,12 +29,12 @@ def average_color(fname):
     return "rgba({}, {}, {}, 0.4)".format(*rgb_color)
 
 
-def fname_to_url(background: Path):
+def fname_to_url(background: Path) -> str:
     return f"{BASE_URL}/{background.name}"
 
 
-def fname_to_local_path(folder: str, background: Path):
-    return f"/{folder}/themes/ios-themes/{background.name}"
+def fname_to_local_path(background: Path) -> str:
+    return f"/local/ios-themes/{background.name}"
 
 
 BACKGROUND_COLORS = {
@@ -49,45 +48,40 @@ def fname_to_local_path(folder: str, background: Path):
     "red": "rgba(234, 88, 63, 0.4)",
 }
 
-
-folder_fname = [
-    ("hacsfiles", Path("themes/ios-themes.yaml")),
-    ("local", Path("manual-install/ios-themes.yaml")),
-]
-for folder, fname in folder_fname:
-    fname.parent.mkdir(parents=True, exist_ok=True)
-    with fname.open("w") as f:
-        f.write("---\n# From https://github.com/basnijholt/lovelace-ios-themes")
-    for background in sorted(Path("themes").glob("homekit-bg-*.jpg")):
-        color = background.stem.split("homekit-bg-")[-1]
-        if color in BACKGROUND_COLORS:
-            app_header_background_color = BACKGROUND_COLORS[color]
-        else:
-            app_header_background_color = average_color(background)
-        for which in ["light", "dark"]:
-            for standard in [False, True]:
-                settings = {k: parse(v[which]) for k, v in all_settings.items()}
-
-                if standard:
-                    settings["state_icon_active_color"] = "rgba(255, 214, 10, 1)"
-                    suffix = ""
-                else:
-                    suffix = "-alternative"
-
-                with open("template.jinja2") as f:
-                    template = jinja2.Template("".join(f.readlines()))
-
-                result = template.render(
-                    **settings,
-                    folder=folder,
-                    which=which,
-                    app_header_background_color=app_header_background_color,
-                    background=fname_to_url(background)
-                    if standard
-                    else fname_to_local_path(folder, background),
-                    color=color,
-                    suffix=suffix,
-                )
-
-                with fname.open("a") as f:
-                    f.write("\n" + result + "\n")
+fname = Path("themes/ios-themes.yaml")
+fname.parent.mkdir(parents=True, exist_ok=True)
+
+with fname.open("w") as f:
+    f.write("---\n# From https://github.com/basnijholt/lovelace-ios-themes")
+for background in sorted(Path("themes").glob("homekit-bg-*.jpg")):
+    color = background.stem.split("homekit-bg-")[-1]
+    if color in BACKGROUND_COLORS:
+        app_header_background_color = BACKGROUND_COLORS[color]
+    else:
+        app_header_background_color = average_color(background)
+    for which in ["light", "dark"]:
+        for standard in [False, True]:
+            settings = {k: parse(v[which]) for k, v in all_settings.items()}
+
+            if standard:
+                settings["state_icon_active_color"] = "rgba(255, 214, 10, 1)"
+                suffix = ""
+            else:
+                suffix = "-alternative"
+
+            with open("template.jinja2") as f:
+                template = jinja2.Template("".join(f.readlines()))
+
+            result = template.render(
+                **settings,
+                which=which,
+                app_header_background_color=app_header_background_color,
+                background=fname_to_url(background)
+                if standard
+                else fname_to_local_path(background),
+                color=color,
+                suffix=suffix,
+            )
+
+            with fname.open("a") as f:
+                f.write("\n" + result + "\n")