Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{cd}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-cd} |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 3 | \bimodindex{cd} |
| 4 | |
| 5 | This module provides an interface to the Silicon Graphics CD library. |
| 6 | It is available only on Silicon Graphics systems. |
| 7 | |
| 8 | The way the library works is as follows. A program opens the CD-ROM |
| 9 | device with \code{cd.open()} and creates a parser to parse the data |
| 10 | from the CD with \code{cd.createparser()}. The object returned by |
| 11 | \code{cd.open()} can be used to read data from the CD, but also to get |
| 12 | status information for the CD-ROM device, and to get information about |
| 13 | the CD, such as the table of contents. Data from the CD is passed to |
| 14 | the parser, which parses the frames, and calls any callback |
| 15 | functions that have previously been added. |
| 16 | |
| 17 | An audio CD is divided into \dfn{tracks} or \dfn{programs} (the terms |
| 18 | are used interchangeably). Tracks can be subdivided into |
| 19 | \dfn{indices}. An audio CD contains a \dfn{table of contents} which |
| 20 | gives the starts of the tracks on the CD. Index 0 is usually the |
| 21 | pause before the start of a track. The start of the track as given by |
| 22 | the table of contents is normally the start of index 1. |
| 23 | |
| 24 | Positions on a CD can be represented in two ways. Either a frame |
| 25 | number or a tuple of three values, minutes, seconds and frames. Most |
| 26 | functions use the latter representation. Positions can be both |
| 27 | relative to the beginning of the CD, and to the beginning of the |
| 28 | track. |
| 29 | |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 30 | Module \code{cd} defines the following functions and constants: |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 31 | |
| 32 | \renewcommand{\indexsubitem}{(in module cd)} |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 33 | |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 34 | \begin{funcdesc}{createparser}{} |
| 35 | Create and return an opaque parser object. The methods of the parser |
| 36 | object are described below. |
| 37 | \end{funcdesc} |
| 38 | |
| 39 | \begin{funcdesc}{msftoframe}{min\, sec\, frame} |
| 40 | Converts a \code{(minutes, seconds, frames)} triple representing time |
| 41 | in absolute time code into the corresponding CD frame number. |
| 42 | \end{funcdesc} |
| 43 | |
| 44 | \begin{funcdesc}{open}{\optional{device\optional{\, mode}}} |
| 45 | Open the CD-ROM device. The return value is an opaque player object; |
| 46 | methods of the player object are described below. The device is the |
| 47 | name of the SCSI device file, e.g. /dev/scsi/sc0d4l0, or \code{None}. |
| 48 | If omited or \code{None}, the hardware inventory is consulted to |
| 49 | locate a CD-ROM drive. The \code{mode}, if not omited, should be the |
| 50 | string 'r'. |
| 51 | \end{funcdesc} |
| 52 | |
| 53 | The module defines the following variables: |
| 54 | |
| 55 | \begin{datadesc}{error} |
| 56 | Exception raised on various errors. |
| 57 | \end{datadesc} |
| 58 | |
| 59 | \begin{datadesc}{DATASIZE} |
| 60 | The size of one frame's worth of audio data. This is the size of the |
| 61 | audio data as passed to the callback of type \code{audio}. |
| 62 | \end{datadesc} |
| 63 | |
| 64 | \begin{datadesc}{BLOCKSIZE} |
| 65 | The size of one uninterpreted frame of audio data. |
| 66 | \end{datadesc} |
| 67 | |
| 68 | The following variables are states as returned by \code{getstatus}: |
| 69 | |
| 70 | \begin{datadesc}{READY} |
| 71 | The drive is ready for operation loaded with an audio CD. |
| 72 | \end{datadesc} |
| 73 | |
| 74 | \begin{datadesc}{NODISC} |
| 75 | The drive does not have a CD loaded. |
| 76 | \end{datadesc} |
| 77 | |
| 78 | \begin{datadesc}{CDROM} |
| 79 | The drive is loaded with a CD-ROM. Subsequent play or read operations |
| 80 | will return I/O errors. |
| 81 | \end{datadesc} |
| 82 | |
| 83 | \begin{datadesc}{ERROR} |
| 84 | An error aoocurred while trying to read the disc or its table of |
| 85 | contents. |
| 86 | \end{datadesc} |
| 87 | |
| 88 | \begin{datadesc}{PLAYING} |
| 89 | The drive is in CD player mode playing an audio CD through its audio |
| 90 | jacks. |
| 91 | \end{datadesc} |
| 92 | |
| 93 | \begin{datadesc}{PAUSED} |
| 94 | The drive is in CD layer mode with play paused. |
| 95 | \end{datadesc} |
| 96 | |
| 97 | \begin{datadesc}{STILL} |
| 98 | The equivalent of \code{PAUSED} on older (non 3301) model Toshiba |
| 99 | CD-ROM drives. Such drives have never been shipped by SGI. |
| 100 | \end{datadesc} |
| 101 | |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 102 | \begin{datadesc}{audio} |
| 103 | \dataline{pnum} |
| 104 | \dataline{index} |
| 105 | \dataline{ptime} |
| 106 | \dataline{atime} |
| 107 | \dataline{catalog} |
| 108 | \dataline{ident} |
| 109 | \dataline{control} |
| 110 | Integer constants describing the various types of parser callbacks |
| 111 | that can be set by the \code{addcallback()} method of CD parser |
| 112 | objects (see below). |
| 113 | \end{datadesc} |
| 114 | |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 115 | Player objects (returned by \code{cd.open()}) have the following |
| 116 | methods: |
| 117 | |
| 118 | \renewcommand{\indexsubitem}{(CD player object method)} |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 119 | |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 120 | \begin{funcdesc}{allowremoval}{} |
| 121 | Unlocks the eject button on the CD-ROM drive permitting the user to |
| 122 | eject the caddy if desired. |
| 123 | \end{funcdesc} |
| 124 | |
| 125 | \begin{funcdesc}{bestreadsize}{} |
| 126 | Returns the best value to use for the \code{num_frames} parameter of |
| 127 | the \code{readda} method. Best is defined as the value that permits a |
| 128 | continuous flow of data from the CD-ROM drive. |
| 129 | \end{funcdesc} |
| 130 | |
| 131 | \begin{funcdesc}{close}{} |
| 132 | Frees the resources associated with the player object. After calling |
| 133 | \code{close}, the methods of the object should no longer be used. |
| 134 | \end{funcdesc} |
| 135 | |
| 136 | \begin{funcdesc}{eject}{} |
| 137 | Ejects the caddy from the CD-ROM drive. |
| 138 | \end{funcdesc} |
| 139 | |
| 140 | \begin{funcdesc}{getstatus}{} |
| 141 | Returns information pertaining to the current state of the CD-ROM |
| 142 | drive. The returned information is a tuple with the following values: |
| 143 | \code{state}, \code{track}, \code{rtime}, \code{atime}, \code{ttime}, |
| 144 | \code{first}, \code{last}, \code{scsi_audio}, \code{cur_block}. |
| 145 | \code{rtime} is the time relative to the start of the current track; |
| 146 | \code{atime} is the time relative to the beginning of the disc; |
| 147 | \code{ttime} is the total time on the disc. For more information on |
| 148 | the meaning of the values, see the manual for CDgetstatus. |
| 149 | The value of \code{state} is one of the following: \code{cd.ERROR}, |
| 150 | \code{cd.NODISC}, \code{cd.READY}, \code{cd.PLAYING}, |
| 151 | \code{cd.PAUSED}, \code{cd.STILL}, or \code{cd.CDROM}. |
| 152 | \end{funcdesc} |
| 153 | |
| 154 | \begin{funcdesc}{gettrackinfo}{track} |
| 155 | Returns information about the specified track. The returned |
| 156 | information is a tuple consisting of two elements, the start time of |
| 157 | the track and the duration of the track. |
| 158 | \end{funcdesc} |
| 159 | |
| 160 | \begin{funcdesc}{msftoblock}{min\, sec\, frame} |
| 161 | Converts a minutes, seconds, frames triple representing a time in |
| 162 | absolute time code into the corresponding logical block number for the |
| 163 | given CD-ROM drive. You should use \code{cd.msftoframe()} rather than |
| 164 | \code{msftoblock()} for comparing times. The logical block number |
| 165 | differs from the frame number by an offset required by certain CD-ROM |
| 166 | drives. |
| 167 | \end{funcdesc} |
| 168 | |
| 169 | \begin{funcdesc}{play}{start\, play} |
| 170 | Starts playback of an audio CD in the CD-ROM drive at the specified |
| 171 | track. The audio output appears on the CD-ROM drive's headphone and |
| 172 | audio jacks (if fitted). Play stops at the end of the disc. |
| 173 | \code{start} is the number of the track at which to start playing the |
| 174 | CD; if \code{play} is 0, the CD will be set to an initial paused |
| 175 | state. The method \code{togglepause()} can then be used to commence |
| 176 | play. |
| 177 | \end{funcdesc} |
| 178 | |
| 179 | \begin{funcdesc}{playabs}{min\, sec\, frame\, play} |
| 180 | Like \code{play()}, except that the start is given in minutes, |
| 181 | seconds, frames instead of a track number. |
| 182 | \end{funcdesc} |
| 183 | |
| 184 | \begin{funcdesc}{playtrack}{start\, play} |
| 185 | Like \code{play()}, except that playing stops at the end of the track. |
| 186 | \end{funcdesc} |
| 187 | |
| 188 | \begin{funcdesc}{playtrackabs}{track\, min\, sec\, frame\, play} |
| 189 | Like \code{play()}, except that playing begins at the spcified |
| 190 | absolute time and ends at the end of the specified track. |
| 191 | \end{funcdesc} |
| 192 | |
| 193 | \begin{funcdesc}{preventremoval}{} |
| 194 | Locks the eject button on the CD-ROM drive thus preventing the user |
| 195 | from arbitrarily ejecting the caddy. |
| 196 | \end{funcdesc} |
| 197 | |
| 198 | \begin{funcdesc}{readda}{num_frames} |
| 199 | Reads the specified number of frames from an audio CD mounted in the |
| 200 | CD-ROM drive. The return value is a string representing the audio |
| 201 | frames. This string can be passed unaltered to the \code{parseframe} |
| 202 | method of the parser object. |
| 203 | \end{funcdesc} |
| 204 | |
| 205 | \begin{funcdesc}{seek}{min\, sec\, frame} |
| 206 | Sets the pointer that indicates the starting point of the next read of |
| 207 | digital audio data from a CD-ROM. The pointer is set to an absolute |
| 208 | time code location specified in minutes, seconds, and frames. The |
| 209 | return value is the logical block number to which the pointer has been |
| 210 | set. |
| 211 | \end{funcdesc} |
| 212 | |
| 213 | \begin{funcdesc}{seekblock}{block} |
| 214 | Sets the pointer that indicates the starting point of the next read of |
| 215 | digital audio data from a CD-ROM. The pointer is set to the specified |
| 216 | logical block number. The return value is the logical block number to |
| 217 | which the pointer has been set. |
| 218 | \end{funcdesc} |
| 219 | |
| 220 | \begin{funcdesc}{seektrack}{track} |
| 221 | Sets the pointer that indicates the starting point of the next read of |
| 222 | digital audio data from a CD-ROM. The pointer is set to the specified |
| 223 | track. The return value is the logical block number to which the |
| 224 | pointer has been set. |
| 225 | \end{funcdesc} |
| 226 | |
| 227 | \begin{funcdesc}{stop}{} |
| 228 | Stops the current playing operation. |
| 229 | \end{funcdesc} |
| 230 | |
| 231 | \begin{funcdesc}{togglepause}{} |
| 232 | Pauses the CD if it is playing, and makes it play if it is paused. |
| 233 | \end{funcdesc} |
| 234 | |
| 235 | Parser objects (returned by \code{cd.createparser()}) have the |
| 236 | following methods: |
| 237 | |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 238 | \renewcommand{\indexsubitem}{(CD parser object method)} |
| 239 | |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 240 | \begin{funcdesc}{addcallback}{type\, func\, arg} |
| 241 | Adds a callback for the parser. The parser has callbacks for eight |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 242 | different types of data in the digital audio data stream. Constants |
| 243 | for these types are defined at the \code{cd} module level (see above). |
| 244 | The callback is called as follows: \code{func(arg, type, data)}, where |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 245 | \code{arg} is the user supplied argument, \code{type} is the |
| 246 | particular type of callback, and \code{data} is the data returned for |
| 247 | this \code{type} of callback. The type of the data depends on the |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 248 | \code{type} of callback as follows: |
| 249 | \begin{description} |
| 250 | \item[\code{cd.audio}: ] |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 251 | The argument is a string which can be passed unmodified to |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 252 | \code{al.writesamps()}. |
| 253 | \item[\code{cd.pnum}: ] |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 254 | The argument is an integer giving the program (track) number. |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 255 | \item[\code{cd.index}: ] |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 256 | The argument is an integer giving the index number. |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 257 | \item[\code{cd.ptime}: ] |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 258 | The argument is a tuple consisting of the program time in minutes, |
| 259 | seconds, and frames. |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 260 | \item[\code{cd.atime}: ] |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 261 | The argument is a tuple consisting of the absolute time in minutes, |
| 262 | seconds, and frames. |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 263 | \item[\code{cd.catalog}: ] |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 264 | The argument is a string of 13 characters, giving the catalog number |
| 265 | of the CD. |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 266 | \item[\code{cd.ident}: ] |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 267 | The argument is a string of 12 characters, giving the ISRC |
| 268 | identification number of the recording. The string consists of two |
| 269 | characters country code, three characters owner code, two characters |
| 270 | giving the year, and five characters giving a serial number. |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 271 | \item[\code{cd.control}: ] |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 272 | The argument is an integer giving the control bits from the CD subcode |
| 273 | data. |
Guido van Rossum | d45c156 | 1995-03-30 11:47:50 +0000 | [diff] [blame] | 274 | \end{description} |
Sjoerd Mullender | ffd6de1 | 1995-03-28 11:56:52 +0000 | [diff] [blame] | 275 | \end{funcdesc} |
| 276 | |
| 277 | \begin{funcdesc}{deleteparser}{} |
| 278 | Deletes the parser and frees the memory it was using. The object |
| 279 | should not be used after this call. This call is done automatically |
| 280 | when the last reference to the object is removed. |
| 281 | \end{funcdesc} |
| 282 | |
| 283 | \begin{funcdesc}{parseframe}{frame} |
| 284 | Parses one or more frames of digital audio data from a CD such as |
| 285 | returned by \code{readda}. It determines which subcodes are present |
| 286 | in the data. If these subcodes have changed since the last frame, |
| 287 | then \code{parseframe} executes a callback of the appropriate type |
| 288 | passing to it the subcode data found in the frame. |
| 289 | Unlike the C function, more than one frame of digital audio data can |
| 290 | be passed to this method. |
| 291 | \end{funcdesc} |
| 292 | |
| 293 | \begin{funcdesc}{removecallback}{type} |
| 294 | Removes the callback for the given \code{type}. |
| 295 | \end{funcdesc} |
| 296 | |
| 297 | \begin{funcdesc}{resetparser}{} |
| 298 | Resets the fields of the parser used for tracking subcodes to an |
| 299 | initial state. \code{resetparser} should be called after the disc has |
| 300 | been changed. |
| 301 | \end{funcdesc} |