2023-03-20

Make my M3U Playlists Relative Again!

For those of us who prefer independent local media, back-up their precious music collection to external drives and use copies on several computers and devices, it's quite annoying that many popular mediaplayers won't export M3U playlists correctly with relative paths.

Problem

For reasons beyond rational thought, some mediaplayers still export M3U playlists with nothing else than absolute file paths.

Absolute paths are file references with full path description, consisting of drive letter, user path, music folder, band name, album, etc.
You can bet on it. By the next opportunity, the affectionate party playlist will explode, in embarrassing silence. Not a single track is found for playback, when user path has changed or the removable disk was assigned a different drive letter or mount point. Absolute playlist paths turn out to be the ball and chain of media file references ...

Relative paths are quite more flexible. They only define the branch of file path which is needed to find the media relative to the M3U file itself. Together, this makes the full path. Any serious mediaplayer can deal with it, and in fact, relative file path references were supported ever since.
If we save our playlists to a fixed location within the directory tree of the music collection and those playlists use relative paths, everything becomes nicely portable. We can rename the root folder of the collection at any time. We have option to relocate the whole directory tree to a different mount point in the filesystem. We are free to mirror the whole stuff to an external hard drive, USB stick, DVD, crypto container etc. with all relative playlists contained therein to remain playable on most computers, multimedia devices and operating systems.

Retroactive conversion of a playlist from absolute to relative paths is indeed possible by manual edit in a plain-text editor. However, it is not always done with a few "find-and-replace" actions. When music files have been relocated in the meantime, first of all, their new locations must be searched in order to re-create valid playlist entries. Even within the same playlist, the absolute portion of the path can have confusingly different format, as soon as symbolic links are involved and/or various applications have messed around with it.

Retroactive conversion of, emm, "a few" (hundreds) of playlists ... clearly recommends for machine processing, for a clever algorithm (buzzword !!!).

Which should be smarter than just blindly shortening path references. It should actually search and find the media files in question. First by trying possible subsets of the absolute file path found in the playlist. And, if this wasn't successful, a broader search using the bare filename can track down "lost" entries, i.e. files which have been relocated or their home folders renamed in the meantime. By this, we get a convenient option to automatically fix "broken" playlists.

I've seen creepy scripts unable to cope with complicated folder structures, windows spyware pretending to be "playlist editors", bloated audio library stuff, all completely unsuitable for the task!

What about a simple and safe conversion and maintenance tool for M3U playlists!


Top | Index

Solution

My minimalistic command line utility relm3u can do for you:

Top | Index

Details

General

The relm3u programme is an easy-to-use utility for Linux/Unix and Windows console.

Input: Main argument is the absolute path of M3U file(s) to be converted.
Processing: Try-out systematically generated search paths for every single media reference in the list. Adopt successful relative path to the new playlist.
Output: Back-up the original file, save new M3U under the original name, display some screen messages.

Search method

The absolute path to the original M3U file, extracted from the commandline argument, is the reference path.
The absolute (or relative) path from a playlist entry is the file path.
The programme creates a search path from reference path and file path in order to see whether the file in question can be found on this path.
If it doesn't work out, file path is shortened by one directory level (until next slash '/') for another try.
If the file path was shrunken to the bare file name this way, and the file was not found, the procedure will start again with modified search path that has 1 to 5 intermediate relative jumps to parent directory levels (by number of '../' inserted between reference path and file path).
This will cope with more tricky situations of relative paths that became invalid due to relocation of playlist itself.
If all this has failed to find the media file, the programme will resort to external filesystem search utilities, namely find on Linux and dir on Windows console. Both can search quite exhaustively for a submitted filename, starting from a submitted referential point in the filesystem. However, as this is a rather context-free "blind" search, it can produce "false positives", especially when lots of mindlessly named media files are in (e.g. titles in album folders just named "Track 1", "Track 2", etc.).
For this reason, and because the searching through a complex directory tree is comparably slow, the first search method is always primary choice.

When by either search procedure the media was actually found, the programme knows the valid absolute path to the file in question. SUCCESS!

The absolute portion of this composed path is identical to the reference path. This part is now cut-off. The remainder is the valid relative path to the respective file, which enters into the new relative playlist.

Next search for the next entry, until all lines of the playlist are processed.

Other conversions

Extended M3U tags are purged. Because they are next to useless. Mediaplayers should follow all file references directly after loading the playlist in order to get meta data directly from the respective file's ID3-tags! This would not even cause notable delay with locally stored files, but provide certainty that all titles and the information to display, are first-hand. That is to say, the format of relm3u processed playlists is pure M3U.

Web links and network protocols are removed. Everybody's free to use streaming and web radio, but relm3u is strictly for local resources. A clear separation from internet playlists is recommended. However, it works fine with crypto containers or NAS which are mapped to a local path.

Input/output formats. For source files with the extension '.m3u' or 'm3u8', plain text encoding such as ASCII, UTF-8, ISO8859 is assumed. In fact, only the linefeeds will change to system standard when saving backups and new M3U playlists. URL-style addresses (percent-encoded) are extracted, path separators converted from backslashes '\' to normal slashes '/'.

System requirements

This command line application was developed using gcc with least dependencies. In particular, no Java nor dotNET stuff required. Executables for Linux are statically compiled for 32 bits to achieve broadest compatibility. Windows executables are also 32 bits created in a MinGW environment. See source code for more details.
The programme does all conversions in a line-by-line manner. There is minimum of memory requirements for buffering and no limits to the absolute size of a playlist!
External dependencies: The programme uses find utility on Linux/Unix. If this is not available for crazy reasons, relm3u could still work, only without deep search capability. On any Windows console, the dir utility shall be available. It is the basis for deep search in the Windows console version of relm3u.

Install

Simply extract the executable relm3u(.exe) into a user directory with file execution privileges. If necessary, mark the file 'executable.' The programme does not save anything to its working directory, so it could as well be write-protected for additional safety.

Application

Screen messages are in English and the utility programme is supposed to be self-explanatory. Plain invoke will show up brief help screen and version info.
The main argument is the path to the original M3U file. Write access would only be attempted within this path/folder. Other media folders could as well be read-only.
However, without further argument, no write access will happen and relm3u is working in a pure testing/simulation mode. Search procedures are fully performed and screen info displayed, but changes are never written over the original file. This is the new safe default mode.
If we want to actually change playlists, we have to submit a second argument of '--serious' short '-s'. With this switch set, relm3u will actually overwrite the respective M3U-file with the changes. Of course, as with previous versions of relm3u, in serious mode there is always a backup of the original file being saved.
Important and quite obvious prerequisite: all media files referenced to in a playlist must be visible in the file system while the process of conversion is running!
Please also have a look at the help screen of the programme for the current syntax.

The following examples assume that we type in a console window and have navigated to the working directory of relm3u and the main folder of this fictitious collection is named "MUSIC".

Single conversion: Say, we have a nice M3U playlist compiled and saved to its destination folder within the directory tree of our precious music collection. To make the stupid absolute paths relative, we now invoke relm3u with the complete path to that playlist file:

relm3u "C:\Documents and Settings\Username\MUSIC\playlist.m3u"   (Windows)

./relm3u "/home/Username/Media/MUSIC/playlist.m3u"    (Linux)

Files found are listed on the screen with their relative search path, prepended by "1:" which stands for the normal (internal) search method, and "2:" for successful advanced search, as described above. Tracks marked with 1: or 2: would enter the new playlist. Files that could not be found at all, are listed with a prepended "X:". These files would not enter the new playlist.
However, only when second argument '--serious' exists, the programme will actually overwrite the original playlist. Of course, in serious mode, a backup copy is made from the original source file. These backups have sequential numbering, so nothing will get lost even with multiple invokes of relm3u.
Finally, a simple stats on the number of files found vs total number of files referenced in the original playlist, is shown. If the new playlist works as expected, we can delete all backups.

Bulk conversion within same directory: If the specified file name contains placeholder symbols, all M3U files matching the pattern are processed one after the other. Example "Process all playlists whose name starts with '2019'!":

relm3u "C:\Documents and Settings\Username\[...]\MUSIC\2019*.m3u"

./relm3u "/home/Username/Media/MUSIC/2019*.m3u"

Observe quoting rules at the commandline. The new version of relm3u demands for a slightly modified quoting in case the file path contains whitespaces and/or wildcards. The full path must be enclosed in quotes. This is to ensure that the argument is sent in an unaltered form (i.e. not resolved by shell interpreter) to the programme.

Bulk conversion over directories and subdirectories: When specifying the path to a folder, relm3u will recursively search this directory tree for files of .m3u (and .m3u8) extension and process them. That is to say, this option can auto-update all playlists in a media collection in one stroke. Of course, every single playlist file is backed-up as usual.

relm3u "C:\Documents and Settings\Username\[...]\MUSIC\"

./relm3u "/home/Username/Media/MUSIC/"

Of course, there is option to set up a desktop shortcut. Under Linux, add the placeholder %f to the command string and do not forget to also add -s as the second argument for serious mode. This will allow to conveniently drag-and-drop M3U files or containing folder to the icon of relm3u.

Updating playlists: Restructuring in the music collection is no longer a horror trip. The automated search will find almost any file that has been relocated or its folder renamed, as long as the file names remain the same (case-insensitive), to adopt with the new relative playlist. Additionally, the process can restore playlists that were already relative paths but have been relocated.

Conversions by way of relm3u can be repeated as often as required.

Top | Index

License

The relm3u programme is Open Source and Freeware in the most permissive sense: No warranties, no restrictions.
My motivation is to publish projects like this as a contribution to a more human and transparent technology.
Feedback and/or donations are strictly welcome...!


Top | Index

Download



Top | Index

Project start: 12/2020