Doc/library/cd.rst

   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 deprecated for removal in Python 3.0.
  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