[Python-checkins] python/dist/src/Doc/lib libossaudiodev.tex,1.3,1.4
gward@users.sourceforge.net
gward@users.sourceforge.net
2003年3月09日 18:09:53 -0800
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv16191
Modified Files:
libossaudiodev.tex
Log Message:
Rewrite intro paragraphs and add a "See also" box for the link to the
official OSS docs.
Markup fixes: change \code{} variously to \function{}, \method{}, or
\constant{} as appropriate.
Index: libossaudiodev.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libossaudiodev.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** libossaudiodev.tex 10 Mar 2003 00:24:42 -0000 1.3
--- libossaudiodev.tex 10 Mar 2003 02:09:51 -0000 1.4
***************
*** 1,25 ****
\section{\module{ossaudiodev} ---
! Access to Open Sound System-compatible audio hardware}
\declaremodule{builtin}{ossaudiodev}
! \platform{OSS}
! \modulesynopsis{Access to OSS-compatible audio hardware.}
!
! % I know FreeBSD uses OSS -- what about Net- and Open-?
! This module allows you to access the Open Sound System audio interface.
! The Open Sound System interface is present on Linux and FreeBSD.
!
! This module provides a very "bare bones" wrapper over the IOCTLs used to
! access the audio hardware. The best---albeit rather daunting---way to
! get a feel for the interface is from the Open Sound System official
! documentation:
! \url{http://www.opensound.com/pguide/oss.pdf}
! The module defines a number of constants which may be used to program
! the device. These constants are the same as those defined in the C
! include file \code{<sys/soundcard.h>}.
! \code{ossaudiodev} defines the following variables and functions:
\begin{excdesc}{error}
--- 1,26 ----
\section{\module{ossaudiodev} ---
! Access to OSS-compatible audio devices}
\declaremodule{builtin}{ossaudiodev}
! \platform{Linux, FreeBSD}
! \modulesynopsis{Access to OSS-compatible audio devices.}
! % XXX OSS is standard for Linux and FreeBSD -- what about NetBSD?
! % OpenBSD? others?
! This module allows you to access the OSS (Open Sound System) audio
! interface. OSS is available for a wide range of open-source and
! commercial Unices, and is the standard audio interface for Linux (up to
! kernel 2.4) and FreeBSD.
! \begin{seealso}
! \seetitle[http://www.opensound.com/pguide/oss.pdf]
! {Open Sound System Programmer's Guide}
! {the official documentation for the OSS C API}
! \seetext{The module defines a large number of constants supplied by
! the OSS device driver; see \file{<sys/soundcard.h>} on either
! Linux or FreeBSD for a listing .}
! \end{seealso}
! \module{ossaudiodev} defines the following variables and functions:
\begin{excdesc}{error}
***************
*** 32,36 ****
object. This object can then be used to do I/O on. The \var{device}
parameter is the audio device filename to use. If it is not specified,
! this module first looks in the environment variable \code{AUDIODEV} for
a device to use. If not found, it falls back to \file{/dev/dsp}.
--- 33,37 ----
object. This object can then be used to do I/O on. The \var{device}
parameter is the audio device filename to use. If it is not specified,
! this module first looks in the environment variable \envvar{AUDIODEV} for
a device to use. If not found, it falls back to \file{/dev/dsp}.
***************
*** 47,51 ****
\var{device} parameter is the mixer device filename to use. If it is
not specified, this module first looks in the environment variable
! \code{MIXERDEV} for a device to use. If not found, it falls back to
\file{/dev/mixer}. You may specify \code{'r'}, \code{'rw'} or
\code{'w'} for \var{mode}; the default is \code{'r'}.
--- 48,52 ----
\var{device} parameter is the mixer device filename to use. If it is
not specified, this module first looks in the environment variable
! \envvar{MIXERDEV} for a device to use. If not found, it falls back to
\file{/dev/mixer}. You may specify \code{'r'}, \code{'rw'} or
\code{'w'} for \var{mode}; the default is \code{'r'}.
***************
*** 60,66 ****
sequence:
\begin{enumerate}
! \item \code{setfmt()} to set the output format,
! \item \code{channels()} to set the number of channels, and
! \item \code{speed()} to set the sample rate.
\end{enumerate}
--- 61,67 ----
sequence:
\begin{enumerate}
! \item \method{setfmt()} to set the output format,
! \item \method{channels()} to set the number of channels, and
! \item \method{speed()} to set the sample rate.
\end{enumerate}
***************
*** 87,99 ****
number of bytes written. If the audio device is opened in blocking
mode, the entire string is always written. If the device is opened in
! nonblocking mode, some data may not be written---see \code{writeall}.
\end{methoddesc}
\begin{methoddesc}[audio device]{writeall}{data}
Writes the entire Python string \var{data} to the audio device. If the
! device is opened in blocking mode, behaves identially to \code{write};
! in nonblocking mode, waits until the device becomes available before
! feeding it more data. Returns None, since the amount of data written is
! always equal to the amount of data supplied.
\end{methoddesc}
--- 88,101 ----
number of bytes written. If the audio device is opened in blocking
mode, the entire string is always written. If the device is opened in
! nonblocking mode, some data may not be written---see
! \method{writeall()}.
\end{methoddesc}
\begin{methoddesc}[audio device]{writeall}{data}
Writes the entire Python string \var{data} to the audio device. If the
! device is opened in blocking mode, behaves identially to
! \method{write()}; in nonblocking mode, waits until the device becomes
! available before feeding it more data. Returns \code{None}, since the
! amount of data written is always equal to the amount of data supplied.
\end{methoddesc}
***************
*** 114,118 ****
\lineii{AFMT_MU_LAW}
{a logarithmic encoding. This is the default format on
! /dev/audio and is the format used by Sun .au files.}
\lineii{AFMT_A_LAW}
{a logarithmic encoding}
--- 116,120 ----
\lineii{AFMT_MU_LAW}
{a logarithmic encoding. This is the default format on
! \file{/dev/audio} and is the format used by Sun .au files.}
\lineii{AFMT_A_LAW}
{a logarithmic encoding}
***************
*** 136,149 ****
\end{tableii}
Most systems support only a subset of these formats. Many devices only
! support \code{AFMT_U8}; the most common format used today is
! \code{AFMT_S16_LE}.
\end{methoddesc}
\begin{methoddesc}[audio device]{setfmt}{format}
Used to set the current audio format to \var{format}---see
! \code{getfmts} for a list. May also be used to return the current audio
! format---do this by passing an ``audio format'' of \code{AFMT_QUERY}.
! Returns the audio format that the device was set to, which may not be
! the requested format.
\end{methoddesc}
--- 138,151 ----
\end{tableii}
Most systems support only a subset of these formats. Many devices only
! support \constant{AFMT_U8}; the most common format used today is
! \constant{AFMT_S16_LE}.
\end{methoddesc}
\begin{methoddesc}[audio device]{setfmt}{format}
Used to set the current audio format to \var{format}---see
! \method{getfmts()} for a list. May also be used to return the current
! audio format---do this by passing an ``audio format'' of
! \constant{AFMT_QUERY}. Returns the audio format that the device was set
! to, which may not be the requested format.
\end{methoddesc}
***************
*** 171,175 ****
returns. This also occurs when the sound device is closed. The OSS
documentation recommends simply closing and re-opening the device rather
! than using \code{sync}.
\end{methoddesc}
--- 173,177 ----
returns. This also occurs when the sound device is closed. The OSS
documentation recommends simply closing and re-opening the device rather
! than using \method{sync()}.
\end{methoddesc}
***************
*** 177,188 ****
Immediately stops and playing or recording and returns the device to a
state where it can accept commands. The OSS documentation recommends
! closing and re-opening the device after calling \code{reset}.
\end{methoddesc}
\begin{methoddesc}[audio device]{post}
! To be used like a lightweight \code{sync}, the \code{post} IOCTL informs
! the audio device that there is a likely to be a pause in the audio
! output---i.e., after playing a spot sound effect, before waiting for
! user input, or before doing disk IO.
\end{methoddesc}
--- 179,190 ----
Immediately stops and playing or recording and returns the device to a
state where it can accept commands. The OSS documentation recommends
! closing and re-opening the device after calling \method{reset()}.
\end{methoddesc}
\begin{methoddesc}[audio device]{post}
! To be used like a lightweight \method{sync()}, the \method{post()}
! IOCTL informs the audio device that there is a likely to be a pause in
! the audio output---i.e., after playing a spot sound effect, before
! waiting for user input, or before doing disk I/O.
\end{methoddesc}
***************
*** 192,199 ****
Initialise the sound device in one method. \var{samplerate},
\var{channels} and \var{format} should be as specified in the
! \code{speed}, \code{channels} and \code{setfmt} methods. If
! \var{emulate} is true, attempt to find the closest matching format
! instead, otherwise raise ValueError if the device does not support the
! format. The default is to raise ValueError on unsupported formats.
\end{methoddesc}
--- 194,202 ----
Initialise the sound device in one method. \var{samplerate},
\var{channels} and \var{format} should be as specified in the
! \method{speed()}, \method{channels()} and \method{setfmt()}
! methods. If \var{emulate} is true, attempt to find the closest matching
! format instead, otherwise raise ValueError if the device does not
! support the format. The default is to raise ValueError on unsupported
! formats.
\end{methoddesc}
***************
*** 230,236 ****
This method returns a bitmask specifying the available mixer controls
(``Control'' being a specific mixable ``channel'', such as
! \code{SOUND_MIXER_PCM} or \code{SOUND_MIXER_SYNTH}). This
bitmask indicates a subset of all available mixer channels---the
! \code{SOUND_MIXER_*} constants defined at module level. To determine if,
for example, the current mixer object supports a PCM mixer, use the
following Python code:
--- 233,239 ----
This method returns a bitmask specifying the available mixer controls
(``Control'' being a specific mixable ``channel'', such as
! \constant{SOUND_MIXER_PCM} or \constant{SOUND_MIXER_SYNTH}). This
bitmask indicates a subset of all available mixer channels---the
! \constant{SOUND_MIXER_*} constants defined at module level. To determine if,
for example, the current mixer object supports a PCM mixer, use the
following Python code:
***************
*** 243,250 ****
\end{verbatim}
! For most purposes, the \code{SOUND_MIXER_VOLUME} (Master volume) and
! \code{SOUND_MIXER_PCM} channels should suffice---but code that uses the
mixer should be flexible when it comes to choosing sound channels. On
! the Gravis Ultrasound, for example, \code{SOUND_MIXER_VOLUME} does not
exist.
\end{methoddesc}
--- 246,253 ----
\end{verbatim}
! For most purposes, the \constant{SOUND_MIXER_VOLUME} (Master volume) and
! \constant{SOUND_MIXER_PCM} channels should suffice---but code that uses the
mixer should be flexible when it comes to choosing sound channels. On
! the Gravis Ultrasound, for example, \constant{SOUND_MIXER_VOLUME} does not
exist.
\end{methoddesc}
***************
*** 254,260 ****
the corresponding channel is stereo; if it is unset, the channel is
either monophonic or not supported by the mixer (use in combination with
! \function{channels} to determine which).
! See the code example for the \function{channels} function for an example
of getting data from a bitmask.
\end{methoddesc}
--- 257,263 ----
the corresponding channel is stereo; if it is unset, the channel is
either monophonic or not supported by the mixer (use in combination with
! \method{channels()} to determine which).
! See the code example for the \method{channels()} function for an example
of getting data from a bitmask.
\end{methoddesc}
***************
*** 262,266 ****
\begin{methoddesc}[mixer device]{reccontrols}{}
Returns a bitmask specifying the mixer controls that may be used to
! record. See the code example for \function{controls} for an example of
reading from a bitmask.
\end{methoddesc}
--- 265,269 ----
\begin{methoddesc}[mixer device]{reccontrols}{}
Returns a bitmask specifying the mixer controls that may be used to
! record. See the code example for \method{controls()} for an example of
reading from a bitmask.
\end{methoddesc}
***************
*** 268,272 ****
\begin{methoddesc}[mixer device]{get}{channel}
Returns the volume of a given mixer channel. The returned volume is a
! 2-tuple of \code{left volume, right volume}. Volumes are specified as
numbers from 0 (silent) to 100 (full volume). If the channel is
monophonic, a 2-tuple is still returned, but both channel volumes are
--- 271,275 ----
\begin{methoddesc}[mixer device]{get}{channel}
Returns the volume of a given mixer channel. The returned volume is a
! 2-tuple \code{(left_volume,right_volume)}. Volumes are specified as
numbers from 0 (silent) to 100 (full volume). If the channel is
monophonic, a 2-tuple is still returned, but both channel volumes are
***************
*** 277,281 ****
\begin{methoddesc}[mixer device]{set}{channel, (left, right)}
! Sets the volume for a given mixer channel to \code{(left, right)}.
\code{left} and \code{right} must be ints and between 0 (silent) and 100
(full volume). On success, the new volume is returned as a 2-tuple.
--- 280,284 ----
\begin{methoddesc}[mixer device]{set}{channel, (left, right)}
! Sets the volume for a given mixer channel to \code{(left,right)}.
\code{left} and \code{right} must be ints and between 0 (silent) and 100
(full volume). On success, the new volume is returned as a 2-tuple.