Move the 3k reST doc tree in place.

1 files changed, 261 insertions, 0 deletions

diff --git a/Doc/library/sunau.rst b/Doc/library/sunau.rst
new file mode 100644
index 0000000..9930133
--- /dev/null
+++ b/Doc/library/sunau.rst
@@ -0,0 +1,261 @@
+
+: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`.
+