CUEgen 1.2.0
============

CUEgen is a FLAC-compatible cuesheet generator for Linux. The FLAC format allows cuesheets to be embedded in .flac files by storing their data in the CUESHEET metadata block. The cuesheet itself is simply a description of the contents of an audio CD. The cuesheet can be used in conjunction with a .flac file to store a complete album in a single FLAC file and then retrieve individual tracks from that file. The cuesheet may also be used by CD burning applications to recreate an identical copy of an original audio CD from its FLAC representation and an associated cuesheet. As such, cuesheets are of great use in archiving, transporting and burning FLAC-encoded audio files.

CUEgen creates a cuesheet for any audio CD. This cuesheet may then be embedded into a FLAC file of the CD or distributed with a FLAC file to permit the original CD to be recreated.

CUEgen is written by Paul Slavin <slavinp@cs.man.ac.uk> and the CUEgen homepage is http://www.cs.man.ac.uk/~slavinp/cuegen.html.

CUEgen is released under the GNU General Public License, see http://www.gnu.org/copyleft/gpl.html.


INSTALLATION
===========

CUEgen will compile on any Linux system; simply untar the archive and  run `make` in the directory created. The resulting program is created in this directory with the name `cuegen`.


USAGE
=====

The program accepts several command-line options:

Usage:   cuegen [options] 
    -h                          Print this usage information.
    -i                          Display detailed CD information in human-readable format.
    -o  <output file>           Write cuesheet to specified file. Default is stdout.
    -f  <dummy filename>        Dummy filename for inclusion in cuesheet. Default is cdda.wav.
    -d  <device name>           Specify a CD device to interrogate. Default is /dev/cdrom.

1) Run the program without any options to interrogate the CD in /dev/cdrom and print a cuesheet on stdout.

2) The -i option displays detailed information about a CD in a human readable format, e.g.:

Track   Start           End             Duration
=========================================================
01      00:00:00        05:06:68        05:06:68
02      05:06:68        09:20:65        04:13:72
03      09:20:65        13:18:70        03:58:05
04      13:18:70        17:38:60        04:19:65
05      17:38:60        22:35:25        04:56:40
06      22:35:25        26:33:20        03:57:70
07      26:33:20        31:42:60        05:09:40
08      31:42:60        35:23:60        03:41:00
09      35:23:60        40:27:63        05:04:03
10      40:27:63        45:34:33        05:06:45
=========================================================

Tracks: 10              Duration: 45m 34s


CUEgen does not produce a cuesheet when run with -i and exits after this information is displayed.

3) Use the -o option to have CUEgen write the resulting cuesheet directly to the specified file. By default, CUEgen writes its cuesheet on stdout, allowing the output to be redirected as required.

4) The -f option allows an alternate filename to be specified for the FILE field in the resulting cuesheet. This is for convenience only, the cuesheet's FILE field has no effect within FLAC and is used only by CD burning software. The default filename is "cdda.wav".

5) The -d option specifies which device contains the CD to interrogate. The default is /dev/cdrom, which is a symbolic link to the CD drive device on all Linux systems.

6) The -t and -p options allow you to specify the title and performer to be displayed in the cuesheet. If these options are omitted, the TITLE and PERFORMER fields will be omitted from the resulting cuesheet.


EXAMPLES
========

The default action is to query the CD in /dev/cdrom and print a cuesheet with the FILE field "cdda.wav" on stdout...

$ cuegen

Produces the following (dummy) cuesheet...

FILE "cdda.wav" WAVE
  TRACK 01 AUDIO
    INDEX 01 00:00:00
  TRACK 02 AUDIO
    INDEX 01 05:06:68
  TRACK 03 AUDIO
    INDEX 01 09:20:65
  TRACK 04 AUDIO
    INDEX 01 13:18:70
  TRACK 05 AUDIO
    INDEX 01 17:38:60
  TRACK 06 AUDIO
    INDEX 01 22:35:25
  TRACK 07 AUDIO
    INDEX 01 26:33:20
  TRACK 08 AUDIO
    INDEX 01 31:42:60
  TRACK 09 AUDIO
    INDEX 01 35:23:60
  TRACK 10 AUDIO
    INDEX 01 40:27:63

To create a human-readable report on the disc in /dev/dvd use the options...

$ cuegen -d /dev/dvd -i

To write a cuesheet for the disc in /dev/dvd directly to the file dummy.cue...

$ cuegen -d /dev/dvd -o dummy.cue


USING CUEGEN WITH FLAC
======================

This section describes the FLAC options that are used to manage cuesheets. See the documentation for flac and metaflac for more details.

To embed a cuesheet into a FLAC file, create the flac file with the FLAC option...

 --cuesheet=FILENAME			(Import cuesheet and store in CUESHEET block)

Individual tracks may then be decoded from the FLAC file using the syntax...
 
 --cue=[#.#][-[#.#]]			(Set the beginning and ending cuepoints to decode)

For example, to decode track 3 from the FLAC file cdda.flac...

$ flac -d --cue=03.01-04.01 -o track03.wav

The FLAC file meta information management program "metaflac" also provides the options...

 --import-cuesheet-from=FILE
 --export-cuesheet-to=FILE

...for managing cuesheets attached to existing FLAC files.

To delete the cuesheet stored in the FLAC file cdda.flac...

$ metaflac --remove --block-type=CUESHEET cdda.flac


BUGS
====

Report any bugs to Paul Slavin <slavinp@cs.man.ac.uk>.

