# `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:

  Velocidad | Descripción
  --- | ---
  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)