"wave" --- Leer y escribir archivos WAV
***************************************

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

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

El módulo "wave" proporciona una interfaz conveniente para el formato
de sonido WAV. No es compatible con la compresión/descompresión, pero
sí es compatible con mono/estéreo.

El módulo "wave" define la siguiente función y excepción:

wave.open(file, mode=None)

   Si *file* es una cadena, abra el archivo con ese nombre, de lo
   contrario trátelo como un objeto similar a un archivo.  *mode*
   puede ser:

   "'rb'"
      Modo de solo lectura.

   "'wb'"
      Modo de solo escritura.

   Tenga en cuenta que no permite archivos WAV de lectura/escritura.

   Un *mode* de "'rb'" retorna un objeto "Wave_read", mientras que un
   *mode* de "'wb'" retorna un objeto "Wave_write".  Si se omite
   *mode* y se pasa un objeto similar a un archivo como *file*,
   "file.mode" se usa como el valor predeterminado para *mode*.

   Si pasa un objeto similar a un archivo, el objeto *wave* no lo
   cerrará cuando se llame al método "close()"; es responsabilidad del
   invocador cerrar el objeto de archivo.

   La función "open()" se puede utilizar en una declaración "with".
   Cuando el bloque  "with" se completa, el método "Wave_read.close()"
   o el método "Wave_write.close()" es invocado.

   Distinto en la versión 3.4: Se agregó soporte para archivos no
   encontrados.

wave.openfp(file, mode)

   Un sinónimo de "open()", es mantenido para la compatibilidad con
   versiones anteriores.

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

exception wave.Error

   Error que se produce cuando algo es imposible porque viola la
   especificación WAV o alcanza una deficiencia de implementación.


Los objetos *Wave_read*
=======================

Los objetos *Wave_read*, tal como lo retorna "open()", tienen los
siguientes métodos:

Wave_read.close()

   Cierra la secuencia si fue abierta por "wave", y hace que la
   instancia sea inutilizable. Esto es llamado automáticamente en la
   colección de objetos.

Wave_read.getnchannels()

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

Wave_read.getsampwidth()

   Retorna el ancho de la muestra en bytes.

Wave_read.getframerate()

   Retorna la frecuencia del muestreo.

Wave_read.getnframes()

   Retorna el número de cuadros del audio.

Wave_read.getcomptype()

   Retorna el tipo de compresión ("'NONE'" es el único tipo admitido).

Wave_read.getcompname()

   Versión legible para humanos de "getcomptype()". Generalmente "'not
   compressed'" significa "'NONE'".

Wave_read.getparams()

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

Wave_read.readframes(n)

   Lee y retorna como máximo *n* cuadros de audio, como un objeto
   "bytes".

Wave_read.rewind()

   Rebobina el puntero del archivo hasta el principio de la secuencia
   de audio.

Los dos métodos siguientes se definen por compatibilidad con el módulo
"aifc", y no hacen nada interesante.

Wave_read.getmarkers()

   Retorna "None".

Wave_read.getmark(id)

   Lanza un error.

Los dos métodos siguientes definen un término "posición" que es
compatible entre ellos y, es dependiente de la implementación.

Wave_read.setpos(pos)

   Establece el puntero del archivo en la posición especificada.

Wave_read.tell()

   Retorna la posición actual del puntero del archivo.


Los objetos *Wave_write*
========================

Para las secuencias de salida que se pueden buscar, el encabezado de
"wave" se actualizará automáticamente para reflejar el número de
cuadros realmente escritos. Para secuencias que no se pueden buscar,
el valor *nframes* debe ser preciso cuando se escriben los datos del
primer cuadro. Se puede lograr un valor *nframes* preciso llamando a
"setnframes()" o "setparams()" con el número de cuadros que se
escribirán antes de que se llame a "close()"  y luego se usa
"writeframesraw()" para escribir los datos del cuadro, o llamando a
"writeframes()" con todos los datos del cuadro que se escribirán. En
el último caso "writeframes()" calculará el número de cuadros en los
datos y establecerá *nframes* como consecuencia antes de escribir los
datos del cuadro.

Los objetos *Wave_write*, retornados por "open()", tienen los
siguientes métodos:

Distinto en la versión 3.4: Se agregó soporte para archivos no
encontrados.

Wave_write.close()

   Asegúrese de que *nframes* sea correcto y cierre el archivo si fue
   abierto por "wave". Este método es invocado en la colección de
   objetos. Levantará una excepción si la secuencia de salida no se
   puede buscar y *nframes* no coinciden con el número de cuadros
   realmente escritos.

Wave_write.setnchannels(n)

   Configure el número de canales.

Wave_write.setsampwidth(n)

   Establezca el ancho de la muestra en *n* bytes.

Wave_write.setframerate(n)

   Establezca la velocidad del cuadro en *n*.

   Distinto en la versión 3.2: Una entrada no-entera para este método
   se redondea al número entero más cercano.

Wave_write.setnframes(n)

   Establezca el número de cuadros en *n*. Esto se cambiará más
   adelante si el número de cuadros realmente escritos es diferente
   (este intento de actualización levantará un error si no se
   encuentra la secuencia de salida).

Wave_write.setcomptype(type, name)

   Establece el tipo de compresión y la descripción. Por el momento,
   solo se admite el tipo de compresión "NONE", lo que significa que
   no hay compresión.

Wave_write.setparams(tuple)

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

Wave_write.tell()

   Retorna la posición actual en el archivo, con el mismo descargo
   para los métodos "Wave_read.tell()" y "Wave_read.setpos()".

Wave_write.writeframesraw(data)

   Escribe cuadros de audio, sin corregir *nframes*.

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

Wave_write.writeframes(data)

   Escribe cuadros de audio y se asegura de que *nframes* sea
   correcto. Levantará un error si no se puede encontrar la secuencia
   de salida y si el número total de cuadros que se han escrito
   después de que se haya escrito *data* no coincide con el valor
   establecido previamente para *nframes*.

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

Tenga en cuenta que no es válido establecer ningún parámetro después
de invocar a "writeframes()" o "writeframesraw()", y cualquier intento
de hacerlo levantará "wave.Error".
