homebridge-ecobee-security 0.9.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.0.0
+
+- New setting **Quick Responses** (`quickResponses`, `quickResponseMessages`) in the Doorbell camera card:
+  short messages the doorbell plays on its speaker. They appear as one "Quick Responses" tile in the Home app
+  with a switch per message (open the tile to pick one; tapping the tile itself plays nothing), which you can
+  add to the live view's Nearby Accessories or use from Siri and automations. New setting
+  `quickResponseVolume` (default 40%) sets how loud they play. Three come built in (Leave
+  Delivery, Hang On, Not Home), each with a Preview button in the settings; remove the ones you don't want
+  (and add them back). With Piper installed you can also reword them and add your own.
+  The doorbell needs to accept audio from the plugin, as for two-way talk, but two-way talk doesn't have to be
+  on. If the doorbell connection is down, a message waits up to 20 seconds for it to come back; it doesn't
+  play while another message is playing or someone is talking in a live view, and the log says why.
+- The built-in messages come as recordings made with Piper's ryan voice (RyanSpeech, CC BY-NC-SA 4.0; see
+  `assets/quick-responses/LICENSE`). Changed or new wording needs [Piper](https://github.com/OHF-Voice/piper1-gpl)
+  on the Homebridge machine (`piperPath`, `piperVoice`; see "Custom wording with Piper" in the README).
+- Two-way talk is no longer a beta.
+- New **Doorbell Pressed** occupancy sensor on the video doorbell (with the doorbell link): Detected for 10
+  seconds after each press of any kind, for automations. It shows No Response while the link is down.
+
 ## 0.9.1
 
 - New setting **Add Comfort Setting switches** (`comfortSetting`, `comfortHoldType`): a Comfort Setting

package/README.md

@@ -38,6 +38,7 @@ GraphQL at `federated-api.prod.federated-graph.generacapis.com`), which ecobee c
 - **Vacation Mode** switch that follows, and starts, an ecobee vacation.
 - **Security holds** let other plugins, like a robot vacuum, keep the system from arming Away while they work.
 - **Doorbell camera** with HomeKit Secure Video, live view and snapshots; with the **doorbell link**, instant ring and motion, the sensors the doorbell bridges to HomeKit, and its Chime, Status Light and Night Vision switches.
+- **Quick Responses**: short messages the doorbell plays on its speaker ("Leave Delivery", "Hang On", "Not Home"), one Quick Responses tile in the Home app, plus a **Doorbell Pressed** sensor for automations.
 
 ## Contents
 
@@ -49,6 +50,7 @@ GraphQL at `federated-api.prod.federated-graph.generacapis.com`), which ecobee c
 - [Keypad unlock](#keypad-unlock)
 - [Security holds](#security-holds)
 - [Doorbell camera](#doorbell-camera)
+- [Quick Responses](#quick-responses)
 - [Home Occupied switch](#home-occupied-switch)
 - [Vacation Mode switch](#vacation-mode-switch)
 - [Smoke alarm and air quality](#smoke-alarm-and-air-quality)
@@ -150,8 +152,12 @@ Sign-in: see [Sign-in](#sign-in).
 | `doorbellCamera` | `false` | Adds the doorbell camera (beta). Restart the bridge after changing it. |
 | `motionGrace` | `15` | Seconds the motion sensor stays on after the doorbell's motion ends (6 to 120). |
 | `ffmpegPath` | `/usr/local/bin/ffmpeg` if it exists, else `ffmpeg` | The ffmpeg to use. |
-| `twoWayAudio` | `false` | Talk through the doorbell from the Home app's live view (beta; see [Two-way talk](#two-way-talk-beta)). |
+| `twoWayAudio` | `false` | Talk through the doorbell from the Home app's live view (see [Two-way talk](#two-way-talk)). |
 | `twoWayAudioTest` | `false` | With `twoWayAudio`: plays a 3-second tone on the doorbell when a live view starts (config file only). |
+| `quickResponses` | `false` | Adds a switch per message that plays it on the doorbell (see [Quick Responses](#quick-responses)). Restart the bridge after changing it. |
+| `quickResponseVolume` | `40` | How loud messages play at the door, in percent (5 to 100). Doesn't change two-way talk. |
+| `quickResponseMessages` | the three built-ins | The messages: a list of `{ "id", "name", "phrase" }`; a built-in with `"enabled": false` is removed but keeps its wording. `id` never changes (it is the switch's identity in the Home app), `name` is the tile name (14 characters at most), `phrase` is what is said. |
+| `piperPath`, `piperVoice` | none | Piper and its voice, only for changed or new wording (see [Custom wording with Piper](#custom-wording-with-piper)). |
 | `debugRecordings` | `false` | Keeps the last five recordings for troubleshooting (config file only; see [Troubleshooting](#troubleshooting)). |
 
 ### Switches and sensors settings
@@ -348,7 +354,8 @@ the Home app. You get:
   occupancy and battery state;
 - the doorbell's own switches: **Chime Doorbell**, **Camera Status Light** and **Night Vision Light**.
   Changes in the Home app are sent to the doorbell, and changes made at the doorbell show up in the Home
-  app. While the link is down, setting one fails.
+  app. While the link is down, setting one fails;
+- a **Doorbell Pressed** sensor (see below).
 
 The pairing is kept in `ecobee-security/doorbell-pairing.json` in the Homebridge folder. **Unlink** in the
 settings removes it from the doorbell as well (restart the bridge afterwards). If the link drops, the
@@ -356,6 +363,13 @@ plugin looks for the doorbell again and reconnects by itself; the ring, motion,
 sensors show **No Response** while it has been down for a minute. The video still comes from the
 cloud session (the doorbell's own stream isn't used).
 
+### Doorbell Pressed sensor
+
+With the doorbell link, the video doorbell also has an occupancy sensor named **Doorbell Pressed**. Each press
+(single, double or long) sets it to Detected for 10 seconds; another press starts the 10 seconds again.
+The Home app can't start an automation from a video doorbell's ring, but it can from a sensor. It shows No
+Response while the doorbell link is down.
+
 ### HomeKit Secure Video
 
 The camera records for HomeKit Secure Video (a home hub and an iCloud+ plan are needed, as for any
@@ -378,11 +392,10 @@ person, animal and package detection, are then made by HomeKit.
 
 To inspect recordings, see [Troubleshooting](#troubleshooting).
 
-### Two-way talk (beta)
+### Two-way talk
 
 Turn on **Two-way talk** (`twoWayAudio`) and restart the bridge to talk through the doorbell from the Home app's
-live view (the microphone button). It is a beta: whether the doorbell accepts audio from the plugin isn't known for
-every firmware, and talking adds a little delay. The log says at start-up what the doorbell answered ("two-way
+live view (the microphone button). Whether the doorbell accepts audio from the plugin can depend on its firmware, and talking adds a little delay. The log says at start-up what the doorbell answered ("two-way
 talk: the camera answered audio sendrecv" is good; anything else means it can't take audio and the plugin carries
 on receive-only, as before). The live view's picture and sound are not affected.
 
@@ -390,6 +403,52 @@ To check that audio reaches the doorbell, set `"twoWayAudioTest": true` in the c
 switch), open the live view while standing at the door, and listen for a 3-second tone; the log says "test tone
 sent". Turn it off afterwards.
 
+## Quick Responses
+
+Quick Responses are short messages the doorbell plays on its speaker, for the person at your door: "You can just leave it", "We'll be right there". Turn on **Quick Responses** (`quickResponses`, in the **Doorbell camera** card, which needs the doorbell camera) and restart the bridge. It needs the doorbell to accept audio from the plugin, the same as [Two-way talk](#two-way-talk) (the log says what it answered), but **Two-way talk** itself doesn't have to be on.
+
+There are three built-in messages:
+
+| Tile | Says |
+|---|---|
+| Leave Delivery | "Hi there. You can just leave it. Thanks!" |
+| Hang On | "Just a sec, we'll be right there." |
+| Not Home | "Hi there, no one can answer the door right now, but we'll be notified that you stopped by." |
+
+The messages appear in the Home app as **one tile, "Quick Responses"**, which holds a switch per message. Tapping the tile itself turns all of them on at once, which the plugin recognises and ignores (it plays nothing and the switches turn back off; the log says so). **Open the tile** (long-press, or tap its settings) and pick one message instead. If you prefer a tile per message, turn on **Show as Separate Tiles** in the accessory's settings in the Home app. In the doorbell's live view, the group appears as one tile in **Nearby Accessories**: add it there and tap the message you want. Turning a message's switch on plays it and it turns itself off when the message ends. Siri works too ("Hey Siri, turn on Not Home"), and so do automations and scenes. Messages play at the volume you set (`quickResponseVolume`, 40% by default).
+
+In the settings, each message is a row: the **title** (the tile name, 14 characters at most), **what is said**, and **Preview**, which plays it in your browser. Without Piper, the three built-in messages are fixed: the rows show their title and wording as text, and you can preview them. Once [Piper](#custom-wording-with-piper) is installed, each built-in row has **Replace** (edit its title and wording; **Restore** goes back to the shipped wording and audio) and **Add a message** adds your own, with a remove button. The built-in messages can be removed (×) and added back from the line under the rows, with or without Piper; a removed message's switch leaves the Home app after a bridge restart, and returns with the same identity when added back. Changing a title or the wording takes effect after a bridge restart.
+
+An example automation: when someone rings and nobody is home, tell them so.
+
+1. **Trigger:** An Accessory is Controlled > **Doorbell Pressed** detects occupancy ([Doorbell Pressed sensor](#doorbell-pressed-sensor)).
+2. **Condition:** only if **Home Occupied** is off ([Home Occupied switch](#home-occupied-switch)).
+3. **Action:** turn on **Not Home**.
+
+How it works: the message is played into the plugin's session with the doorbell, so it can't play while the session is down, while the camera hasn't accepted audio from us, while another message is playing, or while someone is talking in a live view (the microphone has priority; a message that is playing stops when someone starts talking). The switch then turns itself back off after a second, and the log says why. One message plays at a time. The log line "Quick Response "<name>" played" shows how many audio packets were sent. Each switch's identity comes from the message's `id`, not its title or wording, so you can rename a message without breaking the automations that use it. Messages you remove from the settings disappear from the Home app after a restart.
+
+### Custom wording with Piper
+
+The three built-in messages come as recordings with the plugin. Anything else, meaning reworded built-ins and your own messages, is turned into speech on your Homebridge machine with [Piper](https://github.com/OHF-Voice/piper1-gpl), a local text-to-speech program that doesn't send your text anywhere. That is optional: without Piper the built-ins work as they are, and a message that needs it is left out, with a warning in the log.
+
+1. Install Piper into a folder the Homebridge user can read, for example a Python virtual environment:
+
+   ```sh
+   sudo -u homebridge python3 -m venv /var/lib/homebridge/piper
+   sudo -u homebridge /var/lib/homebridge/piper/bin/pip install piper-tts
+   ```
+
+2. Download a voice: an `.onnx` file and its `.onnx.json` file, side by side, from [rhasspy/piper-voices on Hugging Face](https://huggingface.co/rhasspy/piper-voices). The built-in messages use the English (US) **ryan**, **high** quality voice, which is a good place to start.
+3. In the settings, under **Piper settings** in the Quick Responses box, fill in **Piper path** (the `piper` program, for example `/var/lib/homebridge/piper/bin/piper`) and **Piper voice** (the `.onnx` file). The page says whether Piper was found. **Preview** then plays your wording.
+
+The plugin makes the audio for your messages when the bridge starts (one at a time, in the background) and keeps it in `ecobee-security/quick-responses` in the Homebridge folder, and removes it when no message uses it any more. A message shows up in the Home app once its audio is ready. All messages are spoken with the same speed and voice settings as the built-ins.
+
+Tips: a bare "Hi!" can come out as "Aye". Writing "Hi there" usually helps, or give Piper the exact sounds: text between `[[` and `]]` is read as phonemes, for example `[[ hˈaɪ ðɛɹ ]]`. Phonemes are passed through unchanged.
+
+### Voice licensing
+
+The recordings of the built-in messages (in `assets/quick-responses`) were made with Piper's **ryan** voice, whose training data (RyanSpeech) is licensed **CC BY-NC-SA 4.0**. The recordings are therefore licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) too: free for non-commercial use, with attribution: "RyanSpeech (CC BY-NC-SA 4.0), synthesized with Piper". The rest of the plugin stays MIT licensed. A voice you use for your own wording has its own license; check it before sharing recordings made with it.
+
 ## Home Occupied switch
 
 Apple Home asks you to confirm (a notification you have to tap) whenever a people-arrive or

package/assets/quick-responses/LICENSE

@@ -0,0 +1,19 @@
+The audio files in this folder (leave-delivery.wav, hang-on.wav, not-home.wav) are licensed under the
+Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International license (CC BY-NC-SA 4.0).
+
+  https://creativecommons.org/licenses/by-nc-sa/4.0/
+  Legal code: https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode
+
+You may copy and redistribute the recordings and adapt them, for non-commercial purposes only, if you give
+appropriate credit, indicate changes, and share your adaptations under the same license.
+
+Attribution:
+
+  RyanSpeech (CC BY-NC-SA 4.0), synthesized with Piper
+
+The recordings were synthesized with the Piper text-to-speech program (https://github.com/OHF-Voice/piper1-gpl)
+and its "ryan" voice (en_US-ryan-high), which was trained on the RyanSpeech dataset,
+licensed CC BY-NC-SA 4.0.
+
+The rest of this package is licensed under the MIT license (see the LICENSE file in the package root); this
+license applies only to the files in this folder.

package/config.schema.json

@@ -251,6 +251,79 @@
           "functionBody": "return model.doorbellCamera === true && model.twoWayAudio === true;"
         }
       },
+      "quickResponses": {
+        "title": "Quick Responses",
+        "type": "boolean",
+        "default": false,
+        "description": "Short messages the doorbell can play. They appear as one Quick Responses tile in the Home app, with a switch per message, which you can add to the live view's Nearby Accessories. Restart the bridge after changing this. See \"Quick Responses\" in the README.",
+        "condition": {
+          "functionBody": "return model.doorbellCamera === true;"
+        }
+      },
+      "quickResponseVolume": {
+        "title": "Quick Response volume (%)",
+        "type": "integer",
+        "default": 40,
+        "minimum": 5,
+        "maximum": 100,
+        "description": "How loud messages play at the door.",
+        "condition": {
+          "functionBody": "return model.doorbellCamera === true && model.quickResponses === true;"
+        }
+      },
+      "quickResponseMessages": {
+        "title": "Quick Response messages",
+        "type": "array",
+        "description": "The messages, each with an id that stays the same (it keeps the switch's identity in the Home app), a name of up to 14 characters, and what is said. With no list, the three built-in messages (Leave Delivery, Hang On, Not Home).",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "title": "Id",
+              "type": "string"
+            },
+            "name": {
+              "title": "Name",
+              "type": "string",
+              "maxLength": 14
+            },
+            "phrase": {
+              "title": "What is said",
+              "type": "string"
+            },
+            "enabled": {
+              "title": "Enabled",
+              "type": "boolean",
+              "default": true,
+              "description": "Only for the built-in messages: false removes the switch from the Home app and keeps the wording."
+            }
+          },
+          "required": [
+            "id",
+            "name",
+            "phrase"
+          ]
+        },
+        "condition": {
+          "functionBody": "return model.doorbellCamera === true && model.quickResponses === true;"
+        }
+      },
+      "piperPath": {
+        "title": "Piper path",
+        "type": "string",
+        "description": "Only for changed or new wording: the piper program you installed (see \"Custom wording with Piper\" in the README).",
+        "condition": {
+          "functionBody": "return model.doorbellCamera === true && model.quickResponses === true;"
+        }
+      },
+      "piperVoice": {
+        "title": "Piper voice",
+        "type": "string",
+        "description": "Path to the voice (.onnx) Piper speaks with.",
+        "condition": {
+          "functionBody": "return model.doorbellCamera === true && model.quickResponses === true;"
+        }
+      },
       "ffmpegPath": {
         "title": "ffmpeg path",
         "type": "string",

package/homebridge-ui/public/index.html

@@ -1,6 +1,18 @@
 <style>
   /* Inherit the theme's text colour; Bootstrap's muted grey is unreadable on Homebridge's dark themes. */
-  .hint { opacity: 0.75; font-size: 0.875em; }
+  /* Fade the text colour rather than the element, so links in hints keep the theme's full accent colour. */
+  .hint { color: color-mix(in srgb, currentColor 75%, transparent); font-size: 0.875em; }
+  /* Quick Responses rows: title | wording | Preview | actions; the wording drops under the title in a narrow panel. */
+  #qr-rows { container-type: inline-size; }
+  .qr-row { display: grid; grid-template-columns: 9.5em 1fr auto auto; gap: 0.5rem 0.75rem; align-items: center; padding: 0.5rem 0; border-top: 1px solid rgba(127, 127, 127, 0.25); }
+  .qr-row:last-child { border-bottom: 1px solid rgba(127, 127, 127, 0.25); }
+  .qr-row .btn { text-transform: none; letter-spacing: normal; white-space: nowrap; }
+  .qr-title { overflow-wrap: anywhere; }
+  .qr-actions { display: flex; gap: 0.25rem; justify-content: flex-end; }
+  @container (max-width: 480px) {
+    .qr-row { grid-template-columns: 1fr auto auto; }
+    .qr-phrase { grid-column: 1 / -1; grid-row: 2; }
+  }
 </style>
 
 <div class="card card-body mb-3">
@@ -154,10 +166,39 @@
     </div>
     <div class="form-check form-switch mb-1">
       <input class="form-check-input" type="checkbox" role="switch" id="s-twoWayAudio" data-key="twoWayAudio" data-type="bool" data-default="false">
-      <label class="form-check-label" for="s-twoWayAudio">Two-way talk (beta)</label>
+      <label class="form-check-label" for="s-twoWayAudio">Two-way talk</label>
     </div>
     <p class="hint mb-2">Talk through the doorbell from the Home app's live view. Restart the bridge after changing this.
-      <a href="https://github.com/seanfletchr/homebridge-ecobee-security#two-way-talk-beta" target="_blank" rel="noopener">Learn more…</a></p>
+      <a href="https://github.com/seanfletchr/homebridge-ecobee-security#two-way-talk" target="_blank" rel="noopener">Learn more…</a></p>
+    <div class="form-check form-switch mb-1">
+      <input class="form-check-input" type="checkbox" role="switch" id="s-quickResponses" data-key="quickResponses" data-type="bool" data-default="false">
+      <label class="form-check-label" for="s-quickResponses">Quick Responses</label>
+    </div>
+    <p class="hint mb-2">Short messages the doorbell can play. They appear as one Quick Responses tile in the Home app, with a switch per message, which you can add to the live view's Nearby Accessories. Restart the bridge after changing this.
+      <a href="https://github.com/seanfletchr/homebridge-ecobee-security#quick-responses" target="_blank" rel="noopener">Learn more…</a></p>
+    <div id="qr-box" class="mb-2" hidden>
+      <div class="d-flex align-items-center gap-2 mb-1">
+        <label for="s-quickResponseVolume" class="form-label mb-0">Volume (%)</label>
+        <input class="form-control form-control-sm" style="width:6em" type="number" step="5" min="5" max="100" id="s-quickResponseVolume" data-key="quickResponseVolume" data-type="int" data-default="40">
+      </div>
+      <div class="hint mb-2">How loud messages play at the door.</div>
+      <div id="qr-rows"></div>
+      <p class="hint mb-2" id="qr-removed" hidden></p>
+      <p class="hint mb-2" id="qr-piper-hint" hidden>To change these or add your own, install Piper
+        (<a href="https://github.com/seanfletchr/homebridge-ecobee-security#custom-wording-with-piper" target="_blank" rel="noopener">see README</a>)</p>
+      <button type="button" class="btn btn-secondary btn-sm" id="qr-add" hidden>Add a message</button>
+      <div id="qr-error" class="alert alert-danger mt-2 mb-0" role="alert" hidden></div>
+      <details class="mt-2">
+        <summary>Piper settings</summary>
+        <div class="mt-2">
+          <label for="s-piperPath" class="form-label mb-1">Piper path</label>
+          <input class="form-control mb-2" type="text" id="s-piperPath" data-key="piperPath" data-type="text" data-default="" placeholder="/var/lib/homebridge/piper/bin/piper">
+          <label for="s-piperVoice" class="form-label mb-1">Piper voice</label>
+          <input class="form-control mb-1" type="text" id="s-piperVoice" data-key="piperVoice" data-type="text" data-default="" placeholder="/var/lib/homebridge/piper/en_US-ryan-high.onnx">
+          <div class="hint" id="piper-status"></div>
+        </div>
+      </details>
+    </div>
     <details>
       <summary>Advanced</summary>
       <div class="mt-2">
@@ -423,6 +464,7 @@
     if (block?.doorbellCamera === true) {
       await showLink();
     }
+    await showQuickResponses(block);
   }
 
   /**
@@ -546,6 +588,8 @@
           showVacationOptions();
         } else if (key === 'memberPresence') {
           await showMembers();
+        } else if (key === 'quickResponses') {
+          await showQuickResponses();
         } else if (key === 'doorbellCamera') {
           $('camera-box').hidden = !input.checked;
           if (input.checked) {
@@ -689,6 +733,270 @@
     await showKeypad();
   });
 
+  // ── Quick Responses ──
+
+  const NAME_MAX = 14;
+  let qrMessages = [];
+  let qrBuiltIns = new Map();
+
+  function qrError(message) {
+    $('qr-error').textContent = message ?? '';
+    $('qr-error').hidden = !message;
+  }
+
+  /** The messages: the saved list, or the built-ins while none is saved. */
+  async function loadMessages(block) {
+    const defaults = await homebridge.request('/quick-response-defaults').catch(() => []);
+    qrBuiltIns = new Map(defaults.map(m => [m.id, m]));
+    const saved = block?.quickResponseMessages;
+    qrMessages = (Array.isArray(saved) ? saved : defaults).map(m => ({
+      id: String(m.id), name: String(m.name ?? ''), phrase: String(m.phrase ?? ''), enabled: m.enabled !== false,
+    }));
+    // A built-in missing from a saved list is still a built-in: offered under Removed.
+    for (const builtIn of defaults) {
+      if (Array.isArray(saved) && !qrMessages.some(m => m.id === builtIn.id)) {
+        qrMessages.push({ ...builtIn, enabled: false });
+      }
+    }
+  }
+
+  async function showQuickResponses(blockIn) {
+    const block = blockIn ?? (await homebridge.getPluginConfig())[0] ?? {};
+    $('qr-box').hidden = block.quickResponses !== true;
+    if (block.quickResponses !== true) {
+      return;
+    }
+    await loadMessages(block);
+    piperFound = false;
+    renderRows();
+    await showPiperStatus();
+  }
+
+  /** Writes the whole list (built-ins included), so a later change of the built-ins' defaults can't alter what you saved. */
+  async function saveMessages() {
+    await setSetting('quickResponseMessages', qrMessages.map(({ id, name, phrase, enabled }) => ({
+      id, name: name.trim(), phrase: phrase.trim(), ...(qrBuiltIns.has(id) && enabled === false ? { enabled: false } : {}),
+    })));
+  }
+
+  let piperFound = false;
+  const replacing = new Set();   // built-ins being replaced (their title and wording are inputs)
+
+  const same = (message) => {
+    const builtIn = qrBuiltIns.get(message.id);
+    return builtIn && message.name.trim() === builtIn.name && message.phrase.trim() === builtIn.phrase;
+  };
+
+  function renderRows() {
+    const box = $('qr-rows');
+    box.textContent = '';
+    $('qr-add').hidden = !piperFound;
+    $('qr-piper-hint').hidden = piperFound;
+    const removed = qrMessages.filter(m => m.enabled === false);
+    const note = $('qr-removed');
+    note.hidden = !removed.length;
+    note.textContent = '';
+    if (removed.length) {
+      note.append('Removed: ');
+      removed.forEach((message, index) => {
+        if (index) {
+          note.append(' \u00b7 ');
+        }
+        const link = Object.assign(document.createElement('a'), { href: '#', textContent: 'Add back' });
+        link.addEventListener('click', async (event) => {
+          event.preventDefault();
+          message.enabled = true;
+          renderRows();
+          await saveMessages();
+        });
+        note.append(`${message.name} \u00b7 `, link);
+      });
+    }
+    for (const message of qrMessages.filter(m => m.enabled !== false)) {
+      const builtIn = qrBuiltIns.has(message.id);
+      // Built-ins are text unless Piper is there and they are being replaced (or already differ from the shipped wording).
+      const editable = !builtIn || (piperFound && (replacing.has(message.id) || !same(message)));
+      const row = Object.assign(document.createElement('div'), { className: 'qr-row' });
+      const nameWrap = Object.assign(document.createElement('div'), { className: 'qr-title' });
+      const phraseWrap = Object.assign(document.createElement('div'), { className: 'qr-phrase' });
+
+      if (editable) {
+        const name = Object.assign(document.createElement('input'), {
+          type: 'text', className: 'form-control form-control-sm', maxLength: NAME_MAX, value: message.name, placeholder: 'Title',
+        });
+        name.setAttribute('aria-label', 'Title');
+        const counter = Object.assign(document.createElement('div'), { className: 'hint text-end' });
+        counter.style.fontSize = '0.75em';
+        const count = () => {
+          counter.textContent = `${name.value.length}/${NAME_MAX}`;
+        };
+        count();
+        name.addEventListener('input', () => {
+          count();
+          message.name = name.value;
+        });
+        name.addEventListener('change', () => {
+          name.classList.toggle('is-invalid', !name.value.trim());
+          saveMessages();
+        });
+        nameWrap.append(name, counter);
+
+        const phrase = Object.assign(document.createElement('input'), {
+          type: 'text', className: 'form-control form-control-sm', value: message.phrase, placeholder: 'What the doorbell says',
+        });
+        phrase.setAttribute('aria-label', 'What the doorbell says');
+        phrase.addEventListener('input', () => {
+          message.phrase = phrase.value;
+        });
+        phrase.addEventListener('change', () => {
+          phrase.classList.toggle('is-invalid', !phrase.value.trim());
+          saveMessages();
+        });
+        phraseWrap.append(phrase);
+      } else {
+        nameWrap.textContent = message.name;
+        phraseWrap.className += ' hint';
+        phraseWrap.textContent = `\u201c${message.phrase}\u201d`;
+      }
+
+      const preview = Object.assign(document.createElement('button'), { type: 'button', className: 'btn btn-sm btn-outline-secondary', textContent: 'Preview' });
+      preview.addEventListener('click', () => previewMessage(message, preview));
+
+      const slot = Object.assign(document.createElement('div'), { className: 'qr-actions' });
+      const remove = Object.assign(document.createElement('button'), { type: 'button', className: 'btn btn-sm btn-outline-secondary', textContent: '\u00d7' });
+      remove.setAttribute('aria-label', `Remove ${message.name || 'this message'}`);
+      remove.addEventListener('click', async () => {
+        // A built-in is only switched off (its wording stays for "Add back"); your own are deleted.
+        if (builtIn) {
+          message.enabled = false;
+          replacing.delete(message.id);
+        } else {
+          qrMessages = qrMessages.filter(m => m !== message);
+        }
+        renderRows();
+        await saveMessages();
+      });
+      if (builtIn && piperFound) {
+        const replace = editable;
+        const button = Object.assign(document.createElement('button'), {
+          type: 'button', className: 'btn btn-sm btn-outline-secondary', textContent: replace ? 'Restore' : 'Replace',
+        });
+        button.addEventListener('click', async () => {
+          if (replace) {
+            const shipped = qrBuiltIns.get(message.id);
+            message.name = shipped.name;
+            message.phrase = shipped.phrase;
+            replacing.delete(message.id);
+          } else {
+            replacing.add(message.id);
+          }
+          renderRows();
+          await saveMessages();
+        });
+        slot.append(button);
+      }
+      slot.append(remove);
+
+      row.append(nameWrap, phraseWrap, preview, slot);
+      box.append(row);
+    }
+  }
+
+  // Preview plays through the Web Audio API: the settings page's iframe can't play data: URLs in every browser.
+  let audioContext;
+  let playing;   // { source, button }
+
+  function stopPreview() {
+    if (!playing) {
+      return;
+    }
+    const { source, button } = playing;
+    playing = undefined;
+    button.textContent = 'Preview';
+    try {
+      source.stop();
+    } catch {
+      // already stopped
+    }
+  }
+
+  const decode = (context, data) => new Promise((resolve, reject) => {
+    // Older Safari only has the callback form.
+    const promise = context.decodeAudioData(data, resolve, reject);
+    promise?.then?.(resolve, reject);
+  });
+
+  async function previewMessage(message, button) {
+    qrError();
+    const wasPlaying = playing?.button === button;
+    stopPreview();
+    if (wasPlaying) {
+      return;
+    }
+    button.disabled = true;
+    try {
+      // Created and resumed inside the click, before anything is awaited that would end the user gesture.
+      audioContext ??= new (window.AudioContext || window.webkitAudioContext)();
+      const resumed = audioContext.resume();
+      const result = await homebridge.request('/quick-response-preview', {
+        id: message.id, phrase: message.phrase, ...piperFields(),
+      });
+      await resumed;
+      const bytes = Uint8Array.from(atob(result.audio), c => c.charCodeAt(0));
+      const buffer = await decode(audioContext, bytes.buffer);
+      const source = audioContext.createBufferSource();
+      source.buffer = buffer;
+      source.connect(audioContext.destination);
+      const mine = { source, button };
+      source.onended = () => {
+        if (playing === mine) {
+          stopPreview();
+        }
+      };
+      playing = mine;
+      button.textContent = 'Stop';
+      source.start();
+    } catch (error) {
+      qrError(error?.message || String(error) || 'Could not play the preview.');
+    } finally {
+      button.disabled = false;
+    }
+  }
+
+  $('qr-add').addEventListener('click', async () => {
+    const bytes = crypto.getRandomValues(new Uint8Array(3));
+    const id = `m-${[...bytes].map(b => b.toString(16).padStart(2, '0')).join('')}`;
+    qrMessages.push({ id, name: '', phrase: '' });
+    renderRows();
+    $('qr-rows').lastElementChild?.querySelector('input')?.focus();
+    await saveMessages();
+  });
+
+  function piperFields() {
+    return { piperPath: $('s-piperPath').value.trim(), piperVoice: $('s-piperVoice').value.trim() };
+  }
+
+  async function showPiperStatus() {
+    const { piperPath, piperVoice } = piperFields();
+    const status = $('piper-status');
+    let found = false;
+    if (!piperPath && !piperVoice) {
+      status.textContent = 'Piper not set up.';
+    } else {
+      const result = await homebridge.request('/piper-status', { piperPath, piperVoice }).catch(() => ({ found: false, reason: 'could not check' }));
+      found = result.found === true;
+      status.textContent = found ? 'Piper found' : `Piper not found (${result.reason})`;
+    }
+    if (found !== piperFound) {
+      piperFound = found;
+      renderRows();
+    }
+  }
+
+  for (const id of ['s-piperPath', 's-piperVoice']) {
+    $(id).addEventListener('change', showPiperStatus);
+  }
+
   // ── Doorbell link ──
 
   let linkChoice;