plmapper - command line utility for remapping iTunes playlists to work with an external non-iTunes Master Library
plmapper [--help] [--man] [--config FILE] [--exclude LIST] [--force] [--dest DIRECTORY] [--scpdest DIRECTORY] [--itunes FILE] [--library DIRECTORY] [--plroot DIRECTORY] --[xslt FILE] [--utf8mac] [--smb1 VALUE] [--smb2 VALUE] [--squeeze URL]
This command-line program converts playlists in iTunes to the common m3u format,
adjusting file paths to match a (non-iTunes) Master Library on an external NAS device.
Filename changes and path differences from iTunes internal shufflings are accounted for.
Once the conversion is complete,
playlists are copied directly or via scp to a target location.
Optionally,
a Squeezebox server can be pinged to force refresh of playlists.
NOTE: This utility trusts whoever is using it. No effort is made to check parameters for malicious calls. You should be fine if you use this in your home, but don't expose it to the Internet.
The overarching goal is to be able to treat our NAS device as our official Master Library, able to stand on its own without any ties to iTunes, while still keeping the convenience of iTunes playlists.
This is accomplished by publishing the content of iTunes playlists to the Master Library in a simple neutral playlist format that any music player can understand.
In all steps, the external non-iTunes Master Library is treated as the library of record. The iTunes library is simply a copy, with many of the paths modified by iTunes.
In generating these m3u playlists for a different library,
this application must convert potentially unrecognizable file paths in iTunes to canonical paths to the same file in the original non-iTunes Master Library.
This program performs the following:
m3u playlist files.This is done by obtaining the size of the iTunes version of the file and then looking this up in the internal list created in the first step.
Once a short list of candidates is found, the first few thousand bytes of each file are compared until a match is found.
The risks of choosing the wrong file are low: all that will happen is that a song might be switched in the playlist accidentally. As such, it isn't worth scanning the full file to ensure they are exact matches.
This algorithm works quite well, and can detect music files that have been renamed and moved around.
scp.This utility requires several lengthy command line options, such as file paths. In order to facilitate usage, you may create a configuration file and store the parameters as name-value pairs.
The default name for the configuration file is plmapper.config, and it should be placed in the current working directory or your home directory.
You can provide a different configuration file on the command line using the --config FILE option.
Sample file content:
itunes=/Users/Bozo/Music/iTunes Music Library.xml dest=/Users/Bozo/Desktop library=/Volumes/media/music
Displays usage information for command.
Displays this help document.
The path of a configuration file containing name-value pairs. See "CONFIGURATION FILE" for details.
A comma-delimited list of playlist names or regular expressions that you wish excluded from processing.
Example: --exclude "Genius,19.*,On-The-Go"
This example will exclude the "Genius" mix, the sequential year lists for 1990-1999, and the "On-The-Go" playlist.
Forces the processing of playlists even if the iTunes library has not been modified since the last run. Default behavior is to skip processing if the iTunes database file has not been touched since the end of the last run. This facilitates using a scheduled job to run this process.
The path where to copy finished playlist files. This must be a path that is accessible to the current process. It can be a mounted directory, but it must be present at the time that the playlists are being generated.
The SCP path where to copy finished playlist files. This uses scp to securely copy the generated playlist files to some remote target directory. It is assumed that you either provided embedded username/password information or you have configured your machine to automatically authenticate via .ssh/authorized_keys on the remote server.
Example: bozo@myserver.myhome.local:/home/bozo/music
The desired iTunes library database file. This defaults to ~/Music/iTunes/iTunes Music Library.xml. This file is not modified in any way; the plmapper application makes a copy of this database file.
The full path to the true non-iTunes Master Library, often on network attached storage.
This path must be valid at the time that the playlists are being generated. In many cases, you will use the --smb1 and --smb2 options to mount remote shares at the beginning of the playlist generation process.
This is the Playlist Root--an optional path that will be prepended to each playlist entry. This is used because you usually will have a different filesystem structure where the playlist will be employed.
This does not need to match the upstream path to music in the Master Library. For example, your Master Library could be on a NAS, while you wish to generate playlists for a Squeezebox server that has the Master Library mounted differently.
Example: --plroot /srv/squeezebox/music
Old: Tom Jobim/The Girl from Ipanema.mp3
New: /srv/squeezebox/music/Tom Jobim/The Girl from Ipanema.mp3
Provides a way to provide a custom XSLT stylesheet for playlist generation. This is normally not necessary, as the plmapper application provides a default stylesheet.
Forces conversion from utf8mac to utf8. Mac OS X insists on using wide UTF8 characters, composed of things such as "C" plus a special character for "cedilla" instead of using the existing C-cedilla character.
In order to avoid character set issues in some devices, these wide UTF8 characters are converted to their single-character equivalents where possible.
If a character cannot be converted, it is dropped. This will cause a song to disappear from a playlist.
Connection info for first Samba connection.
Syntax:
[options] //[[user]:[password]@]server/share
Examples:
Connect as user bozo with password clown to share music on server jukebox.myhome.local
Connect anonymously to share common on server jukebox.myhome.local
Connect anonymously to share public on server 192.168.1.100 with readonly option
Connection info for second Samba connection.
URL of Squeezebox server.
~/Music/iTunes/iTunes Music Library.xml
The default location for the iTunes music database on a Mac OS X machine.
plmapper.config
Default configuration file that can be used in place of command line arguments.
This file can be placed either in the current directory or in your home directory.
You can override this file with the --config option.
/tmp/.plmapper
Empty file used to hold last run timestamp. You can safely delete this file at any time; it will have the same effect as running plmapper with the --force option.
This typically happens when dealing with foreign or classical music files that have accents in the filename.
Squeezebox server does not handle accented characters in playlists correctly; this is even the case when creating a playlist in Squeezebox itself and then reloading it. Songs with special characters that were originally in the playlist will be omitted once the list is refreshed.
One workaround is to rename song files to only use ASCII characters.
The workaround is to rename song files to only use ASCII characters.
Tad Harrison, with XSLT stylesheet based on original work from Ovidiu Predescu.
Copyright 2011 by Tad Harrison
This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.