[2] | 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
|
---|
[391] | 12 | The :mod:`cd` module has been removed in Python 3.
|
---|
[2] | 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 |
|
---|