/Doc/library/sunaudio.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 166 lines · 102 code · 64 blank · 0 comment · 0 complexity · 76faa15c17d000e8f15f204ed7c5b6dc MD5 · raw file

  1. :mod:`sunaudiodev` --- Access to Sun audio hardware
  2. ===================================================
  3. .. module:: sunaudiodev
  4. :platform: SunOS
  5. :synopsis: Access to Sun audio hardware.
  6. :deprecated:
  7. .. deprecated:: 2.6
  8. The :mod:`sunaudiodev` module has been deprecated for removal in Python 3.0.
  9. .. index:: single: u-LAW
  10. This module allows you to access the Sun audio interface. The Sun audio hardware
  11. is capable of recording and playing back audio data in u-LAW format with a
  12. sample rate of 8K per second. A full description can be found in the
  13. :manpage:`audio(7I)` manual page.
  14. .. index:: module: SUNAUDIODEV
  15. The module :mod:`SUNAUDIODEV` defines constants which may be used with this
  16. module.
  17. This module defines the following variables and functions:
  18. .. exception:: error
  19. This exception is raised on all errors. The argument is a string describing what
  20. went wrong.
  21. .. function:: open(mode)
  22. This function opens the audio device and returns a Sun audio device object. This
  23. object can then be used to do I/O on. The *mode* parameter is one of ``'r'`` for
  24. record-only access, ``'w'`` for play-only access, ``'rw'`` for both and
  25. ``'control'`` for access to the control device. Since only one process is
  26. allowed to have the recorder or player open at the same time it is a good idea
  27. to open the device only for the activity needed. See :manpage:`audio(7I)` for
  28. details.
  29. As per the manpage, this module first looks in the environment variable
  30. ``AUDIODEV`` for the base audio device filename. If not found, it falls back to
  31. :file:`/dev/audio`. The control device is calculated by appending "ctl" to the
  32. base audio device.
  33. .. _audio-device-objects:
  34. Audio Device Objects
  35. --------------------
  36. The audio device objects are returned by :func:`open` define the following
  37. methods (except ``control`` objects which only provide :meth:`getinfo`,
  38. :meth:`setinfo`, :meth:`fileno`, and :meth:`drain`):
  39. .. method:: audio device.close()
  40. This method explicitly closes the device. It is useful in situations where
  41. deleting the object does not immediately close it since there are other
  42. references to it. A closed device should not be used again.
  43. .. method:: audio device.fileno()
  44. Returns the file descriptor associated with the device. This can be used to set
  45. up ``SIGPOLL`` notification, as described below.
  46. .. method:: audio device.drain()
  47. This method waits until all pending output is processed and then returns.
  48. Calling this method is often not necessary: destroying the object will
  49. automatically close the audio device and this will do an implicit drain.
  50. .. method:: audio device.flush()
  51. This method discards all pending output. It can be used avoid the slow response
  52. to a user's stop request (due to buffering of up to one second of sound).
  53. .. method:: audio device.getinfo()
  54. This method retrieves status information like input and output volume, etc. and
  55. returns it in the form of an audio status object. This object has no methods but
  56. it contains a number of attributes describing the current device status. The
  57. names and meanings of the attributes are described in ``<sun/audioio.h>`` and in
  58. the :manpage:`audio(7I)` manual page. Member names are slightly different from
  59. their C counterparts: a status object is only a single structure. Members of the
  60. :cdata:`play` substructure have ``o_`` prepended to their name and members of
  61. the :cdata:`record` structure have ``i_``. So, the C member
  62. :cdata:`play.sample_rate` is accessed as :attr:`o_sample_rate`,
  63. :cdata:`record.gain` as :attr:`i_gain` and :cdata:`monitor_gain` plainly as
  64. :attr:`monitor_gain`.
  65. .. method:: audio device.ibufcount()
  66. This method returns the number of samples that are buffered on the recording
  67. side, i.e. the program will not block on a :func:`read` call of so many samples.
  68. .. method:: audio device.obufcount()
  69. This method returns the number of samples buffered on the playback side.
  70. Unfortunately, this number cannot be used to determine a number of samples that
  71. can be written without blocking since the kernel output queue length seems to be
  72. variable.
  73. .. method:: audio device.read(size)
  74. This method reads *size* samples from the audio input and returns them as a
  75. Python string. The function blocks until enough data is available.
  76. .. method:: audio device.setinfo(status)
  77. This method sets the audio device status parameters. The *status* parameter is
  78. an device status object as returned by :func:`getinfo` and possibly modified by
  79. the program.
  80. .. method:: audio device.write(samples)
  81. Write is passed a Python string containing audio samples to be played. If there
  82. is enough buffer space free it will immediately return, otherwise it will block.
  83. The audio device supports asynchronous notification of various events, through
  84. the SIGPOLL signal. Here's an example of how you might enable this in Python::
  85. def handle_sigpoll(signum, frame):
  86. print 'I got a SIGPOLL update'
  87. import fcntl, signal, STROPTS
  88. signal.signal(signal.SIGPOLL, handle_sigpoll)
  89. fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG)
  90. :mod:`SUNAUDIODEV` --- Constants used with :mod:`sunaudiodev`
  91. =============================================================
  92. .. module:: SUNAUDIODEV
  93. :platform: SunOS
  94. :synopsis: Constants for use with sunaudiodev.
  95. :deprecated:
  96. .. deprecated:: 2.6
  97. The :mod:`SUNAUDIODEV` module has been deprecated for removal in Python 3.0.
  98. .. index:: module: sunaudiodev
  99. This is a companion module to :mod:`sunaudiodev` which defines useful symbolic
  100. constants like :const:`MIN_GAIN`, :const:`MAX_GAIN`, :const:`SPEAKER`, etc. The
  101. names of the constants are the same names as used in the C include file
  102. ``<sun/audioio.h>``, with the leading string ``AUDIO_`` stripped.