From df27526f2ee97a1f2a4a8648ea43d88d8041ab68 Mon Sep 17 00:00:00 2001 From: rocky Date: Fri, 28 Jan 2005 04:15:15 +0000 Subject: [PATCH] Go over documentation yet again. In particular: Move section on image formats out of Appendix and expand. Add a chapter on program internals glossary: add item to concept index and regularize index names. --- doc/glossary.texi | 70 +++++- doc/libcdio.texi | 592 ++++++++++++++++++++++++++++++---------------- 2 files changed, 459 insertions(+), 203 deletions(-) diff --git a/doc/glossary.texi b/doc/glossary.texi index a222ff83..aa1b1171 100644 --- a/doc/glossary.texi +++ b/doc/glossary.texi @@ -3,6 +3,7 @@ See also @uref{http://www.dvdrhelp.com/glossary}. @table @acronym @item ASPI +@cindex ASPI See @acronym{Win32 ASPI} @item ATAPI @@ -17,20 +18,22 @@ devices to the IDE/EIDE connections. A CD-image format developed by Jeff Arnold for CDRWIN software on Microsoft Windows. Many other programs subsequently support using this -format. The .CUE file is a text file which contains CD format and -track layout information, while the .BIN file holds the actual data of -each track. +format. The @code{.CUE} file is a text file which contains CD format +and track layout information, while the @code{.BIN} file holds the +actual data of each track. @item CD Compact Disc @item CD-DA +@cindex CD-DA Compact Disc Digital Audio, described in the ``Red Book'' or ICE 908. This commonly referred to as an audio @acronym{CD} and what most people think of when you play a @acronym{CD} as it was the first to use the @acronym{CD} medium. @item CD+G +@cindex CD+G Compact Disc + Graphics. An extension of the CD audio format contains a limited amount of graphics in subcode channels. This disc works in @@ -38,6 +41,8 @@ all audio players but the graphics portion is only available in a special CD+G or Karaoke player. @item CD-i +@cindex CD-i + Compact Disc Interactive. An extension of the CD format designed around a set-top computer that connects to a TV to provide interactive home entertainment, including digital audio and video, video games, @@ -46,11 +51,14 @@ and software applications. Defined by the ``Green Book'' standard. largely (if not totally) been superceded by VCDs. @item CD-i Bridge +@cindex CD-i Bridge A standard allowing CD-ROM XA discs to play on CD-i. Kodak PhotoCDs are CD-XA Bridge discs. @item CD-ROM +@cindex CD-ROM + Compact Disc Read Only Memory or ``Yellow Book'' describe in Standards ISO/IEC 10149. The data stored on it can be either in the form of audio, computer or video files. @@ -64,6 +72,8 @@ layer. CD-ROM/XA An expansion of the CD-ROM Mode 2 format that allows both computer and audio/video to be mixed in the same track. @item CD Text +@cindex CD Text + CD Text is a technology developed by Sony Corporation and Philips Electronics in 1996 that allows storing in an audio CD and its tracks information such as artist name, title, songwriter, composer, or @@ -71,6 +81,8 @@ arranger. Commercially available audio CDs sometimes contain CD Text information. @item CD XA +@cindex CD XA + CD-ROM EXtended Architecture. A modification to the CD-ROM specification that defines two new types of sectors. CD-ROM XA was developed jointly by Sony, Philips, and Microsoft, and announced in @@ -90,15 +102,22 @@ its own `Green Book' file system only resembles ISO 9660 and isn't fully compatible. @item FSF +@cindex FSF + Free Software Foundation, @uref{http://www.fsf.org/} @item GNU +@cindex GNU + @acronym{GNU} is not @acronym{UNIX}, @uref{http://www.gnu.org/} @item ISO +@cindex ISO + International Standards Organization. @item ISO 9660 +@cindex ISO 9660 The ISO 9660 is an operating-system independent filesystem format for CD-ROM media and DVD-ROMs. It was standardized in 1988 and replaced the @@ -119,6 +138,7 @@ is the European specification which is identical to ISO 9660. ISO 13490 is basically ISO 9660 with multisession support. @item Joliet extensions +@cindex Joliet extensions This ISO-9660 upward-compatible standard was developed for Windows 95 and Windows NT by Microsoft as an extension of ISO 9600 which allows @@ -129,6 +149,7 @@ See @uref{http://bmrc.berkeley.edu/people/chaffee/jolspec.html} for the Joliet Specification. @item LBA +@cindex LBA Logical Block Addressing. Mapped integer numbers from CD Red Book Addressing MSF. The starting sector is -150 and ending sector is @@ -137,6 +158,7 @@ Because an LBA is a single number it is often easier to work with in programming than an MSF. @item Lead in +@cindex lead in The area of a CD where the Table Of Contents (TOC) and CDTEXT are stored. I think it is supposed to be around 4500 (1 min) or more @@ -146,6 +168,7 @@ indicated by the ATIP start of lead-in position that is recorded in the ATIP groove on the disk. @item LSN +@cindex LSN Logical Sector Number. Mapped integer numbers from CD Red Book Addressing MSF. The starting sector is 0 and ending sector is 449699, @@ -155,13 +178,15 @@ MSF. Because it starts at 0 rather than -150 as is the case of an LBA it can be represented as an unsigned value. @item MCN +@cindex MCN Media Catalog Number. A identification number on an audio CD. Also called a UPC. Another identification number is ISRC. @item MMC +@cindex MMC -MMC (MultiMedia Commands). A SCSI programming specification made by +MMC (Multimedia Commands). A SCSI programming specification made by the SCSI committee T10 organization. They are raw commands for communicating with CDROM drives, CD-Rewriters, DVD-Rewriters, etc. @@ -169,6 +194,7 @@ Many manufacturers have adopted this standard and it also applies to ATAPI versions of their drives. @item Mixed Mode CD +@cindex Mixed Mode CD A Mixed Mode is a CD that contains tracks of differing CD-ROM Mode formats. In particular the first track may contain both computer data @@ -176,17 +202,20 @@ formats. In particular the first track may contain both computer data video data. Video CD's can be Mixed Mode CDs. @item Multisession +@cindex Multisession A way of writing to a CD that allows more data to be added to readable discs at a later time. @item Nero NRG format file +@cindex Nero NRG, CD-Image format A proprietary CD image file format use by a popular program for Microsoft Windows, Ahead Nero. The specification of this format is not to our knowlege published. @item SCSI +@cindex SCSI Small Computer System Interface. A set of ANSI standard electronic interfaces (originally developed at Apple Computer) that allow @@ -194,6 +223,7 @@ personal computers to communicate with peripheral hardware such as CD-ROM drives, disk drives, printers, etc. @item SCSI Pass Through Interface. +@cindex SCSI Pass Through Interface. Yet another way of issuing MMC commands for accessing a CD-ROM. As with MMC or ASPI, the CD-ROM doesn't necessarily have to be a @@ -201,6 +231,8 @@ SCSI-attached drive. See also @acronym{MMC} and @acronym{ASPI}. @item SPTI +@cindex SPTI + SCSI Pass Through Interface. See SCSI Pass Through Interface @item Session @@ -209,9 +241,12 @@ A fully readable complete recording that contains one or more tracks of computer data or audio on a CD. @item SVCD +@cindex Super VCD (SVCD) + Super @acronym{VCD} @uref{http://www.dvdrhelp.com/svcd} @item TOC +@cindex TOC Table of Contents. The TOC contains the starting track number, last track number individual track starting time, format of track: CDDA or @@ -220,15 +255,38 @@ recorded at the start of the CD (lead-in area). A multi-session CD may have several TOCs. @item Track +@cindex track A unit of data of a CD. The size of a track can vary; it can occupy the entire contents of the CD. Most CD standards however require that tracks have a 150 frame (or ``2 second'') lead-in gap. @item VCD -Video @acronym{CD} @uref{http://www.dvdrhelp.com/vcd} +@cindex Video CD (VCD) + +The Video Compact Disc (@dfn{Video CD} or @dfn{VCD}) is a standardized +digital video storage format. It is based on the commonly available +Compact Disc technology, which allows for low-cost video authoring. +Video CD's can be played in most @acronym{DVD} standalone player, +dedicated VCD players and finally, modern Personal Computers with +multimedia support. + +A Video CD is made up of @acronym{CD-ROM XA} sectors, +i.e. @acronym{CD-ROM} mode 2 form 1 & 2 sectors. Non-@acronym{MPEG} data +is stored in mode 2 form 1 sectors with a user data area of 2048 byte, +which have a similiar L2 error correction and detection +(@acronym{ECC}/@acronym{EDC}) to @acronym{CD-ROM} mode 1 sectors. While +realtime @acronym{MPEG} streams is stored in @acronym{CD-ROM} mode 2 +form 2 sectors, which by have no L2 @acronym{ECC}, yield a ~14% greater +user data area consisting of 2324 bytes@footnote{actually raw mode 2 +sectors have a 2336 byte user data area, but parts of it are used for +error codes and headers when using the mode 2 form 1 or form 2 +configurations.} + +@uref{http://www.dvdrhelp.com/vcd} @item Win32 ASPI +@cindex ASPI The ASPI interface specification was developed by Adaptec for sending commands to a SCSI host adapter (such as those controlling CD @@ -250,6 +308,8 @@ Microsoft Windows. It is used for sending commands to devices using defined codes and structures. @item XA +@cindex XA + See @acronym{CD-ROM XA} @end table diff --git a/doc/libcdio.texi b/doc/libcdio.texi index 57bdd78a..20314a07 100644 --- a/doc/libcdio.texi +++ b/doc/libcdio.texi @@ -46,7 +46,7 @@ development.'' @titlepage @title GNU libcdio library -@subtitle $Id: libcdio.texi,v 1.31 2005/01/24 08:33:57 rocky Exp $ +@subtitle $Id: libcdio.texi,v 1.32 2005/01/28 04:15:15 rocky Exp $ @author Rocky Bernstein et al. @page @@ -83,14 +83,15 @@ Copyright (C) 2003, 2004, 2005 Rocky Bernstein and Herbert Valerio Riedel * Previous Work:: The problem and previous work * Purpose:: What is in this package (and what's not) * CD Formats:: A tour through the CD-specification spectrum +* CD Image Formats:: A tour through various CD-image formats * CD Units:: The units that make up a CD * How to use:: Okay enough babble, lemme at the library! * Utility Programs:: Diagnostic programs that come with this library * OS Considerations:: Operating System Considerations and Drivers +* Internal Program Organization:: Looking under the hood Appendices * ISO-9660 Character Sets:: -* CD Image Formats:: * Glossary:: * GNU General Public License:: * GNU Free Documentation License:: @@ -529,7 +530,7 @@ System semantics. @node Joliet Extensions @subsubsection Joliet Extensions -@cindex Joliet Extensions +@cindex Joliet extensions Joliet extensions were an upward-compatible extension to the ISO 9660 specification that removes the limitation initially put in to deal @@ -621,6 +622,221 @@ In @value{libcdio} when you you want to read a mode2 format 2 audio sector you call the @code{cdio_read_mode2_sector()} or @code{cdio_read_mode2_sectors()} setting @code{b_form2} to @code{true}. +@node CD Image Formats +@chapter CD Image Formats + +@menu +* CDRDAO TOC Format:: +* CDRWIN BIN/CUE Format:: +* NRG Format:: +@end menu + +In both the @command{cdrdao} and bin/cue formats there is one meta-file with +extensions @code{.toc} or @code{.cue} respectively and one or more +files (often with the extension @code{.bin}) which contains the +content of tracks. The format of the track data is often +interchangeable between the two formats. For example, in +@value{libcdio}'s regression tests we make use of this to reduce the +size of the test data and just provide alternate meta-data files +(@code{.toc} or @code{.cue}). + +In contrast to the first two formats, the NRG format consists of a +single file. This has the advantage of being a self-contained +units. It is possible in the other two formats for the meta file to +refer to a file that can't be found. A disadvantage of the NRG format +is that the meta data can't be easily viewed or modified say in a text +file as it can be with the first two formats. In conjunction with this +disadvantage is another disadvantage that the format is not +documented, so how @value{libcdio} interprets an NRG image is based on +inference. It is recommended that one of the other forms be used +instead of NRG where possible. + +@node CDRDAO TOC Format +@section CDRDAO TOC Format + +This is @command{cdrdao}'s CD-image description format. Since this +program is GPL and everything about it is in the open, it is the +preferred format to use. (Alas, at present it isn't as well supported +in @value{libcdio} as the BIN/CUE format.) + +The @emph{toc}-file describes what data is written to the media in the +@acronym{CD-ROM}; it allows control over track/index positions, +pre-gaps and sub-channel information. It is a text file, so a text +editor can be used to create, view or modify it. + +The @cite{cdrdao(1) manual page}, contains more information about this +format. + +@subsection CDRDAO Grammar + +Here is a list of lexical tokens taken from the cdrdao grammar. + +@example +#lexclass START +#token Eof "@@" +#token "[\t\r\ ]+" +#token Comment "//~[\n@@]*" +#token "\n" +#token BeginString "\"" +#token Integer "[0-9]+" +#token Index "INDEX" +#tokclass AudioFile @{ "AUDIOFILE" "FILE" @} + +#lexclass STRING +#token EndString "\"" +#token StringQuote "\\\"" +#token StringOctal "\\[0-9][0-9][0-9]" +#token String "\\" +#token String "[ ]+" +#token String "~[\\\n\"\t ]*" +@end example + +@example + +toc ::= ( "CATALOG" string | tocType )* @{ cdTextGlobal @} ( track )+ Eof + +track ::= "TRACK" trackMode + @{ subChannelMode @} + ( "ISRC" string | @{ "NO" @} "COPY" | @{ "NO" @} "PRE_EMPHASIS" + | "TWO_CHANNEL_AUDIO" | "FOUR_CHANNEL_AUDIO" )* + @{ cdTextTrack @} + @{ "PREGAP" msf @} + ( subTrack | "START" | "END" )+ + ( Index msf )* + +subTrack ::= + ( AudioFile string @{ "SWAP" @} @{ "#" sLong @} samples + | "DATAFILE" string @{ "#" sLong @{ dataLength @} @} + | "FIFO" string dataLength + | "SILENCE" samples + | "ZERO" @{ dataMode @} @{ subChannelMode @} dataLength + ) + +string ::= BeginString ( ( String | StringQuote | StringOctal ) )+ + EndString + +stringEmpty ::= BeginString ( ( String | StringQuote | StringOctal ) )* + EndString + +uLong ::= Integer + +sLong ::= Integer + +msf ::= Integer ":" Integer ":" Integer + +samples ::= ( msf | uLong ) + +dataLength ::= ( msf | uLong ) + +dataMode ::= ( "AUDIO" | "MODE0" | "MODE1" | "MODE1_RAW" | "MODE2" + | "MODE2_RAW" | "MODE2_FORM1" | "MODE2_FORM2" | "MODE2_FORM_MIX" ) + +trackMode ::= ( "AUDIO" | "MODE1" | "MODE1_RAW" | "MODE2" + | "MODE2_RAW" | "MODE2_FORM1" | "MODE2_FORM2" | "MODE2_FORM_MIX" ) + +subChannelMode ::= ( "RW" | "RW_RAW" ) + +tocType ::= ( "CD_DA" | "CD_ROM" | "CD_ROM_XA" | "CD_I" ) + +packType ::= ( "TITLE" | "PERFORMER" | "SONGWRITER" | "COMPOSER" | "ARRANGER" + | "MESSAGE" | "DISC_ID" | "GENRE" | "TOC_INFO1" | "TOC_INFO2" + | "RESERVED1" | "RESERVED2" | "RESERVED3" | "RESERVED4" | "UPC_EAN" | + "ISRC" | "SIZE_INFO" ) + +binaryData ::= "\@{" + @{ Integer ( "," Integer )* @} + "\@}" + +cdTextItem ::= packType ( stringEmpty | binaryData ) + +cdTextBlock ::= "LANGUAGE" Integer "\@{" ( cdTextItem )* "\@}" + + +cdTextLanguageMap ::= + LanguageMap "\@{" + ( Integer ":" ( Integer | "EN" ) )+ + "\@}" + +cdTextTrack ::= "CD_TEXT" "\@{" ( cdTextBlock )* "\@}" + +cdTextGlobal ::= "CD_TEXT" "\@{" @{ cdTextLanguageMap @} ( cdTextBlock )* "\@}" +@end example + + + +@node CDRWIN BIN/CUE Format +@section CDRWIN BIN/CUE Format +@cindex BIN/CUE, CD Image Format + +The format referred to as @emph{CDRWIN BIN/CUE Format} in this manual +is a popular CD image format used in the @acronym{PC} world. Not +unlike @command{cdrdao}'s toc file, the @emph{cue} file describes the +track layout, i.e. how the sectors are to be placed on the CD +media. The @emph{cue} file usually contains a reference to a file +traditionally having the @file{.bin} extension in its filename, the +@emph{bin} file. This @emph{bin} file contains the sector data payload +which is to be written to the CD medium according to the description +in the @emph{cue} file. + +The following is an attempt to describe the subset of the @file{.cue} +file syntax used in @value{libcdio} and vcdimager in an EBNF-like +notation: + +@subsection BIN/CUE Grammar + +@example +@cartouche + ::= +( + ) + + ::= "0" | "1" ... "8" | "9" + ::= + + ::= ":" ":" + + ::= "FILE" + + ::= [ "\"" ] [ "\"" ] + | "\"" "\"" + + ::= "BINARY" + + ::= [ ] + [ ] * [ ] + + ::= "FLAGS" * + ::= "DCP" + + ::= "TRACK" + + ::= "PREGAP" + + ::= "INDEX" + + ::= "POSTGAP" + + ::= "AUDIO" | "MODE1/2048" | "MODE1/2352" + | "MODE2/2336" | "MODE2/2352" + + ::= "REM" * +@end cartouche +@end example + +@node NRG Format +@section NRG Format +@cindex Nero NRG, CD-Image format + +The format referred to as @emph{NRG Format} in this manual is another +popular CD image format. It is available only on Nero software +on a Microsoft Windows Operating System. It is proprietary and not +generally published, so the information we have comes from guessing +based on sample CD images. So support for this is incomplete and using +this format is not recommended. + +Unlike @command{cdrdao}'s TOC file the BIN/CUE format everything is +contained in one file. that one can edit Meta information such as the +number of tracks and track format is contained at the end of the +file. This information is not inteded to be edited through a text +editor. + @node CD Units @chapter The units that make up a CD @@ -631,7 +847,8 @@ sector you call the @code{cdio_read_mode2_sector()} or @node Tracks @section tracks --- disc subdivisions -@cindex tracks +@cindex track + In this section we describe CD properties and terms that we make use of in @value{libcdio}. @@ -1616,10 +1833,181 @@ More work on this driver is needed. Volunteers? A problem with OS/X is that if the OS thinks it understands the drive it gains exclusive access to it and thus prevents a library like this -to get non-exclusive access. +to get non-exclusive access. + +Currently @value{libcdio} access the CD-ROM non-exclusively. However +in order to be able to issue SCSI-MMC, the current belief is that +exclusive access is needed. Probably in a future @value{libcdio}, +there will be some way to specify which kind of access is desired +(with the inherent consequences of each). More work on this driver is needed. Volunteers? +@node Internal Program Organization +@chapter Internal Program Organization + +@subsection file organization + +Here is a list of @value{libcdio} directories. + +@itemize + +@item @code{include/cdio} + +This contains the headers that are public. One that will probably be +used quite a bit is @code{}. + +@item @code{lib} + +Code for installed libraries. See below for further breakout + +@item @code{lib/driver} + +Code for various OS-specific CD-ROM drivers, image drivers, and +common SCSI-MMC routines. + +This code comprises @code{libcdio.a} (or the shared version of it). + +@item @code{lib/iso9660} + +Code for to extract or query ISO-9660 images. + +This code comprises @code{libiso9660.a} (or the shared version of it). + +@item @code{lib/paranoia} + +This is from cdparanoia. It is the OS- and hardware- dependent code to +detect and correct jitter for CD-DA CDs. + +@item @code{lib/cdda_interface} + +This is also from cdparanoia. It is the OS- and hardware- independent +code to detect and correct jitter for CD-DA CDs. + +@item @code{doc} + +A home for fine documentation such as this masterpiece. + +@item @code{example} + +Here you will find various small example programs using +@value{libcdio} which are largely for pedagogical purposes. You might +be able to find one that is similar to what you want to do that could +be extended. In fact some these are contain the kernel ideas behind of +some of the larger programs in @file{src}. + +@item @code{src} + +Various stand-alone utility programs. See below. + +@item @code{src/paranoia} + +@value{libcdio}'s version of @code{cdparanoia}. Except for the fact +that the back-end CD-reading code has been replaced by +@value{libcdio}'s routines the code is pretty much identical. + +@item @code{test} + +Regression tests + +@end itemize + +@subsection libcdio + +@value{libcdio} exports one opaque type @code{CdIo_t}. Internally this +an enumeration for the driver, a structure containing function +pointers and a generic ``environment'' pointer which is passed as a +parameter on a function call. See +@file{lib/driver/cdio_private.h}. The initialization routine for each +driver sets up the function pointers and allocates memory for the +environment. When a particular user-level cdio routine is called (e.g +@code{cdio_get_first_track_num} for lib/driver/track.c), the +environment pointer is passed to a device-specific routine which will +then cast this pointer into something of the appropriate type. + +Because function pointers are used, there can be and is quite a bit +of sharing of common routines. Some of the common routines are found +in the file @file{lib/driver/_cdio_generic.c}. + +Another set of routines that one is likely to find shared amongst +drivers are the SCSI-MMC commands. These are located in +@file{lib/driver/scsi_mmc.c}. + +There not only an attempt to share functions but we've tried to create +a generic CD structure @code{generic_img_private_t} of file +@file{lib/driver/generic.h}. By putting information into a common +structure, we increase the likelihood of being able to have a common +routine to perform some sort of function. + +The generic CD structure would also be useful in a utility to convert +one CD-image format to another. Basically the first image format is +``parsed'' into the common internal format and then from this +structure it is unparsed. + +@subsection libiso9660 + +To be completed.... + +@subsection Coding Conventions + +In @value{libcdio} there are a number of conventions used. If you +understand some of these conventions it may facilitate understanding +the code a little. + +@subsubsection variable names + +A number of prefixes are used in variable names here's what they mean + +@itemize +@item @code{i_} + +An integer type of some sort. A variable of this ilk one might find +being iterated over in @code{for} loops or used as the index of an +array for example. + +@item @code{b_} + +A boolean type of some sort. A variable of this ilk one might find +being in an @code{if} condition for example. + +@item @code{p_} + +A pointer of some sort. A variable of this ilk, say +@code{p_foo} one is like likely to see @code{*p_foo} or +@code{p_foo->...}. + +@item @code{pp_} + +A pointer to a pointer of some sort. A variable of this ilk, say +@code{pp_foo} one is like likely to see @code{**p_foo} or +@code{p_foo[x][y]} for example + +@item @code{psz_} + +A @code{char *} pointer of some sort. A variable of this ilk, say +@code{psz_foo} may be used in a string operation. For example +@code{printf(%s\n", psz_foo)} or @code{strdup(psz_foo)}. + +@item @code{ppsz_} + +A pointer to a @code{char *} pointer of some sort. A variable of this +ilk, say @code{ppsz_foo} is used for example to return a list of +CD-ROM device names + +@end itemize + +A couple other name conventions. Generally if a routine name starts +@code{cdio_}, e.g. @code{cdio_open}, then it is an externally +visable routine in @code{libcdio}. If a name starts @code{iso9660_}, +e.g. @code{iso9660_isdchar} then it is an externally visable routine +in @code{libiso9660}. If a name starts @code{scsi_mmc_}, +e.g. @code{scsi_mmc_get_discmode}, then it is an externally visable +SCSI-MMC routine. (We don't have a separate library for this yet. + +Names in captal letters only that start @code{CDIO_} are externally +visable @code{#defines}. + + @node ISO-9660 Character Sets @appendix ISO-9660 Character Sets @@ -1678,199 +2066,7 @@ e | . > N f | / ? O _ @end example -@node CD Image Formats -@appendix CD Image Formats - -@menu -* CDRDAO TOC Format:: -* CDRWIN BIN/CUE Format:: -* NRG Format:: -@end menu - -@node CDRDAO TOC Format -@appendixsec CDRDAO TOC Format - -This is @command{cdrdao}'s own cd image description format. Since this -program is GPL and everything about it is in the open, it is the -preferred format to use. (Alas, at present it isn't as well supported -in @value{libcdio} as the BIN/CUE format.) - -A snippet from the @cite{cdrdao(1) manual page}, which you should -refer to for more information about this format: - -@quotation -The @emph{toc}-file describes what data is written to the -@acronym{CD-R} and allows control over track/index positions, pre-gaps -and sub-channel information. It is a simple text file, use your -favorite text editor to create it. -@end quotation - -Here is a list of lexical tokens taken from the cdrdao grammar. - -@example -#lexclass START -#token Eof "@@" -#token "[\t\r\ ]+" -#token Comment "//~[\n@@]*" -#token "\n" -#token BeginString "\"" -#token Integer "[0-9]+" -#token Index "INDEX" -#tokclass AudioFile @{ "AUDIOFILE" "FILE" @} - -#lexclass STRING -#token EndString "\"" -#token StringQuote "\\\"" -#token StringOctal "\\[0-9][0-9][0-9]" -#token String "\\" -#token String "[ ]+" -#token String "~[\\\n\"\t ]*" -@end example - -@example - -toc ::= ( "CATALOG" string | tocType )* @{ cdTextGlobal @} ( track )+ Eof - -track ::= "TRACK" trackMode - @{ subChannelMode @} - ( "ISRC" string | @{ "NO" @} "COPY" | @{ "NO" @} "PRE_EMPHASIS" - | "TWO_CHANNEL_AUDIO" | "FOUR_CHANNEL_AUDIO" )* - @{ cdTextTrack @} - @{ "PREGAP" msf @} - ( subTrack | "START" | "END" )+ - ( Index msf )* - -subTrack ::= - ( AudioFile string @{ "SWAP" @} @{ "#" sLong @} samples - | "DATAFILE" string @{ "#" sLong @{ dataLength @} @} - | "FIFO" string dataLength - | "SILENCE" samples - | "ZERO" @{ dataMode @} @{ subChannelMode @} dataLength - ) - -string ::= BeginString ( ( String | StringQuote | StringOctal ) )+ - EndString - -stringEmpty ::= BeginString ( ( String | StringQuote | StringOctal ) )* - EndString - -uLong ::= Integer - -sLong ::= Integer - -msf ::= Integer ":" Integer ":" Integer - -samples ::= ( msf | uLong ) - -dataLength ::= ( msf | uLong ) - -dataMode ::= ( "AUDIO" | "MODE0" | "MODE1" | "MODE1_RAW" | "MODE2" - | "MODE2_RAW" | "MODE2_FORM1" | "MODE2_FORM2" | "MODE2_FORM_MIX" ) - -trackMode ::= ( "AUDIO" | "MODE1" | "MODE1_RAW" | "MODE2" - | "MODE2_RAW" | "MODE2_FORM1" | "MODE2_FORM2" | "MODE2_FORM_MIX" ) - -subChannelMode ::= ( "RW" | "RW_RAW" ) - -tocType ::= ( "CD_DA" | "CD_ROM" | "CD_ROM_XA" | "CD_I" ) - -packType ::= ( "TITLE" | "PERFORMER" | "SONGWRITER" | "COMPOSER" | "ARRANGER" - | "MESSAGE" | "DISC_ID" | "GENRE" | "TOC_INFO1" | "TOC_INFO2" - | "RESERVED1" | "RESERVED2" | "RESERVED3" | "RESERVED4" | "UPC_EAN" | - "ISRC" | "SIZE_INFO" ) - -binaryData ::= "\@{" - @{ Integer ( "," Integer )* @} - "\@}" - -cdTextItem ::= packType ( stringEmpty | binaryData ) - -cdTextBlock ::= "LANGUAGE" Integer "\@{" ( cdTextItem )* "\@}" - - -cdTextLanguageMap ::= - LanguageMap "\@{" - ( Integer ":" ( Integer | "EN" ) )+ - "\@}" - -cdTextTrack ::= "CD_TEXT" "\@{" ( cdTextBlock )* "\@}" - -cdTextGlobal ::= "CD_TEXT" "\@{" @{ cdTextLanguageMap @} ( cdTextBlock )* "\@}" -@end example - - - -@node CDRWIN BIN/CUE Format -@appendixsec CDRWIN BIN/CUE Format -@cindex BIN/CUE, CD Image Format - -The format referred to as @emph{CDRWIN BIN/CUE Format} in this manual -is a popular CD image format used in the @acronym{PC} world. Not -unlike @command{cdrdao}'s toc file, the @emph{cue} file describes the -track layout, i.e. how the sectors are to be placed on the CD -media. The @emph{cue} file usually contains a reference to a file -traditionally having the @file{.bin} extension in its filename, the -@emph{bin} file. This @emph{bin} file contains the sector data payload -which is to be written to the CD medium according to the description -in the @emph{cue} file. - -The following is an attempt to describe the subset of the @file{.cue} -file syntax as used in vcdimager in an EBNF-like notation: - -@example -@cartouche - ::= +( + ) - - ::= "0" | "1" ... "8" | "9" - ::= + - ::= ":" ":" - - ::= "FILE" - - ::= [ "\"" ] [ "\"" ] - | "\"" "\"" - - ::= "BINARY" - - ::= [ ] - [ ] * [ ] - - ::= "FLAGS" * - ::= "DCP" - - ::= "TRACK" - - ::= "PREGAP" - - ::= "INDEX" - - ::= "POSTGAP" - - ::= "AUDIO" | "MODE1/2048" | "MODE1/2352" - | "MODE2/2336" | "MODE2/2352" - - ::= "REM" * -@end cartouche -@end example - -@node NRG Format -@appendixsec NRG Format -@cindex NRG, CD Image Format - -The format referred to as @emph{NRG Format} in this manual is another -popular CD image format. It is available only on Nero software -on a Microsoft Windows Operating System. It is proprietary and not -generally published, so the information we have comes from guessing -based on sample CD images. So support for this is incomplete and using -this format is not recommended. - -Unlike @command{cdrdao}'s TOC file the BIN/CUE format everything is -contained in one file. that one can edit Meta information such as the -number of tracks and track format is contained at the end of the -file. This information is not inteded to be edited through a text -editor. - -@node Glossary, GNU General Public License, CD Image Formats, Top +@node Glossary @appendix Glossary @include glossary.texi