docs / providers / local files
Providers · chapters · 01 of 25
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:
| Apple | Android | Desktop | |
|---|---|---|---|
| Tags | FLAC/Vorbis, ID3 and MP4 tags | What Android’s own tag reader returns | Not read |
| Fields | Title, artist, album, album artist, track, disc, year, genre, ReplayGain | Title, artist, album, album artist, track, disc, year, genre | Artist, album, disc, track and title from the path Artist/Album/1-02 Title.flac |
| Covers | Embedded in FLAC, MP3 and M4A | Embedded | An image file in the folder; if there is none, a MusicBrainz lookup by the artist and album folder names |
| Format shown | Codec, sample rate, bit depth (lossless), bitrate, channels | Codec, 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:
ffmpegandffprobeon yourPATH. - Desktop, for the network shares list: a file manager that can mount
smb://addresses.
Setup
On Apple:
- In the library panel, under Local Files, choose Add Folder… and pick one or more folders.
- To add single files or folders to the playlist instead, use the + button in the toolbar.
On Android:
- Open Settings → Local Files.
- Choose Add folder and pick a folder in the system picker. Yafmp keeps read access to it.
- To add single files to the playlist, use the + button in the top bar.
On desktop:
- Open Settings → Local Files.
- Choose Add Folder… and pick a folder.
- 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.
- To add single files to the queue, use the + button in the top bar.
To import music on desktop:
- In Settings → Local Files, choose Import….
- Check Staging folder. It is where the copies go. The default is
Music/Plex Musicin your home folder. - Choose Choose Music… and pick files or folders. Yafmp reads their tags and lists where every file will go.
- 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.EXISTSmeans the file is already in the staging folder.→ FLACmeans the file will be converted. - 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:
| Setting | Default | What it does |
|---|---|---|
| Folder list | empty | The 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 folder | Music/Plex Music in your home folder | Desktop 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.jpgorfolder.jpgbeside 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 Titleshows file names. - Desktop: a file plays only if GStreamer on your system can decode it.
- Desktop: the folder images used as covers are
cover,folderandfrontas.jpgor.png, andalbumart.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
| Problem | Why | What to do |
|---|---|---|
| Tracks have gone from the playlist after a relaunch (Apple) | Files that no longer exist are dropped from the playlist at launch | Add them again from their new place. |
| “can’t read this folder; add it again in Settings” (Android) | Android no longer grants access to the folder | Remove 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 mounted | Mount the share again, then play the track. |
| Titles are file names (desktop) | The desktop edition does not read tags | Lay 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 embedded | Embed the cover in the files. |
Import marks every file [name-derived], or conversions to FLAC fail (desktop) | ffprobe or ffmpeg is not installed | Install ffmpeg and make sure both commands are on your PATH. |