| \section{Built-in Module \sectcode{cd}} |
| \label{module-cd} |
| \bimodindex{cd} |
| |
| This module provides an interface to the Silicon Graphics CD library. |
| It is available only on Silicon Graphics systems. |
| |
| The way the library works is as follows. A program opens the CD-ROM |
| device with \function{open()} and creates a parser to parse the data |
| from the CD with \function{createparser()}. The object returned by |
| \function{open()} can be used to read data from the CD, but also to get |
| status information for the CD-ROM device, and to get information about |
| the CD, such as the table of contents. Data from the CD is passed to |
| the parser, which parses the frames, and calls any callback |
| functions that have previously been added. |
| |
| An audio CD is divided into \dfn{tracks} or \dfn{programs} (the terms |
| are used interchangeably). Tracks can be subdivided into |
| \dfn{indices}. An audio CD contains a \dfn{table of contents} which |
| gives the starts of the tracks on the CD. Index 0 is usually the |
| pause before the start of a track. The start of the track as given by |
| the table of contents is normally the start of index 1. |
| |
| Positions on a CD can be represented in two ways. Either a frame |
| number or a tuple of three values, minutes, seconds and frames. Most |
| functions use the latter representation. Positions can be both |
| relative to the beginning of the CD, and to the beginning of the |
| track. |
| |
| Module \module{cd} defines the following functions and constants: |
| |
| |
| \begin{funcdesc}{createparser}{} |
| Create and return an opaque parser object. The methods of the parser |
| object are described below. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{msftoframe}{minutes, seconds, frames} |
| Converts a \code{(\var{minutes}, \var{seconds}, \var{frames})} triple |
| representing time in absolute time code into the corresponding CD |
| frame number. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{open}{\optional{device\optional{, mode}}} |
| Open the CD-ROM device. The return value is an opaque player object; |
| methods of the player object are described below. The device is the |
| name of the SCSI device file, e.g. \code{'/dev/scsi/sc0d4l0'}, or |
| \code{None}. If omitted or \code{None}, the hardware inventory is |
| consulted to locate a CD-ROM drive. The \var{mode}, if not omited, |
| should be the string \code{'r'}. |
| \end{funcdesc} |
| |
| The module defines the following variables: |
| |
| \begin{excdesc}{error} |
| Exception raised on various errors. |
| \end{excdesc} |
| |
| \begin{datadesc}{DATASIZE} |
| The size of one frame's worth of audio data. This is the size of the |
| audio data as passed to the callback of type \code{audio}. |
| \end{datadesc} |
| |
| \begin{datadesc}{BLOCKSIZE} |
| The size of one uninterpreted frame of audio data. |
| \end{datadesc} |
| |
| The following variables are states as returned by |
| \function{getstatus()}: |
| |
| \begin{datadesc}{READY} |
| The drive is ready for operation loaded with an audio CD. |
| \end{datadesc} |
| |
| \begin{datadesc}{NODISC} |
| The drive does not have a CD loaded. |
| \end{datadesc} |
| |
| \begin{datadesc}{CDROM} |
| The drive is loaded with a CD-ROM. Subsequent play or read operations |
| will return I/O errors. |
| \end{datadesc} |
| |
| \begin{datadesc}{ERROR} |
| An error aoocurred while trying to read the disc or its table of |
| contents. |
| \end{datadesc} |
| |
| \begin{datadesc}{PLAYING} |
| The drive is in CD player mode playing an audio CD through its audio |
| jacks. |
| \end{datadesc} |
| |
| \begin{datadesc}{PAUSED} |
| The drive is in CD layer mode with play paused. |
| \end{datadesc} |
| |
| \begin{datadesc}{STILL} |
| The equivalent of \constant{PAUSED} on older (non 3301) model Toshiba |
| CD-ROM drives. Such drives have never been shipped by SGI. |
| \end{datadesc} |
| |
| \begin{datadesc}{audio} |
| \dataline{pnum} |
| \dataline{index} |
| \dataline{ptime} |
| \dataline{atime} |
| \dataline{catalog} |
| \dataline{ident} |
| \dataline{control} |
| Integer constants describing the various types of parser callbacks |
| that can be set by the \method{addcallback()} method of CD parser |
| objects (see below). |
| \end{datadesc} |
| |
| Player objects (returned by \function{open()}) have the following |
| methods: |
| |
| \setindexsubitem{(CD player method)} |
| |
| \begin{funcdesc}{allowremoval}{} |
| Unlocks the eject button on the CD-ROM drive permitting the user to |
| eject the caddy if desired. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{bestreadsize}{} |
| Returns the best value to use for the \var{num_frames} parameter of |
| the \method{readda()} method. Best is defined as the value that |
| permits a continuous flow of data from the CD-ROM drive. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{close}{} |
| Frees the resources associated with the player object. After calling |
| \method{close()}, the methods of the object should no longer be used. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{eject}{} |
| Ejects the caddy from the CD-ROM drive. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getstatus}{} |
| Returns information pertaining to the current state of the CD-ROM |
| drive. The returned information is a tuple with the following values: |
| \var{state}, \var{track}, \var{rtime}, \var{atime}, \var{ttime}, |
| \var{first}, \var{last}, \var{scsi_audio}, \var{cur_block}. |
| \var{rtime} is the time relative to the start of the current track; |
| \var{atime} is the time relative to the beginning of the disc; |
| \var{ttime} is the total time on the disc. For more information on |
| the meaning of the values, see the man page \manpage{CDgetstatus}{3dm}. |
| The value of \var{state} is one of the following: \constant{ERROR}, |
| \constant{NODISC}, \constant{READY}, \constant{PLAYING}, |
| \constant{PAUSED}, \constant{STILL}, or \constant{CDROM}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{gettrackinfo}{track} |
| Returns information about the specified track. The returned |
| information is a tuple consisting of two elements, the start time of |
| the track and the duration of the track. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{msftoblock}{min, sec, frame} |
| Converts a minutes, seconds, frames triple representing a time in |
| absolute time code into the corresponding logical block number for the |
| given CD-ROM drive. You should use \function{msftoframe()} rather than |
| \method{msftoblock()} for comparing times. The logical block number |
| differs from the frame number by an offset required by certain CD-ROM |
| drives. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{play}{start, play} |
| Starts playback of an audio CD in the CD-ROM drive at the specified |
| track. The audio output appears on the CD-ROM drive's headphone and |
| audio jacks (if fitted). Play stops at the end of the disc. |
| \var{start} is the number of the track at which to start playing the |
| CD; if \var{play} is 0, the CD will be set to an initial paused |
| state. The method \method{togglepause()} can then be used to commence |
| play. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{playabs}{minutes, seconds, frames, play} |
| Like \method{play()}, except that the start is given in minutes, |
| seconds, and frames instead of a track number. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{playtrack}{start, play} |
| Like \method{play()}, except that playing stops at the end of the |
| track. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{playtrackabs}{track, minutes, seconds, frames, play} |
| Like \method{play()}, except that playing begins at the spcified |
| absolute time and ends at the end of the specified track. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{preventremoval}{} |
| Locks the eject button on the CD-ROM drive thus preventing the user |
| from arbitrarily ejecting the caddy. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{readda}{num_frames} |
| Reads the specified number of frames from an audio CD mounted in the |
| CD-ROM drive. The return value is a string representing the audio |
| frames. This string can be passed unaltered to the |
| \method{parseframe()} method of the parser object. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{seek}{minutes, seconds, frames} |
| Sets the pointer that indicates the starting point of the next read of |
| digital audio data from a CD-ROM. The pointer is set to an absolute |
| time code location specified in \var{minutes}, \var{seconds}, and |
| \var{frames}. The return value is the logical block number to which |
| the pointer has been set. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{seekblock}{block} |
| Sets the pointer that indicates the starting point of the next read of |
| digital audio data from a CD-ROM. The pointer is set to the specified |
| logical block number. The return value is the logical block number to |
| which the pointer has been set. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{seektrack}{track} |
| Sets the pointer that indicates the starting point of the next read of |
| digital audio data from a CD-ROM. The pointer is set to the specified |
| track. The return value is the logical block number to which the |
| pointer has been set. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{stop}{} |
| Stops the current playing operation. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{togglepause}{} |
| Pauses the CD if it is playing, and makes it play if it is paused. |
| \end{funcdesc} |
| |
| Parser objects (returned by \function{createparser()}) have the |
| following methods: |
| |
| \setindexsubitem{(CD parser method)} |
| |
| \begin{funcdesc}{addcallback}{type, func, arg} |
| Adds a callback for the parser. The parser has callbacks for eight |
| different types of data in the digital audio data stream. Constants |
| for these types are defined at the \module{cd} module level (see above). |
| The callback is called as follows: \code{\var{func}(\var{arg}, type, |
| data)}, where \var{arg} is the user supplied argument, \var{type} is |
| the particular type of callback, and \var{data} is the data returned |
| for this \var{type} of callback. The type of the data depends on the |
| \var{type} of callback as follows: |
| |
| \begin{tableii}{|l|l|}{code}{Type}{Value} |
| \lineii{audio}{String which can be passed unmodified to |
| \function{al.writesamps()}.} |
| \lineii{pnum}{Integer giving the program (track) number.} |
| \lineii{index}{Integer giving the index number.} |
| \lineii{ptime}{Tuple consisting of the program time in minutes, |
| seconds, and frames.} |
| \lineii{atime}{Tuple consisting of the absolute time in minutes, |
| seconds, and frames.} |
| \lineii{catalog}{String of 13 characters, giving the catalog number |
| of the CD.} |
| \lineii{ident}{String of 12 characters, giving the ISRC |
| identification number of the recording. \\ |
| &The string consists of two characters country code, three characters |
| owner code, \\ |
| &two characters giving the year, and five characters giving a serial number.} |
| \lineii{control}{Integer giving the control bits from the CD |
| subcode data} |
| \end{tableii} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{deleteparser}{} |
| Deletes the parser and frees the memory it was using. The object |
| should not be used after this call. This call is done automatically |
| when the last reference to the object is removed. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{parseframe}{frame} |
| Parses one or more frames of digital audio data from a CD such as |
| returned by \method{readda()}. It determines which subcodes are |
| present in the data. If these subcodes have changed since the last |
| frame, then \method{parseframe()} executes a callback of the |
| appropriate type passing to it the subcode data found in the frame. |
| Unlike the \C{} function, more than one frame of digital audio data |
| can be passed to this method. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{removecallback}{type} |
| Removes the callback for the given \var{type}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{resetparser}{} |
| Resets the fields of the parser used for tracking subcodes to an |
| initial state. \method{resetparser()} should be called after the disc |
| has been changed. |
| \end{funcdesc} |