cdgtools - Usage Instructions

CDGGUI Quick Start

cdgtools does not perform the actual ripping from CD/DVD drives - it takes the TOC/BIN files generated by cdrdao and encodes to MP3+G. Before running cdggui, you should therefore 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

cdgrip is the command-line version of the CD+G ripper, for those who would prefer not to use the GUI. 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.

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.

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 supports reading in rw (deinterleaved) mode, you can replace "--read-subchan rw_raw" with "--read-subchan rw". Note that rw_raw is not error-corrected, so it is possible that your rips will have glitches or errors. If this is the case, you should get better results with rw mode which offers error-corrected rips. No rw (deinterleaved) mode drives were available for testing however, 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

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.