Doc/lib/libcd.tex

   1 \section{\module{cd} ---
   2          CD-ROM access on SGI systems}
   3
   4 \declaremodule{builtin}{cd}
   5   \platform{IRIX}
   6 \modulesynopsis{Interface to the CD-ROM on Silicon Graphics systems.}
   7
   8
   9 This module provides an interface to the Silicon Graphics CD library.
  10 It is available only on Silicon Graphics systems.
  11
  12 The way the library works is as follows.  A program opens the CD-ROM
  13 device with \function{open()} and creates a parser to parse the data
  14 from the CD with \function{createparser()}.  The object returned by
  15 \function{open()} can be used to read data from the CD, but also to get
  16 status information for the CD-ROM device, and to get information about
  17 the CD, such as the table of contents.  Data from the CD is passed to
  18 the parser, which parses the frames, and calls any callback
  19 functions that have previously been added.
  20
  21 An audio CD is divided into \dfn{tracks} or \dfn{programs} (the terms
  22 are used interchangeably).  Tracks can be subdivided into
  23 \dfn{indices}.  An audio CD contains a \dfn{table of contents} which
  24 gives the starts of the tracks on the CD.  Index 0 is usually the
  25 pause before the start of a track.  The start of the track as given by
  26 the table of contents is normally the start of index 1.
  27
  28 Positions on a CD can be represented in two ways.  Either a frame
  29 number or a tuple of three values, minutes, seconds and frames.  Most
  30 functions use the latter representation.  Positions can be both
  31 relative to the beginning of the CD, and to the beginning of the
  32 track.
  33
  34 Module \module{cd} defines the following functions and constants:
  35
  36
  37 \begin{funcdesc}{createparser}{}
  38 Create and return an opaque parser object.  The methods of the parser
  39 object are described below.
  40 \end{funcdesc}
  41
  42 \begin{funcdesc}{msftoframe}{minutes, seconds, frames}
  43 Converts a \code{(\var{minutes}, \var{seconds}, \var{frames})} triple
  44 representing time in absolute time code into the corresponding CD
  45 frame number.
  46 \end{funcdesc}
  47
  48 \begin{funcdesc}{open}{\optional{device\optional{, mode}}}
  49 Open the CD-ROM device.  The return value is an opaque player object;
  50 methods of the player object are described below.  The device is the
  51 name of the SCSI device file, e.g. \code{'/dev/scsi/sc0d4l0'}, or
  52 \code{None}.  If omitted or \code{None}, the hardware inventory is
  53 consulted to locate a CD-ROM drive.  The \var{mode}, if not omitted,
  54 should be the string \code{'r'}.
  55 \end{funcdesc}
  56
  57 The module defines the following variables:
  58
  59 \begin{excdesc}{error}
  60 Exception raised on various errors.
  61 \end{excdesc}
  62
  63 \begin{datadesc}{DATASIZE}
  64 The size of one frame's worth of audio data.  This is the size of the
  65 audio data as passed to the callback of type \code{audio}.
  66 \end{datadesc}
  67
  68 \begin{datadesc}{BLOCKSIZE}
  69 The size of one uninterpreted frame of audio data.
  70 \end{datadesc}
  71
  72 The following variables are states as returned by
  73 \function{getstatus()}:
  74
  75 \begin{datadesc}{READY}
  76 The drive is ready for operation loaded with an audio CD.
  77 \end{datadesc}
  78
  79 \begin{datadesc}{NODISC}
  80 The drive does not have a CD loaded.
  81 \end{datadesc}
  82
  83 \begin{datadesc}{CDROM}
  84 The drive is loaded with a CD-ROM.  Subsequent play or read operations
  85 will return I/O errors.
  86 \end{datadesc}
  87
  88 \begin{datadesc}{ERROR}
  89 An error occurred while trying to read the disc or its table of
  90 contents.
  91 \end{datadesc}
  92
  93 \begin{datadesc}{PLAYING}
  94 The drive is in CD player mode playing an audio CD through its audio
  95 jacks.
  96 \end{datadesc}
  97
  98 \begin{datadesc}{PAUSED}
  99 The drive is in CD layer mode with play paused.
 100 \end{datadesc}
 101
 102 \begin{datadesc}{STILL}
 103 The equivalent of \constant{PAUSED} on older (non 3301) model Toshiba
 104 CD-ROM drives.  Such drives have never been shipped by SGI.
 105 \end{datadesc}
 106
 107 \begin{datadesc}{audio}
 108 \dataline{pnum}
 109 \dataline{index}
 110 \dataline{ptime}
 111 \dataline{atime}
 112 \dataline{catalog}
 113 \dataline{ident}
 114 \dataline{control}
 115 Integer constants describing the various types of parser callbacks
 116 that can be set by the \method{addcallback()} method of CD parser
 117 objects (see below).
 118 \end{datadesc}
 119
 120
 121 \subsection{Player Objects}
 122 \label{player-objects}
 123
 124 Player objects (returned by \function{open()}) have the following
 125 methods:
 126
 127 \begin{methoddesc}[CD player]{allowremoval}{}
 128 Unlocks the eject button on the CD-ROM drive permitting the user to
 129 eject the caddy if desired.
 130 \end{methoddesc}
 131
 132 \begin{methoddesc}[CD player]{bestreadsize}{}
 133 Returns the best value to use for the \var{num_frames} parameter of
 134 the \method{readda()} method.  Best is defined as the value that
 135 permits a continuous flow of data from the CD-ROM drive.
 136 \end{methoddesc}
 137
 138 \begin{methoddesc}[CD player]{close}{}
 139 Frees the resources associated with the player object.  After calling
 140 \method{close()}, the methods of the object should no longer be used.
 141 \end{methoddesc}
 142
 143 \begin{methoddesc}[CD player]{eject}{}
 144 Ejects the caddy from the CD-ROM drive.
 145 \end{methoddesc}
 146
 147 \begin{methoddesc}[CD player]{getstatus}{}
 148 Returns information pertaining to the current state of the CD-ROM
 149 drive.  The returned information is a tuple with the following values:
 150 \var{state}, \var{track}, \var{rtime}, \var{atime}, \var{ttime},
 151 \var{first}, \var{last}, \var{scsi_audio}, \var{cur_block}.
 152 \var{rtime} is the time relative to the start of the current track;
 153 \var{atime} is the time relative to the beginning of the disc;
 154 \var{ttime} is the total time on the disc.  For more information on
 155 the meaning of the values, see the man page \manpage{CDgetstatus}{3dm}.
 156 The value of \var{state} is one of the following: \constant{ERROR},
 157 \constant{NODISC}, \constant{READY}, \constant{PLAYING},
 158 \constant{PAUSED}, \constant{STILL}, or \constant{CDROM}.
 159 \end{methoddesc}
 160
 161 \begin{methoddesc}[CD player]{gettrackinfo}{track}
 162 Returns information about the specified track.  The returned
 163 information is a tuple consisting of two elements, the start time of
 164 the track and the duration of the track.
 165 \end{methoddesc}
 166
 167 \begin{methoddesc}[CD player]{msftoblock}{min, sec, frame}
 168 Converts a minutes, seconds, frames triple representing a time in
 169 absolute time code into the corresponding logical block number for the
 170 given CD-ROM drive.  You should use \function{msftoframe()} rather than
 171 \method{msftoblock()} for comparing times.  The logical block number
 172 differs from the frame number by an offset required by certain CD-ROM
 173 drives.
 174 \end{methoddesc}
 175
 176 \begin{methoddesc}[CD player]{play}{start, play}
 177 Starts playback of an audio CD in the CD-ROM drive at the specified
 178 track.  The audio output appears on the CD-ROM drive's headphone and
 179 audio jacks (if fitted).  Play stops at the end of the disc.
 180 \var{start} is the number of the track at which to start playing the
 181 CD; if \var{play} is 0, the CD will be set to an initial paused
 182 state.  The method \method{togglepause()} can then be used to commence
 183 play.
 184 \end{methoddesc}
 185
 186 \begin{methoddesc}[CD player]{playabs}{minutes, seconds, frames, play}
 187 Like \method{play()}, except that the start is given in minutes,
 188 seconds, and frames instead of a track number.
 189 \end{methoddesc}
 190
 191 \begin{methoddesc}[CD player]{playtrack}{start, play}
 192 Like \method{play()}, except that playing stops at the end of the
 193 track.
 194 \end{methoddesc}
 195
 196 \begin{methoddesc}[CD player]{playtrackabs}{track, minutes, seconds, frames, play}
 197 Like \method{play()}, except that playing begins at the specified
 198 absolute time and ends at the end of the specified track.
 199 \end{methoddesc}
 200
 201 \begin{methoddesc}[CD player]{preventremoval}{}
 202 Locks the eject button on the CD-ROM drive thus preventing the user
 203 from arbitrarily ejecting the caddy.
 204 \end{methoddesc}
 205
 206 \begin{methoddesc}[CD player]{readda}{num_frames}
 207 Reads the specified number of frames from an audio CD mounted in the
 208 CD-ROM drive.  The return value is a string representing the audio
 209 frames.  This string can be passed unaltered to the
 210 \method{parseframe()} method of the parser object.
 211 \end{methoddesc}
 212
 213 \begin{methoddesc}[CD player]{seek}{minutes, seconds, frames}
 214 Sets the pointer that indicates the starting point of the next read of
 215 digital audio data from a CD-ROM.  The pointer is set to an absolute
 216 time code location specified in \var{minutes}, \var{seconds}, and
 217 \var{frames}.  The return value is the logical block number to which
 218 the pointer has been set.
 219 \end{methoddesc}
 220
 221 \begin{methoddesc}[CD player]{seekblock}{block}
 222 Sets the pointer that indicates the starting point of the next read of
 223 digital audio data from a CD-ROM.  The pointer is set to the specified
 224 logical block number.  The return value is the logical block number to
 225 which the pointer has been set.
 226 \end{methoddesc}
 227
 228 \begin{methoddesc}[CD player]{seektrack}{track}
 229 Sets the pointer that indicates the starting point of the next read of
 230 digital audio data from a CD-ROM.  The pointer is set to the specified
 231 track.  The return value is the logical block number to which the
 232 pointer has been set.
 233 \end{methoddesc}
 234
 235 \begin{methoddesc}[CD player]{stop}{}
 236 Stops the current playing operation.
 237 \end{methoddesc}
 238
 239 \begin{methoddesc}[CD player]{togglepause}{}
 240 Pauses the CD if it is playing, and makes it play if it is paused.
 241 \end{methoddesc}
 242
 243
 244 \subsection{Parser Objects}
 245 \label{cd-parser-objects}
 246
 247 Parser objects (returned by \function{createparser()}) have the
 248 following methods:
 249
 250 \begin{methoddesc}[CD parser]{addcallback}{type, func, arg}
 251 Adds a callback for the parser.  The parser has callbacks for eight
 252 different types of data in the digital audio data stream.  Constants
 253 for these types are defined at the \module{cd} module level (see above).
 254 The callback is called as follows: \code{\var{func}(\var{arg}, type,
 255 data)}, where \var{arg} is the user supplied argument, \var{type} is
 256 the particular type of callback, and \var{data} is the data returned
 257 for this \var{type} of callback.  The type of the data depends on the
 258 \var{type} of callback as follows:
 259
 260 \begin{tableii}{l|p{4in}}{code}{Type}{Value}
 261   \lineii{audio}{String which can be passed unmodified to
 262 \function{al.writesamps()}.}
 263   \lineii{pnum}{Integer giving the program (track) number.}
 264   \lineii{index}{Integer giving the index number.}
 265   \lineii{ptime}{Tuple consisting of the program time in minutes,
 266 seconds, and frames.}
 267   \lineii{atime}{Tuple consisting of the absolute time in minutes,
 268 seconds, and frames.}
 269   \lineii{catalog}{String of 13 characters, giving the catalog number
 270 of the CD.}
 271   \lineii{ident}{String of 12 characters, giving the ISRC
 272 identification number of the recording.  The string consists of two
 273 characters country code, three characters owner code, two characters
 274 giving the year, and five characters giving a serial number.}
 275   \lineii{control}{Integer giving the control bits from the CD
 276 subcode data}
 277 \end{tableii}
 278 \end{methoddesc}
 279
 280 \begin{methoddesc}[CD parser]{deleteparser}{}
 281 Deletes the parser and frees the memory it was using.  The object
 282 should not be used after this call.  This call is done automatically
 283 when the last reference to the object is removed.
 284 \end{methoddesc}
 285
 286 \begin{methoddesc}[CD parser]{parseframe}{frame}
 287 Parses one or more frames of digital audio data from a CD such as
 288 returned by \method{readda()}.  It determines which subcodes are
 289 present in the data.  If these subcodes have changed since the last
 290 frame, then \method{parseframe()} executes a callback of the
 291 appropriate type passing to it the subcode data found in the frame.
 292 Unlike the \C{} function, more than one frame of digital audio data
 293 can be passed to this method.
 294 \end{methoddesc}
 295
 296 \begin{methoddesc}[CD parser]{removecallback}{type}
 297 Removes the callback for the given \var{type}.
 298 \end{methoddesc}
 299
 300 \begin{methoddesc}[CD parser]{resetparser}{}
 301 Resets the fields of the parser used for tracking subcodes to an
 302 initial state.  \method{resetparser()} should be called after the disc
 303 has been changed.
 304 \end{methoddesc}