mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge Doc changes in rev. 56685:
Remove several h/w and o/s specific modules that are undocumented, obsolete, and/or not widely used: linuxaudiodev.c, sunaudiodev.c Lib/plat-sunos5/SUNAUDIODEV.py Lib/audiodev.py Tools/audiopy/audiopy Move Lib/toaiff.py to Demo. See PEP 3108 for most of the details.
This commit is contained in:
Georg Brandl
parent
1dbcd54a17
commit
1a15ed97bb
@ -8,8 +8,7 @@
|
||||
|
||||
The :mod:`audioop` module contains some useful operations on sound fragments.
|
||||
It operates on sound fragments consisting of signed integer samples 8, 16 or 32
|
||||
bits wide, stored in Python strings. This is the same format as used by the
|
||||
:mod:`al` and :mod:`sunaudiodev` modules. All scalar items are integers, unless
|
||||
bits wide, stored in Python strings. All scalar items are integers, unless
|
||||
specified otherwise.
|
||||
|
||||
.. index::
|
||||
|
||||
@ -65,6 +65,5 @@ documented in the Reference Manual.
|
||||
modules.rst
|
||||
language.rst
|
||||
misc.rst
|
||||
sun.rst
|
||||
windows.rst
|
||||
undoc.rst
|
||||
|
||||
@ -1,14 +0,0 @@
|
||||
|
||||
.. _sunos:
|
||||
|
||||
***********************
|
||||
SunOS Specific Services
|
||||
***********************
|
||||
|
||||
The modules described in this chapter provide interfaces to features that are
|
||||
unique to SunOS 5 (also known as Solaris version 2).
|
||||
|
||||
|
||||
.. toctree::
|
||||
|
||||
sunaudio.rst
|
||||
@ -1,156 +0,0 @@
|
||||
|
||||
:mod:`sunaudiodev` --- Access to Sun audio hardware
|
||||
===================================================
|
||||
|
||||
.. module:: sunaudiodev
|
||||
:platform: SunOS
|
||||
:synopsis: Access to Sun audio hardware.
|
||||
|
||||
|
||||
.. index:: single: u-LAW
|
||||
|
||||
This module allows you to access the Sun audio interface. The Sun audio hardware
|
||||
is capable of recording and playing back audio data in u-LAW format with a
|
||||
sample rate of 8K per second. A full description can be found in the
|
||||
:manpage:`audio(7I)` manual page.
|
||||
|
||||
.. index:: module: SUNAUDIODEV
|
||||
|
||||
The module :mod:`SUNAUDIODEV` defines constants which may be used with this
|
||||
module.
|
||||
|
||||
This module defines the following variables and functions:
|
||||
|
||||
|
||||
.. exception:: error
|
||||
|
||||
This exception is raised on all errors. The argument is a string describing what
|
||||
went wrong.
|
||||
|
||||
|
||||
.. function:: open(mode)
|
||||
|
||||
This function opens the audio device and returns a Sun audio device object. This
|
||||
object can then be used to do I/O on. The *mode* parameter is one of ``'r'`` for
|
||||
record-only access, ``'w'`` for play-only access, ``'rw'`` for both and
|
||||
``'control'`` for access to the control device. Since only one process is
|
||||
allowed to have the recorder or player open at the same time it is a good idea
|
||||
to open the device only for the activity needed. See :manpage:`audio(7I)` for
|
||||
details.
|
||||
|
||||
As per the manpage, this module first looks in the environment variable
|
||||
``AUDIODEV`` for the base audio device filename. If not found, it falls back to
|
||||
:file:`/dev/audio`. The control device is calculated by appending "ctl" to the
|
||||
base audio device.
|
||||
|
||||
|
||||
.. _audio-device-objects:
|
||||
|
||||
Audio Device Objects
|
||||
--------------------
|
||||
|
||||
The audio device objects are returned by :func:`open` define the following
|
||||
methods (except ``control`` objects which only provide :meth:`getinfo`,
|
||||
:meth:`setinfo`, :meth:`fileno`, and :meth:`drain`):
|
||||
|
||||
|
||||
.. method:: audio device.close()
|
||||
|
||||
This method explicitly closes the device. It is useful in situations where
|
||||
deleting the object does not immediately close it since there are other
|
||||
references to it. A closed device should not be used again.
|
||||
|
||||
|
||||
.. method:: audio device.fileno()
|
||||
|
||||
Returns the file descriptor associated with the device. This can be used to set
|
||||
up ``SIGPOLL`` notification, as described below.
|
||||
|
||||
|
||||
.. method:: audio device.drain()
|
||||
|
||||
This method waits until all pending output is processed and then returns.
|
||||
Calling this method is often not necessary: destroying the object will
|
||||
automatically close the audio device and this will do an implicit drain.
|
||||
|
||||
|
||||
.. method:: audio device.flush()
|
||||
|
||||
This method discards all pending output. It can be used avoid the slow response
|
||||
to a user's stop request (due to buffering of up to one second of sound).
|
||||
|
||||
|
||||
.. method:: audio device.getinfo()
|
||||
|
||||
This method retrieves status information like input and output volume, etc. and
|
||||
returns it in the form of an audio status object. This object has no methods but
|
||||
it contains a number of attributes describing the current device status. The
|
||||
names and meanings of the attributes are described in ``<sun/audioio.h>`` and in
|
||||
the :manpage:`audio(7I)` manual page. Member names are slightly different from
|
||||
their C counterparts: a status object is only a single structure. Members of the
|
||||
:cdata:`play` substructure have ``o_`` prepended to their name and members of
|
||||
the :cdata:`record` structure have ``i_``. So, the C member
|
||||
:cdata:`play.sample_rate` is accessed as :attr:`o_sample_rate`,
|
||||
:cdata:`record.gain` as :attr:`i_gain` and :cdata:`monitor_gain` plainly as
|
||||
:attr:`monitor_gain`.
|
||||
|
||||
|
||||
.. method:: audio device.ibufcount()
|
||||
|
||||
This method returns the number of samples that are buffered on the recording
|
||||
side, i.e. the program will not block on a :func:`read` call of so many samples.
|
||||
|
||||
|
||||
.. method:: audio device.obufcount()
|
||||
|
||||
This method returns the number of samples buffered on the playback side.
|
||||
Unfortunately, this number cannot be used to determine a number of samples that
|
||||
can be written without blocking since the kernel output queue length seems to be
|
||||
variable.
|
||||
|
||||
|
||||
.. method:: audio device.read(size)
|
||||
|
||||
This method reads *size* samples from the audio input and returns them as a
|
||||
Python string. The function blocks until enough data is available.
|
||||
|
||||
|
||||
.. method:: audio device.setinfo(status)
|
||||
|
||||
This method sets the audio device status parameters. The *status* parameter is
|
||||
an device status object as returned by :func:`getinfo` and possibly modified by
|
||||
the program.
|
||||
|
||||
|
||||
.. method:: audio device.write(samples)
|
||||
|
||||
Write is passed a Python string containing audio samples to be played. If there
|
||||
is enough buffer space free it will immediately return, otherwise it will block.
|
||||
|
||||
The audio device supports asynchronous notification of various events, through
|
||||
the SIGPOLL signal. Here's an example of how you might enable this in Python::
|
||||
|
||||
def handle_sigpoll(signum, frame):
|
||||
print 'I got a SIGPOLL update'
|
||||
|
||||
import fcntl, signal, STROPTS
|
||||
|
||||
signal.signal(signal.SIGPOLL, handle_sigpoll)
|
||||
fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG)
|
||||
|
||||
|
||||
:mod:`SUNAUDIODEV` --- Constants used with :mod:`sunaudiodev`
|
||||
=============================================================
|
||||
|
||||
.. module:: SUNAUDIODEV
|
||||
:platform: SunOS
|
||||
:synopsis: Constants for use with sunaudiodev.
|
||||
|
||||
|
||||
.. index:: module: sunaudiodev
|
||||
|
||||
This is a companion module to :mod:`sunaudiodev` which defines useful symbolic
|
||||
constants like :const:`MIN_GAIN`, :const:`MAX_GAIN`, :const:`SPEAKER`, etc. The
|
||||
names of the constants are the same names as used in the C include file
|
||||
``<sun/audioio.h>``, with the leading string ``AUDIO_`` stripped.
|
||||
|
||||
@ -51,9 +51,6 @@ documented beyond this mention. There's little need to document these.
|
||||
Multimedia
|
||||
==========
|
||||
|
||||
:mod:`audiodev`
|
||||
--- Platform-independent API for playing audio data.
|
||||
|
||||
:mod:`linuxaudiodev`
|
||||
--- Play audio data on the Linux audio device. Replaced in Python 2.3 by the
|
||||
:mod:`ossaudiodev` module.
|
||||
@ -61,10 +58,6 @@ Multimedia
|
||||
:mod:`sunaudio`
|
||||
--- Interpret Sun audio headers (may become obsolete or a tool/demo).
|
||||
|
||||
:mod:`toaiff`
|
||||
--- Convert "arbitrary" sound files to AIFF files; should probably become a tool
|
||||
or demo. Requires the external program :program:`sox`.
|
||||
|
||||
|
||||
.. _obsolete-modules:
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user