docs: the Sonix player

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

4 files changed, 77 insertions, 4 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 30bba4f..69a7f8e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,11 +12,11 @@ any of them runs alone, and running one does not require the others. `desktop/`
 modules.
 
     desktop/          the drawer (SUPER alone): user details, sound, mail, VMs, status,
-                      performance, clipboard, updates; and the settings
+                      performance, clipboard, updates; the Sonix player; and the settings
                       window for pages set once: wallpaper, transitions, theme, theme status,
                       icons, sunset, idle (the former appearance shell), notifications, autostart, shells,
                       the assistant's daemon and presets, qtmaildir, git,
-                      Hyprland's keyboard shortcuts, options and monitors, fonts
+                      Hyprland's keyboard shortcuts, options and monitors, fonts, the Sonix boot logo
       island/         top-centre pills on DP-1: clock, volume, tray, layout, privacy,
                       calendar, OBS
       assistant/      the assistant canvas on SUPER+Home, a view over desktop-assistant
diff --git a/desktop/README.md b/desktop/README.md
index 0f82445..c7aea52 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -85,6 +85,7 @@ and flashes it, so a page needs no highlight code of its own.
     modules/network/     wired and wifi, radio, scan, join, forget
     modules/bluetooth/   adapter, scan, pair, connect, forget, trust
     modules/kdeconnect/  devices, battery, pairing, ping, clipboard, share, mount
+    modules/sonix/       the Sonix player: device, playlists, folders; boot logo page
     modules/mail/        unread per account, threads, the watcher dot
     modules/vm/          libvirt state, live stats, snapshots
     modules/appearance/  wallpaper, theme, icons, sunset, idle: settings pages
@@ -100,7 +101,7 @@ and flashes it, so a page needs no highlight code of its own.
     modules/qtmaildir/   qtmaildir.conf: general, compose, accounts, tags and keys
     modules/sbbuilder/   sb-builder's GUI config and the build VM helper's config
 
-Sound, mail, vm, network, bluetooth, kdeconnect and ai each carry their own README.
+Sound, mail, vm, network, bluetooth, kdeconnect, sonix and ai each carry their own README.
 So does appearance, for its five settings pages.
 
 ## Writing a module
diff --git a/desktop/island/README.md b/desktop/island/README.md
index 01751c1..7adf9ad 100644
--- a/desktop/island/README.md
+++ b/desktop/island/README.md
@@ -47,10 +47,15 @@ is open or not. Click opens the calendar panel.
 
 ## Status pill
 
-Left to right: headphones icon, volume icon, tray, layout flag. The
+Left to right: Sonix player icon, headphones icon, volume icon, tray, layout flag. The
 performance panel that used to open from here is the drawer's Performance
 page now (`desktop/modules/perf/`).
 
+- **Sonix player icon** shows while a HiBy R1 running Sonix Player is on
+  the network (its SonixLink beacon). A dot under it while it plays. Click
+  opens its panel: cover, title, a heart for the track's favourite,
+  quality, seek, transport, mode, volume (sent once it settles), battery.
+  See `desktop/modules/sonix/README.md`.
 - **Headphones icon** shows while Sony headphones are connected (a BlueZ
   name starting `WH-`, `WF-` or `LinkBuds`). Click opens the headphones
   panel: battery (BlueZ), noise control tiles (ANC, ambient, off), the
diff --git a/desktop/modules/sonix/README.md b/desktop/modules/sonix/README.md
new file mode 100644
index 0000000..945b62e
--- /dev/null
+++ b/desktop/modules/sonix/README.md
@@ -0,0 +1,67 @@
+# sonix
+
+A HiBy R1 running [Sonix Player](https://github.com/Jepl4r/sonix-player),
+over the LAN: an icon and controls panel in the island's status pill, a
+drawer tile and page, and a boot logo editor in the settings window, under
+its own sidebar group "HiBy R1".
+
+## The player's two servers
+
+- **SonixLink**, HTTP on port 7800, no authentication: state, commands,
+  covers, the library. Switched on from the player's control centre.
+  Anyone on the network can drive the player while it is on.
+- **Wi-Fi transfer**, HTTP on port 80: the card's file server. It runs only
+  while its page is open on the player; leaving the page stops it. Used
+  only by the boot logo upload.
+
+## Presence
+
+SonixLink broadcasts `SONIXLINK1 <ip> <port> <name>` to UDP 7801 every 2s.
+`sonix-beacon.py` relays it to stdout (QML has no UDP socket) and
+`desktop/Sonix.qml` reads it: present while beacons arrive, gone 6s after
+the last. The address follows the beacon, so DHCP changes need nothing.
+
+## Polling
+
+`/api/state` is read every second while a view holds the service: the
+island panel, the drawer tile, the drawer page. Nothing is polled
+otherwise, and `/api/bye` is sent when the last view lets go, so the player
+stops counting a client.
+
+## Notes
+
+SonixLink's `bitrate` is in bits per second; the panel shows kbps. The
+heart in the panel sends the `favourite` command (path, value 1 or 0).
+
+## Drawer page
+
+Device: name, address, battery, the player's accent, the library and a
+Rescan, what is playing, a link to Wi-Fi transfer and to the boot logo
+page. Playlists: play, open, remove a track, new names. Folders: browse,
+play a folder or a file, add either to a playlist; folder rows carry
+"folder" as their second line. The tab starts at the card root by browsing
+with an empty path (the player answers `path=/` with plain text "outside
+the card").
+
+SonixLink has no rename, delete or reorder for playlists, and makes a
+playlist only by adding a track to a new name. The player has rename and
+delete internally but does not expose them; the `.m3u` files on the card
+are backups, not the playlists. Do those on the player. `play_all` refuses
+a folder, so a folder plays as its first file with the folder as the list.
+
+## Boot logo
+
+The page is in the settings window, under the "HiBy R1" group. A 480x800
+scene: the picture, panned and zoomed, and the text in one of four faces
+(Bungee with its Inline layer, Major Mono Display, Michroma, Audiowide; SIL
+OFL, in `fonts/`) in two colours: the six player accents, white, black, or
+the udt accent. Save writes `bootlogo-<stamp>.png` and
+`bootlogo-<stamp>-mask.png`, the text on transparency, to the output folder.
+Upload saves, then sends the PNG to `Bootlogo/` on the card through Wi-Fi
+transfer, waiting up to 60s for it to be opened on the player. The logo is
+then picked on the player: Settings > Appearance > Boot logo.
+
+## Tests
+
+    node desktop/modules/sonix/test_sonix.js
+    /usr/bin/python3 desktop/modules/sonix/test_sonix_beacon.py