# cpython / Doc / lib / libcd.tex

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