EasyPMP Manual

This manual page describes the use of the easypmp command line program.

A PDF version of the manual is also available for printing.

Index

NAME
SYNOPSIS
DESCRIPTION
DEVICE SUPPORT
OPTIONS
EXAMPLES
AUTHORS
 

NAME

easypmp - create music databases and playlists used by portable media players
 

SYNOPSIS

easypmp [-c|-u] [-t csv-word-list] [-p [-P source-dir] [-r] [-f] [-i]] [-R [-L level]] [-d device-id] [-s name:value] [-e system-encoding] [-w tag-encoding] [mount-point]
easypmp [-h|-x|-v|-l]

 

DESCRIPTION

easypmp is a command line utility used to create and maintain the music database and playlists on a variety of portable media players.

Many portable music players allow the user to browse tracks by artist, album, genre, predefined playlists etc. In order to do this efficiently, they require a database of track information. Without this database, the player may require the user to browse tracks using only the directory structure. easypmp exists to create music database and playlists, based on the tracks and playlists that are stored on the player.

Normally, easypmp is able to detect the type of any supported media player automatically. It does so by comparing the files and directories found at the specified mount point with the list of files it expects to find on each type of device that it supports. If no mount point is specified, the current working directory is assumed to be the mount point.

In order to check that easypmp can identify the type of media player, the media player should be mounted as a USB device. The program should then be run without any command line switches (although the mount point should be specified if it is not the current directory). If the device is recognised, easypmp displays information about the device, including the directories in which it expects to find music and playlists on that device. If the device is not recognised, an error message to this effect is shown.

For a quick introduction on how to use easypmp, see the EXAMPLES section below.

 

DEVICE SUPPORT

easypmp currently only works with media players that can be mounted as USB Mass Storage (UMS) devices. Specifically, it has been tested with the following devices:

Note that some of the iRiver devices listed above may not support UMS as shipped. For example, in Europe and the United States, the iRiver U10 ships with support for a proprietary file transfer protocol called Media Transfer Protocol (MTP). In order to use these devices with easypmp, it is necessary to re-program (or flash) the firmware on the device to make it support UMS. This can be accomplished by running the iRiver firmware updater for iRiver products. At the time of writing this works with T10, T20, T30, U10 and N12 models, with the exception of 256MB and 2GB models in these series. The firmware updater can be downloaded from:

  http://www.iriver.com/mtp/

Note that the iRiver firmware updater is a Windows program. The program requires that your computer be connected to the Internet when run, in order to download the latest firmware for the device. Please note that updating the firmware on a device using this program will erase any data already stored on the device.

 

OPTIONS

easypmp follows the usual GNU command line syntax, with long options starting with two dashes (-). A summary of options is included below.
-c, --create
Create a new music database from scratch. The music files in the directory on the device used for storing music files is scanned recursively for music files. For each file found, the meta-data stored in that file - including the genre, artist, album and track name - is read, and used to add a record for that file in the music database stored on the device.
-u, --update
Update the music database stored on the device. This is similar to the -c option, with the exception that, when an entry for a given music file already exists in the database stored on the device, the meta-data already stored in the database is not updated.

Using this option means that easypmp does not need to re-read the meta-data in every music file on the device. Rather, it only has to read the meta-data in music files that were not on the device the last time the database was updated. Thus this option is a faster way creating the music database when only a few tracks on the device have been changed since the database was last created or updated. If the meta-data in existing files has changed, easypmp tries to reflect the changes in the database even when using this option.

-p, --playlist
Many programs for playing music allow playlists to be created and saved on disk, ready to be played later. Such playlists frequently have a .m3u or .pls extension. However, the playlists saved by most programs cannot be used directly on portable media players. Instead, it is necessary to convert (or compile) each playlist into a format that the media player can read. When the -p/--playlist option is specified, easypmp will search the playlist directory on the device or the directory specified by -P/--playlist-source option for playlists that can be converted into a form that the media player can read (see the DESCRIPTION section above for information on how to determine the playlist directory for a particular media player).
-P directory, --playlist-source=directory
Specifies the location in which the source playlists are stored. Changing the location to a directory on the computer means on-the-fly playlist conversion without transferring source playlist files on the device.
-r, --reconvert
Overwrite the existing playlists to force conversion.
-f, --find-missing
Find music files described in a playlist with broken references. Setting this option tries to correct the location of a music file referred to by a playlist by searching for the music file in the music directories that have the same file name. Finding two or more music files that have the target file name, easypmp selects a music file with a path name that is the most similar to the original one.
-i, --skip-missing
Skip missing music files in a playlist. Setting this option indicates easypmp to continue the playlist conversion only with music files found in the player. The default behavior for a missing music file is to cancel the conversion for the playlist.
-R, --repr
Output a textual representation of the music database on standard output. This option is seldom used: it may be useful for debugging purposes, or if bored.
-L level, --repr-level=level
Specifies the format of the textual representation of the music database. This option is only meaningful if the -R option is used. The value of level should be an natural number: that is, either 0 or a positive integer. The meaning of the given value depends on the type of media player in use. Currently, the only values of level that may produce different results are 0 and 1.
-l, --list-device
Shows the list of supported devices. This includes the names of the directories where music and playlists are expected to be found and the playlist extension used by each device. The list also includes the device identifier for each device. For more information on the device identifier, see the -d option.
-s name:value, --set=name:value
Overwrites the value of a variable set by the driver. The following is the list of variables.
pmp_music
Relative path to music directory from the mount point.
pmp_playlist
Relative path to playlist directory from the mount point.
-d device-id, --device=device-id
Specifies a device identifier for the player. The device identifier is used to determine where easypmp looks for music files and playlists, and the location and format of the database that it creates. It is not normally necessary to specify the device identifier because it is normally detected automatically, based on the names of system files and directories on the device.
-t csv-word-list, --strip-words=csv-word-list
Specify a list of words to remove from the start of artist names when adding new tracks to the database. The list of words should be comma-separated: that is, a comma (,) should be used to between each word.

For example, easypmp -ct the will strip the word 'The' from the start of artist names. Hence, 'The Proclaimers' and 'The Cat Empire' will appear in the music database as 'Proclaimers' and 'Cat Empire' respectively.

The list is not limited to individual words. Phrases that include spaces may also be specified from the command line, by including the whole list in quotes, separating each word or phrase by a comma. For example: easypmp -ct 'the,pipes and drums of'.

When used with the -u/--update option, only new tracks that are not already in the database are affected by this option. To use this option with all tracks, including those that already exist in the database, it is necessary to re-build the database with -c/--create. This option does not modify music files, it only has an effect on the music database.

-e, --encoding=system-encoding
Specify a character encoding used by the operating system. easypmp converts path/file names from the specified encoding into UCS-2 by using iconv. The default value is determined by the automatic detection of the system character-encoding.
-w, --tagencoding=tag-encoding
Specify a character encoding for parsing non-unicode tags. easypmp converts non-unicode tags embedded in ID3v1, ID3v2, and Riff WAVE into UCS-2 encoding by using iconv. The default value is "ISO-8859-1".
-h, --help
Show summary of options.
-x, --help-variable
Show the list of variables.
-v, --version
Show version of program.
 

EXAMPLES

These examples assume a media player has been mounted as a normal USB disk using /media/sda as a mount point.

Firstly, it is advisable to check that easypmp can support your media player:

easypmp /media/sda

If easypmp supports your device, this will show the paths where music and playlists should be copied to, prior to creating the database. Once music and playlists have been copied into these directories, the music database can be constructed as follows:

easypmp -c /media/sda

Note that, if the current directory is the mount point. it is not necessary to specify this on the command line. Therefore, when running easypmp several times, it is useful to change to the mount point directory first, in order to avoid having to specify it repeatedly.

After adding or removing tracks from the media player, the database no longer reflect the files stored on the device. The database can be updated, without reading tags for files that already exist in the database:

easypmp -u /media/sda


 

AUTHORS

easypmp was written by Naoaki Okazaki <nyaochi at users.sourceforge.net>, who also wrote an initial POSIX port using the Cygwin environment.

This manual page was written by Martin Ellis , who also contributed bug fixes for the POSIX port.

Time: 19:10:45 GMT, February 18, 2007