13. Library

Deutsch

The library is a program in the home network, for example on the NAS. It holds all albums, tags, radio stations and covers. Every box fetches from there what it lacks – and without the library it plays what it has already. A box without a library works as before.

13.1 What changes for the box

• All boxes know the same tags. A tag that was linked on a box or in the library plays on every box.
• Albums come when they are needed. If a tag is placed on a box that does not have the album yet, the box fetches it. The LED changes green → aqua → blue meanwhile, and the box plays as soon as the first track is there.
• The progress belongs to the box. The same tag continues at another position in the nursery than in the kitchen.
• Nothing is lost without WLAN. What is changed on a box applies there at once and reaches the library as soon as the box reaches it again. If both change the same tag, the state of the library applies.
• The space on the SD card takes care of itself. If it gets short, the box deletes the files of the album that was not listened to for the longest time. The library still has it, and the box fetches it again when the tag is placed.

13.2 Connecting a box to the library

Role admin, tab "System", section "Library":

1. Enter the address of the library, e.g. https://nas:8866.
2. The first time, enter the bootstrap password. It was set when the library was installed.
3. "Save", then switch the box off and on.

After that the section shows "connected", and the box appears on the page of the library. What the box had before moves into the library; albums that exist there already are recognized and not created twice. "Not confirmed yet" counts the changes that the library has not taken over yet. "This box" shows the name of the box; "Rename" next to it gives it another one, e.g. "Nursery". The library shows it under this name.

A new box: the page of the library shows a line for it – tab "Boxes", section "Add a box", "Copy". Write Raspberry Pi OS Lite (64-bit) to the SD card of the new box with the Raspberry Pi Imager. In the Imager, give the box a hostname of its own, e.g. kitchen; the page of the box is then https://kitchen.local. Log in over SSH and run the line there. It asks for the password of the user admin of the page of the new box and for the bootstrap password, sets everything up and restarts the box once. Afterwards the box is connected and appears in the tab "Boxes" by itself. A box without a library is set up the same way, but with a different line, from GitHub (curl -fsSL https://github.com/tgd1975/tinyjukebox/releases/latest/download/install.sh | sudo bash).

Unlinking: "Unlink from the library" in the same section. The box keeps everything on its SD card – tags, albums, stations, progress – and works on its own afterwards. The library is not asked; it may be switched off or not exist any more. Before that the page says what is lost: changes that the library has not taken over yet never reach it, and albums that are not completely on the SD card cannot be fetched any more. With "Cancel" you wait until the box has delivered and fetched. The library keeps showing the box until it is removed there (tab "Boxes"). Linking again works like the first time, with the address and the bootstrap password.

13.3 The page of the library

The page of the library looks like the one of a box, without "Now" and "Bluetooth". It has users of its own: who can log in to a box cannot do so there automatically; an admin of the library creates the users in its tab "System". Albums, tags, stations and covers are managed there as in sections 7 to 9.

In the tab "Albums" an album is marked "broken" if one of its MP3 files is damaged: because the library cannot read the file or because a box found errors in it while playing. The album dialog names the files. If the file is replaced, the mark disappears. If the file is fine and the report of a box was wrong, an administrator removes the report there with "Discard reports".

Only the library has these tabs; its tab "Statistics" covers all boxes:

Tab	Content
Boxes	all boxes with version, last contact and address – for a box a link to its page. Rename, remove (e.g. after a lost SD card), take over the progress of an old box to a newly set up one. Albums that are being uploaded from a box. For administrators: change the bootstrap password, create a token for scripts, check the files of albums and covers.
Versions	the versions of the box software. Old versions that are not in the archive any more and that no box runs are left out, as long as "hide old versions that are not in the archive" is ticked; the page says how many. use: boxes install them by themselves. manual: by hand only. dontuse: every box leaves it at once. "Runs on" names the boxes a version runs on and the library itself, "Prepared on" the boxes that have fetched it already and try it the next time they are switched on. Below the table it is set how many versions the library keeps at most (5 at first); what a box still needs always stays. "Access to the releases" says where new versions come from; the token with which the library may fetch them is saved there. On GitHub a fine-grained token for this one repository with the right "Contents: Read-only" is enough.
Statistics	the same as the tab "Statistics" of a box (section 6.3). With several boxes "All boxes" or one of them is chosen at the top. "All boxes" sums per tag, radio station, skipped track and version and names for every tag on which box it played for how long; a table of the boxes shows listening time and when a tag was placed last, a click on a box chooses it. The days are never summed: every box has its own row with its own hours.
Log	the messages of the library, live, also as a file – or what a box delivered of its log: its warnings and errors and how the start of a radio station went, for 30 days. Filters for level, part, version, code, time and text; "Copy" and "Save as file". A box that cannot start is marked in the choice and in the tab "Boxes"; its log shows at the top why. Administrators only.

13.4 Version of the box

A box that is set up for it fetches new versions from the library by itself and tries them the next time it is switched on. If the new version does not work, the previous one runs again after a few seconds. Tab "System", section "Version" (role admin):

Button	Effect
Look for a new version	shows what is installed and what the library offers
Update now	fetches the newest version and restarts the box
Updates: off, by hand only, automatic	whether the box installs new versions by itself. "Off": it does not even look. On a box without a library "by hand only" is called "ask".
Back to the previous version	at once, even if something is playing. No box installs the version that was left by itself any more.
Start emergency mode	for the case that no other version runs: the box plays nothing, installs the newest version it has not gone back from and starts it. With updates "off" or "by hand only" it waits for an administrator.
Keep A as emergency version, Keep B as emergency version	the proven version of slot A or B becomes the emergency version, with which the box asks for versions in emergency mode. The button names the version and works only if it is proven and not the emergency version already

Emergency mode. If neither version of the box runs, the box switches to emergency mode by itself. It plays nothing and shows no page; every 10 minutes it looks for a version it can install. An administrator ends it on the console: tinyjukebox-slot update --now installs a version and starts it, tinyjukebox-slot use a|b switches to one of the two versions. tinyjukebox-slot status says why the box is in emergency mode.

Data left out. If the box finds a damaged entry, or one that a newer version wrote and this version does not know, it works without it and lists it in the section "Version" under "Data left out". Nothing of it is deleted. In the library the tab "Boxes" shows such a box with a note.

If the LED changes between red, white, magenta and yellow, the library is too old for the version of the box. The box plays nothing then. Remedy: update the library, "Back to the previous version" on the box, or unlink the box from the library (section 13.2).

A box without a library fetches new versions itself: once a day it looks at GitHub whether there is a new release. "Source" in the section "Version" says where the versions come from. As long as a box is linked to a library, nothing comes from GitHub.

• The box does not install a new release at once, but after a waiting time of three days: if a correction follows in that time, it downloads only that one. Under "New" the section shows the version and the day on which it is installed by itself. "Install now" does not wait.
• The installation runs in the background; the new version starts the next time the box is switched on.
• With "Updates: ask" the box downloads nothing by itself. It shows administrators "Version … is available" at the top of every page until somebody answers: "Install", or "Skip" – then it asks again only for the next release. "What is new" shows what has changed. With "off" the box does not ask GitHub at all.
• With its request GitHub learns the address of the household and nothing else: no name, no version, nothing of what was listened to.

13.5 Scanning new tags with the phone

An Android phone with NFC can read a tag. This is how a new tag gets into the library without being placed on a box.

1. On the phone, open the page of the library in Chrome and log in.
2. Tab "Tag management", at the bottom at "Create a new tag": "Scan tag". The first time Chrome asks whether the page may use NFC.
3. Hold the tag to the back of the phone. The page shows the tag with its UID; a new one is marked "new" and is added to the library already.
4. As admin, enter the name right there, choose the album or the station. This is also possible later in the table above, on any device.
5. Simply hold further tags to the phone one after the other. "Stop scanning" ends it.

If the phone or its browser cannot read tags, the page says why when "Scan tag" is tapped. It does not work on an iPhone.

If the page reports that Chrome does not allow it to use NFC, the question of Chrome was answered with "Block", or NFC is switched off for websites in Chrome. To allow it: tap the symbol to the left of the address, then "Permissions" and "NFC devices". If the entry is missing there: Chrome menu, "Settings", "Site settings", "NFC devices" – the switch must be on, and the page of the library must not be listed under "Blocked".

• The boxes know the new tag shortly afterwards.
• Nothing changes by itself on other open pages; the new tag is in the tab "Tag management" as soon as it is opened.
• Every logged-in user may scan, only the role admin may link.
• The tag is only read. Nothing is ever written to a tag.
• Only Chrome on an Android phone and the app (section 13.7) can read tags. The button is missing on the PC. The phone must be unlocked and the page in the foreground.

13.6 Backups of the library

The library has the same card "Backup" in the tab "System" as a box (section 11.1). Its backup contains the catalog, the progress and settings of all boxes, the statistics and the covers of albums and stations, and the albums if wanted.

In addition the library backs itself up, under "Back up regularly" (section 11.2):

• The folders are folders on the NAS, e.g. /volume1/tinyjukebox/backups. Empty: the given folder backups in the shared folder tinyjukebox. The library must be allowed to write to the folder.
• Every backup with MP3s takes as much space again as all albums.
• A backup is put back as on a box (section 11.3). The boxes take over the catalog of the backup at their next synchronization.

13.7 The app: a phone as a box

The app for Android phones and tablets makes a phone a box: hold a tag to its back and the album plays, from where it stopped – on this phone. It brings the page of the library along as well ("Expert").

Installing. On the page of the library, tab "Boxes", section "Add a phone": open the link to the app on the phone, or point the camera of the phone at its QR code. The browser warns once about the certificate of the library, and Android asks once whether the browser may install apps. A new version is installed the same way, over the old one.

Pairing. The app first shows "Pair with the library". On the page, tab "Boxes", "Add a phone": "Pair" (as admin). A QR code appears, valid once and for 10 minutes. In the app: "Scan QR code" and point the camera at it. The phone must be in the home network. Afterwards it is in the table of the boxes, as a phone, named after its model – "Rename" gives it a name ("Anna's phone").

Listening (simple mode). The screen is the box:

• Hold a tag to the back of the phone: its album plays, from where it stopped on this phone. Take the tag away: stop. Each phone has its own progress, as each box has.
• Below are the tags as tiles: tap one instead of a tag; tap it again to stop.
• The band at the top shows the light of the box (section 3): green ready, blue playing, white/blue pause, green → aqua → blue the album is being loaded, yellow tag without an album.
• Buttons: back (hold: album from the beginning), play/pause, next – also on a headset and the lock screen, but holding "back" works only in the app itself.
• The screen stays on and goes dark after 30 seconds; a touch brings it back. If the screen goes off anyway, the music plays on; switched on again, the app looks for the tag for 2 seconds and stops if it is gone.
• Albums are loaded the first time they are played and stay on the phone (at most 4 GB at first). At the grandparents', what was played at home plays without the library.
• Volume: the keys of the phone. On the page of the library, at the phone in the tab "Boxes", "Volume" sets the most the app plays with, for speaker and headphones.
• A tag of Spotify plays in the Spotify app of the phone, from where it stopped. This needs the app registered at Spotify once and the Spotify app on the phone, logged in with an account entered there; the tab "Spotify" of the library says how. Otherwise the app says that the tag plays on a box.

Expert. The button "Expert" asks for the login of the page and then shows the page of the library, as in the browser; "Scan tag" in "Tag management" uses the NFC of the phone. "App settings" shows the name, the albums on the phone and their limit, the versions, and "Unpair". "Log out" – also after 30 minutes without a touch – and "Simple mode" lead back to the box, so a child does not stay on the page.

Tips. To keep a child in the app, pin it with the screen pinning of Android (settings of the phone, "Security"). A lost phone: remove it on the page, tab "Boxes" – its key is invalid then. Deleting the data of the app or installing it anew makes a new phone; "Take over an old box" brings back its progress.