cuetools-jp/doc/formats.txt

===========================================================
Description of the Cue Sheet/Table of Contents File Formats
===========================================================

:Author: Svend Sorensen
:Contact: svend@ciffer.net
:Date: $LastChangedDate$

.. contents::

The Cue Sheet (cue) and Table of Contents (toc) file formats both describe the
layout of a CD.

Notes
=====

A cue or toc file has an (optional) global section, followed by any number of
track sections.

Lines (with a few exceptions for the toc format) begin with a keyword, which
may be followed by whitespace separated fields.  Some keywords are only allowed
in the global section or a track section.

Format Notation
---------------

A string may be enclosed in single or double quotation marks.  If the string
contains whitespace, it must be enclosed in quotation marks.

``<field>``
	a required field
``[field]``
	an optional field
``...``
	preceding field may be repeated any number of times

Cue Sheet Format
================

The standard file suffix for a cue file is ``.cue``.

Keywords
--------

CATALOG
~~~~~~~

:Description: Sets the media catalog number of the CD.
:Section(s): global
:Format:
	``CATALOG <catalog_number>``

	``catalog_number``
		an integer consisting of exactly 13 digits.

CDTEXTFILE
~~~~~~~~~~

:Description: Sets an external file for CD-TEXT data.
:Section(s): global
:Format:
	``CDTEXTFILE <filename>``

	``filename``
		a string.

The CD-TEXT file contains encoded CD-TEXT data.  The standard extension for
CD-TEXT files is ``.cdt``.  *TODO: describe CD-TEXT file format*

FILE
~~~~

:Description: Sets a new input file.
:Section(s): track
:Format:
	``FILE <filename> [file_format]``

	``filename``
		a string.
	``file_format``
		one of: ``BINARY``, ``MOTOROLA``, ``AIFF``, ``WAVE``, or
		``MP3`` [#]_.

``FILE`` line precedes the beginning of the track section.

.. [#] ``file_fomat`` differs between software packages.  The cdrtools_
       ``cue.c`` file also has ``file_format`` entries for ``AU`` and ``OGG``.

FLAGS
~~~~~

:Description: Sets track flags.
:Section(s): track
:Format:
	``FLAGS [flag]...``

	``flag``
		one of: ``PRE``, ``DCP``, ``4CH``, or ``SCMS``.

INDEX
~~~~~

:Description: Sets a track index.
:Section(s): track
:Format:
	``INDEX <index_number> <index>``

	``index_number``
		an integer in the range 0-99.
	``index``
		time in MSF format.

Having an ``INDEX 00`` and an ``INDEX 01`` defines a pregap using data from the
``FILE``.

ISRC
~~~~

:Description: Sets track ISRC number.
:Section(s): track
:Format:
	``ISRC <ISRC_number>``

	``ISRC_number``
		a string with the format CCOOOOYYSSSSS.

POSTGAP
~~~~~~~

:Description: Sets track postgap.
:Section(s): track
:Format:
	``POSTGAP <postgap>``

	``postgap``
		time in MSF format.

Postgap is filled with generated silence.

PREGAP
~~~~~~

:Description: Sets track pregap.
:Section(s): track
:Format:
	``PREGAP <pregap>``

	``pregap``
		time in MSF format.

The pregap is filled with generated silence.

REM
~~~

:Description: Begins a comment line.
:Section(s): any
:Format:
	``REM [comments]``

TRACK
~~~~~

:Description: Starts a new track.
:Section(s): track
:Format:
	``TRACK <track_number> <track_mode>``

	``track_number``
		a positive integer in the range 1-99.
	``track_mode``
		one of: ``AUDIO``, ``CDG``, ``MODE1/2048``, ``MODE1/2352``,
		``MODE2/2336``, ``MODE2/2352``, ``CDI/2336``, or ``CDI/2352``.

(CD-TEXT keywords)
~~~~~~~~~~~~~~~~~~

:Description: Sets CD-TEXT data.
:Section(s): any
:Format:
	``<CDTEXT_keyword> <CDTEXT_field>``

	``CDTEXT_keyword``
		one of: (see `CD-TEXT`_ section for a list of keywords).
	``CDTEXT_field``
		a string.

The cue format does not have native support for binary CD-TEXT.

Table of Contents File Format
=============================

The standard file suffix for a toc file is ``.toc``.

Certain keywords begin a block, which must be enclosed between ``{`` and ``}``
brackets.

Comments
--------

Comments begin with ``//`` and may be placed anywhere except inside quoted
strings.  A comment beginning with ``//`` is stripped from each line.

Keywords
--------

AUDIOFILE
~~~~~~~~~

:Description: Add file to current track.
:Section(s): track
:Format:
	``AUDIOFILE "<filename>" <start> [length]``

	``filename``
		a string.
	``start``
		time in MSF format.
	``length``
		time in MSF format.

CATALOG
~~~~~~~

:Description: Sets the media catalog number of the CD.
:Section(s): global
:Format:
	``CATALOG "<catalog_number>"``

	``catalog_number``
		an integer consisting of exactly 13 digits.

CD_DA
~~~~~

:Description: Sets the CD format to audio.
:Section(s): global
:Format: ``CD_DA``

CD_ROM
~~~~~~

:Description: Sets the CD format to data.
:Section(s): global
:Format: ``CD_ROM``

CD_ROM_XA
~~~~~~~~~

:Description: Sets the CD format to mixed.
:Section(s): global
:Format: ``CD_ROM_XA``

CD_TEXT
~~~~~~~

:Section(s): any
:Format: ``CD_TEXT {}``

Begins a CD-TEXT block.

COPY
~~~~

:Description: Sets the copy permitted flag.
:Section(s): track
:Format: ``COPY``

DATAFILE
~~~~~~~~

:Description: Add data from file to current track.
:Section(s): track
:Format:
	``DATAFILE "<filename>" [length]``

	``filename``
		a string.
	``length``
		time in MSF format.

ISRC
~~~~

:Description: Sets track ISRC number.
:Section(s): track
:Format:
	``ISRC "<ISRC_number>"``

	``ISRC_number``
		a string with the format CCOOOOYYSSSSS.

FIFO
~~~~

:Description: Add data from FIFO to current track.
:Section(s): track
:Format:
	``FIFO "<fifoname>" <length>"``

	``length``
		time in MSF format.

FILE
~~~~

:Description: Add data from file to current track.
:Section(s): track
:Format:
	``FILE "<filename>" <start> [length]``

	``filename``
		a string.
	``start``
		time in MSF format.
	``length``
		time in MSF format.

FOUR_CHANNEL_AUDIO
~~~~~~~~~~~~~~~~~~

:Description: Sets the four channel audio flag.
:Section(s): track
:Format: ``FOUR_CHANNEL_AUDIO``

INDEX
~~~~~

:Description: Sets a track index.
:Section(s): track
:Format: ``INDEX <index_number> <index_time>``

	``index_number``
		a non-negative integer.
	``index_time``
		time in MSF format.

LANGUAGE
~~~~~~~~

:Description: Begins a language block.
:Section(s): track
:Subsection(s): CD-TEXT block
:Format:
	``LANGUAGE language_number { cd_text }``

	``language_number``
		an integer in the range 0-255.
	``cd_text``
		a series of CD-TEXT keyword lines.

LANGUAGE_MAP
~~~~~~~~~~~~

:Description: Begins a language map block.
:Section(s): global
:Subsection(s): CD-TEXT block
:Format:
	``LANGUAGE_MAP { language_map... }``

	``language_map``
		is a mapping of an integer in the range 0-255 to a country
		code. *TODO: add description of mapping format*

NO
~~
:Description: Negates (clears) track flags.
:Section(s): track
:Format:
	``NO <flag>``

	``flag``
		  one of: ``COPY`` or ``PRE_EMPHASIS``.

PREGAP
~~~~~~

:Description: Sets track pregap.
:Section(s): track
:Format:
	``PREGAP <pregap>``

	``pregap``
		time in MSF format.

SILENCE
~~~~~~~

:Description: Add zero (silent) audio data to current track.
:Section(s): track
:Format:
	``SILENCE <length>``

	``length``
		time in MSF format.

START
~~~~~

:Description: Sets the length of the pregap.
:Section(s): track
:Format:
	``START <start>``

	``start``
		time in MSF format.

TRACK
~~~~~

:Description: Starts a new track.
:Section(s): track
:Format:
	``TRACK <track_mode> [sub_channel_mode]``

	``track_mode``
		one of: ``AUDIO``, ``MODE1``, ``MODE1_RAW``, ``MODE2``,
		``MODE2_FORM1``, ``MODE2_FORM2``, ``MODE2_FORM_MIX``,
		``MODE2_RAW``
	``sub_channel_mode``
		one of: ``RW``, ``RW_RAW``

TWO_CHANNEL_AUDIO
~~~~~~~~~~~~~~~~~

:Description: Sets the two channel audio flag.
:Section(s): track
:Format: ``TWO_CHANNEL_AUDIO``

ZERO
~~~~

:Description: Add zero data to current track.
:Section(s): track
:Format:
	``ZERO <length>``

	``length``
		time in MSF format.

(CD-TEXT keywords)
~~~~~~~~~~~~~~~~~~

:Description: Sets CD-TEXT data.
:Section(s): any
:Subsection(s): language block
:Format1:
	``<CDTEXT_keyword> "<CDTEXT_field>"``

	``CDTEXT_keyword``
		one of: (see `CD-TEXT`_ section for a list of keywords).
	``CDTEXT_field``
		a string.

:Format2:
	``<CDTEXT_keyword> { CDTEXT_binary_data }``

	``CDTEXT_binary_data``
		comma separated list of integers in the range 0-255.

Format1 is for character data and Format2 is for binary data.  See `CD-TEXT`_
section for a list of CD-TEXT keywords.

CD-TEXT
=======

MMC-3_ specifies 16 CD-TEXT types.  Three are reserved and have no
corresponding keywords.  One is shared; the keyword depends on whether it is
for the disc (``UPC_EAN``) or a track (``ISRC``).  CD-TEXT entries are either
character or binary data.  All descriptions taken from MMC-3_.

Keywords
--------

ARRANGER
~~~~~~~~

:Description: Name(s) of the arranger(s)
:Section: any
:Format: character

COMPOSER
~~~~~~~~

:Description: Name(s) of the composer(s)
:Section: any
:Format: character

DISC_ID
~~~~~~~

:Description: Disc Identification information
:Section: any
:Format: binary

GENRE
~~~~~

:Description: Genre Identification and Genre information
:Section: any
:Format: binary

Genre codes are in the Enhanced CD Specification or cdrtools_ ``cdtext.h`` file.

ISRC
~~~~~

:Description: ISRC Code of each track
:Section: track
:Format: character

MESSAGE
~~~~~~~

:Description: Message from the content provider and/or artist
:Section: any
:Format: character

PERFORMER
~~~~~~~~~

:Description: Name(s) of the performer(s)
:Section: any
:Format: character

SONGWRITER
~~~~~~~~~~

:Description: Name(s) of the songwriter(s)
:Section: any
:Format: character

TITLE
~~~~~

:Description: Title of album name or Track Titles
:Section: any
:Format: character

TOC_INFO
~~~~~~~~~

:Description: Table of Content information
:Section: any
:Format: binary

TOC_INFO2
~~~~~~~~~

:Description: Second Table of Content information
:Section: any
:Format: binary

UPC_EAN
~~~~~~~

:Description: UPC/EAN code of the album
:Section: disc
:Format: character

SIZE_INFO
~~~~~~~~~

:Description: Size information of the Block
:Section: any
:Format: binary

Definitions
===========

frame
	1/75 of a second.

International Standard Recording Code (ISRC)
	A 12 character identification code for sound recordings.  See
	`ISRC intro`_ for details.

Media Catalog Number (MCN)
	A 13 digit UPC/EAN code for the disc.

MSF format
	a representation of time in the form ``m:s:f``.  ``m`` is minutes,
	``s`` is seconds, and ``f`` is frames.  Fields may be zero padded.

.. _MMC-3: ftp://ftp.t10.org/t10/drafts/mmc3/
.. _cdrtools: http://www.fokus.gmd.de/research/cc/glone/employees/joerg.schilling/private/cdrecord.html
.. _ISRC intro: http://www.ifpi.org/site-content/online/isrc_intro.html