Skip to content

feat: Add local music library browsing and playback#2890

Open
alltechdev wants to merge 11 commits intomainfrom
feature/local-music
Open

feat: Add local music library browsing and playback#2890
alltechdev wants to merge 11 commits intomainfrom
feature/local-music

Conversation

@alltechdev
Copy link
Contributor

@alltechdev alltechdev commented Feb 16, 2026

Problem

Users cannot browse or play local audio files (mp3, m4a, flac, ogg, etc.) stored on their device. The app only supports streaming from YouTube Music.

Cause

The app lacked integration with Android's MediaStore to scan and index local audio files, and had no UI for browsing local music.

Solution

  • Added LOCAL tab in Library to browse local artists → albums → songs
  • Integrated with MediaStore to scan device for audio files
  • Reused existing SongEntity.isLocal and downloadUri fields for playback
  • Added permission handling for READ_MEDIA_AUDIO (Android 13+) / READ_EXTERNAL_STORAGE
  • Adapted menus to hide YouTube-specific options for local songs (download, share, radio, refetch)
  • Added long-press menu support for local albums
  • Local songs can be mixed with online songs in playlists
  • Added search within local music library

Testing

Important: Back up your database before testing. This build adds local music entries to the database. Reverting to the official release after testing would require clearing app data.

  • Granted audio permission when prompted
  • Browsed local artists, albums, songs
  • Played local songs (single, queue, shuffle)
  • Long-pressed albums/songs for context menu
  • Added local songs to playlists alongside online songs
  • Verified online music playback still works normally

@alltechdev
feat(library): add local music browsing and playback
3516e62 
Browse and play local audio files from device storage.
- Scan MediaStore for local audio files
- Navigate: Library → Local box → Artists → Albums → Songs
- Support all audio formats via DefaultExtractorsFactory
- TopAppBar with back navigation
- Scroll-to-top support
- Pull-to-refresh to resync
- Search and sort options

Not ready, just saving progress, feel free to check it out though
@alltechdev
fix(local): remove redundant filter chip from LocalMusicScreen
e8a6c2c 
TopAppBar with back button handles navigation, filter chip was redundant.
@alltechdev
fix(local): improve local song menu and details handling
f6552f3 
- Show local file info in details dialog instead of fetching from YouTube
- Hide download option for local songs (already on device)
- Hide start radio option for local songs (requires YouTube)
- Hide share option for local songs in queue menu
- Use storage icon for Local box in library
@alltechdev
fix(local): hide add/remove from library for local songs
78a21a1 
Local songs are always in the library since they exist on the device.
The option doesn't make functional sense as they would reappear after
the next MediaStore sync anyway.
@alltechdev
fix(local): hide song count while loading artist data
6de4826 
Hide the song count text in LocalArtistScreen header until data loads
from database, avoiding the "0 songs" flash during initial load.
@alltechdev
feat(local): add long-press menu support for local albums
6d9f1ca 
- Add combinedClickable with onLongClick for albums in LocalArtistScreen
- Update AlbumMenu to handle local albums properly:
  - Hide share option (no YouTube URL for local albums)
  - Hide download option (already on device)
  - Hide refetch option (no YouTube data to refresh)
  - Navigate to local_artist route for local album artists

Playlists already support mixing local and online songs since they
just store song IDs in the database.
@alltechdev
fix(local): show loading indicator for song count in artist screen
769a34a 
Display a small CircularProgressIndicator while songs are loading
instead of showing nothing or "0 songs".
@alltechdev
fix(local): auto-focus search field when opening search
ed96dcf 
Add FocusRequester to automatically focus the search text field
and show keyboard when search is toggled on in LocalMusicScreen.
@alltechdev
feat(local): Add full search to match online
f693c1e
@alltechdev
feat(listen-together): Block local file playback during Listen Together
1a1d7c3 
- Filter out local files from queue when creating/joining rooms
- Block local playback in MusicService, screens, and menus
- Hide Listen Together option when playing local files
- Fix local file playback when seeking (use downloadUri regardless of position)
- Dismiss mini player when timeline is cleared
@hydrogenicMetallium
Copy link

hydrogenicMetallium commented Feb 17, 2026

Awesome to see this added
Would it be possible to add in sorting by folder by any chance?
Cause as of right now, since I have a lot of songs, it got immediately populated with a lot of artists names and it can be very confusing to add in albums when there are a lot of names to go through so yea, the ability to view which songs are in what folder would be nice

@alltechdev
Copy link
Contributor Author

alltechdev commented Feb 17, 2026

Awesome to see this added Would it be possible to add in sorting by folder by any chance? Cause as of right now, since I have a lot of songs, it got immediately populated with a lot of artists names and it can be very confusing to add in albums when there are a lot of names to go through so yea, the ability to view which songs are in what folder would be nice

Can you explain a bit more please?

@hydrogenicMetallium
Copy link

hydrogenicMetallium commented Feb 17, 2026

Awesome to see this added Would it be possible to add in sorting by folder by any chance? Cause as of right now, since I have a lot of songs, it got immediately populated with a lot of artists names and it can be very confusing to add in albums when there are a lot of names to go through so yea, the ability to view which songs are in what folder would be nice

Can you explain a bit more please?

Look at the images below, this is what I mean
These screenshots come from Outertune
I'm here, the way they handle local files is by organizing them in the folders the songs are in.
An example would be if I wanted to add in a specific album to my playlist but didn't want to dig through all the folders I have my music stored in, with the folder setup, I can precisely go to the folder that I need to go to, grab the album from there, and then go on and place it on the playlist I want it to be in. I hope you understood from the screenshots alone but yeah that's the idea of what I'm trying to get at with this.

Screenshot_20260217_130022
Screenshot_20260217_130028
Screenshot_20260217_130229

@alltechdev
Copy link
Contributor Author

alltechdev commented Feb 18, 2026 •
edited
Loading

@hydrogenicMetallium

Try latest when it's done building.

@hydrogenicMetallium
Copy link

hydrogenicMetallium commented Feb 18, 2026

@hydrogenicMetallium

Try latest when it's done building.

The scanning can be a bit hit or miss sometimes like songs not showing up in some folders
Other than that it works pretty well!!!
Just add in multi select for local songs and ur golden!!!

@mostafaalagamy mostafaalagamy changed the base branch from master to main February 18, 2026 22:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@alltechdev @hydrogenicMetallium