Mercurial > cpython-lru_cache-weakref

annotate Doc/libcd.tex @ 2602:bee2aed416d6 legacy-trunk

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