\section{\module{cd} --- CD-ROM access on SGI systems} \declaremodule{builtin}{cd} \platform{IRIX}\modulesynopsis{Interface to the CD-ROM on Silicon Graphics systems.} 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-ROMdevice with \function{open()} and creates a parser to parse the datafrom the CD with \function{createparser()}. The object returned by\function{open()} can be used to read data from the CD, but also to getstatus information for the CD-ROM device, and to get information aboutthe CD, such as the table of contents. Data from the CD is passed tothe parser, which parses the frames, and calls any callbackfunctions that have previously been added. An audio CD is divided into \dfn{tracks} or \dfn{programs} (the termsare used interchangeably). Tracks can be subdivided into\dfn{indices}. An audio CD contains a \dfn{table of contents} whichgives the starts of the tracks on the CD. Index 0 is usually thepause before the start of a track. The start of the track as given bythe table of contents is normally the start of index 1. Positions on a CD can be represented in two ways. Either a framenumber or a tuple of three values, minutes, seconds and frames. Mostfunctions use the latter representation. Positions can be bothrelative to the beginning of the CD, and to the beginning of thetrack. Module \module{cd} defines the following functions and constants: \begin{funcdesc}{createparser}{}Create and return an opaque parser object. The methods of the parserobject are described below.\end{funcdesc} \begin{funcdesc}{msftoframe}{minutes, seconds, frames}Converts a \code{(\var{minutes}, \var{seconds}, \var{frames})} triplerepresenting time in absolute time code into the corresponding CDframe 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 thename of the SCSI device file, e.g. \code{'/dev/scsi/sc0d4l0'}, or\code{None}. If omitted or \code{None}, the hardware inventory isconsulted to locate a CD-ROM drive. The \var{mode}, if not omitted,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 theaudio 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 operationswill return I/O errors.\end{datadesc} \begin{datadesc}{ERROR}An error occurred while trying to read the disc or its table ofcontents.\end{datadesc} \begin{datadesc}{PLAYING}The drive is in CD player mode playing an audio CD through its audiojacks.\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 ToshibaCD-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 callbacksthat can be set by the \method{addcallback()} method of CD parserobjects (see below).\end{datadesc} \subsection{Player Objects}\label{player-objects} Player objects (returned by \function{open()}) have the followingmethods: \begin{methoddesc}[CD player]{allowremoval}{}Unlocks the eject button on the CD-ROM drive permitting the user toeject the caddy if desired.\end{methoddesc} \begin{methoddesc}[CD player]{bestreadsize}{}Returns the best value to use for the \var{num_frames} parameter ofthe \method{readda()} method. Best is defined as the value thatpermits a continuous flow of data from the CD-ROM drive.\end{methoddesc} \begin{methoddesc}[CD player]{close}{}Frees the resources associated with the player object. After calling\method{close()}, the methods of the object should no longer be used.\end{methoddesc} \begin{methoddesc}[CD player]{eject}{}Ejects the caddy from the CD-ROM drive.\end{methoddesc} \begin{methoddesc}[CD player]{getstatus}{}Returns information pertaining to the current state of the CD-ROMdrive. 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 onthe 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{methoddesc} \begin{methoddesc}[CD player]{gettrackinfo}{track}Returns information about the specified track. The returnedinformation is a tuple consisting of two elements, the start time ofthe track and the duration of the track.\end{methoddesc} \begin{methoddesc}[CD player]{msftoblock}{min, sec, frame}Converts a minutes, seconds, frames triple representing a time inabsolute time code into the corresponding logical block number for thegiven CD-ROM drive. You should use \function{msftoframe()} rather than\method{msftoblock()} for comparing times. The logical block numberdiffers from the frame number by an offset required by certain CD-ROMdrives.\end{methoddesc} \begin{methoddesc}[CD player]{play}{start, play}Starts playback of an audio CD in the CD-ROM drive at the specifiedtrack. The audio output appears on the CD-ROM drive's headphone andaudio jacks (if fitted). Play stops at the end of the disc.\var{start} is the number of the track at which to start playing theCD; if \var{play} is 0, the CD will be set to an initial pausedstate. The method \method{togglepause()} can then be used to commenceplay.\end{methoddesc} \begin{methoddesc}[CD player]{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{methoddesc} \begin{methoddesc}[CD player]{playtrack}{start, play}Like \method{play()}, except that playing stops at the end of thetrack.\end{methoddesc} \begin{methoddesc}[CD player]{playtrackabs}{track, minutes, seconds, frames, play}Like \method{play()}, except that playing begins at the specifiedabsolute time and ends at the end of the specified track.\end{methoddesc} \begin{methoddesc}[CD player]{preventremoval}{}Locks the eject button on the CD-ROM drive thus preventing the userfrom arbitrarily ejecting the caddy.\end{methoddesc} \begin{methoddesc}[CD player]{readda}{num_frames}Reads the specified number of frames from an audio CD mounted in theCD-ROM drive. The return value is a string representing the audioframes. This string can be passed unaltered to the\method{parseframe()} method of the parser object.\end{methoddesc} \begin{methoddesc}[CD player]{seek}{minutes, seconds, frames}Sets the pointer that indicates the starting point of the next read ofdigital audio data from a CD-ROM. The pointer is set to an absolutetime code location specified in \var{minutes}, \var{seconds}, and\var{frames}. The return value is the logical block number to whichthe pointer has been set.\end{methoddesc} \begin{methoddesc}[CD player]{seekblock}{block}Sets the pointer that indicates the starting point of the next read ofdigital audio data from a CD-ROM. The pointer is set to the specifiedlogical block number. The return value is the logical block number towhich the pointer has been set.\end{methoddesc} \begin{methoddesc}[CD player]{seektrack}{track}Sets the pointer that indicates the starting point of the next read ofdigital audio data from a CD-ROM. The pointer is set to the specifiedtrack. The return value is the logical block number to which thepointer has been set.\end{methoddesc} \begin{methoddesc}[CD player]{stop}{}Stops the current playing operation.\end{methoddesc} \begin{methoddesc}[CD player]{togglepause}{}Pauses the CD if it is playing, and makes it play if it is paused.\end{methoddesc} \subsection{Parser Objects}\label{cd-parser-objects} Parser objects (returned by \function{createparser()}) have thefollowing methods: \begin{methoddesc}[CD parser]{addcallback}{type, func, arg}Adds a callback for the parser. The parser has callbacks for eightdifferent types of data in the digital audio data stream. Constantsfor 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} isthe particular type of callback, and \var{data} is the data returnedfor this \var{type} of callback. The type of the data depends on the\var{type} of callback as follows: \begin{tableii}{l|p{4in}}{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 numberof the CD.} \lineii{ident}{String of 12 characters, giving the ISRCidentification number of the recording. The string consists of twocharacters country code, three characters owner code, two charactersgiving the year, and five characters giving a serial number.} \lineii{control}{Integer giving the control bits from the CDsubcode data}\end{tableii}\end{methoddesc} \begin{methoddesc}[CD parser]{deleteparser}{}Deletes the parser and frees the memory it was using. The objectshould not be used after this call. This call is done automaticallywhen the last reference to the object is removed.\end{methoddesc} \begin{methoddesc}[CD parser]{parseframe}{frame}Parses one or more frames of digital audio data from a CD such asreturned by \method{readda()}. It determines which subcodes arepresent in the data. If these subcodes have changed since the lastframe, then \method{parseframe()} executes a callback of theappropriate type passing to it the subcode data found in the frame.Unlike the \C{} function, more than one frame of digital audio datacan be passed to this method.\end{methoddesc} \begin{methoddesc}[CD parser]{removecallback}{type}Removes the callback for the given \var{type}.\end{methoddesc} \begin{methoddesc}[CD parser]{resetparser}{}Resets the fields of the parser used for tracking subcodes to aninitial state. \method{resetparser()} should be called after the dischas been changed.\end{methoddesc}
\section{\module{cd} ---
CD-ROM access on SGI systems}
\declaremodule{builtin}{cd}
\platform{IRIX}
\modulesynopsis{Interface to the CD-ROM on Silicon Graphics systems.}
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 omitted,
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 occurred 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}
\subsection{Player Objects}
\label{player-objects}
Player objects (returned by \function{open()}) have the following
methods:
\begin{methoddesc}[CD player]{allowremoval}{}
Unlocks the eject button on the CD-ROM drive permitting the user to
eject the caddy if desired.
\end{methoddesc}
\begin{methoddesc}[CD player]{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{methoddesc}
\begin{methoddesc}[CD player]{close}{}
Frees the resources associated with the player object. After calling
\method{close()}, the methods of the object should no longer be used.
\end{methoddesc}
\begin{methoddesc}[CD player]{eject}{}
Ejects the caddy from the CD-ROM drive.
\end{methoddesc}
\begin{methoddesc}[CD player]{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{methoddesc}
\begin{methoddesc}[CD player]{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{methoddesc}
\begin{methoddesc}[CD player]{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{methoddesc}
\begin{methoddesc}[CD player]{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{methoddesc}
\begin{methoddesc}[CD player]{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{methoddesc}
\begin{methoddesc}[CD player]{playtrack}{start, play}
Like \method{play()}, except that playing stops at the end of the
track.
\end{methoddesc}
\begin{methoddesc}[CD player]{playtrackabs}{track, minutes, seconds, frames, play}
Like \method{play()}, except that playing begins at the specified
absolute time and ends at the end of the specified track.
\end{methoddesc}
\begin{methoddesc}[CD player]{preventremoval}{}
Locks the eject button on the CD-ROM drive thus preventing the user
from arbitrarily ejecting the caddy.
\end{methoddesc}
\begin{methoddesc}[CD player]{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{methoddesc}
\begin{methoddesc}[CD player]{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{methoddesc}
\begin{methoddesc}[CD player]{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{methoddesc}
\begin{methoddesc}[CD player]{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{methoddesc}
\begin{methoddesc}[CD player]{stop}{}
Stops the current playing operation.
\end{methoddesc}
\begin{methoddesc}[CD player]{togglepause}{}
Pauses the CD if it is playing, and makes it play if it is paused.
\end{methoddesc}
\subsection{Parser Objects}
\label{cd-parser-objects}
Parser objects (returned by \function{createparser()}) have the
following methods:
\begin{methoddesc}[CD parser]{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|p{4in}}{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{methoddesc}
\begin{methoddesc}[CD parser]{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{methoddesc}
\begin{methoddesc}[CD parser]{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{methoddesc}
\begin{methoddesc}[CD parser]{removecallback}{type}
Removes the callback for the given \var{type}.
\end{methoddesc}
\begin{methoddesc}[CD parser]{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{methoddesc}