lodesong

iPhone app

updated Nov 2, 2026

The player in its own app: your own icon, no browser bars, and music that keeps playing with the screen locked or the silent switch on. It's the same page the browser shows (the layout is already made for a phone), wrapped in apps/ios, like the Mac app.

You don't need a paid Apple developer account (the 99 USD a year one) to try it. There are four ways, from least to most effort:

what you needlastsbackground audio
1. Add to Home Screenjust Safariuntil you remove itworks, with the limits below
2. Sideload the IPAa free Apple ID, and a computer once7 days, then it refreshesyes
3. Build it in Xcodea Mac, Xcode and a free Apple ID7 days, then run it againyes
4. The simulatora Mac with Xcodeforeverno real lock screen

1. Add to Home Screen (no app at all)

Open your lodesong in Safari → Share → Add to Home Screen. It opens full screen with its own icon. iOS limits web apps: the silent switch can mute it, and iOS may stop audio when the screen has been locked for a while. That's what the app fixes.

2. Sideload the prebuilt app (free Apple ID)

Each release has lodesong-ios.ipa (also an artifact of the iOS workflow). It's unsigned: a sideloading tool signs it with your own free Apple ID.

  • Sideloadly (Mac or Windows): plug in the phone, drag the IPA in, enter your Apple ID, press Start.
  • AltStore or SideStore: install once, then add the IPA under My Apps, or better, add the lodesong source (below). They refresh it before the 7 days run out (AltStore while your computer is on the same Wi-Fi; SideStore needs no computer after setup).

Then: Settings → General → VPN & Device Management → trust your Apple ID. On iOS 16 and later also switch on Settings → Privacy & Security → Developer Mode (it asks to restart).

A free Apple ID allows 3 sideloaded apps at a time, and each one expires after 7 days; opening your sideloading tool renews it.

The AltStore / SideStore source (updates itself)

Every release also carries altstore.json, a source feed the release workflow generates from the IPA (apps/ios/altstore/source.sh). Add this URL in AltStore (Browse → Sources → +) or SideStore (Sources → +):

https://github.com/FindMalek/lodesong/releases/latest/download/altstore.json

lodesong then shows up under the source, installs from there, and each new release appears as an update. The feed points at that release's lodesong-ios.ipa, so it only changes when a release is made. Not yet checked in a real AltStore: the first release that carries altstore.json is the test.

3. Build it yourself in Xcode (free Apple ID)

brew install xcodegen
cd apps/ios && xcodegen generate && open Lodesong.xcodeproj

In Xcode: Lodesong target → Signing & Capabilities → Team: add your Apple ID (Xcode → Settings → Accounts) and pick the Personal Team. Change the bundle identifier to something unique to you (com.yourname.lodesong). Plug in the phone, choose it as the destination, press Run, then trust the developer on the phone as above. Run it again every 7 days.

4. The simulator

Same project, destination iPhone 16 (or any). Good for checking the layout and the first-run screen. It can't show the lock screen or the silent switch.

Using it

  1. On first launch it asks where your lodesong is: https://music.example.com, or an IP and port on your home network (192.168.1.20:8080). Away from home it needs a route to the server: your tunnel, or Tailscale on the phone.
  2. Sign in with your Navidrome account, as in the browser. The sign-in is kept in the app.
  3. Four quick taps on the sign-in page's background open a small menu: reload, or change server. If the server can't be reached, the app says so and offers the same.

What to check on your phone

This version was written and compiled without a phone in reach. The full step-by-step list, with what should happen and where to look when it doesn't, is the device checklist. The short version, in order: silent switch, screen lock, lock screen controls, AirPods, a call or alarm, then Wi-Fi off. The first three are where WebKit in a web view is most likely to behave differently from Safari.

How it works

  • PlayerController owns the web view and reports to the same bridge the Mac app uses (webkit.messageHandlers.keep): it takes the audio session when a song starts playing.
  • The audio session category is playback, which is what ignores the silent switch and allows background audio (UIBackgroundModes: audio).
  • After a call or alarm the app takes the audio session back and resumes if music was playing.
  • The lock screen controls come from WebKit's media session, from the page's own navigator.mediaSession, the same as in Safari and in the Mac app.
  • NSAllowsArbitraryLoadsInWebContent and local networking are allowed, so a server at http://192.168… works.

Later

A native Now Playing and remote-command layer, offline downloads and a share extension if the web view's lock screen turns out to be flaky. See the mobile app notes.

On this page