Cómo comenzar

En esta sección, se proporciona la información necesaria para comenzar a usar las APIs de OpenSL ES.

Cómo agregar OpenSL ES a tu app

Puedes llamar a OpenSL ES desde el código C y C++. Para agregar el conjunto de atributos central de OpenSL ES a tu app, incluye el archivo de encabezado OpenSLES.h:

#include <SLES/OpenSLES.h>

Para agregar también las extensiones para Android de OpenSL ES, incluye el archivo de encabezado OpenSLES_Android.h:

#include <SLES/OpenSLES_Android.h>

Cuando incluyes el archivo de encabezado OpenSLES_Android.h, los siguientes encabezados se incluyen automáticamente:

#include <SLES/OpenSLES_AndroidConfiguration.h>
#include <SLES/OpenSLES_AndroidMetadata.h>

Nota: Estos encabezados no son obligatorios, pero se muestran como una ayuda para conocer la API.

Cómo compilar y depurar

Puedes incorporar OpenSL ES a tu compilación si así lo especificas en el archivo Android.mk, que funciona como uno de los archivos Make del sistema de compilación del NDK. Agrega la siguiente línea a Android.mk:

LOCAL_LDLIBS += -lOpenSLES

Para una depuración más profunda, te recomendamos examinar el valor SLresult que muestra la mayoría de las API de OpenSL ES. Puedes usar aserciones o una lógica de administración de errores más avanzada para la depuración. Ninguna ofrece una ventaja inherente para trabajar con OpenSL ES, aunque cualquiera de las dos podría ser más adecuada para un determinado caso práctico.

Usamos aserciones en nuestros ejemplos porque nos ayudan a detectar condiciones poco comunes que podrían indicar un error de programación. Ya usamos la administración de errores explícitos para otras condiciones que ocurren con mayor frecuencia durante la producción.

Muchos errores de API generan una entrada de registro, además de un código de resultado que no es cero. Estas entradas de registro pueden proporcionar más información que resulta útil, sobre todo para algunas API relativamente complejas, como Engine::CreateAudioPlayer.

Puedes ver el registro desde la línea de comandos o en Android Studio. Para examinar el registro desde la línea de comandos, escribe lo siguiente:

$ adb logcat

Para examinar el registro de Android Studio, selecciona View > Tool Windows > Logcat. Para obtener más información, consulta Cómo escribir y ver registros con Logcat.

Ejemplo de código

Te recomendamos usar código de ejemplo compatible y probado que puedas usar como modelo para tu propio código, que se encuentra en las carpetas audio-echo y native-audio del repositorio de GitHub android-ndk.

Precaución: La especificación OpenSL ES 1.0.1 incluye ejemplo de código en el apéndice (consulta Registro OpenSL ES de Khronos para obtener más detalles). Sin embargo, los ejemplos del Apéndice B: Código de muestra y Apéndice C: Caso práctico de código de muestra usan características que Android no admite. Algunos ejemplos también contienen errores tipográficos o usan APIs que probablemente cambien. Cuando hagas referencia a estos códigos, hazlo con precaución; si bien el código puede ser útil para comprender el estándar OpenSL ES completo, no debe usarse tal como está en Android.

Contenido de audio

A continuación, te mostramos algunas de las diferentes maneras de empaquetar contenido de audio para tu aplicación:

  • Recursos: Si colocas tus archivos de audio en la carpeta res/raw/, puedes acceder a ellos fácilmente mediante las APIs asociadas para Resources. No obstante, como no hay acceso directo nativo a los recursos, debes redactar código de lenguaje de programación Java para copiarlos antes de usarlos.
  • Recursos: Si colocas tus archivos de audio en la carpeta assets/, puedes acceder a ellos directamente mediante las APIs del administrador de recursos nativo de Android. Consulta los archivos de encabezado android/asset_manager.h y android/asset_manager_jni.h para obtener más información sobre estas APIs. El ejemplo de código que se encuentra en el repositorio android-ndk de GitHub usa estas APIs del administrador de recursos nativo junto con el localizador de datos del descriptor de archivos de Android.
  • Red: Puedes usar el localizador de datos del URI para reproducir contenido de audio directamente desde la red. De todos modos, asegúrate de leer Seguridad y permisos.
  • Sistema de archivos local: El localizador de datos del URI admite el esquema file: para archivos locales, siempre y cuando la aplicación pueda acceder a los archivos. Ten en cuenta que el marco de trabajo de seguridad de Android limita el acceso a los archivos mediante los mecanismos de ID de usuario y de ID de grupo de Linux.
  • Grabado: Tu aplicación puede grabar datos de audio desde la entrada del micrófono, almacenar este contenido y luego reproducirlo más tarde. En el ejemplo de código, se usa este método para el clip de Reproducción.
  • Compilado y vinculado en línea: Puedes vincular tu contenido de audio directamente a tu biblioteca compartida y luego reproducirlo con un reproductor de audio utilizando un localizador de datos de la cola de búfer. Esto es más adecuado para clips cortos en formato PCM. En el ejemplo de código, se usa esta técnica para los clips de Hello y Android. Los datos PCM se convirtieron en cadenas hexadecimales usando una herramienta bin2c (no se proporciona).
  • Síntesis en tiempo real: Tu aplicación puede sintetizar datos PCM sobre la marcha y, luego, reproducirlos con un reproductor de audio mediante el uso de un localizador de datos de cola de búfer. Esta es una técnica relativamente avanzada y los detalles de la síntesis de audio exceden el alcance de este artículo.

Nota: Encontrar o crear contenido de audio útil para tu aplicación excede el alcance de este artículo. Puedes usar términos de búsqueda web, como audio interactivo, audio de juegos, diseño de sonido y programación de audio para obtener más información.

Precaución: Tú eres responsable de garantizar que tengas permiso legal para reproducir o grabar contenido. Es posible que existan consideraciones de privacidad para la grabación de contenido.

Muestras de código

Estas apps de ejemplo están disponibles en nuestra página de GitHub:

  • audio-echo crea un bucle completo de entrada y salida.
  • native-audio es un reproductor y una grabadora de audio simple.

La implementación de OpenSL ES en el NDK de Android difiere de la especificación de referencia para OpenSL ES 1.0.1 en diversos aspectos. Esas diferencias son un motivo importante por el cual el ejemplo de código que copias directamente desde la especificación de referencia de OpenSL ES probablemente no funcione en tu app para Android.

Para obtener más información sobre las diferencias entre la especificación de referencia y la implementación para Android, consulta OpenSL ES para Android.