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

Minirok is a small music player written in Python for the K Desktop
Environment. As its name hints, it's modelled after Amarok, but with a
reduced set of features. In particular, it is designed to cover all the
needs and wishes of the author, leaving everything else out. The look
and feel is almost identical to Amarok's, though.

The main interface is a *tree view of the filesystem*, with a playlist
that can only be populated via drag and drop. There is no collection
built from tags, so it's targeted at people whose collection is
structured in a tree already at the filesystem level. Searches can be
performed both in the tree view and the playlist.

Other features include:

  * DCOP interface for controlling the player and retrieving the
    currently played track, among other things

  * alter the playing order in the playlist by queueing tracks;
    stop after a certain track; repeat track or playlist; random mode;
    undo and redo

  * reading of tags when adding to the playlist can be disabled by
    specifying a regular expression to extract them from the filename

  * submission of played songs to Last.fm (with lastfmsubmitd)

  * support for the classic Amarok "funky-monkey" theme

  * global shortcuts


Audio formats
=============

Minirok supports playing and reading tags from MP3, Ogg Vorbis, FLAC and
Musepack, which are the formats I use. If you need some other format,
please send me a polite e-mail and I will add them if GStreamer and
Mutagen support them (which they probably will).


Motivation
==========

Let me start by saying that I've been a happy Amarok user for more than
three years, and that I think it's a terrific player which deserves all
the success it can get. That said, I've always wished some things were
different... who doesn't? :)

In particular, I always missed a tree view of the filesystem, because my
music collection is highly structured, and it would've been enough. The
collection seemed an overkill to me, though it worked very nicely for me
until:

  (1) they "fixed" Bug#116127. Read the bug log for details, and my
      comment #10 in particular. The bottom line is that my collection
      became uselessly cluttered, because I have a lot of different
      artists in my collection, but a high percentage with only one song
      coming from compilation albums.

  (2) I got a laptop. I discovered that despite mounting desktop:/mnt/mp3
      via sshfs at laptop:/mnt/mp3, I could not share the collection.db
      file (Debian's Bug#437873, I think). Plus I could not have two
      collections, one eg. for the mounted /mnt/mp3, and another for a
      local ~/mp3 archive.

So on summer 2007 I found myself with much spare time, and one night
the idea of writing a player tailored to my needs popped up: I'd get
a personalized player, get rid of my free time, and learn PyKDE as a
bonus. A win-win-win situation! I also like having Python projects to
hack on, so that too.


Requirements
============

Minirok is written in Python, version 2.4 or later is required. If it's
available from your distribution, I recommend you install that package,
since it'll take care of installing everything necessary. For Debian and
derivatives, you can grab the latest package from here:

    http://chistera.yi.org/~adeodato/code/minirok/packages

For installing from source, here's a list of the *required* libraries
for the program to run:

  * PyQt and PyKDE (version 4)
    Debian and Ubuntu: python-qt4, python-kde4
    Source: http://www.riverbankcomputing.co.uk/pyqt/download.php
            http://www.riverbankcomputing.co.uk/pykde/download.php (XXX-KDE4?)

  * Mutagen (audio metadata library)
    Debian and Ubuntu: python-mutagen
    Source: http://www.sacredchao.net/quodlibet/wiki/Development/Mutagen

  * The GStreamer media framework, in particular:

    + The GStreamer Python bindings
      Debian and Ubuntu: python-gst0.10

    + Plugins, in all the flavours needed to cover your audio formats:
      	- MP3: gst-plugins-ugly *and* gst-plugins-good
      	- Ogg Vorbis: gst-plugins-base
      	- FLAC: gst-plugins-good
      	- Musepack (MPC): gst-plugins-bad
      Debian and Ubuntu: gstreamer0.10-plugins-ugly, gstreamer0.10-plugins-base,
	gstreamer0.10-plugins-good, gstreamer0.10-plugins-bad

    + A suitable audiosink, for example ALSA.
      Debian and Ubuntu: gstreamer0.10-alsa

    Source: http://gstreamer.freedesktop.org

The following dependencies are optional and enhance Minirok in some way:

  * lastfmsubmitd - enables submission of played tracks to Last.fm
    Debian and Ubuntu: lastfmsubmitd
    Source: http://www.red-bean.com/~decklin/software/lastfmsubmitd

    (See README.Lastfm for tips on configuring it.)


Author and license
==================

Adeodato Simó <dato@net.com.org.es>
Licensed under the terms of the MIT license.

vi: sw=2