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

Minirok is a small music player written in Python for the K Desktop
Environment. As its name hints, it's modelled after Amarok (1.4), 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 the old Amarok, 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:

  * DBus 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

  * 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 was a very happy Amarok user for more than
three years, and that I think at least version 1.4 is a terrific player
which deserved all the success it got (I haven't tried version 2 at all).

Anyway, I always wished for some things to be different. 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.5 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 should be able to install directly with apt-get, and
you can check if there's a more recent version 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

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

  * The json or simplejson modules (shipped with Python 2.6 already)
    Debian and Ubuntu: python-simplejson | python (>= 2.6)
    Source: http://undefined.org/python/#simplejson

  * 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:

  * dbus-python - enables controlling the player from scripts, à-la-DCOP
    Debian and Ubuntu: python-dbus
    Source: http://www.freedesktop.org/wiki/Software/DBusBindings#python

    (You'll also need DBus support compiled-in in the PyQt bindings
    above; in Debian and Ubuntu, just install python-qt4-dbus in
    addition to python-dbus. Additionally, you must be running Qt 4.4.0
    or later for the DBus interface to work.)

  * python-psutil - makes the scrobble lock handling more robust
    Debian and Ubuntu: python-psutil
    Source: http://code.google.com/p/psutil/


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

Minirok is written by Adeodato Simó (dato@net.com.org.es), and licensed
under the terms of the MIT license.

vi: sw=2