/Lib/plat-irix6/readcd.doc

  1Interface to CD-ROM player.
  2
  3This module implements an interface to the built-in cd module.  The
  4intention is to provide a more user-friendly interface than the
  5built-in module.
  6
  7The module defines a class Readcd with several methods.  The
  8initialization of the class will try to open the CD player.  This
  9means that initialization will fail if the CD player is already in
 10use.  A RuntimeError will be raised by the cd module in that case.
 11
 12The way to work with this module is as follows.  The user specifies
 13the parts of the CD that are to be read and he specifies callback
 14functions which are to be called by the system.  At some point he can
 15tell the system to play.  The specified parts of the CD will then be
 16read and the callbacks will be called.
 17
 18Initialization.
 19===============
 20
 21r = readcd.Readcd([cd-player [, mode]])
 22
 23The optional arguments are the name of the CD device and the mode.
 24When "mode" is not specified, it defaults to 'r' (which is the only
 25possible value); when "cd-player" also isn't specified, it defaults
 26to "None" which indicates the default CD player.
 27
 28Methods.
 29========
 30
 31eject() -- Eject the CD from the player.
 32
 33reset() -- Reset the list of data stretches to be played.
 34
 35appendtrack(track) -- Append the specified track to the list of music
 36stretches.
 37
 38appendstretch(first, last) -- Append the stretch from "first" to "last"
 39to the list of music stretches.  Both "first" and "last" can be in one
 40of four forms.  "None": for "first", the beginning of the CD, for
 41"last" the end of the CD; a single integer: a track number--playing
 42starts at the beginning of the track or ends at the end of the
 43specified track; a three-tuple: the absolute time from the start of
 44the CD in minutes, seconds, frames; a four-tuple: track number and
 45relative time within the track in minutes, seconds, frames.
 46
 47settracks(tracklist) -- The argument is a list of integers.  The list
 48of stretches is set to argument list.  The old list is discarded.
 49
 50setcallback(type, func, arg) -- Set a callback function for "type".
 51The function will be called as func(arg, type, data) where "arg" is
 52the third argument of setcallback, "type" is the type of callback,
 53"data" is type-dependent data.  See the CDsetcallback(3) manual page
 54for more information.  The possible "type" arguments are defined in
 55the CD module.
 56
 57removecallback(type) -- Remove the callback for "type".
 58
 59gettrackinfo([tracklist]) -- Return a list of tuples.  Each tuple
 60consists of start and length information of a track.  The start and
 61length information consist of three-tuples with minutes, seconds and
 62frames.  The optional tracklist argument gives a list of interesting
 63track numbers.  If no tracklist is specified, information about all
 64tracks is returned.
 65
 66getstatus() -- Return the status information of the CD.
 67
 68play() -- Play the preprogrammed stretches of music from the CD.  When
 69nothing was programmed, the whole CD is played.
 70
 71Specifying stretches.
 72=====================
 73
 74There are three methods available to specify a stretch of music to be
 75played.  The easiest way is to use "settracklist(tracklist)" with which
 76a list of tracks can be specified.  "settracklist(tracklist)" is
 77equivalent to the sequence
 78	reset()
 79	for track in tracklist:
 80		appendtrack(track)
 81
 82The next method is "appendtrack(track)" with which a whole track can be
 83added to the list of music to be played.  "appendtrack(track)" is
 84equivalent to "appendstretch(track, track)".
 85
 86The most complete method is "appendstretch(first, last)".  Using this
 87method, it is possible to specify any stretch of music.
 88
 89When two consecutive tracks are played, it is possible to choose
 90whether the pause that may be between the tracks is played as well or
 91whether the pause should be skipped.  When the end of a stretch is
 92specified using a track number and the next stretch starts at the
 93beginning of the following track and that was also specified using the
 94track number (that is, both were specified as integers, not as tuples),
 95the pause is played.  When either value was specified using absolute
 96time or track-relative time (that is, as three-tuple or as
 97four-tuple), the pause will not be played.
 98
 99Errors.
100=======
101
102When an error occurs, an exception will be raised.  Depending on where
103the error occurs, the exception may either be "readcd.Error" or
104"RuntimeError".