Most self-hosters end up with two ways to reach their Audiobookshelf server: a fast local address at home, and a tunnel or VPN address for everywhere else. Before v2.1 you had to pick one and live with it.

SoundLeaf can now hold both and switch on its own.

The Local Address Is Much Faster

A local address on your own network is direct. Nothing relays it, nothing tunnels it, and it never leaves the building. Downloads are faster and playback starts sooner.

Your remote address, whether that’s a Cloudflare tunnel, a Tailscale IP or a reverse proxy on a public domain, has to work from anywhere, and pays for that in latency even when you’re sitting ten feet from the server.

Setting both means you get the fast one at home without doing anything, and the reliable one when you leave.

Setting It Up

Go to Settings → Networking.

1. Turn on automatic switching

Flip Automatic endpoint switching.

2. Name your home network

Under Home Network, set the WiFi name (SSID). Tap the wifi icon beside the field while you’re on that network and SoundLeaf fills it in.

3. Set your local server URL

Local server URL is the address that works on your own network, for example http://192.168.1.20:13378.

The address needs a scheme on the front. Write http://192.168.1.20:13378, not 192.168.1.20:13378. Unlike the login screen, this field does not guess one for you.

4. Add your away addresses

Under External URLs, add the addresses that work from outside. You can add more than one and drag to reorder them. SoundLeaf tries them in order.

More than one is useful if you have, say, a Tailscale address you’d prefer and a public tunnel as a fallback.

How SoundLeaf Picks

• On your home Wi-Fi, SoundLeaf checks the local address. If it answers and looks like an Audiobookshelf server, that becomes the active address.
• Anywhere else, it works down the external list until one answers.
• If nothing answers, it falls back to the address you originally logged in with.

The Current Endpoint row on the Networking screen shows which one is live right now, and tapping it gives you the server info so you can confirm you reached what you expected. A row reading “Not reachable, or not an Audiobookshelf server” means the address answered with something that wasn’t your server, which usually means a typo or a proxy in front of the wrong thing.

About the Location Permission

Detecting your home network needs location access, and this catches people out, so here’s the reason.

iOS treats the Wi-Fi network name as location data. An app cannot read the SSID at all without location permission, and it needs Precise Location specifically. Apple decides that, not SoundLeaf.

SoundLeaf reads the name, compares it to the one you set, and that’s the end of it. Nothing is stored off the device and no location is sent anywhere.

If you’d rather not grant it, leave automatic switching off and use a single address. Everything else works exactly the same.

Your Login Address Doesn’t Change

The address you logged in with stays as your identity for the account, which is why the screen shows it separately as Login server. Switching between home and away addresses does not sign you out, does not re-download your library, and does not affect your downloads.

Troubleshooting

It never switches to the local address

Check that Precise Location is granted, that the SSID matches exactly (they’re case sensitive and easy to mistype), and that the local URL includes http:// if the server is plain HTTP.

It switched to local and now nothing loads

The local address probably isn’t reachable from the network you’re on. Some routers block devices on a guest network from reaching the main one. Tap the Current Endpoint row to see what the probe found.

I’m on a VPN at home

A VPN can make your traffic leave the house and come back, so the local address may not be reachable even though you’re at home. Tailscale users generally want the Tailscale address in the external list and can skip the local address entirely, since Tailscale already routes directly on the same network. See the Tailscale guide.

My tunnel needs custom headers

Those are set once and apply to whichever address is active. See the Cloudflare Access guide.