# `sunau` — Lectura y escritura de ficheros Sun AU

Código fuente: Lib/sunau.py

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 encabezado | Tamaño del encabezado, incluyendo información, en bytes.
tamaño de la información | Tamaño físico de la información, en bytes.
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`.

`sunau.``openfp`(file, mode)

  Un sinónimo para `open()`, mantenido para compatibilidad con versiones anteriores.

  Deprecated since version 3.7, will be removed in version 3.9.

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()`.