PearTune

Only if you want to be the one hosting music. If a friend or someone in your family is already running a library and has let you in, skip this page entirely: install the app, scan the code they show you and you are listening.

You want a server if the music is on a machine of yours and you want to reach it from your phone wherever you are, or if you want to let other people into your collection without giving them a login or copying files to them.

Less than the word suggests. It is a small background program that sits on the machine your music is already on, and its job is to answer your phone, check whether that phone is allowed in and send over the music it asks for.

What it needs:

• To be on when you want to listen. That is the only real requirement. A machine that sleeps is a library that is unreachable while it sleeps.
• Your music files on it, or reachable from it. Wherever they already are is fine.
• An ordinary internet connection. Nothing special, and nothing configured on your router.

What it does not need: a fixed address, a domain name, a dynamic DNS service, an open port, a VPN or a PearTune account. If a guide anywhere tells you to forward a port to make this work, it is not describing PearTune.

People usually already own something that will do. In rough order of how little you will think about it afterwards:

• A home server appliance, such as an Umbrel or Start9 box. Built to stay on, quiet, and already where a lot of people keep their media.
• A NAS or any always-on Linux machine. If it already holds the music, it is the obvious candidate.
• A spare desktop or an old laptop. Perfectly good, as long as you stop it sleeping.
• Your everyday Mac or Windows PC. The quickest way to try PearTune out, because this is the case the installer is built for. The catch is that it has to be awake and on the network for you to listen, which is a real limitation on a laptop you carry around.

Music does not take much work to serve, so an old low-powered machine is fine. What matters far more than the processor is that it stays on.

Anything in that list with a desktop on it takes the installer below. Anything without one, which is most NAS boxes and appliances, takes the manual route.

Two ways, and neither one moves, renames or re-encodes a single file.

A folder. Give PearTune the folder your music is in and it reads the tags out of the files to build artists, albums and tracks. This is the simplest option and the one to pick if you are not already running anything.

A media server you already run. If you have Navidrome, Jellyfin or another Subsonic-compatible server, PearTune can read its library instead, so your existing artwork and organisation come along. You keep using it as you do now, and PearTune becomes another way to reach it.

You choose which of these on the dashboard after the server is running, and you can change your mind later.

There are two routes. Take the first unless something about your machine rules it out.

The installer, on a Mac, Windows PC or Linux desktop. Download it, run it, and that is the install finished. PearTune then lives quietly in the menu bar or system tray, starts itself when you log in, and gives you one menu with two items: open the dashboard, or quit. There is no window to leave open and no terminal at any point.

It starts out pointed at your computer's own Music folder, so if that is where your music already is, there is genuinely nothing left to configure. Downloads: the PearTune releases page, which carries a disk image for Mac (Apple silicon and Intel), an installer for Windows, and an AppImage or Debian package for Linux.

Your computer will warn you the first time, and it is right to. These builds are not code-signed yet. Signing means paying Apple and Microsoft for a certificate that vouches for who published the software, and PearTune has not done that yet. Nothing is wrong with the download, but your computer has no way to confirm that, so it says so. Here is what you will see and what to do:

• Windows. A blue "Windows protected your PC" box. Click More info, then Run anyway. If there is no More info link, the file is still downloading or was blocked by your browser.
• macOS. A message that 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 you can instead Control-click the app and choose Open.
• Linux. No warning of this kind. An AppImage needs to be marked executable before it will run, which your file manager offers in its properties, and the Debian package installs normally.

This is worth being blunt about rather than glossing over: you are being asked to override a security prompt, and you should only ever do that for software you went looking for and downloaded from a source you meant to. If you are not sure the download is genuine, get it from the releases page rather than from anywhere else, and remember the whole thing is open source if you want to read or build it yourself. Signed builds are the plan, and these warnings go away when they land.

The manual route, for a machine with no desktop on it. A NAS, a home server appliance, a headless box in a cupboard or anything you administer over SSH has no menu bar to put an icon in, so it runs the server directly instead. The commands live with the source code, where they are kept current rather than copied here to go stale:

• Running the host on Linux, which also covers home server appliances and anything that runs Docker.
• Running the host on macOS or Windows, for the times you want it running as a service rather than as a tray app.

One thing worth knowing if you take that route, because it is the single most common cause of "it works at home but not away from home": if you run it inside Docker, the container has to share the host machine's networking. Docker's default private network sits between PearTune and the internet in a way that stops your phone reaching it from outside the house. The guides above spell out the setting. The installer has nothing in the way, so this does not apply to it.

A one-click listing for home server appliance app stores is on the way too, so an Umbrel or Start9 box will install PearTune the same way it installs anything else.

Once it is running, the server has a small web page you open in a browser. That is where you point it at your music, give the library a name and manage who can reach it. With the installer, "Open dashboard" in the menu bar or tray takes you straight there.

Because that page can hand out access to your whole collection, it asks for a password whenever it can be reached from anywhere other than the machine it runs on. The installer keeps it to that machine only, so there is no password to set and none to type. If you set the server up manually and open the dashboard to your network, it will want one, and it makes a strong one for you on first run if you do not choose your own.

To add a device, yours or somebody else's, start a pairing on the dashboard. It shows a code to scan with the app, and a link you can send if the person is not in the room. Each pairing lasts a few minutes and then closes on its own.

Everyone you let in appears in a list as their own person, with their own devices under them. Removing someone, or one of their devices, takes effect immediately, even mid-song. Nobody has a password to change and nothing has to be re-secured afterwards, because there was never a shared secret to leak.

Worth doing deliberately rather than discovering it on a train. Once your phone is paired and playing at home, turn off wifi on the phone so it is on mobile data only, and play something. If it plays, you are done: that is the case the whole design exists for.

If it works at home but not on mobile data, that is a specific and fixable situation rather than a mystery. See Troubleshooting.

Email peerloomllc@proton.me or open a GitHub issue. Say what the machine is, what operating system it runs and whether you installed natively or with Docker.