PearTune

Almost everything falls into one of three buckets: the pairing code did not work, the library is not awake, or the phone and the library cannot reach each other on the network you are currently on. The sections below are in the order worth trying.

One question tells you a lot before you do anything else: does it work at home but not away, or does it not work anywhere? Those are different problems with different fixes.

Expected, and not a sign that anything is wrong with the download. The installers are not code-signed yet, which means your computer cannot confirm who published them and says so rather than staying quiet.

• Windows shows "Windows protected your PC". Click More info, then Run anyway.
• macOS says PearTune cannot be opened because the developer cannot be verified. Open System Settings, go to Privacy & Security, scroll to the bottom and click Open Anyway next to the note about PearTune. On older versions of macOS, Control-click the app and choose Open instead.
• An AppImage on Linux that does nothing when double-clicked has not been marked executable. Your file manager can set that in the file's properties.

Only override a warning like this for software you deliberately went and downloaded. Get the installers from the releases page and nowhere else. Signed builds are planned, and these prompts stop once they ship.

Pairing codes last a few minutes and are meant to be used once. If yours is refused:

• Show a fresh code on the dashboard and try again. An expired code is by far the most common cause.
• Only the newest code works. If the dashboard has been asked for a code more than once, the earlier ones stop working, so make sure you are scanning the one on screen now.
• Make sure the machine running the library is awake and connected while you pair. Pairing needs both ends online at the same moment.

If the code will not scan, raise the screen brightness on whatever is showing it and clean the phone's camera lens. Failing that, copy the pairing link shown under the code and send it to the phone by any means. Opening that link, or pasting it into the app, pairs without the camera.

This is the interesting one, and it usually is not the app. On your home wifi the phone and the library can find each other the easy way. From outside, they have to make a direct connection across two networks, and a small number of networks will not allow that.

Things worth checking, roughly in order:

• Is the library machine actually awake? A desktop or laptop that has gone to sleep looks exactly like a network problem from the phone's point of view. Check it first, because it costs nothing.
• Give it a moment. The first connection after being away can take several seconds while the two ends find each other. If it eventually connects, nothing is wrong.
• Is the relay switched off? In the app's settings there is an option that allows a fallback route for the rare networks where a direct connection cannot be made. If you have turned it off, some mobile networks will not connect at all. Turning it back on is the fix. It is explained in Privacy and peer to peer.
• Is the library running inside Docker? If so, and it works on your home network but never from outside, the container is almost certainly on Docker's default private network, which blocks the kind of connection PearTune needs. The server has to share the host machine's networking instead. This is the single most common server-side cause, and the setup guide covers the setting.
• Are you on a corporate, school or guest network? Some deliberately block traffic that is not ordinary web browsing. Try mobile data to tell that apart from a problem at home.

The app says which libraries it can currently see, and a library it cannot reach is greyed out rather than hidden, so you can tell "not available right now" from "no longer mine".

• Check the machine is on and connected.
• If you have several libraries and only one is unreachable, the problem is that machine and not your phone.
• If access was removed by whoever runs the library, it will not reconnect no matter what you do. Ask them to pair you again.

The library builds an index of your music so the app can browse it quickly, and files added since that index was built are not in it yet.

• Open the dashboard and rescan. New music appears in the app once the scan finishes.
• Missing artist or album names almost always mean missing tags in the files themselves, not a PearTune problem. Fix the tags and rescan.
• If the library reads from a media server such as Navidrome or Jellyfin, scan there first. PearTune shows what that server reports.

Track down whether it is the connection or the file.

• Does a downloaded album play? If offline music plays fine and streaming does not, the problem is the connection rather than the app or the file.
• Stuttering on mobile data usually means bandwidth. The app can send a smaller version of the track when you are not on wifi. Check the quality setting.
• One track fails and everything else is fine. That points at the file itself. Try playing it on the machine holding it.
• Playback stopped after a while and will not resume. If access was removed while you were listening, whatever had already been downloaded finishes and then playback stops. That is deliberate, so a network change does not cut a song off.

Make sure PearTune is installed first. A link tapped before the app exists has nothing to open it. Install the app, then tap the link again, or copy it and paste it into the app's "paste a link instead" box on the pairing screen.

Email peerloomllc@proton.me or open a GitHub issue. Include the phone model and version, what the library machine is, whether it fails at home or only away and what you have already tried.