"sunau" --- Lectura y escritura de ficheros Sun AU
**************************************************

**Código fuente:** Lib/sunau.py

Obsoleto desde la versión 3.11, se eliminará en la versión 3.13: El
módulo "sunau" está obsoleto (ver **PEP 594** para más detalles).

======================================================================

El módulo "sunau" provee una interfaz conveniente para el formato de
sonido Sun AU. Note que este módulo es de interfaz compatible con los
módulos "aifc" y "wave".

Un fichero de audio consiste de un encabezado seguido por la
información. Los campos del encabezado son:

+-----------------+-------------------------------------------------+
| Campo           | Contenido                                       |
|=================|=================================================|
| palabra mágica  | Los cuatro bytes ".snd".                        |
+-----------------+-------------------------------------------------+
| tamaño del      | Tamaño del encabezado, incluyendo información,  |
| encabezado      | en bytes.                                       |
+-----------------+-------------------------------------------------+
| tamaño de la    | Tamaño físico de la información, en bytes.      |
| información     |                                                 |
+-----------------+-------------------------------------------------+
| codificación    | Indica cómo las muestras de audio están         |
|                 | codificadas.                                    |
+-----------------+-------------------------------------------------+
| tasa de muestra | La tasa de muestreo.                            |
+-----------------+-------------------------------------------------+
| # de canales    | El número de canales en las muestras.           |
+-----------------+-------------------------------------------------+
| información     | Cadena de caracteres ASCII dando una            |
|                 | descripción del fichero de audio (rellenada con |
|                 | bytes nulos).                                   |
+-----------------+-------------------------------------------------+

Aparte del campo de información, todos los campos de encabezado tienen
4 bytes de tamaño. Todos ellos son enteros sin signo codificados en
orden de bytes *big-endian*.

El módulo "sunau" define las siguientes funciones:

sunau.open(file, mode)

   Si *file* es una cadena, abre el fichero por ese nombre, de otra
   forma lo trata como un objeto similar a un fichero buscable. *mode*
   puede ser cualquiera de

   "'r'"
      Modo de sólo lectura.

   "'w'"
      Modo de sólo escritura.

   Note que no acepta ficheros de lectura/escritura.

   Un *mode* de "'r'" retorna un objeto "AU_read", mientras un *mode*
   de "'w'" o "'wb'" retorna un objeto "AU_write".

El módulo "sunau" define la siguiente excepción:

exception sunau.Error

   Un error generado cuando algo es imposible por especificaciones de
   Sun AU o deficiencia de implementación.

El módulo "sunau" define los siguientes ítems de información:

sunau.AUDIO_FILE_MAGIC

   Un entero por cada fichero Sun AU válido comienza con, almacenada
   en la forma *big-endian*. Esto es la cadena ".snd" interpretada
   como un entero.

sunau.AUDIO_FILE_ENCODING_MULAW_8
sunau.AUDIO_FILE_ENCODING_LINEAR_8
sunau.AUDIO_FILE_ENCODING_LINEAR_16
sunau.AUDIO_FILE_ENCODING_LINEAR_24
sunau.AUDIO_FILE_ENCODING_LINEAR_32
sunau.AUDIO_FILE_ENCODING_ALAW_8

   Valores del campo de codificación para el encabezado AU que son
   soportados por este módulo.

sunau.AUDIO_FILE_ENCODING_FLOAT
sunau.AUDIO_FILE_ENCODING_DOUBLE
sunau.AUDIO_FILE_ENCODING_ADPCM_G721
sunau.AUDIO_FILE_ENCODING_ADPCM_G722
sunau.AUDIO_FILE_ENCODING_ADPCM_G723_3
sunau.AUDIO_FILE_ENCODING_ADPCM_G723_5

   Valores adicionales conocidos por el campo de codificación del
   encabezado AU, pero que no son soportados por este módulo.


Objetos AU_read
===============

Objetos AU_read, como se retornan por "open()" arriba, tienen los
siguientes métodos:

AU_read.close()

   Cierra el flujo, y hace que la instancia sea inutilizable. (Esto es
   llamado automáticamente en la eliminación.)

AU_read.getnchannels()

   Retorna el número de canales de audio (1 para mono, 2 para
   estéreo).

AU_read.getsampwidth()

   Retorna el ancho de muestra en bytes.

AU_read.getframerate()

   Retorna la frecuencia de muestreo.

AU_read.getnframes()

   Retorna el número de cuadros por segundo de audio.

AU_read.getcomptype()

   Retorna el tipo de compresión. Los tipos de compresión soportados
   son "'ULAW'", "'ALAW'" y "'NONE'".

AU_read.getcompname()

   Versión legible por humanos de "getcomptype()". Los tipos
   soportados tienen los nombres respectivos "'CCITT G.711 u-law'",
   "'CCITT G.711 A-law'" y "'not compressed'".

AU_read.getparams()

   Retorna un "namedtuple()" "(nchannels, sampwidth, framerate,
   nframes, comptype, compname)", equivalente a la salida de los
   métodos "get*()".

AU_read.readframes(n)

   Lee y retorna al menos *n* fotogramas de audio, como un objeto
   "bytes". La información será retornada en formato linear. Si la
   información original está en formato u-LAW, será convertida.

AU_read.rewind()

   Rebobina el puntero del fichero al comienzo del flujo de audio.

Los siguientes dos métodos definen un término "position" el cual es
compatible entre ellos, y es de otra manera dependiente de la
implementación.

AU_read.setpos(pos)

   Establece el puntero del fichero a la posición especificada. Sólo
   valores retornados desde "tell()" deberían ser utilizados por
   *pos*.

AU_read.tell()

   Retorna la posición actual del puntero de fichero. Note que el
   valor retornado no tiene nada que ver con la posición actual en el
   fichero.

Las siguientes dos funciones están definidas por compatibilidad con el
"aifc", y no hace nada interesante.

AU_read.getmarkers()

   Retorna "None".

AU_read.getmark(id)

   Lanza un error.


Objetos AU_write
================

Objetos AU_write, como se retornan por "open()" arriba, tienen los
siguientes métodos:

AU_write.setnchannels(n)

   Establece el número de canales.

AU_write.setsampwidth(n)

   Establece el ancho de muestra (en bytes.)

   Distinto en la versión 3.4: Agregado soporte para muestras de 24
   bits.

AU_write.setframerate(n)

   Establece la velocidad de cuadros por segundo.

AU_write.setnframes(n)

   Establece el número de cuadros por segundo. Esto puede ser cambiado
   más adelante, cuando y si más cuadros por segundo son escritos.

AU_write.setcomptype(type, name)

   Establece el tipo de compresión y descripción. Sólo "'NONE'" y
   "'ULAW'" son soportados en salida.

AU_write.setparams(tuple)

   La *tuple* debería ser "(nchannels, sampwidth, framerate, nframes,
   comptype, compname)", con valores válidos para los métodos
   "set*()". Establece todos los parámetros.

AU_write.tell()

   Retorna la posición actual en el fichero, con los mismos descargos
   de responsabilidad para los métodos "AU_read.tell()" y
   "AU_read.setpos()".

AU_write.writeframesraw(data)

   Escribe cuadros por segundo de audio, sin corregir *nframes*.

   Distinto en la versión 3.4: Cualquier *bytes-like object* es
   aceptado ahora.

AU_write.writeframes(data)

   Escribe cuadros por segundo de audio y se asegura que *nframes* sea
   correcto.

   Distinto en la versión 3.4: Cualquier *bytes-like object* es
   aceptado ahora.

AU_write.close()

   Se asegura que *nframes* sea correcto, y cierra el fichero.

   Este método es llamado después de la eliminación.

Note que es inválido establecer cualquier parámetro después de llamar
"writeframes()" o "writeframesraw()".
