docs: record the classroom test checklist and DVD notes

The checklist covers the bottom-shell regression explicitly, since that is the part most likely to be broken by a later change, and records the known limitation that Chrome's own minimize button does nothing under sway. Co-Authored-By: Claude Opus 5 <[email protected]>
2026-09-04 17:07:30 -05:00
parent 0c1acfe5f5
commit a8cf9ef337
2 changed files with 169 additions and 0 deletions
@@ -0,0 +1,82 @@
+# DVD support
+
+DVD support is optional per classroom and off by default.
+
+## Enabling a room
+
+Edit `/etc/ekklesia-classroom/device.conf` on that endpoint:
+
+```
+DVD_ENABLED=true
+```
+
+Then restart the session (reboot, or restart `classroom-dock`).
+
+With `DVD_ENABLED=false`, or the key absent, the DVD button is not built
+at all and no drive polling happens. Older endpoints get a commented
+`DVD_ENABLED=false` appended on upgrade so the option is discoverable,
+which leaves their behaviour unchanged.
+
+## Behaviour
+
+The dock polls the drive every two seconds with the `CDROM_DRIVE_STATUS`
+ioctl. That is a status query, so it does not spin the disc up.
+
+| State | Dock icon | Clicking the button |
+| --- | --- | --- |
+| No drive connected | DVD logo held back at 55% | "No DVD drive is connected to this classroom computer." |
+| Drive present, no disc | DVD logo held back at 55% | "No disc is in the drive. Insert a disc to get started." |
+| Tray open | held back | "The disc tray is open. Insert a disc to get started." |
+| Disc still being read | held back | "Reading the disc. Please try again in a moment." |
+| Disc ready | DVD logo at full strength | Plays the disc |
+
+When a disc becomes ready, a **DVD Ready** notification is shown once.
+Discs never play on their own; playback always needs a button press.
+
+The first poll after login only records what is already in the drive, so
+a disc left in over the week does not announce itself at every boot.
+
+## Playback
+
+Playback is VLC, chosen over mpv because mpv dropped DVD menu support.
+VLC's `dvdnav` path gives working menus, chapters and audio tracks.
+
+`classroom-dvd toggle` hands the disc to VLC through `classroom-window`,
+so the DVD player behaves like any other classroom application: the DVD
+button focuses it, minimises it, and restores it. `Super+M` minimises it
+too. VLC starts fullscreen; `Esc` leaves fullscreen.
+
+## Commercial (CSS encrypted) discs
+
+Most retail DVDs are CSS encrypted, and Debian cannot ship the
+decryption library. Unencrypted discs — curriculum discs, home-burned
+video — play without any extra work.
+
+For commercial discs, run once per endpoint, as root:
+
+```
+sudo classroom-dvd-css-setup
+```
+
+That enables the Debian `contrib` component, installs `libdvd-pkg` and
+builds `libdvdcss`. It needs network access and it compiles a package,
+which is why it is deliberately not run from the package `postinst`: the
+postinst runs while dpkg already holds the apt lock during an OTA update.
+
+**Commercial DVD playback has not been verified on hardware yet.** Test
+with an actual disc before relying on it for a service.
+
+## Command line
+
+```
+classroom-dvd status    # drive node, drive state, whether VLC is installed
+classroom-dvd toggle    # what the dock button does
+classroom-dvd play      # start playback even if the drive is unsure
+classroom-dvd eject     # open the tray
+```
+
+## Permissions
+
+Reading the drive needs group `cdrom`. The postinst adds the `classroom`
+user to it; that takes effect at the next login, which the OTA reboot
+provides. Without it the drive reads as absent.