Skip to content

docs(players): ship descriptors from /usr/share, not /etc #662

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hifiberry merged 2 commits into from
Sep 7, 2026
Merged

docs(players): ship descriptors from /usr/share, not /etc #662

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
94b1667
docs(players): ship descriptors from /usr/share, not /etc
Sep 7, 2026
7511b7e
docs(players): retarget the step-by-step section to /usr/share too
Sep 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 25 additions & 10 deletions docs/add-your-own-player.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ To make your player appear on the **Services > Players** page with a toggle swit

### a) Player descriptor

Create `/etc/hifiberry/players.d/<name>.json`:
Create `/usr/share/hifiberry/players.d/<name>.json`:

```json
{
Expand All @@ -125,7 +125,7 @@ Fields:

### b) Icon

Place an SVG icon at `/etc/hifiberry/players.d/icons/<icon>.svg`.
Place an SVG icon at `/usr/share/hifiberry/players.d/icons/<icon>.svg`.

The icon is served by the configurator API and displayed as a 40x40 image. Use `currentColor` for fill/stroke to match the UI theme.

Expand Down Expand Up @@ -240,22 +240,37 @@ Here is the full set of drop-in files needed for a player called "my-player":
| File | Purpose |
|------|---------|
| `/etc/audiocontrol/players.d/my-player.json` | ACR player config (audio routing + metadata) |
| `/etc/hifiberry/players.d/my-player.json` | Web UI descriptor (name, icon, service, optional settings) |
| `/etc/hifiberry/players.d/icons/my-player.svg` | SVG icon for the UI |
| `/usr/share/hifiberry/players.d/my-player.json` | Web UI descriptor (name, icon, service, optional settings) |
| `/usr/share/hifiberry/players.d/icons/my-player.svg` | SVG icon for the UI |
| `/etc/configserver/conf.d/my-player.json` | Systemd permissions for start/stop |

No code changes required — everything is pure drop-in.

**Ship the descriptor and icon under `/usr/share`, not `/etc`.** A descriptor

@hifiberry-codereview hifiberry-codereview Bot Sep 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 LOW: Section 5 still directs plugin authors to /etc, contradicting the new /usr/share guidance

The PR's stated purpose is to stop the guide from telling plugin authors to install the descriptor and icon into /etc/hifiberry/players.d. The new guidance at line 249 explicitly says "Ship the descriptor and icon under /usr/share, not /etc", and the table in section 6 now lists /usr/share paths. However, section 5 ("Register in the Web UI"), which is the primary step-by-step instructional section that authors follow, still reads: "Create /etc/hifiberry/players.d/.json" and "Place an SVG icon at /etc/hifiberry/players.d/icons/.svg". These lines were not changed in this diff.

How it fails: A third-party plugin author follows the guide top-to-bottom. At section 5 they create the descriptor at /etc/hifiberry/players.d/my-player.json and the icon at /etc/hifiberry/players.d/icons/my-player.svg, exactly as instructed. They then reach section 6 and see the table listing /usr/share paths plus the new paragraph saying "Ship the descriptor and icon under /usr/share, not /etc". The guide now contradicts itself: the step-by-step instructions say /etc, the summary and guidance say /usr/share. The author either ships to /etc (reproducing the exact conffile-staleness problem the PR is fixing) or is confused about which path is correct. The PR's stated goal of eliminating the stale /etc advice is not achieved for the section that actually instructs the author where to create the files.

Suggested fix: Update section 5's sub-sections (a) and (b) to use /usr/share/hifiberry/players.d/.json and /usr/share/hifiberry/players.d/icons/.svg, matching the table in section 6 and the new guidance paragraph. For example: "Create /usr/share/hifiberry/players.d/.json:" and "Place an SVG icon at /usr/share/hifiberry/players.d/icons/.svg."

stated-intent · confidence 75%

is package data, not configuration. Shipping it as a conffile in `/etc` means
dpkg treats any pre-existing file as a local edit and preserves it for ever,
so a device that once had one placed by hand never receives another packaged
update to it. configurator reads both directories and lets `/etc` shadow
`/usr/share`, so `/etc` remains available — but for an administrator who
genuinely wants to override or add a player, not for your package.

For the same reason, do not write the descriptor from your `postinst`. A file
your maintainer script rewrites on every configure shadows the one you ship,
silently destroys any override an administrator put there, and drifts from the
packaged copy without anything reporting it.

## 7) Example: Spotify/librespot as a community plugin

The `hifiberry-librespot` package is a real-world example of a native Debian package (no Docker) that registers itself using the drop-in mechanism. Its `postinst` creates three files on install:
The `hifiberry-librespot` package is a real-world example of a native Debian package (no Docker) that registers itself using the drop-in mechanism. It installs four files:

- `/etc/hifiberry/players.d/librespot.json` — UI descriptor (name: "Spotify", service: "librespot")
- `/etc/hifiberry/players.d/icons/librespot.svg` — Spotify icon (stroke-based SVG)
- `/etc/configserver/conf.d/librespot.json` — systemd permission (`"librespot": "all"`)
- `/etc/audiocontrol/players.d/librespot.json` — ACR player registration
- `/usr/share/hifiberry/players.d/librespot.json` — UI descriptor (name: "Spotify", service: "librespot"), shipped by the package
- `/usr/share/hifiberry/players.d/icons/librespot.svg` — Spotify icon (stroke-based SVG), shipped by the package
- `/etc/audiocontrol/players.d/librespot.json` — ACR player registration, shipped as a conffile so local edits survive upgrades
- `/etc/configserver/conf.d/librespot.json` — systemd permission (`"librespot": "all"`), written by `postinst`

Its `postrm` removes all four files on uninstall. The icon SVG is shipped inside the package at `/usr/share/hifiberry-librespot/icons/spotify.svg` and copied to the drop-in directory during `postinst`.
Only the last is created by a maintainer script; the rest are ordinary packaged
files. `postrm` removes the configserver drop-in on uninstall and the ACR
conffile on purge.

This pattern works for any Debian-packaged player — no Docker required.

Expand Down
Loading