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

Release:       cdgtools v0.3.2
Date:          02/06/2009
License:       LGPL
Website:       http://www.kibosh.org/cdgtools/
Authors:       Kelvin Lawson <kelvinl@users.sf.net>
               Will Ferrell <willfe@gmail.com>

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

INTRODUCTION

cdgtools is a suite of software tools for handling CD+G karaoke disks on Linux
as well as other operating systems.

It currently includes:

 * cdgrip:           Rip CD+G disks to MP3+G (command-line tool)
 * cdg2bin:	     Convert MP3/OGG+G tracks to CD+G disc image
 * cdggui:           GUI version of cdgrip
 * cdgdao/cdgparse:  Python modules for handling CD+G data
 * cdg2text:         Convert binary .cdg files to a textual representation 
 * cdgcddb:          FreeDB/CDDB query module

cdgtools is evolving, let us know if there are any other CD+G tools that you
would like to see added.

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

CDGRIP / CDGGUI

cdgrip and cdggui allow you to rip your CD+G disks and encode them to MP3+G
files. You can optionally look up the CD+G disk using FreeDB/CDDB to get actual
track names for the resultant .mp3 and .cdg files.

cdgrip is a command-line tool, and cdggui provides you with a GUI, but both
tools perform the same function - you can choose whichever interface suits you
best.

The tools works together with cdrdao, and should therefore run on any operating
system for which cdrdao is available. Development and testing was done on
Linux.

Note that not all drives support reading CD+G disks. To be able to read the
graphics data, your drive needs to support reading RW subchannel data.  You can
use any CD/DVD drive that supports either raw interleaved mode or deinterleaved
mode.

Requirements for cdgrip are:

 * Python
 * cdrdao
 * lame

Adding support for other CD ripping packages or audio encoders is relatively
easy. If cdrdao or lame are not available on your system, feel free to suggest
adding support for alternative packages.

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

CDG2BIN

cdg2bin is a command-line utility to create a cdrdao-compatible image and cue
sheet (TOC file) from one or more CD+G tracks. It can convert both MP3+G and
OGG+G tracks, and can handle them plain (two files per track, one .cdg and one
.ogg or .mp3) or archived (.zip, .tar.gz, and .tar.bz2 are supported -- one
track per archive).

It supports byte-swapping as well to ensure audio data is in the correct byte
order for recording. On x86 and AMD64 platforms, the default options should
produce correct results.

The resulting .bin and .cue files can be immediately burned by cdrdao.
Currently, only "cooked" mode is supported (thus only CD recorders that support
writing cooked R-W subchannel data are currently supported).

Requirements for cdg2bin:

 * Python
 * lame (for decoding MP3 files)
 * oggdec (for decoding OGG files)

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

CDGDAO/CDGPARSE

These are general purpose Python modules for accessing CD+G data in binary rips
of CDs. They can be used to create CD+G ripping software, and are easily
extended to support rippers other than cdrdao.

Requirements for these modules:

 * Python

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

CDG2TEXT

cdg2text is a debugging tool that generates textual representations of your
binary .cdg files.

Requirements for cdg2text:

 * Python

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

CDGCDDB

cdgcddb is a module for querying FreeDB/CDDB records. It is not CDG-specific
and can therefore be used as a general purpose FreeDB/CDDB module.

Requirements for cdgcddb:

 * Python

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

INSTALLATION

cdgtools can be unpacked and run directly from the unpack location.

To use cdgtools you need to install the prerequisites. Linux users should find
these packages available directly from their distro's package manager.  For
example Gentoo users can install all prerequisites using:

    # emerge python lame cdrdao

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

CDGGUI QUICK START

cdgtools does not perform the actual ripping from CD/DVD drives - cdrdao is
used for that. Before calling cdggui, you should use cdrdao to rip your CD+G
disk. This generates a BIN file and a TOC file, which you can then open in
cdggui to do the MP3+G encoding.

To use cdrdao, try the following from the command-line (replacing the --device
option by the path to your CD or DVD device):

   $ cdrdao read-cd --driver generic-mmc-raw --device /dev/cdroms/cdrom0
                    --read-subchan rw_raw mycd.toc

You may need to use a different --driver option or --read-subchan mode to
cdrdao depending on your CD device. For more in depth details, see the full
cdrdao instructions below.

Once the disk has been ripped you can open it in cdggui:

   $ python cdggui.py

You can then open your TOC file from the File menu, and encode single tracks by
right-clicking in the track list, or encode the whole CD using the Actions
menu.

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

CDGRIP QUICK START

To start using cdgrip immediately, try the following from the command-line
(replacing the --device option by the path to your CD or DVD device):

   $ cdrdao read-cd --driver generic-mmc-raw --device /dev/cdroms/cdrom0
                    --read-subchan rw_raw mycd.toc
   $ python cdgrip.py --delete-bin-toc --with-cddb mycd.toc

You may need to use a different --driver option or --read-subchan mode to
cdrdao depending on your CD device. For more in depth details, see the full
instructions below.

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

CDRDAO RIPPING INSTRUCTIONS

cdgtools makes use of cdrdao for performing the actual raw read from your CD or
DVD drive. You must rip your disk using cdrdao before using the cdgrip
command-line tool or the cdggui GUI ripper.

The CD+G disk should be ripped using the --read-subchan command of cdrdao. An
example command-line is:

   $ cdrdao read-cd --driver generic-mmc-raw --device /dev/cdroms/cdrom0 
                    --read-subchan rw_raw mycd.toc

You should replace the device by the correct path to your CD/DVD drive.  You
may also need to use a different driver, depending on your drive. See the
cdrdao manpage for more details on the driver options.

You can rip in either rw_raw (interleaved) or rw (deinterleaved) modes,
depending on what modes your CD drive supports. If your drive only supports
reading in rw (deinterleaved) mode, you can replace "--read-subchan rw_raw"
with "--read-subchan rw". Note that no deinterleaved mode drives were available
for testing, please let us know what success you have with this mode.

Once the cdrdao rip is complete, you should be left with a toc file (e.g.
mycd.toc) and a bin file (data.bin by default). You can now use cdgrip
(command-line) or cdggui (GUI) to do the MP3+G encoding:

  $ python cdgrip.py mycd.toc

  or

  $ python cdggui.py

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

CDGRIP COMMAND LINE OPTIONS

Once you have generated the TOC/BIN files using cdrdao, you can do a basic
command-line rip using:

  $ python cdgrip.py mycd.toc

This will rip the entire CD, generating a full set of .mp3 and .cdg files for
you (using generic track names, not CDDB-queried names).

The toc and bin files are left on disk by default. If you would like cdgrip to
delete them for you when it is finished, add the --delete-bin-toc option:

  $ python cdgrip.py --delete-bin-toc mycd.toc

By default cdgrip uses generic track names (track01.mp3, track02.mp3 etc). To
attempt to get actual track names using a FreeDB/CDDB connection, add the
--with-cddb option:

  $ python cdgrip.py --with-cddb mycd.toc

If a match is found in CDDB then your .mp3 and .cdg files will use these names
instead.

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

CDG2BIN QUICK START

To create your own custom CD+G discs with files stored on your machine, use
cdg2bin to create a disc image and cdrdao to write it to a CD-R. cdg2bin's
command-line syntax is straightforward:

$ cdg2bin.py [options] <files>

You must pass at least one CD+G track to cdg2bin to create a disc image. To
provide a CD+G track, specify one of the track's two files (the .cdg graphic
data file or the .mp3/.ogg audio data file), or specify a .zip, .tar.gz, or
.tar.bz2 archive that contains a single pair of files for a track). Archives
are handled automatically and transparently.

Given this directory of files:

track01.cdg	track01.ogg	track02.zip	track03.tar.bz2

With track02.zip containing:

track02.cdg	track02.mp3

And track03.tar.bz2 containing:

track03.cdg	track03.mpg

You can create a three track disc with either of the following commands:

$ cdg2bin.py track01.cdg track02.zip track03.tar.bz2
$ cdg2bin.py track01.ogg track02.zip track03.tar.bz2

(note you can use the CDG or audio file to specify a track -- cdg2bin
automatically locates the appropriate matching file based on your
specification)

Wildcards can also be used to easily create a multiple-track disc from every
track stored in a directory:

$ cdg2bin.py /home/user/karaoke/dk97/*zip

The index file produced (suffixed with .txt) is a plain text file listing the
CDG filenames placed on the disc (in the order they appear on the disc). It can
be used to keep track of the disc's contents, or removed; cdrdao does not use
or need this file to record discs.

cdg2bin needs write access to the directory(ies) where your source files are
stored if they are archives. It also naturally needs write access to the output
directory (the current directory if not specified with the -o option).

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

CDG2BIN COMMAND LINE OPTIONS

With no options, cdg2bin will create an image file named cdg.bin, a cue sheet
named cdg.toc, and an index file named cdg.txt. It uses appropriate
byte-swapping for little-endian machines (x86 and AMD64) to produce big-endian
audio data as required by the redbook audio specification.

Use the -o or --output-prefix= option to specify the name of the output files:

$ cdg2bin.py -o MYDISC001 /home/user/karaoke/dk97/*zip
$ cdg2bin.py --output-prefix=MYDISC001 /home/user/karaoke/dk97/*zip

This produces MYDISC001.bin, MYDISC001.toc, and MYDISC001.txt instead of cdg.bin, cdg.toc, and cdg.txt.

Use the -s or --split-image option to write each track into its own individual
.bin file. A single .toc cue sheet will still be created that correctly
specifies each of these individual .bin files:

$ cdg2bin.py -s /home/user/karaoke/dk97/*zip
$ cdg2bin.py --split-image /home/user/karaoke/dk97/*zip

Use the -b or --byte-swap option to change how audio data is produced by the
MP3 decoder (the OGG Vorbis decoder always produces the correct, big-endian
output, regardless of platform). If your CD images show correct graphics but
play static, use this option to generate a new image and record the disc again.

Use the -r or --raw option to write raw R-W subchannel data instead of cooked
R-W subchannel data (the default). If your recorder cannot record a CD with
cooked data, use this option to produce raw output. The .toc cue sheet is
written properly to reflect which data scheme is used.

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

CDRDAO WRITING INSTRUCTIONS

Once you have produced an image with cdg2bin, you can write it to your recorder
with cdrdao:

   $ cdrdao write --device /dev/cdroms/cdrom0 -speed 4 cue.toc

Replace /dev/cdroms/cdrom0 with the appropriate device if this doesn't work
(try /dev/hdc for a secondary master CD recorder). The -speed argument is
optional, but highly recommended (the slower you can record the CD, the more
likely it is to work properly in a standalone CD+G player; they are notoriously
picky devices.

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

MP3+G PLAYER

cdgtools does not contain an MP3+G player. We have also released a player under
our sister project PyKaraoke. See http://www.kibosh.org/pykaraoke/ for more
details

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

SUGGESTIONS

This is an early release of cdgtools. 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.sf.net>.

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