======================
 mkplaylist.py Manual
======================
------------------
A playlist creator
------------------

:author: Marc 'BlackJack' Rintsch
:contact: marc@rintsch.de
:date: $Date: 2005-11-19 15:57:33 +0100 (Sat, 19 Nov 2005) $
:version: 0.7
:revision: $Rev: 790 $
:copyright: This document has been placed in the public domain.

.. meta::
   :description: Manual for the mkplaylist.py script.
   :keywords: playlist, m3u, WinAMP, XMMS, Python

.. contents::
.. sectnum::


Name
====

mkplaylist.py -- creates playlists from directory trees.


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.


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.


Known File Name Extensions
--------------------------

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

.. table:: 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
  ========= ============================


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.


MP3
---

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

:MAD: http://www.underbit.com/products/mad/
:pyMAD: http://spacepants.org/src/pymad/

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.


Ogg Vorbis
----------

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


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)
  -f OUTPUT_FORMAT, --output-format=OUTPUT_FORMAT
                        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)
  --cache-file=CACHE_FILE
                        name of the cache file (default: ~/.mkplaylist.cache)
  -v, --verbose         be more verbose.
  -q, --quiet           be really quiet.


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     \
                                      /data/music/Soundtracks


Output Formats
==============


M3U
---

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


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.


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.


Credits
=======

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


History
=======

0.4.5 : ?
  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.


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.


Bugs
====

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


Copyright
=========

Copyright © 2004, 2005 Marc 'BlackJack' Rintsch <marc@rintsch.de>

This is free software; see the source for copying conditions. There is
NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.


.. _Free Lossless Audio Codec: http://flac.sourceforge.net/
.. _ID3: http://id3-py.sourceforge.net/
.. _ID3reader: http://www.nedbatchelder.com/code/modules/id3reader.html
.. _Ogg Vorbis: http://www.xiph.org/ogg/vorbis/
.. _Optik: http://optik.sourceforge.net/
.. _Python: http://www.python.org/
