Doc/libcd.tex

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