Switch musicdolphin's screen from the IR remote's power key

pi_kiosk installs kiosk-screen on|off|toggle|status, which switches the monitor via
DPMS on the kiosk's X display (the Dell P2419H has no HDMI-CEC). Turning it back on
also turns DPMS off again, as .xinitrc does, so the screen never blanks by itself.

musicdolphin's backend config runs `kiosk-screen toggle` for the power key (the new
screen: section, MusicMouse 2d0caeb). config.yml is install-once, so the running host
is changed by hand the same way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

roles/pi_kiosk/README.md

@@ -15,6 +15,15 @@ Vars:
 Meant to run alongside `pi_musicmouse` on the same host when it's serving the page
 locally (the default `pi_kiosk_url`), gated in `mediapis.yml` by `mediapi_has_monitor`.
 
+## Switching the screen off
+
+`/usr/local/bin/kiosk-screen on|off|toggle|status` switches the monitor through DPMS:
+X stops the HDMI signal and the monitor goes into standby, while the browser and
+whatever is playing carry on. It is there for the MusicMouse backend, whose `screen:`
+config section runs `kiosk-screen toggle` on the IR remote's power key, and works the
+same as root over ssh. HDMI-CEC would switch a TV off properly, but musicdolphin's Dell
+P2419H does not speak it, and every monitor understands losing its signal.
+
 ## Why Chromium
 
 Firefox was the original choice and lost on measurement. Same page, same machine, idle:

roles/pi_kiosk/tasks/main.yml

@@ -132,6 +132,13 @@
     mode: "0755"
   notify: Reload systemd and restart getty
 
+- name: Install kiosk-screen (switches the monitor on and off)
+  # Run by the MusicMouse backend for the IR remote's power key; see the template.
+  ansible.builtin.template:
+    src: kiosk-screen.j2
+    dest: /usr/local/bin/kiosk-screen
+    mode: "0755"
+
 - name: Ensure the browser policy directory exists
   ansible.builtin.file:
     path: "{{ '/etc/chromium/policies/managed' if pi_kiosk_browser == 'chromium' else '/etc/firefox-esr' }}"

roles/pi_kiosk/templates/kiosk-screen.j2

@@ -0,0 +1,44 @@
+#!/bin/sh
+# Managed by ansible (pi_kiosk role).
+#
+# kiosk-screen on|off|toggle|status - switch the kiosk's monitor on or off.
+#
+# "Off" is DPMS: X stops the HDMI signal and the monitor drops into standby. The
+# session, the browser and everything playing carry on. The MusicMouse backend runs
+# `kiosk-screen toggle` for the IR remote's power key (its config's screen: section);
+# it works over ssh as root too.
+#
+# .xinitrc turns DPMS off so the screen never blanks by itself. Forcing it off has to
+# turn DPMS on, so `on` turns it back off again - otherwise the screen would blank on
+# its own ten minutes after every switch-on.
+
+set -e
+export DISPLAY=:0
+export XAUTHORITY=/home/{{ pi_kiosk_user }}/.Xauthority
+
+# With DPMS disabled `xset q` prints no monitor line at all, and the monitor is on.
+status() {
+    if xset q | grep -q "Monitor is Off"; then echo off; else echo on; fi
+}
+
+screen_on() {
+    xset dpms force on
+    xset -dpms
+}
+
+screen_off() {
+    xset +dpms
+    xset dpms force off
+}
+
+case "$1" in
+    on) screen_on ;;
+    off) screen_off ;;
+    toggle) if [ "$(status)" = off ]; then screen_on; else screen_off; fi ;;
+    status) ;;
+    *)
+        echo "usage: $0 on|off|toggle|status" >&2
+        exit 2
+        ;;
+esac
+status

roles/pi_musicmouse/files/config-musicdolphin.yml

@@ -78,6 +78,11 @@ general:
     port: 8765
     remote_name: "hauppauge"
 
+  # The remote's power key switches the monitor off and on. kiosk-screen is pi_kiosk's:
+  # it asks X whether the monitor is on and flips it, so nothing here tracks the state.
+  screen:
+    toggle_command: /usr/local/bin/kiosk-screen toggle
+
   # Backlight of the prev/next buttons while a figure is playing, 0..1. Inert here
   # (no mouse), kept so the file reads the same as the other hosts'.
   button_leds_brightness: 0.5