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