thrash.dev

docs / providers / local files

Providers · chapters · 01 of 25

← Yafmp manual

  1. Local Files
  2. Plex
  3. Navidrome
  4. Jellyfin
  5. Bandcamp
  6. Lidarr
  7. Apple Music
  8. Spotify
  9. SoundCloud
  10. YouTube Music
  11. SiriusXM
  12. Radio
  13. Podcasts
  14. AirPlay
  15. Chromecast
  16. MusicBrainz
  17. Discogs
  18. Labels
  19. Releases
  20. Last.fm
  21. ListenBrainz
  22. Connect
  23. Home Assistant
  24. MCP server
  25. DJ

Local Files

Add music files and folders from this device, iCloud Drive or any Files location.

facts

status
beta
kind
source
on by default
yes
needs
Music files on the device or on a mounted share
platforms
iPhone, iPad, Mac, Vision Pro, Android, Android TV, Linux, FreeBSD, Windows

Description

Local Files plays music that is stored as files: on the device, in iCloud Drive or another Files location (Apple), in a folder you grant access to (Android), or in any folder or mounted network share (desktop).

There are two ways in. A folder you add stays in the library panel and is browsed as folders. The + button in the toolbar puts single files straight into the playlist without adding anything to the library.

A file’s album is its folder. Search matches the names of files and folders in the added folders, not tags. Every word you type must be in the name; case and accents are ignored. The first 200 matches are shown.

What is read from each file differs by edition:

AppleAndroidDesktop
TagsFLAC/Vorbis, ID3 and MP4 tagsWhat Android’s own tag reader returnsNot read
FieldsTitle, artist, album, album artist, track, disc, year, genre, ReplayGainTitle, artist, album, album artist, track, disc, year, genreArtist, album, disc, track and title from the path Artist/Album/1-02 Title.flac
CoversEmbedded in FLAC, MP3 and M4AEmbeddedAn image file in the folder; if there is none, a MusicBrainz lookup by the artist and album folder names
Format shownCodec, sample rate, bit depth (lossless), bitrate, channelsCodec, bitrate; sample rate and bit depth on Android 12 and later—

The desktop edition also has Import, which copies music into an Artist/Album (Year) folder layout, and a list of the SMB file servers on your network.

Local Files is not on Apple TV.

Requirements

  • Music files. Apple plays FLAC, MP3, WAV, AIFF, ALAC and AAC.
  • On Android and desktop, files with these extensions are listed: flac, mp3, m4a, aac, alac, ogg, oga, opus, wav, aif, aiff, wma, ape. Android also lists any file the system reports as audio.
  • Desktop, for Import only: ffmpeg and ffprobe on your PATH.
  • Desktop, for the network shares list: a file manager that can mount smb:// addresses.

Setup

On Apple:

  1. In the library panel, under Local Files, choose Add Folder… and pick one or more folders.
  2. To add single files or folders to the playlist instead, use the + button in the toolbar.

On Android:

  1. Open Settings → Local Files.
  2. Choose Add folder and pick a folder in the system picker. Yafmp keeps read access to it.
  3. To add single files to the playlist, use the + button in the top bar.

On desktop:

  1. Open Settings → Local Files.
  2. Choose Add Folder… and pick a folder.
  3. For a network share: under Network shares, choose Connect beside a server. Your file manager mounts the share and asks for the password. The mounted share then appears in the list with an Add button.
  4. To add single files to the queue, use the + button in the top bar.

To import music on desktop:

  1. In Settings → Local Files, choose Import….
  2. Check Staging folder. It is where the copies go. The default is Music/Plex Music in your home folder.
  3. Choose Choose Music… and pick files or folders. Yafmp reads their tags and lists where every file will go.
  4. Read the list. [name-derived] means the names came from the file name, not from tags. [track#=order] means the track number was taken from the file order. EXISTS means the file is already in the staging folder. → FLAC means the file will be converted.
  5. Choose Import.

Import copies files to Artist/Album (Year)/Artist - Album - NN - Title. .m4a and .alac files are converted to FLAC. The originals are never changed.

Settings

The Apple edition has no settings pane for Local Files. Add Folder… is at the top of the Local Files section of the library; to take a folder out, right-click (or long-press) it and choose Remove from Library.

On Android and desktop, Settings → Local Files has:

SettingDefaultWhat it does
Folder listemptyThe folders shown in the library. Remove beside a folder takes it out; the files are not touched.
Add folder (Android), Add Folder… (desktop)—Adds a folder to the library.
Import…—Desktop only. Opens the Import window.
Staging folderMusic/Plex Music in your home folderDesktop only, in the Import window. Where imported copies are written.
Network shares—Desktop only. SMB servers found on your network, each with Connect. Mounted shares have Add.

Limits

  • Search looks at file and folder names only. It walks the folders on every search, so it is slow on a very large library, and it stops at 200 matches.
  • Apple: only embedded covers are shown. A cover.jpg or folder.jpg beside the files is not used.
  • Android: ReplayGain tags are not read.
  • Desktop: tags are not read. Titles, artists and albums come from the file path, so a library that is not laid out as Artist/Album/NN Title shows file names.
  • Desktop: a file plays only if GStreamer on your system can decode it.
  • Desktop: the folder images used as covers are cover, folder and front as .jpg or .png, and albumart.jpg.
  • The network shares list is for Linux and FreeBSD. It does not work on Windows.
  • Import copies and converts. It does not write tags.

Troubleshooting

ProblemWhyWhat to do
Tracks have gone from the playlist after a relaunch (Apple)Files that no longer exist are dropped from the playlist at launchAdd them again from their new place.
“can’t read this folder; add it again in Settings” (Android)Android no longer grants access to the folderRemove the folder in Settings → Local Files and add it again.
A track says its file “is gone (an unmounted share?)” (desktop)The folder is on a share that is not mountedMount the share again, then play the track.
Titles are file names (desktop)The desktop edition does not read tagsLay the folder out as Artist/Album/NN Title, or use Import… to make such a copy.
No cover for an album (Apple)The cover is a separate image file, not embeddedEmbed the cover in the files.
Import marks every file [name-derived], or conversions to FLAC fail (desktop)ffprobe or ffmpeg is not installedInstall ffmpeg and make sure both commands are on your PATH.