Skip to content

About

Local-first Android audio player prototype based on quietswitch/LocalTracklist. Upstream: https://github.com/quietswitch/LocalTracklist

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

63 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

LocalTracklist+

Private Android prototype developed from quietswitch/LocalTracklist. The original Git history, MIT license, package identity, local library, and Media3 playback architecture are retained. Original development credit belongs to quietswitch; this repository contains the LocalTracklist+ modifications.

Prototype Scope

The prototype adds a German-first Home, local search, live Radio Browser stations with electronic subgenres, a Radio Favorites tab, an openly licensed music catalog with offline playlists, and Bibliothek navigation with a shared mini-player. Albums, artists, playlists, favorites, folder import, and the full player reuse the upstream implementation. Implemented online sources: Radio Browser (streaming) and Internet Archive / Openverse (search, playlist selection, verified offline download). Only recordings with recording-specific, re-verified permission evidence can be downloaded; unknown and radio sources can never be downloaded. Existing upstream screens are not yet fully translated. See IMPLEMENTATION_STATUS.md for verification and limitations.

Listen To Music

  1. Open Radio and search for a station, for example Radio Paradise.
  2. Optionally filter by genre, country or language, then press the station's play button. The electronic row adds Minimal, Minimal Techno, Trance, Psytrance, Acid, Acid Techno, Techno, Hard Techno, Hardcore, Hardstyle, House, Deep House, Tech House and Drum & Bass.
  3. Use the heart to save a station. Bibliothek → Radio-Favoriten lists saved stations and works offline.
  4. Tap the mini-player for the LIVE player. Local music remains accessible in Bibliothek.

The first source supports direct HTTPS MP3, AAC/AAC+, Ogg/Vorbis/Opus and FLAC audio, subject to device codec support. HTTP-only stations and HLS/M3U/PLS playlists are deliberately excluded from this version. Search is bounded to 30 results. The most recent matching search is cached for up to 24 hours for network-failure fallback. Radio Browser receives station searches/filter values and a play-click request. Playing connects directly to the broadcaster. No account, analytics SDK, stream recording, download cache or radio entries in local listening history are added.

Search And Offline Playlists

  1. Open Suche. Local results appear on top; offene Musikkataloge below search Internet Archive, Openverse, Audius and ccMixter.
  2. Optionally restrict to one provider with the source chips. This is not a full commercial catalog: it contains openly licensed recordings, artist-published Audius tracks and verified previews.
  3. Press Zur Playlist hinzufügen, choose an existing or new playlist. Tracks are queued for download automatically.
  4. Bibliothek → Offline-Playlists shows durable per-track progress, retry/cancel, license and attribution.
  5. Ready tracks appear in the normal playlist and play from the local file only.

Downloads are foreground-independent WorkManager jobs capped at 25 MiB per track and 3 attempts. Every download re-checks the recording-specific license and publisher evidence before any audio byte is fetched. Files live in app-private storage; the media scanner never reconciles them away. Ordinary playlist reordering and removal stay authoritative, including mixed local/download playlists.

Per-source download rules:

Source Search Offline download
Internet Archive yes only the reviewed CC BY 4.0 album
Openverse (Freesound) yes publisher page verified per recording
Audius yes only when the artist enabled downloads and the track carries a CC licence
ccMixter yes CC0 / BY / BY-SA / BY-NC / BY-NC-SA (NC is shown in the attribution)
SomaFM radio directory, not song search never
Radio Browser radio directory never

Unverified results stay discovery-only and cannot be added.

Source Repositories

Project Relationship
LocalTracklist Actual source base; upstream history and license retained.
AndroidX / Media3 / Compose / Room Existing Android playback, UI, and persistence dependencies.
Radio Browser API Implemented station directory, search and stream resolution via its public HTTPS API.
OkHttp HTTPS API and streaming transport with URL/DNS/redirect restrictions.
NewPipeExtractor Planned optional metadata/external-open provider; not bundled or integrated. GPLv3 obligations must be reviewed before distribution if added.
Openverse API Implemented search metadata; downloads require independent publisher verification.
Internet Archive Implemented search, metadata and verified file download for reviewed CC-licensed recordings.
Audius Implemented search, streaming and licence-gated downloads via the public discovery API.
ccMixter Implemented search and CC-licensed downloads via its public query API.
SomaFM Implemented second radio directory using its public channel list and official .pls stream endpoints.
WorkManager Durable, network-constrained offline playlist downloads.

Planned catalog services: LibriVox API and an authenticated catalog (e.g. Jamendo tracks API, which requires a client_id). Implemented radio services: Radio Browser API documentation and SomaFM. Not implemented: Free Music Archive (public API retired), Musopen (no usable public API), and Bandcamp / SoundCloud / YouTube Music via NewPipeExtractor (see below). These links document provenance and plans, not an assertion that these services are implemented or endorse this project.

Why Bandcamp, SoundCloud and YouTube Music are not integrated

The table in the requirements lists these three via NewPipeExtractor. They are deliberately not included:

  • NewPipeExtractor bypasses the official interfaces of those services, and their terms restrict stream extraction.
  • YouTube Music downloads are explicitly not generally permitted.
  • NewPipeExtractor is GPLv3; linking it changes the licence obligations of this MIT-licensed repository.

If those sources are wanted, the defensible route is an official/partner API or opening the item in the provider's own app.

Upstream Documentation

Local music player for Android.

Publisher/developer: quietswitch.

LocalTracklist, formerly LibrePlayer, is the same application. Published v1.0.4 and v1.1.0 releases retain the LibrePlayer name; Android package identity remains com.libreplayer.

LocalTracklist is a free, open-source Android music player for audio files stored on the device. It is offline and local-first: playback, library data, playlists, favorites, settings, and history remain on the device.

Features

  • Incremental MediaStore library synchronization with optional Storage Access Framework folder import
  • Incremental rescans for additions, changes, and removals, plus an on-demand full library rebuild
  • Songs, albums, artists, playlists, favorites, and recently played
  • Search across songs, albums, and artists
  • Queue playback with shuffle and repeat
  • Background playback through a Media3 MediaSessionService
  • Lock-screen, notification, Bluetooth, and headset controls
  • Persistent queue and playback-position restoration
  • Local playlists stored with Room
  • Audio details, artwork, theme, sorting, metadata fallback, and rescan settings

Android Requirements

  • Android 8.0 (API 26) or newer
  • The project compiles and targets Android API 36
  • Android SDK Platform 36 and a Java 21 runtime available to Gradle are required to build the project

Permissions

LocalTracklist requests only the permissions needed for local playback:

  • READ_MEDIA_AUDIO: reads audio indexed by MediaStore on Android 13 and newer.
  • READ_EXTERNAL_STORAGE: reads local audio on Android 12L and older; the manifest limits this permission to API 32.
  • FOREGROUND_SERVICE: keeps active playback running in a foreground service.
  • FOREGROUND_SERVICE_MEDIA_PLAYBACK: identifies that foreground service as media playback on supported Android versions.
  • WAKE_LOCK: lets active playback continue reliably while the screen is off.

Folder import uses Android's system document picker, which grants access only to locations selected by the user. LocalTracklist does not request MANAGE_EXTERNAL_STORAGE or INTERNET.

Privacy

  • No ads, usage analytics, remote telemetry, crash reporting, or user accounts
  • No cloud sync
  • No media or metadata uploaded off-device
  • App backups are disabled
  • Library data, playlists, favorites, settings, and playback state are stored locally

Build and Verify on Windows

Prerequisites are Android Studio or the Android SDK command-line tools, Android SDK Platform 36, and a Java 21 runtime. Run these commands from the repository root in Windows PowerShell:

.\gradlew.bat testDebugUnitTest --console=plain
.\gradlew.bat lintDebug --console=plain
.\gradlew.bat assembleDebug --console=plain
.\gradlew.bat assembleRelease --console=plain
git diff --check

Build artifacts are written to:

  • Debug APK: app\build\outputs\apk\debug\app-debug.apk
  • Unsigned release APK: app\build\outputs\apk\release\app-release-unsigned.apk

To build and install the debug variant on a connected device or emulator:

.\gradlew.bat installDebug --console=plain

The release task intentionally produces an unsigned APK. A public release APK must be signed with a private release key before installation or distribution. Signing keys, passwords, aliases, and credential files must remain outside Git. See RELEASE.md for the release procedure.

Architecture

LocalTracklist is a single-module Kotlin application using Jetpack Compose, Material 3, Media3/ExoPlayer, Room, DataStore, coroutines, and Flow. Playback uses Media3 and the codecs available through the Android platform, so format support can vary by Android version and device.

Current Limitations

  • Album and artist artwork uses a deterministic representative track and may not be canonical.
  • Permission behavior and settings surfaces can vary between Android device manufacturers.
  • Folder import is available, but there is no dedicated folder-browsing library view.
  • The default MediaStore scan includes items marked as music with a duration of at least 30 seconds.
  • Codec and container support depends on the Android platform and device.
  • Streaming, remote libraries, lyrics, casting, and recommendations are outside the current scope.
  • Future Room schema changes require explicit migrations; the current database configuration can recreate local app data during an incompatible schema upgrade.
  • Automated coverage focuses on unit-tested logic rather than a broad instrumentation/UI suite.

Contributing

Issues and pull requests are welcome. Keep the app local-first, permissions minimal, and changes within the offline music-player scope. Add tests for pure logic where practical.

License

LocalTracklist is available under the MIT License. See LICENSE.

About

Local-first Android audio player prototype based on quietswitch/LocalTracklist. Upstream: https://github.com/quietswitch/LocalTracklist

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages