PageRenderTime 407ms CodeModel.GetById 161ms app.highlight 12ms RepoModel.GetById 229ms app.codeStats 1ms

/Doc/library/cd.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 340 lines | 207 code | 133 blank | 0 comment | 0 complexity | 59e6b3547e8f6d9da21b7000fe05311f MD5 | raw file
  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
 15This module provides an interface to the Silicon Graphics CD library. It is
 16available only on Silicon Graphics systems.
 17
 18The 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
 21data from the CD, but also to get status information for the CD-ROM device, and
 22to get information about the CD, such as the table of contents.  Data from the
 23CD is passed to the parser, which parses the frames, and calls any callback
 24functions that have previously been added.
 25
 26An audio CD is divided into :dfn:`tracks` or :dfn:`programs` (the terms are used
 27interchangeably).  Tracks can be subdivided into :dfn:`indices`.  An audio CD
 28contains a :dfn:`table of contents` which gives the starts of the tracks on the
 29CD.  Index 0 is usually the pause before the start of a track.  The start of the
 30track as given by the table of contents is normally the start of index 1.
 31
 32Positions on a CD can be represented in two ways.  Either a frame number or a
 33tuple of three values, minutes, seconds and frames.  Most functions use the
 34latter representation.  Positions can be both relative to the beginning of the
 35CD, and to the beginning of the track.
 36
 37Module :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
 60The 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
 78The 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
133Player Objects
134--------------
135
136Player 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
267Parser Objects
268--------------
269
270Parser 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