Skip to content
TechPsychoticPublic

About

A free music app that builds its picks from what you play, right on your phone or computer. No sign-in, no ads, no servers of ours.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Harp logo

Harp

Website · Download · GPL-3.0

A music app that learns your taste on your own device. No account, no sign-in, no API keys and no servers of ours. For Android, iPhone, Linux, Windows and macOS.

Harp streams music from the web (through yt-dlp), plays your own files, and builds its recommendations from what you listen to, right on the device.

Website: https://techpsychotic.github.io/harp/ · Download: latest release

What it does

  • Listen: search songs, albums, artists and podcasts; Smart Shuffle and moods; charts and genres; new releases from artists you follow; your own music files; downloads for offline listening.
  • Sound: gapless playback or crossfade, equalizer presets and a 10-band equalizer, headphone correction for ~9,000 measured models (AutoEq), even volume (EBU R128), spatial modes, 3D audio (HRTF) that follows your head with AirPods on Linux, playback speed, sleep timer.
  • Lyrics: synced lyrics from several free sources, with Hindi, Urdu, Punjabi and other Indian scripts shown in English letters if you like.
  • Library: playlists with folders, pins, covers, sorting, Smart Shuffle and recommendations; liked songs, saved albums and podcasts, followed artists. Import from Spotify, Apple Music links, other public playlist links and playlist files; export as CSV, M3U or JSON; back up and restore.
  • Together: listen in sync with friends, sync your library between your own devices, and share playlists that stay up to date. All peer to peer over iroh.
  • Everywhere: notification and lock-screen controls, Android Auto, a home-screen widget, desktop media keys and a mini player.

Install

Download the latest release from Releases:

Platform File Notes
Android 9+ (64-bit) harp-android-arm64.apk Signed with Harp's release key. Allow installing from your browser or file manager.
iPhone / iPad (iOS 15+) harp-ios-unsigned.ipa Unsigned: you sign it with your own Apple ID when you install it. See below.
Linux (x64) harp-linux-x64.tar.gz Unpack and run harp, or use scripts/install-linux.sh for a menu entry.
Windows (x64) harp-windows-x64.zip Unzip and run harp.exe.
macOS harp-macos.zip Not notarized: right-click › Open the first time.

SHA256SUMS.txt in each release lists the files' checksums. Harp checks for new releases itself (Settings › About).

iPhone and iPad (no App Store)

Harp isn't on the App Store, and the .ipa isn't signed by a developer account. Install it with a tool that signs it with your own (free) Apple ID:

  • AltStore or SideStore: install the tool, then open harp-ios-unsigned.ipa with it. With a free Apple ID the app must be refreshed every 7 days; both tools do that in the background (SideStore without a computer). A free Apple ID allows 3 sideloaded apps at a time.
  • iLoader (Windows, Mac or Linux; tested with Harp): connect the iPhone by cable, sign in with your Apple ID and pick harp-ios-unsigned.ipa. Re-install every 7 days with a free Apple ID.
  • Sideloadly (Windows or Mac): connect the iPhone by cable, drag the .ipa in, sign in with your Apple ID. Re-install every 7 days with a free Apple ID.
  • TrollStore (only on the iOS versions it supports): installs the .ipa permanently, no re-signing.
  • LiveContainer (installed through SideStore): runs Harp inside one container app, so it doesn't count against a free Apple ID's limit of 3 apps. Add harp-ios-unsigned.ipa to LiveContainer.
  • Build it yourself (a Mac with Xcode): clone this repository, install Flutter and Rust (with rustup target add aarch64-apple-ios), run cd app && flutter build ios, then open app/ios/Runner.xcworkspace in Xcode, choose your Apple ID under Signing & Capabilities, connect the iPhone and press Run. With a free Apple ID, run it again from Xcode every 7 days.

After the first install, iOS asks you to trust your Apple ID: Settings › General › VPN & Device Management. On iOS 16+, also turn on Developer Mode (Settings › Privacy & Security).

On iOS, apps can't start other programs, so yt-dlp runs inside Harp itself: an embedded Python (app/python/) runs the official yt-dlp release, with iOS's built-in JavaScriptCore as its JavaScript runtime. Harp keeps yt-dlp up to date on the phone, as on every other platform.

Build from source

You need Flutter 3.47+, Rust (stable), and for Android the Android SDK and NDK.

cargo test --workspace                 # the Rust core
cd app && flutter test                 # the app
flutter build linux --release          # or: windows, macos
scripts/android-tools.sh && flutter build apk --release --target-platform android-arm64

scripts/ci-local.sh runs everything (tests, builds, APK checks) with a memory guard, for laptops.

How it's built

  • crates/harp-core: songs, queue, the taste model and recommender, playlists, library, backup, lyrics, transliteration (Rust).
  • crates/harp-ytdlp: yt-dlp, the music catalogue (search, artists, albums, radio), lyrics sources, AutoEq, imports.
  • crates/harp-party: listening together, device sync and shared playlists over iroh.
  • crates/harp-ffi: the bridge to the app (flutter_rust_bridge).
  • app/: the Flutter app; audio through mpv_audio_kit (libmpv + FFmpeg).

UPDATES.md is the changelog. The website lives in docs/ (GitHub Pages).

Contributing

Bug reports, ideas and pull requests are welcome: see CONTRIBUTING.md. Error codes (H-101 and so on) are explained in ERRORS.md. Security issues: see SECURITY.md.

Privacy

Your listening history, taste and library stay on your devices. Harp talks to its music source (search and streams), the lyrics sources, GitHub (yt-dlp, AutoEq, update checks) and, only when you use them, iroh's relays to reach your other devices or friends. There is no Harp account and no analytics.

Legal

Streaming through yt-dlp may go against the terms of service of the sites it fetches from, and Harp is not affiliated with any music service, Spotify or Apple. Harp is distributed here and for side-loading, not on Google Play or the App Store.

License

Harp is free software under the GNU General Public License v3.0 or later (see LICENSE).

It builds on: yt-dlp (Unlicense), Python (PSF), QuickJS (MIT), mpv_audio_kit (BSD-3-Clause) with libmpv (LGPL-2.1+) and FFmpeg (LGPL), iroh (MIT/Apache-2.0), flutter_rust_bridge (MIT/Apache-2.0), AutoEq data (MIT), SADIE II HRTF data (Apache-2.0, University of York), sofar (MIT/Apache-2.0), and the Flutter and Rust ecosystems (see each package's license). On Android arm64 the audio engine is a modified libmpv (LGPL; mpv_audio_kit's r23 build plus a processing hook for 3D audio), built from TechPsychotic/libmpv-scripts branch harp/r23.

Inspiration and thanks

Projects and work that shaped Harp, beyond the libraries it's built on:

  • yt-dlp: streaming, and its research into how the source's players work.
  • NewPipe Extractor: how a music catalogue is read without an account.
  • AutoEq: the measured headphone corrections behind headphone correction.
  • SADIE II (University of York): the measured head-related impulse responses behind 3D audio.
  • mousepods: its public notes on reading AirPods' motion sensors on Linux, which Harp's head tracking is written from.
  • iroh: peer-to-peer connections for listening together, device sync and shared playlists.
  • LRCLIB: free synced lyrics.
  • Better Lyrics and YouLy+: ideas for word-synced lyrics.
  • SwiftyTube: ideas for an iOS version without yt-dlp.
  • Equalizer314, Steam Audio and OpenAL-MOB: research for the sound work and the planned 3D (HRTF) mode.

About

A free music app that builds its picks from what you play, right on your phone or computer. No sign-in, no ads, no servers of ours.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages