UI hints
========

  * Enqueue tracks in the playlist with Ctrl+RightButtonClick, like in
    Amarok.

  * Mark a track as "stop after this track" with Ctrl+MiddleButtonClick.

  * Press return in the tree view search line to append all the search
    results to the playlist, starting playback if the playlist was empty
    and the player stopped. Press return as well in the playlist search
    line to start playing the first track in the search result.


DCOP interface
==============

Minirok exports a DCOP interface containing functions to perform
Playlist actions (play, pause, playPause, stop, next, previous,
stopAfterCurrent), and a function to retrieve the currently playing
track, "nowPlaying".

This last functions comes in two flavours: without an argument, it will
return a string like "Artist - Title", or just "Title" if there's no
known artist. However, you can pass a string argument that will be
formatted against a dict of the tags with the Python % operator. For
example:

  % dcop minirok player nowPlaying "%(Artist)s - %(Title)s (%(Album)s)"

Do not forget the "s" after the brackets, it's needed by Python.

There is also a appendToPlaylist function, which does the same as
`minirok --append`. The function takes a QStringList as argument, so to
invoke it you must place the arguments between square brackets, like this:

  % dcop minirok player appendToPlaylist [ /path/to/file.mp3 ... ]

Note that you have to specify the full paths of files, or it won't work.

Finally, there is a toggleWindow function, which hides/shows the main
window.


Global shortcuts
================

One of the top items in the list of features I wanted was global shortcuts,
since I can't live without them. However, having them directly supported
in the application turned out impossible, because there's a bug in PyKDE
that makes the program crash when they're used. (See gaccel.py in the
pykde-bugs/ directory for an example and a link to a mailing list thread.
With a bit of luck, the Python bindings for KDE 4 won't suffer from this
bug.)

So the next option is using KHotKeys and DCOP. A default set of bindings
is provided, but it is disabled by default. To activate it, go to
Control Centre -> Regional & Accessibility -> Input Actions; there
should be a "Minirok" group there. Uncheck the "Disable" box, and voilà.
You can of course change the default keys.

If a Minirok group is not available, this probably means you're running
Minirok directly from the source tree, or that something went wrong with
kconf_update. You can go to the General Settings tab, and import directly
minirok.khotkeys by specifying the full path to its location (in the
source tree is in the config/ subdirectory).


Regular expressions
===================

Instead of reading tags from audio files, a Python regular expression
can be used to guess them from the filename. The full patch will be
searched, but the regular expression does not need to match the full
path (for pythonistas, it'll be a re.search, not a re.match). The tags
will be extracted from the named groups of the match, namely: "title",
"artist", "album", and "track".

Even if a regular expression is configured, tags will still be read from
the files in the background. This can be configured in the Preferences
dialog so that they are never read, or only if the regular expression
did not match. A regular expression match with an empty "title" group is
considered as failure to match.

An example of a simple regular expression that matches "Artist - Title.mp3"
would be:

    '/((?P<artist>.+?) - )?(?P<title>.+)\.[^.]+$'

A more elaborated one, the one I use:

    '(?i).*?/(\(\d+\) )?(?P<album>[^/]+(/(CD|vol|disco) *\d+)?)/((?P<track>\d+)_)?((?P<artist>[^/]+?) - )?(?P<title>[^/]+)\.[^.]+$'

This matches, case insensitively:

    .../Album/Artist - Title.mp3
    .../Album/07_Artist - Title.mp3
    .../(year) Album/07_Artist - Title.mp3
    .../(year) Album/cd 1/07_Artist - Title.mp3

For more information on Python regular expression:

    http://docs.python.org/lib/module-re.html
    http://docs.python.org/lib/re-syntax.html