Both Unpopular Music Player and Opus 1 Music Player use Android's media database. Unfortunately it is incomplete, error prone, and the update automatism is hardly to predict and unreliable. Sometimes it fails.
For music management these player programs use their own tagger library to extract the missing and wrong information directly from the music files. This works, but the inconsistency problem remains.
Both SAF Media Scanner and Classical Music Scanner create media databases, which are used instead of Android's one (if configured accordingly) in the mentioned programs. However, this database only contains information about audio files and album pictures, neither other pictures nor movies. Note that the tagger libraries in the music player applications are no longer used in this case.
Via menu entry "Scan Device for Audio Files…" and the context menu.
Via menu entry "Scan Device for Audio Files…" and the context menu in the Playback view.
Runs invisibly in background whenever files are changed or deleted.
CMS: Just run it and press the green floating button.
SMS: Just run it and use the green floating "+" button to add search paths and the red "x" button to remove paths. Then select the path you want to scan and press the "PROCEED" button. Follow the displayed explanation.
The "Auto Scan" or "Incremental Scan" looks for changed, added and deleted audio files and updates the database accordingly. In case there many of such changes, the application automatically decides to run a complete scan, this will also happen in case of a failure of whatever reason.
The incremental scan might not handle every possible metadata or file system change. In case of any problem, like unexpected results, the complete scan should be initiated manually, using the yellow floating button (CMS) or magnifier icon (SMS).
Contrary to the Android system the scanner detects multi-CD-albums and manages them accordingly. The album folder shall contain some album picture ("albumart.jpg" or "folder.jpg") and for each CD its subdirectory named "CD1" etc..
Otherwise an album is defined by album name and "album artist", and all audio files should be located in the same directory.
Album Pictures are located in the album directory and are named "albumart.jpg", "folder.jpg" or "folder.png". Additionally "cover.jpg" is allowed. Other file names, including "Folder.jpg" e.g., are ignored.
In case of a missing picture the largest embedded one (if any) is extracted and stored as "albumart.jpg/png" (SMS) or "folder.jpg/png" (CMS). If necessary and configured via settings, it is scaled down, while, if configured, the original picture is saved as ".backup".
If configured, existing album pictures are also downscaled and the original file is saved.
Large album pictures slow down album browsing. Thus 500 pixels limit are preconfigured, like in Android system. Contrarily to Android pictures of 501 pixels are not scaled to 250, but to 500. Android always halves the size until the picture fits.
Note that at least Samsung and LG changed the internal Android media scanner in that way, that only "albumart.jpg" is detected, but not "folder.jpg" This "deprovement" is verifiable with a look into the Android source code.
The ID3 unsynchronisation flag is currently not supported when using the new Java library.
Cover art in .ogg and .flac files might be not supported when using the native library.
CMS: The main functionality is written in C++, so called "native code". This includes the directory scan, file operations, the C++ library TagLib and its own SQLite library. The last mentioned is necessary, because for whatever reason Android's database functions are not accessible in native code.
SMS: As SAF is not available in C or C++, the main file search loop had to be implemented in Java. Further, a new Tag Reader Library is used, also written in Java, and Android's SQLite database functions for Java. Note that alternatively the native tag reader TagLib can be used instead of the Java library. This is configurable in the settings.
The music databases could be used by any arbitrary program. The database files ".db" can even be copied to a computer, e.g. for analysis using some "DB Browser".
According to Google, programs normally should use the Android media database for all metadata and access to photos, audio and video files. But if this database lacks - or contains wrong - information, for example only supports pop music and only in mp3 format, one needs direct read access to the corresponding files.
Standard file access in Java is based on the File class, there are corresponding functions in "native code" (C or C++). With these functions, directories can be read or created, files can be read, written, created or deleted. This works the same way in desktop computers running Linux, Unix or macOS. The Classical Music Scanner mainly runs in "native code" for maximum execution speed.
For access control and restrictions, the Linux kernel, which is also used in Android, provides proven mechanisms. However, Google was not satisfied with this access protection concept and increasingly restricted the standard file access to certain directories, depending on the Android version. On the other hand Google invented the "Storage Access Framework" (SAF) that grants access only after an explicit user interaction. This permission can also be permanent, i.e. remains valid after an application restart.
A major limitation of SAF is that no standard functions of Java or C or C++ work with it. Instead one has to use Google's class DocumentFile that is only available in Java, not in C or C++. However, once opened in Java, a file can, with restrictions, also be read and written in C or C++, but it cannot be opened, neither created or deleted. Not even a directory search is possible. Finally, Google did not provide a corresponding Java class RandomAccessDocumentFile, which also makes rewriting existing Java code unnecessarily difficult. Also, libraries like SQLite cannot deal with DocumentFile and thus are useless when using SAF, this is also true for Android's own SQLite library. Furthermore, SAF is extremely slow. Therefore "normal" file access is preferable, if possible. But unfortuntately Google drastically restricted this kind of access with the introduction of Android 11.
For which directories such "normal" access is (still) allowed?
Each application has its private directories in internal memory and SD card (if exists). Here the
access is unrestricted, SAF is not needed.
"Music", "Photos", "Documents" directories etc. in internal memory are unrestricted up to Android 10. Applications written
for Android 11 and above may still scan the directories, but no longer have non-media-file access, neither read nor write,
without SAF. Precisely, this restriction holds for applications targeting SDK 30 and running on any arbitrary,
also on an older, Android. Note that media files can still be read in Android 11 and above, these can
be audio, video or picture files, that are listed in Android's media database. Note that images
like "albumart.jpg" or "folder.jpg" are used by Android as album cover, but not registered in Android's picture
database and thus cannot be accessed without SAF.
"Music" etc. on SD card is readable up to Android 10, but one needs SAF for write access. If the
application is written for Android 11 and above, the restrictions are the same as for internal memory.
USB memory (via OTG adapter) is treated like SD cards with Android 9 and newer. For older OS versions
one needs SAF for both read and write access.
Note that all these restrictions can be avoided by applying for the MANAGE_EXTERNAL_STORAGE
permission. But not only that permission must be granted by the user at runtime, additionally the permission to
ask for that permission must explicitly be granted by Google when uploading the application to
the Play Store. According to Google, this universal permission is only legal for file managers etc.,
and other applications are not allowed to request it.
As the SMS currently does not request MANAGE_EXTERNAL_STORAGE, it must ask the user for read and write permission and then must use SAF for write access to internal or external memory. In particular, write access to the SQLite database file is not possible, which is a heavy design flaw of Google's security concept. To circumvent this restriction, the database file must be copied to the application's private memory, where it can be modified, and later it must be copied back to its correct position, using SAF functionality.
SAF operations are executed by some "Document Provider" that either are pre-installed or can be
installed later like an application.
Some "Document Providers" support "Open Document Tree" or "FLAG_SUPPORTS_IS_CHILD", others do not.
Only the former are visible in the SAF selection dialog, because this functionality is required
by Classical Music Tagger and SAF Media Scanner to search subdirectories.
Access to internal memory, SD card or USB memory is no problem, because tree search is supported.
Some "document providers" allow "random access", i.e. the file is "seekable", which means that
it can be read or written anywhere within the file, just like "normal" file accesses, and it is
not necessary to read the whole file into memory before it can be used. This is true for
internal memory, SD card and USB memory.
The "Android SMB Client" allows read and write access to network storage (although somewhat
unstable...), "Open Document Tree" is supported, but no "random access".
Google Drive does not support "Open Document Tree". A respective request, issued by
various developers, has explicitly been rejected by Google, with the explanation: "We will not".
Rumors say that the NextCloud Client does support "Open Document Tree".
Conclusion: The player applications need SAF to play music from USB memory on older Android versions (before 9). SAF is also required for all types of network storage, but this only works if the responsible "Document Provider" is capable accordingly. And finally, with Android 11, SAF has generally become more important.
TagLib C++ Library:
Source: https://taglib.org/
License: LGPL (http://www.gnu.org/copyleft/lesser.html) and MPL (https://www.mozilla.org/en-US/MPL/1.1/)
SQLite C Library (CMS):
Source: https://www.sqlite.org/
License: https://www.sqlite.org/copyright.html