Amperfy talks to Ampache and Subsonic from one Swift codebase

One Swift codebase against two different server APIs

Amperfy is written in Swift and talks to a self-hosted music server over HTTP, targeting either Ampache or Subsonic. That dual support is a defining constraint of the project: two server types presented through one interface.

Self-hosted is the point. Nothing in the repository connects to a streaming service; the model is that your library is on a machine you run, and the app is a client for it. That is a different relationship with a music library from any subscription service, and it explains why offline mode is a headline feature rather than an afterthought. When the server is not reachable, the app still has something to play.

It is also Apple-only. The stated platforms are iOS, iPadOS and macOS, there is no Android target, and CarPlay and Siri integration are both listed features. The App Store listing covers iPhone and Mac through the same app id.

The project is GPL-3.0. For an end user installing from the App Store that has no practical effect; for anyone considering a fork or an embedded use in a product they distribute, it is the first constraint to evaluate.

Offline mode, multi-account and the sync model

The feature list is short and concrete: multi account, offline mode, CarPlay, gapless playback for appropriate media file formats, music, podcast and radio support, Siri play media command, Siri Shortcuts and App Intents, equalizer, replay gain, sleep timer, 5 star song rating, favorite song, and scrobbling.

Several of these depend on the server being reachable and several do not, and the split is what determines whether Amperfy works for you. Ratings and favorites are writes back to the server, scrobbling is a write, and playback can be either streamed or local. Offline mode is therefore the feature that reconciles the two: the library survives a server outage, and the writes queue or fail quietly until connectivity returns.

Gapless playback is qualified as applying to appropriate media file formats. That phrasing matters. Whether your tracks play gaplessly depends on what format your server is storing and streaming, not on anything Amperfy does.

Multi-account arrived in v2.1.0 on 2026-03-19, in a release titled for multi account, the Home tab, and a CarPlay and AppIntent rework. That release is the reason the release history reads the way it does: the big features land in a version bump, and the patch releases after them are fixes.

Building from source means Xcode 26 and a scheme, not a package manager

The requirements are stated in two words: Xcode 26, Swift 6. There is no Swift Package Manager entry point, no CocoaPods file and no Carthage setup described. The distribution route is an Xcode project.

Clone the repository and open it:

git clone https://github.com/BLeeEZ/amperfy.git
cd amperfy

Then open `Amperfy.xcodeproj` and build and run the "Amperfy" scheme. There is no command line build step in the README, and no CI badge to suggest the project is built headlessly anywhere.

The repository layout tells you how the code is organised. `Amperfy/` holds the application, `AmperfyKit/` holds a separate framework-style module, `AmperfyKitTests/` holds the tests, `BuildTools/` holds scripts including `applyFormat.sh`, `Design/` holds design assets, and there is a `Helper/` directory. The separation of `AmperfyKit` from `Amperfy` is what makes `AmperfyKitTests` runnable without launching the app, and it is why the contribution note points at the test suite rather than the app target.

`.gitmodules` at the root tells you some dependencies arrive as submodules, consistent with the attributions list.

CarPlay and Siri need entitlements you probably do not have

This is the most practical obstacle for a contributor, and the README addresses it directly.

Apple CarPlay and Siri support both require a developer certificate with granted access to `com.apple.developer.playable-content` and `com.apple.developer.siri`. If you are contributing and do not hold them, the README tells you what to do: clear all entries in `Amperfy/Amperfy.entitlements`.

That edit disables CarPlay and Siri, so it is a development-time workaround rather than a product decision. It also means the code paths guarded by those entitlements are exactly the ones a contributor without the entitlements cannot exercise, which is a real review gap for a project that lists both as features.

The project publishes beta releases through a GitHub issue rather than a TestFlight link: the README points to https://github.com/BLeeEZ/amperfy/issues/25 for information and for joining the public beta. So the pre-release channel is a conversation on an issue, not a self-service signup.

Running the tests reformats your code as a side effect

The contribution instructions contain a detail that will surprise you if you miss it. Pull requests are welcome, but you are asked to execute `AmperfyKitTests`, and running those tests triggers SwiftFormat to apply the Google Swift Style Guide, configured by the Google-SwiftFormat-Config repository.

So the test run is not read-only. It rewrites source files according to the project's `.swiftformat` configuration at the repository root, and it does so as part of executing tests rather than as a separate step. If you want the same formatting without running the suite, there is a script for that:

./BuildTools/applyFormat.sh

The practical advice for a first contribution is to run `./BuildTools/applyFormat.sh` before you commit, so the formatting change is a deliberate diff you have reviewed rather than something that appeared during your test run alongside genuine code changes.

The build also has a container definition at the top level alongside `CHANGELOG.md` and `LICENSE`, which is likely the CI path, although the README does not describe it.

Dependency licensing is MIT almost throughout, with one Apache exception

Amperfy itself is GPL-3.0, linked from the README as the Amperfy license, and copyright on bundled third-party libraries remains with their authors under their own terms.

The attributions section lists the dependencies and their licences, which is unusually complete for an app of this size. Alamofire, AudioStreaming, MarqueeLabel, NotificationBanner, ID3TagEditor, CoreDataMigrationRevised-Example, VYPlayIndicator, CallbackURLKit, DominantColors, AudioVisualizerKit and iOS-swiftUI-spotify-equalizer are all under MIT. swift-collections from Apple is the one exception, under Apache License 2.0.

Two of those entries describe the technical approach more than the licensing does.

Ifrit from Andrii Vynnychenko appears in the list and is MIT licensed. The README does not describe what it is used for.

Version 2.1.1 shipped in August, and the feature roadmap is version-shaped

The release history is short enough to read as a roadmap. v2.0.0 on 2025-11-10 brought Liquid Glass, an equalizer and replay gain. v2.1.0 on 2026-03-19 brought multi account, a Home tab, and the CarPlay and AppIntent rework. v2.1.1 on 2026-08-13 is titled for custom HTTP headers, autoplay and instant mix.

That last one is worth pausing on for anyone running a server behind a reverse proxy. Custom HTTP headers is a client-side feature for reaching servers that require an authentication header, and the README's feature list does not mention it at all; it exists only in the release title.

The repository is not archived and the last push was on 2026-08-13, the same date as v2.1.1. The release date and last-push date are both 2026-08-13. That is a gap worth weighing if you are deciding whether to fork: the code is complete and released, but it is not currently being changed.

Swift 6 and Xcode 26 as stated requirements is itself a maintenance signal in the other direction. Requiring the current toolchain means the app is kept current with Apple's platform, and it means a contributor cannot build with an older Xcode.

What Amperfy is not

Setting the boundaries plainly helps more than restating the feature list.

There is no Android or web client. If any member of your household is not on Apple hardware, this does not serve them, and no part of the architecture suggests that is coming.

There is no server component. Amperfy does not host a library, and the README does not document standing up an Ampache or Subsonic server. Whatever admin interface your server offers is what you use for library management; this app is a player and a client.

There is no documented headless or automated build in the README. Everything described happens in Xcode, and the CarPlay and Siri code cannot be exercised without Apple-granted entitlements. For an organisation that wants to build this in CI as part of a larger verification pipeline, that is a real constraint rather than a preference.

And the offline story is only as good as the server's format support. Gapless playback is documented as applying to appropriate media file formats, which means the storage format decision upstream determines an experience users attribute to the client.

Editorial conclusion

Amperfy is the right client if your music lives on an Ampache or Subsonic server you control and you use only Apple hardware, since multi-account, offline mode and gapless playback are all in scope and the App Store build is already there. It is the wrong choice on Android, and you should not fork it for an embedded or commercial product without reading GPL-3.0, which is why it is licensed that way. Before building, clear the entries in `Amperfy/Amperfy.entitlements` if you have no CarPlay and Siri entitlements, otherwise the CarPlay and Siri code paths will not run on your device.

Frequently asked questions

Official sources

1. BLeeEZ/amperfy on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases