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