Le dépannage

Huit pannes courantes : ce que tu vois, pourquoi, et quoi faire. Dans les exemples, l'écran a pour adresse 192.168.1.50.

« Aucun jeton »

Ce que tu vois: La carte de musique affiche « aucun jeton » plutôt qu'un morceau.
La cause: MUSIC_ASSISTANT_JETON est vide : depuis la 2.10, Music Assistant refuse tout accès anonyme.
Le remède: Tire un jeton et pose-le dans /etc/ecran-atelier.env : chapitre Installer l'écran, étape 5.

Ce que tu vois: Le journal de ecran-agent répète no route to host, alors que l'écran répond depuis un terminal.
La cause: macOS n'a pas encore accordé l'accès au réseau local à ecran-agent, lancé par launchd sans les droits de ton Terminal.
Le remède: Vérifie l'écran depuis un terminal (nc -vz 192.168.1.50 8098) : s'il répond, autorise ecran-agent dans Réglages Système → Confidentialité et sécurité → Réseau local. Détails : chapitre Installer le Mac, étape 6.

Ce que tu vois: ~/Library/Logs/ecran-agent.log reste vide, ou vieux : le LaunchAgent semble ne jamais démarrer, sans aucun message d'erreur visible.
La cause: ecran-agent n'est pas signé par un Developer ID : s'il porte encore la marque de quarantaine, macOS refuse de le lancer, sans fenêtre à cliquer puisque launchd n'a pas d'écran.
Le remède: Retire la marque sur le binaire installé, pas sur le fichier téléchargé : xattr -d com.apple.quarantine ~/bin/ecran-agent, puis relance le service. Détails : chapitre Installer le Mac, étape 3.

Ce que tu vois: La barre de progression du morceau est en avance, en retard, ou saute : elle ne suit pas ce que tu entends.
La cause: L'écran calcule cette position depuis l'instant où Music Assistant l'a notée : sur une horloge fausse, faute de synchronisation NTP, le calcul l'est aussi.
Le remède: Installe systemd-timesyncd et vérifie timedatectl : chapitre Installer l'écran, étape 8.

Ce que tu vois: La pastille de ta machine se vide, ses touches s'éteignent, et elle dit « injoignable depuis N min » — ou « jamais connectée » si elle ne s'est encore jamais montrée.
La cause: La connexion TCP entre ecran-agent et l'écran est coupée : Mac endormi, Wi-Fi perdu, service arrêté — ou un jeton qui ne correspond plus, auquel cas la pastille dit « refusée : jeton refusé ».
Le remède: Vérifie que ecran-agent tourne et son journal (chapitre Installer le Mac), et que son jeton correspond mot pour mot à celui de JETONS_MACHINES sur l'écran. La musique et l'heure continuent, eux, sans interruption : seules les touches de cette machine se taisent.

Ce que tu vois: « visualiseur absent de Music Assistant », ou « jeton refusé par le visualiseur », à la place du spectre : le reste de la musique fonctionne.
La cause: Le premier message veut dire que le relais de visualisation MilkDrop de Music Assistant n'est pas actif ; le second, que le jeton que l'écran lui présente est refusé — même famille de panne que « aucun jeton ».
Le remède: Active le relais MilkDrop dans Music Assistant ; si c'est le jeton, régénère-le comme au chapitre Installer l'écran.

Ce que tu vois: Une touche s'affiche avec son libellé seul, sans icône — la config n'est pas refusée pour autant.
La cause: Le chemin PNG de icone ne mène à rien, ou à un fichier que ta machine ne sait pas convertir. Ce n'est vérifié qu'au démarrage et à chaque relecture de config.json, pas à sa lecture elle-même : le journal dit alors <id> : pas d'icône, libellé seul.
Le remède: Vérifie le chemin (absolu, voir Créer ses touches) et le fichier, ou reviens à un emoji.

Ce que tu vois: Rien sur l'écran : ta machine n'apparaît jamais, pas même « jamais connectée ». Le seul indice est dans ~/Library/Logs/ecran-agent.log.
La cause: config.json est lisible par d'autres que toi : comme ssh, le service refuse de démarrer avant même de lire l'écran ou le jeton, donc rien ne part vers l'écran pour dire pourquoi.
Le remède: chmod 600 ~/Library/Application\ Support/ecran-agent/config.json, puis relance le service.