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

:author: Marc 'BlackJack' Rintsch
:contact: marc@rintsch.de
:date: 2004-11-08
:version: 0.4
: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 format.  This very simple format is used or at least understood by
the vast majority of media players on different platforms.

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.3 or higher.


Commandline Options
===================

  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -oOUTFILE, --output=OUTFILE
                        name of the output file or '-' for stdout (default)
  -fOUTPUT_FORMAT, --output-format=OUTPUT_FORMAT
                        format of the output (default: m3u)  
  --shuffle             shuffle the playlist before saving it.


Examples
========

Scan the directory `/data/music` and write all media files into a
(sorted) playlist named `playlist.m3u`::

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

Scan the directories `/data/music/Various` and
`/data/Music/Soundtracks` and write a shuffled playlist to standard
output::

  ./mkplaylist.py --shuffle /data/music/Various     \
                            /data/music/Soundtracks


History
=======

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
====

- Support for meta data like length, title etc.,
- exclude files by name pattern (simple or even regular expressions),
- list known file name extensions in ``--help`` output,
- (x)html output,
- use logging module and add switches ``-v`` and ``--verbose``,
- add more playlist formats,
- filter local directory prefix ("./") from file names in the playlist.


Bugs
====

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


Copyright
=========

Copyright  2004 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/
.. _Ogg Vorbis: http://www.xiph.org/ogg/vorbis/
.. _Python: http://www.python.org/
