mkplaylist.py Manual

Author: Marc 'BlackJack' Rintsch
Contact: marc@rintsch.de
Date: 2011-05-26
Version: 0.8
Copyright: This document has been placed in the public domain.

1   Name

mkplaylist.py -- creates playlists from directory trees.

2   Synopsis

mkplaylist.py [-h|--help|--version]
mkplaylist.py [options] directory [directory ...]

The directories are the ones where the scripts starts to search for media files.

3   Description

The script scans the given directories for media files with known file name extensions and writes the names into a playlist file in M3U, extended M3U or PLS format. Those very simple formats are used or at least understood by the vast majority of media players on different platforms.

For huge collections which have to be rescanned after adding or modifying some files, the program can cache the meta data to speed up subsequent runs.

Symlinks to directories are not scanned to avoid running into cycles.

3.1   Known File Name Extensions

The script searches for the following file name extensions (case insensitive):

Media file name extensions.
Extension Format
ac3 ATSC A/52
flac Free Lossless Audio Codec
it Impulse Tracker
mod Amiga MOD
mp3 MPEG 2 Layer 3
ogg Ogg Vorbis
s3m Scream Tracker III
wav Wave

4   Requirements

The script requires Python version 2.4 or higher.

For reading meta data from media files some third party modules are needed. The program will run without those modules, but doesn't generate meta information output for those formats ofcourse.

4.1   MP3

The MAD MP3 decoder and its python bindings are used to read the length of MP3 files.


For reading the information from ID3 tags you can use the ID3 module or Ned Batchelder's id3reader. Both modules have to be in the PYTHONPATH, so the simplest installation would be putting them into the same directory as mkplaylist.py. The id3reader module is prefered if both modules are available.

4.2   Ogg Vorbis

Beside the Ogg Vorbis codecs you will need Andrew Chatham's python bindings for them: http://www.andrewchatham.com/pyogg

5   Commandline Options

--version show program's version number and exit
-h, --help show this help message and exit
-o OUTFILE, --output=OUTFILE
 name of the output file or '-' for stdout (default)
 format of the output ['extm3u', 'm3u', 'pls'] (default: extm3u)
-r, --relative-paths
 write relative paths. (default: absolute paths)
--shuffle shuffle the playlist before saving it.
-c, --cache use a cache file. (default: False)
 name of the cache file (default: ~/.mkplaylist.cache)
-v, --verbose be more verbose.
-q, --quiet be really quiet.

6   Examples

Scan the directory /data/music, using a cache file to avoid rereading already known meta data and write all media files into a (sorted) playlist named playlist.m3u:

./mkplaylist.py --cache -o playlist.m3u /data/music

Scan the directories /data/music/Various and /data/Music/Soundtracks and write a shuffled playlist, without meta information and relative instead of absolute paths, to standard output:

./mkplaylist.py -r -f m3u --shuffle /data/music/Various     \

7   Output Formats

7.1   M3U

A very simple playlist format which just lists all media file names in a text file with one file name per row.

7.2   Extended M3U

The M3U format extended with meta information for each file. There's an extra line which contains the playing time and a formatted name to be displayed by the player application.

7.3   PLS

Playlists in PLS format were introduced by WinAMP and look a lot like windows ini files. There is one section called [playlist] and some enumerated key value pairs for each file.

8   Credits

Many thanks to Oliver Pütz for sharing patches and thoughts.

9   History

0.4.5 : 2007-07-25

Added PLS playlist format.

Fixed a unicode bug reported by Jussi Ekholm. The information from the id3reader module wasn't encoded properly so the program crashed at non-ASCII charcters in the meta data for extm3u format.

Changed the encoding of the documentation to UTF-8.

0.4.4 : 2005-09-01
Bug in cache code regarding relative and absolute paths was fixed. The path was saved in the cache file the first time an entry was created as absolute or relative path depending on the -r/--relative-paths switch and used in this form in subsequent calls to the programm without taking the presence or absence of the -r switch into account.
0.4.3 : 2005-06-17

The program requires Python 2.4.x now or a recent package of the optparse module which is available seperately under the name optik.

Detailed messages of what is going on while the directories are scanned for media files can be controlled by the command line switches --quiet and --verbose.

To be more compatible with WinAMP playlists the paths in the playlist file are absolute now. There is a switch to get relative paths like before.

The ID3 module can only read ID3 version 1 tags. Now Ned Batchelder's id3reader module is prefered if available, as it reads recent versions of ID3 tags too.

Scanning huge collections takes some time and rescanning them after adding or changing some files takes the same or even a little more time. The meta data can now be cached into a file which cuts down the time for rescanning significantly.

0.3 : 2004-12-03

Finally meta data is extracted from MP3 and Ogg Vorbis files so this thingy does actually more than the find-based Bash script I used before for the job.

The script became a little bit more "silent" -- only directory names are printed and not every discovered media file.

0.2 : 2004-11-08

The playlist is sorted now and can be shuffled with an option (--shuffle). It's possible to give more than one directory name at the command line.

There are many changes under the surface to allow extensions to read meta data from the media files and to support different output formats too. That's the reason for the new -f and --output-format options which are not very useful at the moment because the only allowed value is m3u which happens to be the default anyway.

0.1.1 : 2004-10-23
Fixed a minor(?) packaging problem. The archive content is now in an own subdirectory. Much more standard on Unices. :-)
0.1 : 2004-10-20
Initial release. Creates simple playlists in M3U format.

10   ToDo

  • exclude files by name pattern (simple or even regular expressions),
  • list known file name extensions in --help output,
  • options for output encoding and assumed MP3 tags encoding,
  • (x)html output,
  • add more playlist formats (B4S, amaroK, ...),
  • filter local directory prefix ("./") from file names in the playlist,
  • add more possibilities to read meta data (other ID3 modules, kfile, etc.),
  • debug / dump output format,
  • per directory playlist,
  • use SQLite (or other SQL DB) for caching,
  • option to use existing AmaroK DB (SQLite) as cache (read only),
  • option to prune cache file.

11   Bugs

None known yet. If you find some please send me a mail.