Start at the Manager's Status tab. Find a problem there asks what is wrong and runs the checks the Manager can run itself: is the player playing, is the display on the screen and did it die, does the audio tap head the sound path and is what plays measured, are the controls on and is there a panel to touch, whose is the screen and is it turned as the panel suggests, are remote displays served and receiving, did the display lower its frame rate, and glass-evo's own: is it installed and does it work with this Glass, does it hold the screen with a display started after its install and with its own binary, which module do the views and the look panel draw with, are the look and the picture chosen there, is a place set and its reading fresh, when does the clock come after a stop, does the look show the buttons, what does the player offer to browse, and did the last install go through or was it refused for the pair. It lists the likely causes first, then what is worth knowing, then what it checked and found right, each with a button to the tab where it is set; most of this page is those checks in words. When that does not settle it, Make a report under the findings captures the problem and builds the report to post; Reporting a problem has the steps.

The sheet below it says whether the display is up, which theme is on show, whether what plays is measured, which displays and remotes are connected, and the last problems Glass wrote to the journal. The System tab's Logging panel shows the last three hundred lines Glass wrote and downloads a thousand as a file for a report; set the level to Info or Verbose there first, reproduce, then download. Most questions end there. The Logging page has the levels and what each line means.

When asking for help, make a report there. For a quick question the sheet alone will do: "Copy as text" puts the whole sheet on the clipboard, with the findings of a diagnosis when one was run, or take a screenshot of the tab. The player's addresses stay hidden unless "Reveal addresses" is pressed first; a question about reaching the player from a phone is the one case that needs them.

They are for the player's own screen: how big the theme is drawn on it and where. The Face is a browser window looking at the same theme, and a browser window has no fixed size, so the Face always shows the whole theme sized to the window; there is nothing for an offset to act on. Expect the settings to work on the player and the Face to fill itself.

The settings page's Display section sends the "Fit to screen" switch when saved, so the switch turns the fit on as well as off. A release whose Display section did not send it read every save as off: the switch could turn the fit off but never on, and the toast said there was nothing to change; upgrade. The Manager's Display panel sets the fit on any release.

The install copies PeppyMeter Screensaver's themes and the four bundled ones into Glass's folder once, when Glass's theme folder is first made, so a theme removed from Glass's folder stays removed at the next upgrade; an install that copied them at every upgrade, without overwriting, brought a removed theme back while the old plugin's folder still held it. If the old plugin's folder still holds themes, the Manager's System tab says so and can wipe them.

The Status tab's Player line says "measured" or "not measured". Not measured means the source plays below the audio tap, so it is heard but not seen. This happens when a source's own player was started before the tap joined the sound path, or picked its device while the player's ALSA file was half written at boot.

The needles' response is the Meter section's: Smooth needle for inertia, Meter sensitivity for quiet material.

The display moves on only to a meter that is not the one on show and stays put when the rotation holds no other: a theme with one meter, or one meter chosen from the Meter section's list, with a change interval set, is not loaded again at every interval. On a release that loads it again, a visible reload, upgrade, or choose two meters or the longest interval.

The log names the reason, prefixed glass: or glass-launcher::

The previews on the Themes tab are rendered the theme alone; a release that rendered them with glass-evo's clock, date and bar of controls over the theme, on a player whose screen glass-evo held, left such previews behind. Upgrade Glass, then press Render missing previews on the Themes tab: the previews made by an earlier version are rendered again, the theme alone.

The Manager tells which pictures a preview render made whatever the log level; a release that could not with the log level below Info gave up with "the render produced no pictures", for every theme, whenever an upgrade made the previews stale. On it, set Logging to Info on the System tab and open the Themes tab again; the previews render.

Volumio names a track inside a cue sheet in its own way; the sheet's folder is the track's, on the player's screen and on remote displays alike, so back.jpg and the other pictures a theme reads from the album's folder show for CUE + FLAC and CUE + APE albums as for single files. A release that took such a track for a stream with no folder never showed them; upgrade.

A letter drawn as a grey block with a faint shape in it, the w of "The Show Must Go On" in a theme's bold title for one, is a fault of an earlier release's text rasteriser for a glyph standing at an exact quarter or half of a pixel; rare, and the same wherever the theme was drawn. Upgrade from the System tab.

The Meters-Reference has every key.

Glass repaints only what changed, so a still theme is nearly free. What costs is what moves: a large spectrum, records and reels, a fanart slideshow with fades.

GLASS_PROFILE in the display's environment prints where each frame's time goes; the Logging page has it.

• The Face or Anymote stood still after the player stopped. They show what the player's screen shows: the persist countdown after a stop or a pause, and then a banner saying the player is stopped or paused and the display has left the screen, until the player plays again; on a screen that is the display's own (glass-evo holding it, or a player with no kiosk), where the display stays on the screen, the banner says only that the player is stopped or paused. With glass-evo installed the pages show glass-evo's clock, date and controls themselves and there is no banner; if they show the theme alone, look at "The Face tab and Anymote show" on the Screen tab, and at the System tab for a glass-evo that needs updating.
• The Face showed a track as just begun after a reload. A page or a display that attaches mid-track starts at the player's position; a release that did not needs an upgrade.
• A waterfall fills with green when the player stops or pauses. In a look laid out for two channels that names only palette.left and palette.right, a release that took silence for a one-channel analyser wrote the silent rows across both sides in the one-channel palette's lowest colour, and one that took a mono recording the same way made its two sides one for as long as the track played. Upgrade Glass, and glass-evo for the player's own screen.

Find a problem has a symptom for them, "Browsing, search or the queue shows nothing or will not play". Its checks: whether glass-evo is installed and works with this Glass, whether the look shows the buttons the More sheet opens from, whether the display is connected to the player so a tap reaches it, which module the pages draw with, and what the player offers to browse, counted and named. The glass-evo wiki's Home page has the queue, browsing and search as they work; what looks wrong but is as meant:

• The Screen tab shows no rotation, pointer or touch controls. The kiosk holds the screen, running or on its way: the Touch Display plugin or the Display Configuration plugin is running or starting, the kiosk unit is running or enabled at boot, or an X server of the kiosk's is up; or no panel is connected. That is as it should be: the kiosk is the player's interface, and Glass runs as a screensaver over it. The controls apply only on a player with no kiosk at all, and the tab says which it is.
• The picture is portrait and cropped. With no kiosk the display draws in the panel's own orientation, and many panels are portrait by nature; X turned them for you before. Set the rotation on the Manager's Screen tab to the angle the Touch Display plugin used, which the tab suggests, and touch turns with it.
• Save on the Screen tab answers "bad request". One release read the face size of an unset key wrongly and refused every save of rotation or pointer. Upgrade from the System tab.
• The theme is turned on its side under the kiosk. A rotation kept for a panel the display draws on itself applies only where the display draws on the screen itself, not under X, where the X server makes the turn; a release that applied the same turn under X too, on top of the X server's, needs an upgrade.
• The kiosk did not come back after turning its plugin on. The display steps aside within two seconds of the kiosk's X server trying to start and starts the kiosk again if it failed in between; a release that could hold the screen while the X server tried to start needs an upgrade.
• Touches land in the wrong place, or on the wrong side. The panel's touch frame is not the picture's. On the Screen tab, under Touch, try the swap and mirror switches first; if the touches are off in a way those do not fix, calibrate on the screen: five targets, one touch each, and the display keeps the map.
• The screen showed the console when the player stopped. With the display drawing through KMS/DRM the screen is Glass's alone, so the display stays on it, the theme standing still once the player has stopped, and comes back by itself if it is ever gone; a release that left the screen to the console needs an upgrade.
• Nothing shows on a screen with no kiosk. The display logs "renderer ... on kmsdrm" when it opened the screen; GLASS_GRAB=/tmp/shown.png in the display's environment writes the picture as shown, after its first thirty frames, so it can be looked at from a terminal; GLASS_GRAB_AFTER=240 waits that many frames instead.

• "Use glass-evo on the screen" is not offered, and the tab says the player cannot draw on its screen without the kiosk. The Manager asks before a take whether the player's graphics can draw on the screen itself, and where they cannot it says what it found and turns nothing off. The reason is the system's own: a graphics library that will not load is named with the loader's words. The graphics libraries are the system's, not Glass's; the three faults seen so far and their cures are under Known system issues below, and Find a problem tells them apart and names the cure itself. The status sheet's Graphics row and Make a report carry the same.
• The kiosk is back and glass-evo is gone from the screen. The screen went back by itself, and the Screen tab says why: glass-evo could not start (the reason follows in brackets), its component was gone, or Glass was turned off. Fix the cause, then hand the screen over again.
• glass-evo will not take the screen, or lost it after a restart of the player: "kmsdrm not available". On a Raspberry Pi whose panel is on DSI (or any player with a second graphics card that has nothing connected), the display is told the card and does not search for it. A release that searched depended on the order the system listed its graphics cards in, which changes from one boot to the next, so the same player worked after one start and not after another, and a display on a player with no kiosk died at every start the same way. Upgrade Glass, and glass-evo, which carries the same in itself.
• The screen went black for a minute or more after "Use glass-evo on the screen", then the kiosk came back. glass-evo could not start on this screen. The kiosk has the screen back in about ten seconds, and a second try straight after is as quick as the first; a release whose three tries stood the screensaver's delay apart kept the screen black for a minute or more.
• The reason reads "SDL error: Can't load EGL/GL library on window creation". The display could not open the screen itself: a graphics library is not on the player, or the graphics driver refused the screen. The reason on the Screen tab goes on to say which: what Mesa reported, and a library the player lacks by name, with the line that installs it (sudo apt-get install -y libegl1 libgl1). Where the reason adds nothing, look at the kiosk's own X log, grep -n -E "glamor|eglGetDisplay|swrast" /var/log/Xorg.0.log: glamor initialized is a player whose graphics work; eglGetDisplay() failed and swrast is one where the kiosk itself draws without the GPU, and glass-evo, which draws through the same libraries, cannot start until the system is repaired. Where the reason names a libgallium that will not load, see Known system issues below: the Mesa packages are out of step with one another, and the cure is there. Upgrade Glass, hand the screen over once more, and read the reason again; Make a report on the Status tab carries the log with it.
• "This player has no screen glass-evo can draw on by itself." The player has neither a screen the kernel drives nor an X server installed. The kiosk stays the interface there.
• On x86 the theme is cut off or stands small under glass-evo, and "fit the theme to the screen" does nothing. One release brought up the X server for glass-evo with no window manager, so the window kept the theme's size. Upgrade, then give the screen back and hand it over again.
• The clock flashes and the bar comes up at every change of track. An out-of-date glass-evo takes the moment the player says "stop" between two tracks for the player standing still. Update glass-evo on the System tab.
• The clock cannot be made to fill the screen, or stops growing as its size goes up. A size you set is the size you get: the controls reach four times the look's own size, the clock fills the width at the size that takes, and past it runs over the screen's edges, which the likeness shows before you save. A glass-evo that keeps a margin and its glass's room about the clock whatever size is asked for, and never lets it be taller than half the picture, is out of date: update glass-evo and Glass on the System tab.
• glass-evo is "older than this Glass works with". Update it on the System tab; where no newer release is out yet, the tab says so.
• glass-evo will not be removed. It owns the screen: give the screen back to the kiosk first, on the Screen tab, then remove it on the System tab.
• glass-evo keeps dying and the screen went back. After three failed starts in a row the screen returns to the kiosk. Installing glass-evo again, or putting the kept version back, starts the count afresh; hand the screen over again after it.
• Find a problem says the kiosk service has failed, with glass-evo on the screen and nothing wrong. On a player whose image runs its own kiosk (x86), a release that left the kiosk's unit standing as failed on handing the screen to glass-evo had the diagnosis take that for the cause. Upgrade Glass; the finding goes at once, and the unit's state at the next take or restart.

Faults of the player's own system that Glass's checks bring to light. None is in Glass or glass-evo, and none is repaired by anything Glass does; Glass names them so they can be put right. They were found together on one player and are written up in the order they were cured there; a player may have one, or all three. Read the Screen tab's reason first: it says which.

What it looks like. glass-evo will not take the screen, or takes it and gives it back within seconds, the reason reading SDL error: Can't load EGL/GL library on window creation. The Screen tab's Graphics row and the status sheet say it in the loader's words:

EGL gave no display for /dev/dri/card0 (EGL_SUCCESS); the EGL vendor library libEGL_mesa.so.0
would not load: libgallium-24.2.8-1~bpo12+rpt4.so: cannot open shared object file: No such file or directory

and the kiosk's own X server draws in software (eglGetDisplay() failed in /var/log/Xorg.0.log). The kiosk still shows: it does not need the GPU. glass-evo draws through the same libraries and cannot start without them.

What it is. The system's Mesa packages are from two different builds. The EGL vendor library asks for a libgallium of the exact build it was packaged with (here rpt4), and the libgallium on the player is a later one (rpt5). Nothing above them reaches the GPU. Seen where the Touch Display plugin was installed on an earlier Volumio, bringing the Mesa packages of that day for its X server, and the player was then brought up through updates to an image whose libgallium had moved on. A fresh image does not have it.

See it for yourself, over SSH, and post the output as text when asking for help:

dpkg -l | grep -E "mesa|libgallium|libegl|libgbm" ; ls -l /usr/lib/*/libgallium*

Packages all at one build suffix and the file on disk at the same: fine. Packages at one and the file at another: this fault.

The cure. Bring the six Mesa packages up to the build the archive offers today, over SSH:

sudo apt-get update && sudo apt-get install --only-upgrade libegl-mesa0 libgbm1 libgl1-mesa-dri libglapi-mesa libglx-mesa0 mesa-libgallium

Read what apt says it will do before it does it: those six packages upgraded to one build, and nothing more. If it wants to remove anything, or install a long list of other packages, answer no and ask for help with its output as text. Then reboot, and Use glass-evo on the screen on the Screen tab. Run the check above afterwards: all at one build and glass-evo on the screen is the mark of a repair.

Two things that do not cure it, so you need not try them: uninstalling and reinstalling the Touch Display plugin leaves the Mesa packages as they are, since apt finds them installed already; and the factory reset works, but only because it replaces the whole system, which the one line above does without it. If apt itself refuses, see the Python entry below first.

What it looks like. glass-evo gives the screen back at once, the reason reading Permission denied (os error 13) on /dev/dri/card0, or Failed to get evdev touchscreen name; the kiosk draws in software. The user and the device permissions are all in order, and ls -l /dev/dri/ shows one card0 and no renderD128, where a working Pi 5 shows card0, card1, card2 and renderD128. lsmod | grep -E "v3d|vc4" shows vc4 with nobody using it and no v3d at all.

What it is. The one card0 is the DSI panel's own driver (drm-rp1-dsi), which the kernel brought up; the Pi 5's GPU driver, v3d, never loaded, so there is no render device and nothing above it reaches the GPU. Volumio's own boot file carries dtoverlay=vc4-kms-v3d under [pi5], but on this player, with the panel's overlay in userconfig.txt, that was not enough. Seen on a Pi 5 with the Raspberry Pi Touch Display 2 on DSI.

The cure. Keep a copy of the file, then add one line to /boot/userconfig.txt, directly above the panel's own dtoverlay= line, exactly as written:

sudo cp /boot/userconfig.txt /boot/userconfig.txt.bak
sudo nano /boot/userconfig.txt

dtoverlay=vc4-kms-v3d-pi5,cma-512

Change nothing else; a wrong line in a boot file and the player does not boot. Reboot, then ls -l /dev/dri/; lsmod | grep v3d: renderD128 in the list and a v3d line is the GPU up. The copy is the way back if the player does not return; on an NVMe system that means reaching the boot partition from another machine, so say so when asking for help before doing anything else.

What it looks like. Installing or reinstalling a plugin that brings system packages (the Touch Display plugin among them) fails at Installing necessary utilities with apt saying You might want to run 'apt --fix-broken install' and a list of Python packages depending on versions of one another that do not match. The plugin's own files were fine; the system would not take anything new, and the failed install's own cleanup then removes the kiosk's files and the user's graphics rights, which the next successful install puts back.

What it is. Python's own packages on the player are caught between two versions, half upgraded, and apt installs nothing until they agree. Seen on Volumio 4 where FusionDsp was installed first and a plugin needing Python was installed after it. Not Glass, not glass-evo, not the display.

The cure, over SSH, in this order:

sudo dpkg -i --force-overwrite /var/cache/apt/archives/libpython3.11-stdlib_3.11.2-6+deb12u8_armhf.deb
sudo apt install -f

The first line puts the stuck package in place from the copy apt already fetched; the second lets apt finish. If the first says the file does not exist, the version on your player differs from this example: ls /var/cache/apt/archives/libpython3.11* shows what is there, and the apt message names the version it wants. Then install the plugin that failed, and go back to the Mesa cure above if that is what brought you here.

Afterwards. With glass-evo on the screen the display's processor share drops from the kiosk's software drawing to a few percent; and a portrait panel shows the theme turned until the rotation is set on the Screen tab.

Find a problem has four symptoms of glass-evo's own: the clock, the date, the forecast or the picture wrong or missing on the screen; the look panel's likeness and the screen disagreeing; the forecast missing, stale or for the wrong place; browsing, search or the queue showing nothing or not playing. Their checks read the status sheet's glass-evo section and say, in words with a button to the tab:

The System tab upgrades Glass to the latest release and goes back to the kept version. The backend restarts a few seconds after the job says so; the page waits for the new version and reloads. A backup named before-<version> is written first and is on the Backups tab. If the player's backend does not come back within a minute, restart it from the command line:

sudo systemctl restart volumio

Restore a backup from the Backups tab, or remove the plugin and install it again. The themes and the backups are under /data/INTERNAL/glass/. The settings backups stay through an uninstall always; the themes stay when "Do not delete themes" is on and are removed when it is off.

Make a report on the Status tab, under Find a problem's findings, builds the report for you, whatever the checks said:

1. Start. Glass logs in full from here, and the display starts again so its own lines are full too. The log level goes back by itself: when the report is made, on Cancel, after ten minutes, and after a restart of the player in between, which is a fair way to reproduce a problem that shows at start.
2. Reproduce. Do what goes wrong. When it has happened, say in a line what you did and what you saw, and press the button.
3. The system log. The player's system log is sent to Volumio's log server through Volumio's own submitter, the one the player's dev page uses: the kernel's and the player's journal, with Glass's lines of those minutes in it, the configuration and the network details, passwords left out. Its link joins the report.
4. The report. Your words, the minutes it was reproduced in by the player's clock and the log level Glass wrote at in them, the log's link, what the checks found, and the status sheet as it stands, its glass-evo section with it; the addresses and the forecast's place stay hidden in it unless revealed.

Hand it over one of three ways. Open a GitHub issue at foonerd/glass for a defect: the issue opens with the report in it, and the report is on the clipboard too. Copy for the forum for a question or anything else, and paste it into a post on the community forum; a report longer than a post takes is cut at a line with a word that the file has the whole. Download the report saves the whole as a text file named by the player and the minute, for an attachment or a mail.

On a player with no way out to the internet the log cannot be sent: the report says so, and Download the system log gives the file to attach. The addresses in the status sheet stay hidden unless "Reveal addresses" is pressed; the system log itself carries the player's network details, as every Volumio log does.