"aifc" — Lee y escribe archivos AIFF y AIFC
*******************************************

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

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

Este módulo provee soporte para la lectura y escritura de archivos
AIFF y AIFF-C. AIFF son las siglas de Formato de Intercambio de
Archivos de Audio (*Audio Interchange File Format*), un formato para
almacenar muestras de audio digital en un archivo. AIFF-C es una nueva
versión del formato que incluye la habilidad de comprimir los datos de
audio.

Los archivos de audio tienen una serie de parámetros que describen los
datos de audio. La tasa de muestreo o tasa de fotogramas se refiere a
la cantidad de veces por segundo que se toman muestras del sonido. El
número de canales indica si el audio es mono, estéreo o cuadrafónico.
Cada fotograma está compuesto de una muestra por canal. El tamaño de
la muestra es el tamaño en bytes de cada muestra. De esta manera, un
fotograma está formado por "nchannels * samplesize" bytes, y un
segundo de audio está formado por "nchannels * samplesize * framerate"
bytes.

Por ejemplo, el audio de calidad de CD tiene un tamaño de muestreo de
2 bytes (16 bits), usa dos canales (estéreo) y tiene una tasa de
fotogramas de 44.100 fotogramas/segundo. Esto da como resultado un
tamaño del fotograma de 4 bytes (2*2), y un segundo de audio en esta
calidad ocupa 2*2*44.100 bytes (176.400 bytes).

El módulo "aifc" define a la siguiente función:

aifc.open(file, mode=None)

   Abre un archivo AIFF o AIFF-C y retorna una instancia de objeto con
   los métodos descriptos más abajo. El argumento *file* puede ser
   tanto una cadena de caracteres nombrando a un archivo como un *file
   object*. *mode* debe ser "'r'" o "'rb'" cuando el archivo sea
   abierto para lectura, o "'w'" o "'wb'" cuando lo sea para
   escritura. Si este argumento se omite, se usará "file.mode" si es
   que existe; en caso contrario se usará "'rb'" . Cuando se use para
   escribir el objeto archivo deberá ser "buscable" (*seekable*), a
   menos que se sepa por adelantado cuántas muestras se escribirán en
   total y use "writeframesraw()" and "setnframes()". La función
   "open()" se puede usar dentro de una sentencia "with". Cuando el
   bloque "with" se complete, se invocará al método "close()".

   Distinto en la versión 3.4: Se agregó soporte para las sentencias
   "with".

Los objetos que retorna "open()" cuando un archivo es abierto para
lectura contienen los siguientes métodos:

aifc.getnchannels()

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

aifc.getsampwidth()

   Retorna el tamaño en bytes de cada muestra.

aifc.getframerate()

   Retorna la tasa de muestreo (cantidad de fotogramas de audio por
   segundo).

aifc.getnframes()

   Retorna el número de fotogramas de audio en el archivo.

aifc.getcomptype()

   Retorna un arreglo de bytes de longitud 4 que describe el tipo de
   compresión usada en el archivo de audio. Para archivos AIFF, el
   valor que retorna es "b’NONE’".

aifc.getcompname()

   Retorna un arreglo de bytes con una descripción legible para
   humanos del tipo de compresión usada en el archivo de audio. Para
   archivos AIFF, el valor que retorna es "b’not compressed’" (no
   comprimido).

aifc.getparams()

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

aifc.getmarkers()

   Retorna una lista de los marcadores en el archivo de audio. Un
   marcador consiste de una tupla de tres elementos. El primero es el
   identificador de marca (*mark ID*, un número entero); el segundo es
   la posición de la marca, en fotogramas, desde el comienzo de los
   datos (un número entero); el tercero es el nombre de la marca (una
   cadena de caracteres).

aifc.getmark(id)

   Retorna una tupla tal como se describe en "getmarkers()" para la
   marca con el *id* dado.

aifc.readframes(nframes)

   Lee y retorna los *nframes* fotogramas siguientes del archivo de
   audio. Los datos los retorna como una cadena de caracteres que
   contiene, por cada fotograma, las muestras sin comprimir de todos
   los canales.

aifc.rewind()

   Rebobina el puntero de lectura. La próxima ejecución de
   "readframes()" comenzará desde el comienzo del archivo.

aifc.setpos(pos)

   Busca el número de fotograma especificado.

aifc.tell()

   Retorna el número de fotograma actual.

aifc.close()

   Cierra el archivo AIFF. Después de invocar este método, el objeto
   no puede usarse más.

Cuando un archivo se abre para escritura, los objetos que retorna
"open()" poseen todos los métodos mencionados más arriba, excepto
"readframes()" y "setpos()". Adicionalmente se incluyen los métodos
abajo descriptos. Los métodos "get*()" sólo pueden ser invocados
después de haber invocado su correspondiente método "set*()". Antes de
invocar por primera vez "writeframes()" o "writeframesraw()", todos
los parámetros -excepto el número de fotogramas- deben estar
completos.

aifc.aiff()

   Crea un archivo AIFF. Por defecto se crea un archivo AIFF-C,
   excepto que el nombre del archivo termine en "'.aiff'", en cuyo
   caso se creará un archivo AIFF.

aifc.aifc()

   Crea un archivo AIFF-C. La acción por defecto es que cree un
   archivo AIFF-C, excepto que el nombre del archivo termine en
   "'.aiff'", en cuyo caso se crea por defecto un archivo AIFF.

aifc.setnchannels(nchannels)

   Especifica el número de canales en el archivo de audio.

aifc.setsampwidth(width)

   Especifica el tamaño en bytes de las muestras de audio.

aifc.setframerate(rate)

   Especifica la frecuencia de muestreo en fotogramas por segundo.

aifc.setnframes(nframes)

   Especifica el número de fotogramas que se escribirán en el archivo
   de audio. Si este parámetro no es definido, o si no se lo define
   correctamente, el archivo necesitará soporte de búsqueda
   (*seeking*).

aifc.setcomptype(type, name)

   Especifica el tipo de compresión. Si no es especificada, los datos
   de audio no serán comprimidos. En los archivos AIFF la compresión
   no está disponible. El parámetro de nombre *name* deberá ser una
   descripción del tipo de compresión legible por humanos, en forma de
   un arreglo de bytes. El parámetro de tipo *type* deberá ser un
   arreglo de bytes de longitud 4. Actualmente se soportan los
   siguientes tipos de compresión: "b'NONE'", "b'ULAW'", "b'ALAW'",
   "b'G722'".

aifc.setparams(nchannels, sampwidth, framerate, comptype, compname)

   Establece de una vez todos los parámetros mostrados arriba. El
   argumento es una tupla compuesta por estos parámetros. Esto quiere
   decir que es posible usar el resultado de una llamada "getparams()"
   como argumento para "setparams()".

aifc.setmark(id, pos, name)

   Agrega una marca con el identificador *id* dado (mayor a 0) y el
   nombre *name* dado, en la posición *pos* dada. Este método se puede
   invocar en cualquier momento antes de "close()".

aifc.tell()

   Retorna la posición de escritura actual en el archivo de salida. Es
   útil en combinación con "setmark()".

aifc.writeframes(data)

   Escribe los datos al archivo de salida. Este método sólo se puede
   invocar una vez establecidos los parámetros del archivo de audio.

   Distinto en la versión 3.4: Acepta cualquier *bytes-like object*.

aifc.writeframesraw(data)

   Funciona igual que "writeframes()", excepto que el encabezado del
   archivo de audio no es actualizado.

   Distinto en la versión 3.4: Acepta cualquier *bytes-like object*.

aifc.close()

   Cierra el archivo AIFF. El encabezado del archivo se actualiza para
   reflejar el tamaño real de los datos de audio. Después de invocar a
   este método, el objeto no puede usarse más.
