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

:author: Marc 'BlackJack' Rintsch
:contact: marc@rintsch.de
:date: 2004-10-23
:version: 0.2
: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

The directory is the one where the scripts starts to search for media
files.


Description
===========

The script scans the given directory 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):

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


Examples
========
::

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

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


History
=======

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,
- sort the list before writing,
- add a switch for shuffling the list,
- (x)html output,
- use logging module and add switches ``-v`` and ``--verbose``,
- and add more playlist formats,
- take more than one directory at the command line and default to the
  current directory if no directory is given at all.


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/
