
---------------------------------------------------------------------------

Release:      pykaraoke v0.5
Date:         12/07/2006
Author:       Kelvin Lawson <kelvinl@users.sourceforge.net>
License:      LGPL
Website:      http://www.kibosh.org/pykaraoke/
Contributors: William Ferrell <willfe@gmail.com>
              David Rose <pykar@ddrose.com>

---------------------------------------------------------------------------

INTRODUCTION

PyKaraoke is a karaoke player for Linux, FreeBSD, Windows and GP2X.

The following song formats are supported:
 * CDG (MP3+G, OGG+G)
 * MIDI/KAR
 * MPEG

No song files are provided - this package provides you with the player
needed to play your own karaoke song files.

---------------------------------------------------------------------------

WHAT'S NEW

PyKaraoke has undergone a major overhaul for this release thanks to the new
developer on the project David Rose. David has made huge improvements to
the performance of the CDG player, making it possible to run PyKaraoke on
older, low end machines. The CDG player now offers smoother scrolling, and
support for horizontal scrolling CDGs. The MIDI player has benefited from
a number of improvements, including smooth font scaling at any window size,
and word-wrapping for systems with a small screen size.

He has also added the pykaraoke_mini interface, suitable for environments
lacking a keyboard/mouse, or home karaoke parties using a remote control.

Finally PyKaraoke has also been ported to the handheld GP2X console, and
now runs on Windows, Linux, FreeBSD and GP2X.

---------------------------------------------------------------------------

INSTALLATION (LINUX, SOURCE INSTALLS)

PyKaraoke requires the following libraries to be installed:

 * Python (www.python.org)
 * Pygame (www.pygame.org)
 * WxPython (www.wxpython.org)
 * SDL source distribution (www.libsdl.org)

PyKaraoke now offers two builds: an ultra-portable Python version, and a
highly optimised C version. The default install is to use the faster C 
version which requires the SDL source distribution for compilation 
purposes. All supported platforms should support compilation of the C
version, but the portable Python-only version will continue to be 
supported. Python-only installs do not require the SDL source 
distribution, and instead require the Numeric Python module 
(numpy.sourceforge.net).

If these libraries are not already installed on your system, you can
download them from the websites listed.

Linux users may find these packages are available directly from their
distro's package manager. For example Debian users can install all
prerequisites using:
	# apt-get install python python-pygame libwxgtk-python libsdl-dev

With the prerequisites installed, unzip the release and run the following
as root:

# python setup.py install

This installs the executables into /usr/bin, and you can then run
PyKaraoke from anywhere using "pykaraoke".

Alternatively you can run PyKaraoke without installing by simply
unzipping and running "python pykaraoke.py" from the unzip location.
Beware that this method requires the Numeric library, and runs the
more portable but slower Python-only version of the CDG player.

---------------------------------------------------------------------------

INSTALLATION (WINDOWS)

Windows users can install PyKaraoke by simply downloading and running the
installer executable. This installs all prerequisite libraries, and adds
icons in your start menu to run PyKaraoke.

If you prefer, you may choose to build the Windows version from source. We
will assume you are familiar with the steps involved for installing a
Python distribution from source on Windows; they are similar to those for
the Linux installation, below. You will need to have pygame
(www.pygame.org) and wxpython (www.wxpython.org) installed. You will also
need to download and unpack the SDL source distribution (www.libsdl.org) 
into the same directory with PyKaraoke, under its default name, which will
be something like "SDL-1.2.11" (by default, setup.py will search for any
directories named SDL* in the current directory). You will then invoke the
command:

python setup.py install

You may also choose to unpack the source distribution elsewhere and
specify its path with --sdl-location=/path/to/SDL on the above command.

---------------------------------------------------------------------------

CREATING WINDOWS INSTALLERS

To build a Windows installer, you additionally need to have py2exe
(www.py2exe.org) and NSIS (nsis.sourceforge.net) installed, and then you
may invoke:

python setup.py nsis

This will create an executable called pykaraoke-<current_version>.exe
in the current directory, which will be a standalone Windows installer
program you may then distribute to other Windows users. You don't
need to install PyKaraoke before building an installer for it.

---------------------------------------------------------------------------

INSTALLATION (MIDI/KAR FILE SUPPORT ON LINUX)

Windows users can enjoy MIDI/KAR file support using the standard
installation procedure.

MIDI/KAR support on Linux, however, requires the following:

 * Timidity++ (timidity.sourceforge.net)
 * Sound/patches for Timidity++

There are various sound patch collections available for Timidity++. Users
of PyKaraoke have used freepats and Eric Welsh's GUS patches.

To install Timidity++ on Gentoo together with Eric Welsh's patches use:

	# emerge timidity++ timidity-eawpatches

---------------------------------------------------------------------------

INSTALLATION (GP2X)

PyKaraoke can run on the GP2X handheld console, giving you a Karaoke
machine that fits in your pocket. You may find it easiest simply to 
install the prebuilt binary version. The prebuilt version already
includes Python and the necessary supporting libraries (except SDL, which
you should already have installed on your GP2X). Simply unpack this
archive onto your SD card; it will expand to a small hierarchy of files.
One of these directory names is pykaraoke/songs, which will be empty; you
should put your song files in this pykaraoke/songs directory. The first 
time you install, and each time you add new song files to this directory,
you should run the "rescan_songs" script to rebuild the database with the
new song files; but most of the time, you should start PyKaraoke simply by
running the script named "pykaraoke".

If, for some reason, you wish to build your own version for the GP2X, this
is possible, but there will be a bit of work involved.  You will need to
install the GP2X development kit, which includes a cross-compiler for the
GP2X. You should next use this cross-compiler to build and install SDL and
PyGame, so that you have the appropriate source headers and matching 
binaries for these library. Note it may be necessary for you to apply 
patches to SDL_mixer to support using tremor and libmad, which are 
alternative libraries used for playing OGG and MP3 files, respectively.
(The default OGG and MP3 implementations used by SDL_mixer make heavy use
of floating-point arithmetic, which does not perform well on the GP2X.)
You will also need to patch the timidity/config.h file to reduce the MIDI
rendering demands on the CPU. All of these patches are available for 
download elsewhere.

Once all that is done, you need to use the cross compiler to build
_pycdgAux.so. A sample script called cross-build-gp2x.sh is provided to do
this. Then it is simply a matter of copying this file, along with all of 
the .py files, to the GP2X.

---------------------------------------------------------------------------

INSTRUCTIONS

If you used the install script you can start the player using:

	$ pykaraoke

Otherwise, start the player using:
	$ python pykaraoke.py

Once started, you will be presented with the Search View. From here you
can search through the karaoke songs in your database. You must first set
up your searchable song database, however, by clicking "Add Songs".

On the Add Songs popup you can add the folders containing your karaoke
songs, and perform your initial scan. This can be slow if you have a lot
of files, so PyKaraoke searches the disk once to build the database, and 
actual searches in the search engine only do a fast search in the database.

Once the scan is performed, you can save your database so that it will
still be available the next time you run PyKaraoke.

You can also specify various options when building the database, such as
filtering out which type of song file you wish to include in the database.
You can also request that the scan looks inside ZIP files for any karaoke
files contained in them.

Don't forget to run the scan again if you collect more karaoke files in
your folders.

With the search database set up, you can now enter searches in the search
engine in the main window. Matched search results will fill up in the left
pane, from where you can play them directly (double-click) or add them to
the playlist (right-click popup).

The right pane contains your playlist. You can perform your searches and
add them to the playlist, without actually starting a song playing. When
you are happy with the playlist collection, double-click on the song you
would like to start on, and a player window will open. When that song is
finished PyKaraoke moves on to the next song in your playlist. You can
delete single songs from the playlist, or clear the entire list by right-
clicking items in the playlist.

If you do not wish to use the search engine functionality, there is also a
Folder View, which can be selected using a drop-down in the main window.
From here you can browse the folders on your disk, and select individual
tracks for playing, or adding to the playlist.

---------------------------------------------------------------------------

MINI VERSION

There is now a reduced-interface frontend for PyKaraoke, which you can
invoke with:

	$ pykaraoke_mini

Or:
	$ python pykaraoke_mini.py

This is a more primitive interface which runs in the same window that
is also used for displaying the lyrics of the Karaoke songs. It is
specifically designed to be a useful interface with a minimal input
device, for instance with a joystick or a remote control, for those
environments when you don't have convenient access to a full keyboard and
mouse. It is the default interface on the GP2X handheld.

The pykaraoke_mini interface presents a scrolling window that lists all of
the songs in your database in alphabetical order by filename (but you can
also sort them by song title or artist name; see TITLES AND ARTIST NAMES
below).

You can easily navigate through this list with the up and down arrow keys,
and press enter to select a song.  If you hold down the arrow keys, the
highlight gradually accelerates until it is moving quite fast, so it
doesn't take long to navigate through even a very large list. You can also
use the PageUp and PageDown keys to move a screen's worth at a time.

By default, the font is quite large, chosen to be easily visible on a
Karaoke monitor across the room. You can change the font size at run time
(for instance, to make more text appear on the page) by pressing the - and
+ keys.  This also affects the size of the font chosen for the lyrics if
you select a .kar file.

There is no search function in the mini player; the list always includes
the entire database (but you can type a few letters to go straight to the
song that begins with that string). There is also no playlist feature; you
must pick each song and play it one at a time.

The mini player uses the same database as the full-featured player, so
you may need to launch the full player from time to time to re-scan the
song database or update the directory list. Alternatively, you can use the
command-line interface to do this:

pykaraoke_mini --set_scan_dir=/my/song/directory

   Removes any directories you had already set, and adds
   /my/song/directory as the only song directory.

pykaraoke_mini --add_scan_dir=/my/other/song/directory

   Adds /my/other/song/directory to the list of directories to scan.
   This option may be repeated.

pykaraoke_mini --scan

   Actually rescans all of the recorded directories into the database.

---------------------------------------------------------------------------

GP2X USAGE

On the GP2X you will run PyKaraoke with the pykaraoke_mini interface (see
above). This interface presents your song files in a long list. While 
viewing this list, use the joystick up and down to navigate to a song, or
hold it down to scroll very rapidly. Use the left and right shoulder
buttons to move a page at a time. Press B or X to select a song, and Y
to exit. If you have supplied song titles and artist names with a 
titles.txt file (see below), you can change the sort order of the list
with the A button.

---------------------------------------------------------------------------

SONG TITLE AND ARTIST NAMES

By default, songs are listed in the search results panel by filename.
If you name your karaoke files with descriptive names, that may be all
you need.  However, as of PyKaraoke version 0.5, there is now a
feature which can record a separate title and/or artist name along
with each song.  These names will appear in separate columns in the
search results, and you can click on the column header to re-sort the
selected songs by the indicated column; for instance, click on the
"Artist" column to sort all of the songs in alphabetical order by
artist name.  In the mini player, press the TAB key to change the sort
mode between title, artist, and filename.

To get the artist and title names in the database, you must create a
file called titles.txt in the same directory with your song files, and
add one line for each song file, of the form:

filename<tab>title

or

filename<tab>title<tab>artist

The separator character between the fields must be an actual TAB
character, not just a sequence of spaces.  If you want to use
international characters in the title and artist names, save the file
using the utf-8 encoding.

Once you have created this file, re-scan the directory to read it into
the database.

---------------------------------------------------------------------------

COMMAND LINE VERSION

PyKaraoke is actually a GUI frontend which controls three libraries, pycdg
for CDG files, pykar for MIDI/KAR files, and pympg for MPEG files. If you 
do not wish to use the GUI you can actually start a player directly from 
the command-line (or by associating file-types in your operating system).

You can play MP3+G or OGG+G files using:
	# python pycdg.py songfilename.cdg

For a list of command-line options for pycdg.py, run:
	# python pycdg.py --help

KAR/MID files can be played using:
	# python pykar.py karfilename.mid

MPEG files can be played using:
	# python pympg.py mpegfilename.mpg

Note that if you used the install script, the above scripts can be started
using "pycdg", "pykar" or "pympg" from anywhere.

---------------------------------------------------------------------------

COMMON INSTALLATION ISSUES

LINUX DISTROS WITHOUT MP3 SUPPORT

Due to MP3 licensing issues, some distros such as Fedora Core and SUSE may
not include MP3 support in the SDL_mixer library. If this is the case you
will see the following message when attempting to play an MP3+G track:

    pygame.mixer.music.load(self.SoundFileName)
    error: Module format not recognized

To rebuild SDL_mixer with MP3 support, you need to install the smpeg-devel
package, and download and build SDL_mixer from source. The source tarball
for SDL_mixer can be downloaded from 
http://www.libsdl.org/projects/SDL_mixer/ and should be built as follows:

    # ./configure --prefix=/usr --enable-music-mp3
    # make; make install

You may need to modify the --prefix option depending on where
libSDL_mixer.so is installed on your distro. The above example assumes it
will be installed to /usr/lib/libSDL_mixer.so.

A full example SDL_mixer build procedure for Fedora Core has been 
provided by a PyKaraoke user:

    # rpm -ivh smpeg-devel-0.4.4-0.rhfc1.dag.i386.rpm
    # rpm -ev --nodeps SDL_mixer
    # tar xzvf SDL_mixer-1.2.6.tar.gz
    # cd SDL_mixer-1.2.6
    # ./configure --prefix=/usr --enable-music-mp3
    # make; make install

SuSE users may also need to install the slang-devel package.


LINUX: NO AVAILABLE AUDIO DEVICE

Linux users may get the following error message:

    pygame.error: No available audio device

You should try switching between libsdl-oss and libsdl-alsa.


AMD64 INSTALLATIONS

If you are running on the AMD64 platform (and possibly others) you may see
this error on startup:

Exception in thread Thread-1:
Traceback (most recent call last):
	...
ValueError: unsupported datatype for array

If this occurs, you need to download and install the latest development
release of pygame. Follow the instructions at http://pygame.org/cvs.html to
obtain the latest development release, then:

1. Build the new release by running:
   # python makeref.py
   # python setup.py install --prefix=/path/to/temporary/spot
2. Find the directory named "pygame" within /path/to/temporary/spot/lib (on a
   development machine, the path was lib/python2.4/site-packages/pygame) and
   copy or move it (all of it, including the directory itself) into the
   folder containing pycdg.py and the rest of the PyKaraoke files.

The CDG player should then work properly.


SLACKWARE AND TIMIDITY++

Slackware users may find that the MIDI player cannot find the timidity 
configuration files. You can fix this by creating a link from the PyKaraoke
installation directory:

    # cd pykaraoke_install_dir
    # ln -s /usr/share/timidity/timidity.cfg .
    # ln -s /usr/share/timidity/instruments 


GP2X ISSUES

When you store your Karaoke files within a zip archive, PyKaraoke has
to unpack them to a temporary file in order to play them. This all
happens transparently; normally, PyKaraoke will unpack them within the
/tmp directory.

However, on the GP2X the /tmp directory is mounted as a 5MB Ramdisk. This
is good, because it's very fast; but it means you can't unpack a file
larger than about 5MB. Many mp3 and ogg files are smaller than 5MB, but
depending on the bitrate you used to encode them, you may also have some
that are larger than this. This means you cannot play these large song 
files on your GP2X if they are stored within a zip file.

There are several possible workarounds to this.

(1) Reconfigure your GP2X to make the size of the /tmp directory
    larger. We don't recommend doing this.

(2) Reencode all of your mp3 or ogg files so that they are smaller
    than 5MB.  This is certainly a fine option; you will lose a bit of
    quality, but probably not much.

(3) Uncomment the indicated lines in pykaraoke.gpe to configure
    PyKaraoke to store temporary files on the SD card instead. This,
    however, will be much slower; and it does require that you keep a
    certain amount of space available on your SD card.

(4) Don't store your mp3 and ogg files in a zip file. Just store the
    cdg files there, if you want to use zip files at all, but leave
    the mp3 files in the directory, next to the zip file--PyKaraoke
    can still find them there. You won't get any compression benefit
    from storing the mp3 or ogg files in a zip file, anyway. If you
    are using zip files for organization, use a subdirectory instead.

We recommend approach (4).

---------------------------------------------------------------------------

SUGGESTIONS

This is an early release of pykaraoke. Please let us know if there are any
features you would like to see added, or you have any other suggestions or
bug reports. Contact the project at <kelvinl@users.sourceforge.net>

---------------------------------------------------------------------------
