"ossaudiodev" --- Acceso a dispositivos de audio compatibles con OSS
********************************************************************

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

Este módulo le permite acceder a la interfaz de audio OSS (Open Sound
System). OSS está disponible para una amplia gama de Unices
comerciales y de código abierto, y es la interfaz de audio estándar
para Linux y versiones recientes de FreeBSD.

Distinto en la versión 3.3: Las operaciones en este módulo ahora
generan "OSError" donde "IOError`" es generado.

Ver también:

  Open Sound System Programmer’s Guide
     la documentación oficial de la API de OSS C

  El módulo define una gran cantidad de constantes suministradas por
  el controlador de dispositivo OSS; consulte "<sys/soundcard.h>" en
  Linux o FreeBSD para obtener un listado.

"ossaudiodev" define las siguientes variables y funciones:

exception ossaudiodev.OSSAudioError

   Esta excepción se genera en ciertos errores. El argumento es una
   cadena que describe qué salió mal.

   (Si "ossaudiodev`" recibe un error de una llamada al sistema como
   "open()", "write()", o "ioctl()", genera "OSError". Los errores
   detectados directamente por "ossaudiodev" dan como resultado
   "OSSAudioError".)

   (Para compatibilidad con versiones anteriores, la clase de
   excepción también está disponible como "ossaudiodev.error".)

ossaudiodev.open(mode)
ossaudiodev.open(device, mode)

   Abra un dispositivo de audio y retorne un objeto de dispositivo de
   audio OSS. Este objeto admite muchos métodos similares a archivos,
   como "read()", "write()", and "fileno()" (aunque existen
   diferencias sutiles entre la semántica de lectura/escritura
   convencional de Unix y la de audio OSS dispositivos). También es
   compatible con varios métodos específicos de audio; vea a
   continuación la lista completa de métodos.

   *device* es el nombre de archivo del dispositivo de audio que se
   utilizará. Si no se especifica, este módulo primero busca en la
   variable de entorno "AUDIODEV" para un dispositivo a usar. Si no se
   encuentra, vuelve a "/dev/dsp".

   *mode* es uno de "’r’" para acceso de solo lectura (grabación),
   "’w’" para acceso de solo escritura (reproducción) y "’rw’" para
   ambos. Dado que muchas tarjetas de sonido solo permiten que un
   proceso tenga la grabadora o el reproductor abiertos a la vez, es
   una buena idea abrir el dispositivo solo para la actividad
   necesaria. Además, algunas tarjetas de sonido son semidúplex: se
   pueden abrir para leer o escribir, pero no ambas a la vez.

   Tenga en cuenta la sintaxis de llamada inusual: el *first*
   argumento es opcional y el segundo es obligatorio. Este es un
   artefacto histórico para la compatibilidad con el módulo anterior
   "linuxaudiodev" que "ossaudiodev" reemplaza.

ossaudiodev.openmixer([device])

   Abra un dispositivo mezclador y retorne un objeto de dispositivo
   mezclador OSS. *device* es el nombre de archivo del dispositivo
   mezclador que se utilizará. Si no se especifica, este módulo
   primero busca en la variable de entorno "MIXERDEV" para usar un
   dispositivo. Si no se encuentra, vuelve a "/dev/mixer".


Objetos de dispositivo de audio
===============================

Antes de poder escribir o leer desde un dispositivo de audio, debe
llamar a tres métodos en el orden correcto:

1. "setfmt()" para configurar el formato de salida

2. "channels()" para configurar el número de canales

3. "speed()" para configurar la frecuencia de muestreo

Alternativamente, puede usar el método "setparameters()" para
configurar los tres parámetros de audio a la vez. Esto es más
conveniente, pero puede que no sea tan flexible en todos los casos.

Los objetos de dispositivo de audio retornados por "open()" definen
los siguientes métodos y atributos (de solo lectura):

oss_audio_device.close()

   Cierre explícitamente el dispositivo de audio. Cuando haya
   terminado de escribir o leer desde un dispositivo de audio, debe
   cerrarlo explícitamente. Un dispositivo cerrado no se puede volver
   a utilizar.

oss_audio_device.fileno()

   Retorna el descriptor de archivo asociado con el dispositivo.

oss_audio_device.read(size)

   Leer *size* bytes de la entrada de audio y retornarlos como una
   cadena de Python. A diferencia de la mayoría de los controladores
   de dispositivos Unix, los dispositivos de audio OSS en modo de
   bloqueo (el predeterminado) bloquearán "read()" hasta que esté
   disponible toda la cantidad de datos solicitada.

oss_audio_device.write(data)

   Escriba un *bytes-like object* *data* en el dispositivo de audio y
   retorne el número de bytes escritos. Si el dispositivo de audio
   está en modo de bloqueo (el predeterminado), todos los datos
   siempre se escriben (nuevamente, esto es diferente de la semántica
   habitual del dispositivo Unix). Si el dispositivo está en modo sin
   bloqueo, es posible que algunos datos no se escriban---see
   "writeall()".

   Distinto en la versión 3.5: Ahora se aceptan objetos con permisos
   de escritura con formato *bytes-like object*.

oss_audio_device.writeall(data)

   Escriba un *bytes-like object* *data* en el dispositivo de audio:
   espera hasta que el dispositivo de audio sea capaz de aceptar
   datos, escribe tantos datos como acepte y repite hasta que *data*
   se hayan escrito por completo. Si el dispositivo está en modo de
   bloqueo (el predeterminado), esto tiene el mismo efecto que
   "write()"; "writeall()" solo es útil en el modo sin bloqueo. No
   tiene valor de retorno, ya que la cantidad de datos escritos
   siempre es igual a la cantidad de datos suministrados.

   Distinto en la versión 3.5: Ahora se aceptan objetos con permisos
   de escritura con formato *bytes-like object*.

Distinto en la versión 3.2: Los objetos de dispositivo de audio
también admiten el protocolo de gestión de contexto, es decir, se
pueden utilizar en una declaración "with".

Los siguientes métodos se asignan exactamente a una llamada al sistema
"ioctl()". La correspondencia es obvia: por ejemplo, "setfmt()"
corresponde al "SNDCTL_DSP_SETFMT" ioctl, y "sync()" a
"SNDCTL_DSP_SYNC" (esto puede ser útil cuando se consulta la
documentación de OSS). Si el subyacente "ioctl()" falla, todos generan
"OSError".

oss_audio_device.nonblock()

   Ponga el dispositivo en modo sin bloqueo. Una vez en el modo sin
   bloqueo, no hay forma de volverlo al modo de bloqueo.

oss_audio_device.getfmts()

   Retorna una máscara de bits de los formatos de salida de audio
   admitidos por la tarjeta de sonido. Algunos de los formatos
   admitidos por OSS son:

   +---------------------------+-----------------------------------------------+
   | Formato                   | Descripción                                   |
   |===========================|===============================================|
   | "AFMT_MU_LAW"             | una codificación logarítmica (utilizada por   |
   |                           | los archivos Sun ".au" y "/dev/audio")        |
   +---------------------------+-----------------------------------------------+
   | "AFMT_A_LAW"              | una codificación logarítmica                  |
   +---------------------------+-----------------------------------------------+
   | "AFMT_IMA_ADPCM"          | un formato comprimido 4:1 definido por la     |
   |                           | Interactive Multimedia Association            |
   +---------------------------+-----------------------------------------------+
   | "AFMT_U8"                 | Audio de 8 bits sin firmar                    |
   +---------------------------+-----------------------------------------------+
   | "AFMT_S16_LE"             | Orden de bytes little-endian firmado, audio   |
   |                           | de 16 bits (como lo utilizan los procesadores |
   |                           | Intel)                                        |
   +---------------------------+-----------------------------------------------+
   | "AFMT_S16_BE"             | Orden de bytes big-endian firmado, audio de   |
   |                           | 16 bits (como lo utilizan 68k, PowerPC,       |
   |                           | Sparc)                                        |
   +---------------------------+-----------------------------------------------+
   | "AFMT_S8"                 | Firmado, audio de 8 bits                      |
   +---------------------------+-----------------------------------------------+
   | "AFMT_U16_LE"             | Audio little-endian de 16 bits sin firmar     |
   +---------------------------+-----------------------------------------------+
   | "AFMT_U16_BE"             | Audio big-endian de 16 bits sin firmar        |
   +---------------------------+-----------------------------------------------+

   Consulte la documentación de OSS para obtener una lista completa de
   los formatos de audio y tenga en cuenta que la mayoría de los
   dispositivos solo admiten un subconjunto de estos formatos. Algunos
   dispositivos antiguos solo admiten "AFMT_U8"; el formato más común
   utilizado hoy en día es "AFMT_S16_LE".

oss_audio_device.setfmt(format)

   Intente establecer el formato de audio actual en
   *format*---consulte "getfmts()" para obtener una lista. Retorna el
   formato de audio en el que se configuró el dispositivo, que puede
   no ser el formato solicitado. También se puede utilizar para
   retornar el formato de audio actual. Haga esto pasando un "formato
   de audio" de "AFMT_QUERY".

oss_audio_device.channels(nchannels)

   Establezca el número de canales de salida en *nchannels*. Un valor
   de 1 indica sonido monofónico, 2 estereofónico. Algunos
   dispositivos pueden tener más de 2 canales y algunos dispositivos
   de gama alta pueden no admitir mono. Retorna el número de canales
   en los que se configuró el dispositivo.

oss_audio_device.speed(samplerate)

   Intente establecer la frecuencia de muestreo de audio en
   *samplerate* muestras por segundo. Retorna la tasa realmente
   establecida. La mayoría de los dispositivos de sonido no admiten
   frecuencias de muestreo arbitrarias. Las tarifas comunes son:

   +---------+---------------------------------------------+
   | Veloci  | Descripción                                 |
   | dad     |                                             |
   |=========|=============================================|
   | 8000    | tasa predeterminada para "/dev/audio"       |
   +---------+---------------------------------------------+
   | 11025   | grabación de voz                            |
   +---------+---------------------------------------------+
   | 22050   |                                             |
   +---------+---------------------------------------------+
   | 44100   | Audio con calidad de CD (a 16 bits/muestra  |
   |         | y 2 canales)                                |
   +---------+---------------------------------------------+
   | 96000   | Audio con calidad de DVD (a 24              |
   |         | bits/muestra)                               |
   +---------+---------------------------------------------+

oss_audio_device.sync()

   Espere hasta que el dispositivo de sonido haya reproducido todos
   los bytes de su búfer. (Esto sucede implícitamente cuando el
   dispositivo está cerrado). La documentación de OSS recomienda
   cerrar y volver a abrir el dispositivo en lugar de usar "sync()".

oss_audio_device.reset()

   Deje de reproducir o grabar inmediatamente y retorne el dispositivo
   a un estado en el que pueda aceptar comandos. La documentación de
   OSS recomienda cerrar y volver a abrir el dispositivo después de
   llamar "reset()".

oss_audio_device.post()

   Dígale al controlador que es probable que haya una pausa en la
   salida, lo que hace posible que el dispositivo maneje la pausa de
   manera más inteligente. Puede usar esto después de reproducir un
   efecto de sonido puntual, antes de esperar la entrada del usuario o
   antes de realizar E/S de disco.

Los siguientes métodos de conveniencia combinan varios ioctl, o un
ioctl y algunos cálculos simples.

oss_audio_device.setparameters(format, nchannels, samplerate[, strict=False])

   Configure los parámetros clave de muestreo de audio (formato de
   muestra, número de canales y frecuencia de muestreo) en una llamada
   de método. *format*, *nchannels*, y *samplerate* deben ser como se
   especifica en los métodos "setfmt()", "channels()", y "speed()". Si
   *strict* es verdadero, "setparameters()" comprueba si cada
   parámetro se estableció realmente en el valor solicitado, y genera
   "OSSAudioError" si no es así. Retorna una tupla (*format*,
   *nchannels*, *samplerate*) que indica los valores de los parámetros
   que realmente estableció el controlador del dispositivo (es decir,
   los mismos que los valores retornados de "setfmt()", "channels()",
   y "speed()").

   Por ejemplo,

      (fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)

   es equivalente a

      fmt = dsp.setfmt(fmt)
      channels = dsp.channels(channels)
      rate = dsp.rate(rate)

oss_audio_device.bufsize()

   Retorna el tamaño del búfer de hardware, en muestras.

oss_audio_device.obufcount()

   Retorna el número de muestras que están en el búfer de hardware que
   aún no se han reproducido.

oss_audio_device.obuffree()

   Retorna el número de muestras que se podrían poner en cola en el
   búfer de hardware para reproducirse sin bloqueos.

Los objetos de dispositivo de audio también admiten varios atributos
de solo lectura:

oss_audio_device.closed

   Booleano que indica si el dispositivo se ha cerrado.

oss_audio_device.name

   Cadena que contiene el nombre del archivo del dispositivo.

oss_audio_device.mode

   El modo de E/S para el archivo, ya sea ""r"", ""rw"", o ""w"".


Objetos del dispositivo mezclador
=================================

El objeto del mezclador proporciona dos métodos similares a archivos:

oss_mixer_device.close()

   Este método cierra el archivo del dispositivo mezclador abierto.
   Cualquier otro intento de usar el mezclador después de que este
   archivo esté cerrado generará un "OSError".

oss_mixer_device.fileno()

   Retorna el número de identificador de archivo del archivo del
   dispositivo mezclador abierto.

Distinto en la versión 3.2: Los objetos Mixer también admiten el
protocolo de gestión de contexto.

Los métodos restantes son específicos para la mezcla de audio:

oss_mixer_device.controls()

   Este método retorna una máscara de bits que especifica los
   controles del mezclador disponibles ("Control"  es un "canal"
   mezclable específico, como "SOUND_MIXER_PCM" o
   "SOUND_MIXER_SYNTH"). Esta máscara de bits indica un subconjunto de
   todos los controles de mezclador disponibles --- las constantes
   "SOUND_MIXER_*" definidas a nivel de módulo. Para determinar si,
   por ejemplo, el objeto mezclador actual admite un mezclador PCM,
   utilice el siguiente código Python:

      mixer=ossaudiodev.openmixer()
      if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM):
          # PCM is supported
          ... code ...

   Para la mayoría de los propósitos, los controles
   "SOUND_MIXER_VOLUME" (volumen maestro) y "SOUND_MIXER_PCM" deberían
   ser suficientes --- pero el código que usa el mezclador debe ser
   flexible cuando se trata de elegir los controles del mezclador. En
   el Ultrasonido Gravis, por ejemplo, "SOUND_MIXER_VOLUME" no existe.

oss_mixer_device.stereocontrols()

   Retorna una máscara de bits que indica los controles del mezclador
   estéreo. Si se establece un bit, el control correspondiente es
   estéreo; si no está configurado, el control es monofónico o no es
   compatible con el mezclador (úselo en combinación con "controls()"
   para determinar cuál).

   Consulte el ejemplo de código de la función "controls()" para ver
   un ejemplo de cómo obtener datos de una máscara de bits.

oss_mixer_device.reccontrols()

   Retorna una máscara de bits que especifica los controles del
   mezclador que se pueden usar para grabar. Consulte el ejemplo de
   código de "controls()" para ver un ejemplo de lectura desde una
   máscara de bits.

oss_mixer_device.get(control)

   Retorna el volumen de un control de mezcla determinado. El volumen
   retornado es una tupla de 2 "(left_volume,right_volume)". Los
   volúmenes se especifican como números del 0 (silencioso) al 100
   (volumen completo). Si el control es monofónico, todavía se retorna
   una tupla de 2, pero ambos volúmenes son iguales.

   Genera "OSSAudioError" si se especifica un control no válido, o
   "OSError" si se especifica un control no admitido.

oss_mixer_device.set(control, (left, right))

   Establece el volumen para un control de mezclador dado en
   "(left,right)". "left" y "right" deben ser enteros y estar entre 0
   (silencio) y 100 (volumen completo). En caso de éxito, el nuevo
   volumen se retorna como 2 tuplas. Tenga en cuenta que puede que no
   sea exactamente el mismo que el volumen especificado, debido a la
   resolución limitada de algunos mezcladores de tarjetas de sonido.

   Aumenta "OSSAudioError" si se especificó un control de mezcla no
   válido, o si los volúmenes especificados estaban fuera de rango.

oss_mixer_device.get_recsrc()

   Este método retorna una máscara de bits que indica qué control(es)
   se están utilizando actualmente como fuente de grabación.

oss_mixer_device.set_recsrc(bitmask)

   Llame a esta función para especificar una fuente de grabación.
   Retorna una máscara de bits que indica la nueva fuente de grabación
   (o fuentes) si tiene éxito; plantea "OSError" si se especificó una
   fuente no válida. Para configurar la fuente de grabación actual a
   la entrada del micrófono:

      mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)
