/Doc/library/wave.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 198 lines · 98 code · 100 blank · 0 comment · 0 complexity · 71280bf13976cf3121bb5f6398af6094 MD5 · raw file

  1. :mod:`wave` --- Read and write WAV files
  2. ========================================
  3. .. module:: wave
  4. :synopsis: Provide an interface to the WAV sound format.
  5. .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
  6. .. Documentations stolen from comments in file.
  7. The :mod:`wave` module provides a convenient interface to the WAV sound format.
  8. It does not support compression/decompression, but it does support mono/stereo.
  9. The :mod:`wave` module defines the following function and exception:
  10. .. function:: open(file[, mode])
  11. If *file* is a string, open the file by that name, other treat it as a seekable
  12. file-like object. *mode* can be any of
  13. ``'r'``, ``'rb'``
  14. Read only mode.
  15. ``'w'``, ``'wb'``
  16. Write only mode.
  17. Note that it does not allow read/write WAV files.
  18. A *mode* of ``'r'`` or ``'rb'`` returns a :class:`Wave_read` object, while a
  19. *mode* of ``'w'`` or ``'wb'`` returns a :class:`Wave_write` object. If *mode*
  20. is omitted and a file-like object is passed as *file*, ``file.mode`` is used as
  21. the default value for *mode* (the ``'b'`` flag is still added if necessary).
  22. .. function:: openfp(file, mode)
  23. A synonym for :func:`open`, maintained for backwards compatibility.
  24. .. exception:: Error
  25. An error raised when something is impossible because it violates the WAV
  26. specification or hits an implementation deficiency.
  27. .. _wave-read-objects:
  28. Wave_read Objects
  29. -----------------
  30. Wave_read objects, as returned by :func:`open`, have the following methods:
  31. .. method:: Wave_read.close()
  32. Close the stream, and make the instance unusable. This is called automatically
  33. on object collection.
  34. .. method:: Wave_read.getnchannels()
  35. Returns number of audio channels (``1`` for mono, ``2`` for stereo).
  36. .. method:: Wave_read.getsampwidth()
  37. Returns sample width in bytes.
  38. .. method:: Wave_read.getframerate()
  39. Returns sampling frequency.
  40. .. method:: Wave_read.getnframes()
  41. Returns number of audio frames.
  42. .. method:: Wave_read.getcomptype()
  43. Returns compression type (``'NONE'`` is the only supported type).
  44. .. method:: Wave_read.getcompname()
  45. Human-readable version of :meth:`getcomptype`. Usually ``'not compressed'``
  46. parallels ``'NONE'``.
  47. .. method:: Wave_read.getparams()
  48. Returns a tuple ``(nchannels, sampwidth, framerate, nframes, comptype,
  49. compname)``, equivalent to output of the :meth:`get\*` methods.
  50. .. method:: Wave_read.readframes(n)
  51. Reads and returns at most *n* frames of audio, as a string of bytes.
  52. .. method:: Wave_read.rewind()
  53. Rewind the file pointer to the beginning of the audio stream.
  54. The following two methods are defined for compatibility with the :mod:`aifc`
  55. module, and don't do anything interesting.
  56. .. method:: Wave_read.getmarkers()
  57. Returns ``None``.
  58. .. method:: Wave_read.getmark(id)
  59. Raise an error.
  60. The following two methods define a term "position" which is compatible between
  61. them, and is otherwise implementation dependent.
  62. .. method:: Wave_read.setpos(pos)
  63. Set the file pointer to the specified position.
  64. .. method:: Wave_read.tell()
  65. Return current file pointer position.
  66. .. _wave-write-objects:
  67. Wave_write Objects
  68. ------------------
  69. Wave_write objects, as returned by :func:`open`, have the following methods:
  70. .. method:: Wave_write.close()
  71. Make sure *nframes* is correct, and close the file. This method is called upon
  72. deletion.
  73. .. method:: Wave_write.setnchannels(n)
  74. Set the number of channels.
  75. .. method:: Wave_write.setsampwidth(n)
  76. Set the sample width to *n* bytes.
  77. .. method:: Wave_write.setframerate(n)
  78. Set the frame rate to *n*.
  79. .. method:: Wave_write.setnframes(n)
  80. Set the number of frames to *n*. This will be changed later if more frames are
  81. written.
  82. .. method:: Wave_write.setcomptype(type, name)
  83. Set the compression type and description. At the moment, only compression type
  84. ``NONE`` is supported, meaning no compression.
  85. .. method:: Wave_write.setparams(tuple)
  86. The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
  87. compname)``, with values valid for the :meth:`set\*` methods. Sets all
  88. parameters.
  89. .. method:: Wave_write.tell()
  90. Return current position in the file, with the same disclaimer for the
  91. :meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods.
  92. .. method:: Wave_write.writeframesraw(data)
  93. Write audio frames, without correcting *nframes*.
  94. .. method:: Wave_write.writeframes(data)
  95. Write audio frames and make sure *nframes* is correct.
  96. Note that it is invalid to set any parameters after calling :meth:`writeframes`
  97. or :meth:`writeframesraw`, and any attempt to do so will raise
  98. :exc:`wave.Error`.