diff options
Diffstat (limited to 'Doc/libcd.tex')
| -rw-r--r-- | Doc/libcd.tex | 300 |
1 files changed, 0 insertions, 300 deletions
diff --git a/Doc/libcd.tex b/Doc/libcd.tex deleted file mode 100644 index 44111a3..0000000 --- a/Doc/libcd.tex +++ /dev/null @@ -1,300 +0,0 @@ -\section{Built-in Module \module{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} - - -\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 spcified -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} |