/Doc/library/aifc.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 226 lines · 129 code · 97 blank · 0 comment · 0 complexity · 6a37b40d45c8cc41ba17c9cb12b0ec99 MD5 · raw file

  1. :mod:`aifc` --- Read and write AIFF and AIFC files
  2. ==================================================
  3. .. module:: aifc
  4. :synopsis: Read and write audio files in AIFF or AIFC format.
  5. .. index::
  6. single: Audio Interchange File Format
  7. single: AIFF
  8. single: AIFF-C
  9. This module provides support for reading and writing AIFF and AIFF-C files.
  10. AIFF is Audio Interchange File Format, a format for storing digital audio
  11. samples in a file. AIFF-C is a newer version of the format that includes the
  12. ability to compress the audio data.
  13. .. note::
  14. Some operations may only work under IRIX; these will raise :exc:`ImportError`
  15. when attempting to import the :mod:`cl` module, which is only available on
  16. IRIX.
  17. Audio files have a number of parameters that describe the audio data. The
  18. sampling rate or frame rate is the number of times per second the sound is
  19. sampled. The number of channels indicate if the audio is mono, stereo, or
  20. quadro. Each frame consists of one sample per channel. The sample size is the
  21. size in bytes of each sample. Thus a frame consists of
  22. *nchannels*\**samplesize* bytes, and a second's worth of audio consists of
  23. *nchannels*\**samplesize*\**framerate* bytes.
  24. For example, CD quality audio has a sample size of two bytes (16 bits), uses two
  25. channels (stereo) and has a frame rate of 44,100 frames/second. This gives a
  26. frame size of 4 bytes (2\*2), and a second's worth occupies 2\*2\*44100 bytes
  27. (176,400 bytes).
  28. Module :mod:`aifc` defines the following function:
  29. .. function:: open(file[, mode])
  30. Open an AIFF or AIFF-C file and return an object instance with methods that are
  31. described below. The argument *file* is either a string naming a file or a file
  32. object. *mode* must be ``'r'`` or ``'rb'`` when the file must be opened for
  33. reading, or ``'w'`` or ``'wb'`` when the file must be opened for writing. If
  34. omitted, ``file.mode`` is used if it exists, otherwise ``'rb'`` is used. When
  35. used for writing, the file object should be seekable, unless you know ahead of
  36. time how many samples you are going to write in total and use
  37. :meth:`writeframesraw` and :meth:`setnframes`.
  38. Objects returned by :func:`open` when a file is opened for reading have the
  39. following methods:
  40. .. method:: aifc.getnchannels()
  41. Return the number of audio channels (1 for mono, 2 for stereo).
  42. .. method:: aifc.getsampwidth()
  43. Return the size in bytes of individual samples.
  44. .. method:: aifc.getframerate()
  45. Return the sampling rate (number of audio frames per second).
  46. .. method:: aifc.getnframes()
  47. Return the number of audio frames in the file.
  48. .. method:: aifc.getcomptype()
  49. Return a four-character string describing the type of compression used in the
  50. audio file. For AIFF files, the returned value is ``'NONE'``.
  51. .. method:: aifc.getcompname()
  52. Return a human-readable description of the type of compression used in the audio
  53. file. For AIFF files, the returned value is ``'not compressed'``.
  54. .. method:: aifc.getparams()
  55. Return a tuple consisting of all of the above values in the above order.
  56. .. method:: aifc.getmarkers()
  57. Return a list of markers in the audio file. A marker consists of a tuple of
  58. three elements. The first is the mark ID (an integer), the second is the mark
  59. position in frames from the beginning of the data (an integer), the third is the
  60. name of the mark (a string).
  61. .. method:: aifc.getmark(id)
  62. Return the tuple as described in :meth:`getmarkers` for the mark with the given
  63. *id*.
  64. .. method:: aifc.readframes(nframes)
  65. Read and return the next *nframes* frames from the audio file. The returned
  66. data is a string containing for each frame the uncompressed samples of all
  67. channels.
  68. .. method:: aifc.rewind()
  69. Rewind the read pointer. The next :meth:`readframes` will start from the
  70. beginning.
  71. .. method:: aifc.setpos(pos)
  72. Seek to the specified frame number.
  73. .. method:: aifc.tell()
  74. Return the current frame number.
  75. .. method:: aifc.close()
  76. Close the AIFF file. After calling this method, the object can no longer be
  77. used.
  78. Objects returned by :func:`open` when a file is opened for writing have all the
  79. above methods, except for :meth:`readframes` and :meth:`setpos`. In addition
  80. the following methods exist. The :meth:`get\*` methods can only be called after
  81. the corresponding :meth:`set\*` methods have been called. Before the first
  82. :meth:`writeframes` or :meth:`writeframesraw`, all parameters except for the
  83. number of frames must be filled in.
  84. .. method:: aifc.aiff()
  85. Create an AIFF file. The default is that an AIFF-C file is created, unless the
  86. name of the file ends in ``'.aiff'`` in which case the default is an AIFF file.
  87. .. method:: aifc.aifc()
  88. Create an AIFF-C file. The default is that an AIFF-C file is created, unless
  89. the name of the file ends in ``'.aiff'`` in which case the default is an AIFF
  90. file.
  91. .. method:: aifc.setnchannels(nchannels)
  92. Specify the number of channels in the audio file.
  93. .. method:: aifc.setsampwidth(width)
  94. Specify the size in bytes of audio samples.
  95. .. method:: aifc.setframerate(rate)
  96. Specify the sampling frequency in frames per second.
  97. .. method:: aifc.setnframes(nframes)
  98. Specify the number of frames that are to be written to the audio file. If this
  99. parameter is not set, or not set correctly, the file needs to support seeking.
  100. .. method:: aifc.setcomptype(type, name)
  101. .. index::
  102. single: u-LAW
  103. single: A-LAW
  104. single: G.722
  105. Specify the compression type. If not specified, the audio data will not be
  106. compressed. In AIFF files, compression is not possible. The name parameter
  107. should be a human-readable description of the compression type, the type
  108. parameter should be a four-character string. Currently the following
  109. compression types are supported: NONE, ULAW, ALAW, G722.
  110. .. method:: aifc.setparams(nchannels, sampwidth, framerate, comptype, compname)
  111. Set all the above parameters at once. The argument is a tuple consisting of the
  112. various parameters. This means that it is possible to use the result of a
  113. :meth:`getparams` call as argument to :meth:`setparams`.
  114. .. method:: aifc.setmark(id, pos, name)
  115. Add a mark with the given id (larger than 0), and the given name at the given
  116. position. This method can be called at any time before :meth:`close`.
  117. .. method:: aifc.tell()
  118. Return the current write position in the output file. Useful in combination
  119. with :meth:`setmark`.
  120. .. method:: aifc.writeframes(data)
  121. Write data to the output file. This method can only be called after the audio
  122. file parameters have been set.
  123. .. method:: aifc.writeframesraw(data)
  124. Like :meth:`writeframes`, except that the header of the audio file is not
  125. updated.
  126. .. method:: aifc.close()
  127. Close the AIFF file. The header of the file is updated to reflect the actual
  128. size of the audio data. After calling this method, the object can no longer be
  129. used.