/Doc/library/sunau.rst
http://unladen-swallow.googlecode.com/ · ReStructuredText · 261 lines · 144 code · 117 blank · 0 comment · 0 complexity · ae3a3f6decf16382d0e7564722f69445 MD5 · raw file
- :mod:`sunau` --- Read and write Sun AU files
- ============================================
- .. module:: sunau
- :synopsis: Provide an interface to the Sun AU sound format.
- .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
- The :mod:`sunau` module provides a convenient interface to the Sun AU sound
- format. Note that this module is interface-compatible with the modules
- :mod:`aifc` and :mod:`wave`.
- An audio file consists of a header followed by the data. The fields of the
- header are:
- +---------------+-----------------------------------------------+
- | Field | Contents |
- +===============+===============================================+
- | magic word | The four bytes ``.snd``. |
- +---------------+-----------------------------------------------+
- | header size | Size of the header, including info, in bytes. |
- +---------------+-----------------------------------------------+
- | data size | Physical size of the data, in bytes. |
- +---------------+-----------------------------------------------+
- | encoding | Indicates how the audio samples are encoded. |
- +---------------+-----------------------------------------------+
- | sample rate | The sampling rate. |
- +---------------+-----------------------------------------------+
- | # of channels | The number of channels in the samples. |
- +---------------+-----------------------------------------------+
- | info | ASCII string giving a description of the |
- | | audio file (padded with null bytes). |
- +---------------+-----------------------------------------------+
- Apart from the info field, all header fields are 4 bytes in size. They are all
- 32-bit unsigned integers encoded in big-endian byte order.
- The :mod:`sunau` module defines the following functions:
- .. function:: open(file, mode)
- If *file* is a string, open the file by that name, otherwise treat it as a
- seekable file-like object. *mode* can be any of
- ``'r'``
- Read only mode.
- ``'w'``
- Write only mode.
- Note that it does not allow read/write files.
- A *mode* of ``'r'`` returns a :class:`AU_read` object, while a *mode* of ``'w'``
- or ``'wb'`` returns a :class:`AU_write` object.
- .. function:: openfp(file, mode)
- A synonym for :func:`open`, maintained for backwards compatibility.
- The :mod:`sunau` module defines the following exception:
- .. exception:: Error
- An error raised when something is impossible because of Sun AU specs or
- implementation deficiency.
- The :mod:`sunau` module defines the following data items:
- .. data:: AUDIO_FILE_MAGIC
- An integer every valid Sun AU file begins with, stored in big-endian form. This
- is the string ``.snd`` interpreted as an integer.
- .. data:: AUDIO_FILE_ENCODING_MULAW_8
- AUDIO_FILE_ENCODING_LINEAR_8
- AUDIO_FILE_ENCODING_LINEAR_16
- AUDIO_FILE_ENCODING_LINEAR_24
- AUDIO_FILE_ENCODING_LINEAR_32
- AUDIO_FILE_ENCODING_ALAW_8
- Values of the encoding field from the AU header which are supported by this
- module.
- .. data:: AUDIO_FILE_ENCODING_FLOAT
- AUDIO_FILE_ENCODING_DOUBLE
- AUDIO_FILE_ENCODING_ADPCM_G721
- AUDIO_FILE_ENCODING_ADPCM_G722
- AUDIO_FILE_ENCODING_ADPCM_G723_3
- AUDIO_FILE_ENCODING_ADPCM_G723_5
- Additional known values of the encoding field from the AU header, but which are
- not supported by this module.
- .. _au-read-objects:
- AU_read Objects
- ---------------
- AU_read objects, as returned by :func:`open` above, have the following methods:
- .. method:: AU_read.close()
- Close the stream, and make the instance unusable. (This is called automatically
- on deletion.)
- .. method:: AU_read.getnchannels()
- Returns number of audio channels (1 for mone, 2 for stereo).
- .. method:: AU_read.getsampwidth()
- Returns sample width in bytes.
- .. method:: AU_read.getframerate()
- Returns sampling frequency.
- .. method:: AU_read.getnframes()
- Returns number of audio frames.
- .. method:: AU_read.getcomptype()
- Returns compression type. Supported compression types are ``'ULAW'``, ``'ALAW'``
- and ``'NONE'``.
- .. method:: AU_read.getcompname()
- Human-readable version of :meth:`getcomptype`. The supported types have the
- respective names ``'CCITT G.711 u-law'``, ``'CCITT G.711 A-law'`` and ``'not
- compressed'``.
- .. method:: AU_read.getparams()
- Returns a tuple ``(nchannels, sampwidth, framerate, nframes, comptype,
- compname)``, equivalent to output of the :meth:`get\*` methods.
- .. method:: AU_read.readframes(n)
- Reads and returns at most *n* frames of audio, as a string of bytes. The data
- will be returned in linear format. If the original data is in u-LAW format, it
- will be converted.
- .. method:: AU_read.rewind()
- Rewind the file pointer to the beginning of the audio stream.
- The following two methods define a term "position" which is compatible between
- them, and is otherwise implementation dependent.
- .. method:: AU_read.setpos(pos)
- Set the file pointer to the specified position. Only values returned from
- :meth:`tell` should be used for *pos*.
- .. method:: AU_read.tell()
- Return current file pointer position. Note that the returned value has nothing
- to do with the actual position in the file.
- The following two functions are defined for compatibility with the :mod:`aifc`,
- and don't do anything interesting.
- .. method:: AU_read.getmarkers()
- Returns ``None``.
- .. method:: AU_read.getmark(id)
- Raise an error.
- .. _au-write-objects:
- AU_write Objects
- ----------------
- AU_write objects, as returned by :func:`open` above, have the following methods:
- .. method:: AU_write.setnchannels(n)
- Set the number of channels.
- .. method:: AU_write.setsampwidth(n)
- Set the sample width (in bytes.)
- .. method:: AU_write.setframerate(n)
- Set the frame rate.
- .. method:: AU_write.setnframes(n)
- Set the number of frames. This can be later changed, when and if more frames
- are written.
- .. method:: AU_write.setcomptype(type, name)
- Set the compression type and description. Only ``'NONE'`` and ``'ULAW'`` are
- supported on output.
- .. method:: AU_write.setparams(tuple)
- The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
- compname)``, with values valid for the :meth:`set\*` methods. Set all
- parameters.
- .. method:: AU_write.tell()
- Return current position in the file, with the same disclaimer for the
- :meth:`AU_read.tell` and :meth:`AU_read.setpos` methods.
- .. method:: AU_write.writeframesraw(data)
- Write audio frames, without correcting *nframes*.
- .. method:: AU_write.writeframes(data)
- Write audio frames and make sure *nframes* is correct.
- .. method:: AU_write.close()
- Make sure *nframes* is correct, and close the file.
- This method is called upon deletion.
- Note that it is invalid to set any parameters after calling :meth:`writeframes`
- or :meth:`writeframesraw`.