Manager API

Manager API

The Manager is a web application the plugin serves on the player, on port 5582 unless the settings page moved it. Its page uses the routes below; so can anything else on the network: a script, a home automation system, a second page. There is no login, as with Volumio's own interface: the API is for the network the player is on.

Every route is under /api and answers JSON, except the page itself and the pictures and files it serves. Bodies are JSON with Content-Type: application/json, except the two uploads, which take a zip as the raw body. An error is { "error": "<code>", "message": "..." } with a 4xx or 5xx status; a code that starts with GLASS. is the key of one of the plugin's strings, which /api/i18n translates.

curl http://volumio.local:5582/api/status
curl -X POST -H 'Content-Type: application/json' -d '{"mode":"random","interval":60}' http://volumio.local:5582/api/meter

The page and its strings

Route	Answer
GET /	The page.
GET /api/i18n?lang=xx	{ "lang": "xx", "strings": { ... } }: the plugin's strings in that language, English behind them. Without lang, the player's language.

Status

Route	Answer
GET /api/status	The Status tab's data, below.

{
  "version": "0.7.5",
  "arch": "arm",
  "binary": true,
  "running": true,
  "display": "0",
  "headless": false,
  "timeout": 5,
  "activeTheme": "1280x720_g5_710_Turntables",
  "meter": { "theme": "...", "mode": "random", "names": [], "available": ["..."], "onTitle": false, "interval": 60 },
  "channel": { "clients": 1, "status": "play", "service": "mpd", "title": "...", "artist": "..." },
  "showing": { "theme": "1280x720_g5_710_Turntables", "meter": "142G5_01_Pioneer Gold" },
  "logging": { "level": "warn", "targets": [], "levels": ["error", "warn", "info", "verbose", "trace"], "targetsAvailable": ["audio", "channel", "display", "remotes", "themes", "artwork", "manager", "settings"] },
  "performance": { "profile": "auto", "auto": "standard", "values": { "frameRate": 30, "rotationQuality": "medium", "rotationFps": 8, "transitions": true }, "valuesProfile": "standard", "board": { "model": "Raspberry Pi 5 Model B Rev 1.1", "cores": 4, "arch": "aarch64", "class": "pi5" } },
  "measured": true,
  "remotes": { "enabled": true, "serving": true, "ports": { "frames": 5580, "channel": 5581, "beacon": 5579, "manager": 5582 }, "receiving": 1, "connected": 1, "problem": null },
  "manager": { "port": 5582, "url": "http://volumio.local:5582/", "uptimeS": 780 },
  "catalog": { "fetchedAt": "...", "updated": "...", "count": 179, "installed": 1 },
  "rings": [ { "name": "glasstap.glass.7297.0", "tag": "glass", "pid": 7297, "rate": 44100, "channels": 2, "seq": 12345, "writtenAgoMs": 19, "live": true } ],
  "diskFree": 932000000000,
  "hostname": "volumio",
  "legacy": false,
  "language": "en",
  "jobs": 0
}

Field	Meaning
binary	Whether the display binary for this player's processor is in place.
running	Whether the display is up (its run flag stands).
showing	The meter the player's own display shows at the moment, as it last reported it, or null.
display, headless	The X display chosen, and whether the player has no screen of its own.
measured	While the player reports play: whether a live ring exists, so what plays passes the tap.
rings	Every ring under /dev/shm, with its stream and how long ago it was written; live within three seconds.
remotes	Whether remotes are served, the ports, how many receive frames, how many are connected, any problem the daemon or the channel reported.
legacy	Whether PeppyMeter Screensaver is enabled.
jobs	Jobs still running.

Themes

Route	What it does
GET /api/themes	{ "active": "...", "meterBase": "...", "spectrumBase": "...", "themes": [ ... ] }. Each theme: folder, meters (the section names), spectrum (whether a spectrum twin exists), width, height, bytes, active, previews (none, stale, fresh, queued, rendering), catalog (the catalog entry it came from, or null).
POST /api/themes/:folder/activate	Puts the theme on show. { "ok": true, "active": "...", "changed": true }. 400 with invalid, not_found or no_config.
DELETE /api/themes/:folder	Removes the theme from both trees and its previews. { "ok": true, "switchedTo": "..." } names the theme put on show when the removed one was. The last theme is refused.
GET /api/themes/:folder/previews	{ "folder", "state", "meters": [ { "meter", "url", "thumb" } ] }: the rendered pictures and their addresses.
POST /api/themes/:folder/render	Draws the previews unless fresh. Body { "force": true } draws again, { "wait": true } answers when done, with the same answer as previews. 404 when the theme has no meters.txt; 500 render-failed with the reason.
GET /api/themes/:folder/preview/:meter	The rendered picture, PNG; ?thumb=1 the thumbnail. 404 until rendered.
GET /api/themes/:folder/files	The theme's files with checksums: { "folder", "files": [ { "path", "sha256", "bytes" } ], "spectrum": { "folder", "files": [ ... ] } } or "spectrum": null. What a remote display syncs from.
GET /api/themes/:folder/file?tree=templates&path=...	One file of the theme, from templates or templates_spectrum, only from inside the folder.

A folder name is one the display accepts: letters, digits, spaces, dots, underscores, brackets, plus and hyphens, starting with a letter or digit. Anything else is refused with bad-folder.

The meter selection

Route	What it does
GET /api/meter	{ "theme", "mode": "random" | "list" | "single", "names": [...], "available": [...], "onTitle": false, "interval": 60 }.
POST /api/meter	The same fields to set: mode, names (for list and single), onTitle, interval (15 to 1000 seconds). Answers with ok and the selection as set. The display moves to the new selection at once; a remote that follows the player follows it.

The catalog

Route	What it does
GET /api/catalog	{ "fetchedAt", "updated", "source", "error", "entries": [ ... ] }. Reads the index when none is kept. Each entry: name, kind (meters, spectrum, both), category, width, height, bytes, units (the folders the zip holds, with install, folder, from, kind, names), thumb (a route below, or null), preview (the collection's picture), state (absent, installed, update, present).
POST /api/catalog/refresh	Reads the index again; the same answer. 502 with the index's error when it could not be read.
GET /api/catalog/thumb/:name	The entry's thumbnail, cached for a day.
POST /api/catalog/install	{ "name": "..." } starts an install; 202 with { "ok": true, "job": { ... } }. 404 not-found for a name not in the index.

Uploads and jobs

Route	What it does
POST /api/upload?name=file.zip	The theme zip as the request body (or the name in an X-File-Name header). 202 with the job. 413 too-large above the limit, 400 empty or bad-name.
GET /api/jobs	{ "jobs": [ ... ] }, newest first, the last hundred.
GET /api/jobs/:id	One job.

A job:

{
  "id": 3, "kind": "install", "name": "1280x720_Reloop_RL7000",
  "state": "unpacking", "progress": { "done": 812000, "total": 1300000 },
  "folders": [ { "install": "templates", "folder": "1280x720_Reloop_RL7000", "kind": "meters", "files": 12, "bytes": 1300000, "names": ["..."] } ],
  "error": null, "startedAt": "...", "endedAt": null
}

kind	state in order
install, upload	queued, downloading (install only), checking, unpacking, rendering, then done or failed
upgrade, rollback	queued, downloading or staging, verifying, backing-up, applying, restarting, or failed

error on a failed job is { "error": "<code>", "message": "..." }: checksum, size, bad-theme, units-differ, network, and the like. Installs, uploads and upgrades run one at a time; a job waits in queued for its turn.

Artwork

Route	What it does
GET /api/artwork	{ "enabled", "keyMode": "personal" | "project", "personalKey", "interval", "order": "sequential" | "random", "transition": "none" | "fade" | "merge", "transitionMs", "unlimited", "maxImages" }.
POST /api/artwork	The same fields to set; answers with ok and the settings as set.
POST /api/artwork/clear-cache	Drops the cached fanart copies. { "ok": true }.

Settings the manager owns

Route	What it does
GET /api/settings	{ "themeTagRules": "...", "doNotDeleteThemes": false, "managerPort": 5582, "managerHost": "" }.
POST /api/settings	themeTagRules and doNotDeleteThemes to set. The port and address are set on the settings page.

Backups

Route	What it does
GET /api/backups	{ "backups": [ { "name", "created", "pluginVersion" } ] }, newest first.
POST /api/backups	{ "name": "..." } creates one; answers with the list. 400 with the plugin's backup codes when the name is bad or taken, or storage is short.
POST /api/backups/:name/restore	Restores it; { "ok": true }. 400 with the plugin's codes when the backup is damaged or from a newer version.
DELETE /api/backups/:name	Removes it; answers with the list.
GET /api/backups/:name/download	The backup as glass-backup-<name>.zip: manifest.json, config.json, peppymeter_config.txt, spectrum_config.txt.
POST /api/backups/upload?name=file.zip	The zip as the request body becomes a backup, named by its manifest or by the file, with a number when the name is taken; the four files may sit at the zip root or under one folder. { "ok": true, "name": "...", "backups": [ ... ] }. 400 bad-backup when the files are not all there, or with the plugin's codes when they do not parse; 413 when too large.

Upgrades

Route	What it does
GET /api/update	{ "current", "latest": { "version", "notes", "bytes", "sha256", "url", "publishedAt" }, "checkedAt", "available", "previous": { "version", "at", "bytes" }, "last": { "from", "to", "phase", "ok", "error", "at" } }. Reads GitHub when the last look is older than a day; with an error field when it could not, and the last known values.
POST /api/update/check	Reads the latest release now. 502 when GitHub could not be read.
POST /api/update/install	Upgrades to the latest release; 202 with the job. 400 up-to-date, 409 busy while an upgrade runs. The backend restarts a few seconds after the job reaches restarting; the job is gone with it, and GET /api/status answers with the new version once it is up.
POST /api/update/rollback	Puts the kept previous version back the same way. 400 no-previous.

Logging

Route	What it does
GET /api/logging	{ "level": "warn", "targets": [], "levels": [...], "targetsAvailable": [...] }.
POST /api/logging	level and targets to set; applied at once for the plugin, at the next start of the display and the daemon. Answers with the settings as set. The System tab's Logging panel uses these.
GET /api/logs?lines=300	{ "lines": [...], "total": n }: the last Glass lines from the player's journal, newest last, 20 to 3000. With download=1, the lines as a text file named after the player and the time. 500 journal when the journal could not be read.

Performance

Route	What it does
GET /api/performance	{ "profile": "auto", "auto": "standard", "values": { "frameRate", "rotationQuality", "rotationFps", "transitions" }, "valuesProfile": "standard", "board": { "model", "cores", "arch", "class" }, "profiles": { ... } }.
POST /api/performance	{ "profile": "auto" | "full" | "standard" | "light" | "minimal" | "custom" }: applies the profile's values to the meter configuration and the settings page, and the display starts again with them; custom only records the choice. Answers with changed and the same as the GET. 400 bad-profile.

Remote displays

Route	What it does
GET /api/remote/status	{ "ports": { "enabled", "frames", "channel", "beacon", "manager" }, "beacon": { ... as sent ... }, "serve": { "at", "port", "rate", "ring", "sent", "subscribers": [ { "address", "id", "name", "release", "sent", "since" } ] } or null, "serving", "errors": { "serve", "channel" }, "headless", "remotes": [ { "id", "name", "release", "screen", "page", "address", "since" } ] }.
GET /api/remote/settings	{ "enabled", "framesPort", "channelPort", "beaconPort", "managerPort" }.
POST /api/remote/settings	enabled, framesPort, channelPort, beaconPort to set; applied at once. 400 GLASS.MANAGER_RM_PORTS_INVALID or GLASS.MANAGER_RM_PORTS_CLASH. Answers with ok, changed and the settings as set.
GET /api/remote/config	What a remote syncs: version, release, theme, meter, files.meter and files.spectrum (the configuration texts), assets.fonts and assets.icons (name, sha256, bytes), webfonts (the web font files the configuration names).
GET /api/remote/asset/font/:name, GET /api/remote/asset/icon/:name	One of the plugin's fonts or format icons.
GET /api/remote/track-file?uri=...&name=...	One picture from the playing track's folder: uri as the player reports the track, name a plain file name with a picture extension. Only files inside that folder under /mnt, up to 32 MB. 404 not-found otherwise.

The Remotes page has the wire between the player and a remote, and the remote's own page API.

Errors

Status	When
400	A bad name, folder, meter or body; a refused change, with the reason in error.
404	No such theme, preview, entry, job, backup, asset or route.
409	An upgrade while one runs.
413	An upload above the limit.
500	A render that failed, or a cache that could not be cleared.
502	The catalog's index, a thumbnail or GitHub could not be read.