summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorSjoerd Mullender <sjoerd@acm.org>1994-09-29 16:46:42 (GMT)
committerSjoerd Mullender <sjoerd@acm.org>1994-09-29 16:46:42 (GMT)
commitcd57dc3a9861fe9fe85bc76580a15542354c63e5 (patch)
treebe73cfbda6fdf1e289882dbd03e5010ebc3be928 /Doc
parent457c0ab366e439abc36089e7440b36ac0517cedd (diff)
downloadcpython-cd57dc3a9861fe9fe85bc76580a15542354c63e5.zip
cpython-cd57dc3a9861fe9fe85bc76580a15542354c63e5.tar.gz
cpython-cd57dc3a9861fe9fe85bc76580a15542354c63e5.tar.bz2
Added documentation on the aifc module.
Diffstat (limited to 'Doc')
-rw-r--r--Doc/lib.tex1
-rw-r--r--Doc/lib/lib.tex1
-rw-r--r--Doc/lib/libaifc.tex180
-rw-r--r--Doc/libaifc.tex180
4 files changed, 362 insertions, 0 deletions
diff --git a/Doc/lib.tex b/Doc/lib.tex
index a0cc009..88ceffa 100644
--- a/Doc/lib.tex
+++ b/Doc/lib.tex
@@ -70,6 +70,7 @@ language.
\input{libregsub}
\input{libstring}
\input{libwhrandom}
+\input{libaifc}
\input{libunix} % UNIX ONLY
\input{libdbm}
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index a0cc009..88ceffa 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -70,6 +70,7 @@ language.
\input{libregsub}
\input{libstring}
\input{libwhrandom}
+\input{libaifc}
\input{libunix} % UNIX ONLY
\input{libdbm}
diff --git a/Doc/lib/libaifc.tex b/Doc/lib/libaifc.tex
new file mode 100644
index 0000000..0a56ca6
--- /dev/null
+++ b/Doc/lib/libaifc.tex
@@ -0,0 +1,180 @@
+\section{Standard Module \sectcode{aifc}}
+\stmodindex{aifc}
+
+This module provides support for reading and writing AIFF and AIFF-C
+files. AIFF is Audio Interchange File Format, a format for storing
+digital audio samples in a file. AIFF-C is a newer version of the
+format that includes the ability to compress the audio data.
+
+Audio files have a number of parameters that describe the audio data.
+The sampling rate or frame rate is the number of times per second the
+sound is sampled. The number of channels indicate if the audio is
+mono, stereo, or quadro. Each frame consists of one sample per
+channel. The sample size is the size in bytes of each sample. Thus a
+frame consists of nchannels*framesize bytes, and a second's worth of
+audio consists of nchannels*framesize*framerate bytes.
+
+Module \code{aifc} defines the following function:
+
+\renewcommand{\indexsubitem}{(in module aifc)}
+\begin{funcdesc}{open}{file\, mode}
+Opens an AIFF or AIFF-C file and returns an object instance with
+methods that are described below. The argument file is either a
+string naming a file or a file object. The mode is either the string
+'r' when the file must be opened for reading, or 'w' when the file
+must be opened for writing.
+\end{funcdesc}
+
+Objects returned by \code{aifc.open()} when a file is opened for
+reading have the following methods:
+
+\renewcommand{\indexsubitem}{(aifc object method)}
+\begin{funcdesc}{getnchannels}{}
+Return the number of audio channels (1 for mono, 2 for stereo).
+\end{funcdesc}
+
+\begin{funcdesc}{getsampwidth}{}
+Return the size in bytes of individual samples.
+\end{funcdesc}
+
+\begin{funcdesc}{getframerate}{}
+Return the sampling rate (number of audio frames per second).
+\end{funcdesc}
+
+\begin{funcdesc}{getnframes}{}
+Return the number of audio frames in the file.
+\end{funcdesc}
+
+\begin{funcdesc}{getcomptype}{}
+Return a four-character string describing the type of compression used
+in the audio file. For AIFF files, the returned value is
+\code{'NONE'}.
+\end{funcdesc}
+
+\begin{funcdesc}{getcompname}{}
+Return a human-readable description of the type of compression used in
+the audio file. For AIFF files, the returned value is \code{'not
+compressed'}.
+\end{funcdesc}
+
+\begin{funcdesc}{getparams}{}
+Return a tuple consisting of all of the above values in the above
+order.
+\end{funcdesc}
+
+\begin{funcdesc}{getmarkers}{}
+Return a list of markers in the audio file. A marker consists of a
+tuple of three elements. The first is the mark ID (an integer), the
+second is the mark position in frames from the beginning of the data
+(an integer), the third is the name of the mark (a string).
+\end{funcdesc}
+
+\begin{funcdesc}{getmark}{id}
+Return the tuple as described in \code{getmarkers} for the mark with
+the given id.
+\end{funcdesc}
+
+\begin{funcdesc}{readframes}{nframes}
+Read and return the next nframes frames from the audio file. The
+returned data is a string containing for each frame the uncompressed
+samples of all channels.
+\end{funcdesc}
+
+\begin{funcdesc}{rewind}{}
+Rewind the read pointer. The next \code{readframes} will start from
+the beginning.
+\end{funcdesc}
+
+\begin{funcdesc}{setpos}{pos}
+Seek to the specified frame number.
+\end{funcdesc}
+
+\begin{funcdesc}{tell}{}
+Return the current frame number.
+\end{funcdesc}
+
+\begin{funcdesc}{close}{}
+Close the AIFF file. After calling this method, the object can no
+longer be used.
+\end{funcdesc}
+
+Objects returned by \code{aifc.open()} when a file is opened for
+writing have all the above methods, except for \code{readframes} and
+\code{setpos}. In addition the following methods exist. The
+\code{get} methods can only be called after the corresponding
+\code{set} methods have been called. Before the first
+\code{writeframes} or \code{writeframesraw}, all parameters except for
+the number of frames must be filled in.
+
+\begin{funcdesc}{aiff}{}
+Create an AIFF file. The default is that an AIFF-C file is created,
+unless the name of the file ends in '.aiff' in which case the default
+is an AIFF file.
+\end{funcdesc}
+
+\begin{funcdesc}{aifc}{}
+Create an AIFF-C file. The default is that an AIFF-C file is created,
+unless the name of the file ends in '.aiff' in which case the default
+is an AIFF file.
+\end{funcdesc}
+
+\begin{funcdesc}{setnchannels}{nchannels}
+Specify the number of channels in the audio file.
+\end{funcdesc}
+
+\begin{funcdesc}{setsampwidth}{width}
+Specify the size in bytes of audio samples.
+\end{funcdesc}
+
+\begin{funcdesc}{setframerate}{rate}
+Specify the sampling frequency in frames per second.
+\end{funcdesc}
+
+\begin{funcdesc}{setnframes}{nframes}
+Specify the number of frames that are to be written to the audio file.
+If this parameter is not set, or not set correctly, the file needs to
+support seeking.
+\end{funcdesc}
+
+\begin{funcdesc}{setcomptype}{type\, name}
+Specify the compression type. If not specified, the audio data will
+not be compressed. In AIFF files, compression is not possible. The
+name parameter should be a human-readable description of the
+compression type, the type parameter should be a four-character
+string. Currently the following compression types are supported:
+NONE, ULAW, ALAW, G722.
+\end{funcdesc}
+
+\begin{funcdesc}{setparams}{(nchannels\, sampwidth\, framerate\, comptype\, compname)}
+Set all the above parameters at once. The argument is a tuple
+consisting of the various parameters. This means that it is possible
+to use the result of a \code{getparams} call as argument to
+\code{setparams}.
+\end{funcdesc}
+
+\begin{funcdesc}{setmark}{id\, pos\, name}
+Add a mark with the given id (larger than 0), and the given name at
+the given position. This method can be called at any time before
+\code{close}.
+\end{funcdesc}
+
+\begin{funcdesc}{tell}{}
+Return the current write position in the output file. Useful in
+combination with \code{setmark}.
+\end{funcdesc}
+
+\begin{funcdesc}{writeframes}{data}
+Write data to the output file. This method can only be called after
+the audio file parameters have been set.
+\end{funcdesc}
+
+\begin{funcdesc}{writeframesraw}{data}
+Like \code{writeframes}, except that the header of the audio file is
+not updated.
+\end{funcdesc}
+
+\begin{funcdesc}{close}{}
+Close the AIFF file. The header of the file is updated to reflect the
+actual size of the audio data After calling this method, the object
+can no longer be used.
+\end{funcdesc}
diff --git a/Doc/libaifc.tex b/Doc/libaifc.tex
new file mode 100644
index 0000000..0a56ca6
--- /dev/null
+++ b/Doc/libaifc.tex
@@ -0,0 +1,180 @@
+\section{Standard Module \sectcode{aifc}}
+\stmodindex{aifc}
+
+This module provides support for reading and writing AIFF and AIFF-C
+files. AIFF is Audio Interchange File Format, a format for storing
+digital audio samples in a file. AIFF-C is a newer version of the
+format that includes the ability to compress the audio data.
+
+Audio files have a number of parameters that describe the audio data.
+The sampling rate or frame rate is the number of times per second the
+sound is sampled. The number of channels indicate if the audio is
+mono, stereo, or quadro. Each frame consists of one sample per
+channel. The sample size is the size in bytes of each sample. Thus a
+frame consists of nchannels*framesize bytes, and a second's worth of
+audio consists of nchannels*framesize*framerate bytes.
+
+Module \code{aifc} defines the following function:
+
+\renewcommand{\indexsubitem}{(in module aifc)}
+\begin{funcdesc}{open}{file\, mode}
+Opens an AIFF or AIFF-C file and returns an object instance with
+methods that are described below. The argument file is either a
+string naming a file or a file object. The mode is either the string
+'r' when the file must be opened for reading, or 'w' when the file
+must be opened for writing.
+\end{funcdesc}
+
+Objects returned by \code{aifc.open()} when a file is opened for
+reading have the following methods:
+
+\renewcommand{\indexsubitem}{(aifc object method)}
+\begin{funcdesc}{getnchannels}{}
+Return the number of audio channels (1 for mono, 2 for stereo).
+\end{funcdesc}
+
+\begin{funcdesc}{getsampwidth}{}
+Return the size in bytes of individual samples.
+\end{funcdesc}
+
+\begin{funcdesc}{getframerate}{}
+Return the sampling rate (number of audio frames per second).
+\end{funcdesc}
+
+\begin{funcdesc}{getnframes}{}
+Return the number of audio frames in the file.
+\end{funcdesc}
+
+\begin{funcdesc}{getcomptype}{}
+Return a four-character string describing the type of compression used
+in the audio file. For AIFF files, the returned value is
+\code{'NONE'}.
+\end{funcdesc}
+
+\begin{funcdesc}{getcompname}{}
+Return a human-readable description of the type of compression used in
+the audio file. For AIFF files, the returned value is \code{'not
+compressed'}.
+\end{funcdesc}
+
+\begin{funcdesc}{getparams}{}
+Return a tuple consisting of all of the above values in the above
+order.
+\end{funcdesc}
+
+\begin{funcdesc}{getmarkers}{}
+Return a list of markers in the audio file. A marker consists of a
+tuple of three elements. The first is the mark ID (an integer), the
+second is the mark position in frames from the beginning of the data
+(an integer), the third is the name of the mark (a string).
+\end{funcdesc}
+
+\begin{funcdesc}{getmark}{id}
+Return the tuple as described in \code{getmarkers} for the mark with
+the given id.
+\end{funcdesc}
+
+\begin{funcdesc}{readframes}{nframes}
+Read and return the next nframes frames from the audio file. The
+returned data is a string containing for each frame the uncompressed
+samples of all channels.
+\end{funcdesc}
+
+\begin{funcdesc}{rewind}{}
+Rewind the read pointer. The next \code{readframes} will start from
+the beginning.
+\end{funcdesc}
+
+\begin{funcdesc}{setpos}{pos}
+Seek to the specified frame number.
+\end{funcdesc}
+
+\begin{funcdesc}{tell}{}
+Return the current frame number.
+\end{funcdesc}
+
+\begin{funcdesc}{close}{}
+Close the AIFF file. After calling this method, the object can no
+longer be used.
+\end{funcdesc}
+
+Objects returned by \code{aifc.open()} when a file is opened for
+writing have all the above methods, except for \code{readframes} and
+\code{setpos}. In addition the following methods exist. The
+\code{get} methods can only be called after the corresponding
+\code{set} methods have been called. Before the first
+\code{writeframes} or \code{writeframesraw}, all parameters except for
+the number of frames must be filled in.
+
+\begin{funcdesc}{aiff}{}
+Create an AIFF file. The default is that an AIFF-C file is created,
+unless the name of the file ends in '.aiff' in which case the default
+is an AIFF file.
+\end{funcdesc}
+
+\begin{funcdesc}{aifc}{}
+Create an AIFF-C file. The default is that an AIFF-C file is created,
+unless the name of the file ends in '.aiff' in which case the default
+is an AIFF file.
+\end{funcdesc}
+
+\begin{funcdesc}{setnchannels}{nchannels}
+Specify the number of channels in the audio file.
+\end{funcdesc}
+
+\begin{funcdesc}{setsampwidth}{width}
+Specify the size in bytes of audio samples.
+\end{funcdesc}
+
+\begin{funcdesc}{setframerate}{rate}
+Specify the sampling frequency in frames per second.
+\end{funcdesc}
+
+\begin{funcdesc}{setnframes}{nframes}
+Specify the number of frames that are to be written to the audio file.
+If this parameter is not set, or not set correctly, the file needs to
+support seeking.
+\end{funcdesc}
+
+\begin{funcdesc}{setcomptype}{type\, name}
+Specify the compression type. If not specified, the audio data will
+not be compressed. In AIFF files, compression is not possible. The
+name parameter should be a human-readable description of the
+compression type, the type parameter should be a four-character
+string. Currently the following compression types are supported:
+NONE, ULAW, ALAW, G722.
+\end{funcdesc}
+
+\begin{funcdesc}{setparams}{(nchannels\, sampwidth\, framerate\, comptype\, compname)}
+Set all the above parameters at once. The argument is a tuple
+consisting of the various parameters. This means that it is possible
+to use the result of a \code{getparams} call as argument to
+\code{setparams}.
+\end{funcdesc}
+
+\begin{funcdesc}{setmark}{id\, pos\, name}
+Add a mark with the given id (larger than 0), and the given name at
+the given position. This method can be called at any time before
+\code{close}.
+\end{funcdesc}
+
+\begin{funcdesc}{tell}{}
+Return the current write position in the output file. Useful in
+combination with \code{setmark}.
+\end{funcdesc}
+
+\begin{funcdesc}{writeframes}{data}
+Write data to the output file. This method can only be called after
+the audio file parameters have been set.
+\end{funcdesc}
+
+\begin{funcdesc}{writeframesraw}{data}
+Like \code{writeframes}, except that the header of the audio file is
+not updated.
+\end{funcdesc}
+
+\begin{funcdesc}{close}{}
+Close the AIFF file. The header of the file is updated to reflect the
+actual size of the audio data After calling this method, the object
+can no longer be used.
+\end{funcdesc}