Development
PyKaraoke is an open source project released under the LGPL. The development pages are hosted on Sourceforge.The project can be broken down into two main components:
* Karaoke Player modules (pycdg, pykar and pympg)
* GUI frontend/playlist (pykaraoke)
Player Modules
You can use the karaoke player modules in your own programs by simply importing the modules. If you would like to add CDG file support to your player, just import pycdg.py and instantiate a cdgPlayer() class. Similarly you can import pykar.py and instantiate midPlayer() if you would like to add MIDI/KAR support or import pympg.py and instantiate mpgPlayer() if you would like to add a simple MPEG player to your application.
The player modules require the pygame library, which is used for audio and video output. The CDG and KAR modules also require the Numeric python module - this is used for faster arithmetic on the pixel arrays.
GUI Frontend
A simple frontend has been created using WxPython. This provides a GUI interface to the karaoke player modules.
Portability
The libraries used by PyKaraoke have been selected for their portability. The utilised libraries (pygame, WxPython, Numeric) are available for at least Windows, Linux, FreeBSD, NetBSD, GP2X and OS X.
The majority of development and testing has been done on Linux, but PyKaraoke also works on FreeBSD, NetBSD, GP2X and Windows. As far as we are aware, PyKaraoke has not been tested on OS X - if you would like to help with this, we would love to hear from you.
Module HowTo
You can incorporate a CDG, KAR or MPEG player in your own projects by importing the relevant module. The classes cdgPlayer, midPlayer and mpgPlayer are exported by the pycdg, pykar and pympg modules.
The CDG module can be used as follows:
import pycdg
from pykmanager import manager
player = pycdg.cdgPlayer("/songs/theboxer.cdg")
player.Play()
manager.WaitForPlayer()
The MIDI/KAR module can be used as follows:
import pykar
from pykmanager import manager
player = pykar.midPlayer("/songs/theboxer.kar")
player.Play()
manager.WaitForPlayer()
The MPEG module can be used as follows:
import pympg
from pykmanager import manager
player = pympg.mpgPlayer("/songs/theboxer.mpg")
player.Play()
manager.WaitForPlayer()
These five lines are all you need to start a player. All three classes also export Close(), Pause(), Rewind(), GetPos(), GetDisplaySize() and SetDisplaySize(). Because pycdg, pykar and pympg export the same functions, your program can use the same code to work with either type of player object. i.e. player.Pause() can be used whether the player is a cdgPlayer object, a midPlayer object or an mpgPlayer object.
There are two optional parameters to the initialiser, errorNotifyCallback and doneCallback.
errorNotifyCallback, if provided, will be used to print out any error messages (e.g. song file not found). This allows the module to fit together well with GUI playlist managers by utilising the same GUI's error popup window mechanism (or similar). If no callback is provided, errors are printed to stdout. errorNotifyCallback should take one parameter, the error string, e.g.:
def errorPopup (ErrorString):
msgBox (ErrorString)
doneCallback can be used to register a callback so that the player calls you back when the song is finished playing. The callback should take no parameters, e.g.:
def songFinishedCallback():
msgBox ("Song is finished")
To register callbacks, pass the functions in to the initialiser:
cdgPlayer ("/songs/theboxer.cdg", errorPopup, songFinishedCallback)
These parameters are optional and default to None. If the initialiser fails (e.g. the song file is not present), __init__ raises an exception.
Credits
All of the information on the CDG file format was learned from Jim Bumgardner's excellent CDG Revealed tutorial.
Contributors
* Kelvin Lawson - Developer
* Will Ferrell - Developer
* David Rose - Developer
* Jay R Ashworth - Design
* Mantas Kriaučiūnas - Non-ASCII support, scriptability
* Miriam Ruiz - Debian packages
* Elias Mandouvalos - FreeBSD packages
* Thomas Klausner - NetBSD packages
