Primeros pasos

En esta sección, se proporciona la información necesaria para comenzar a usar las API 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 principal de funciones 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>

Al incluir 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.

Compilación y depuración

Puedes incorporar OpenSL ES a tu compilación especificándolo 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 manejo de errores más avanzada. Ninguna ofrece una ventaja inherente para trabajar con OpenSL ES, aunque una o la otra podrían ser más adecuadas para un caso de uso determinado.

Usamos aserciones en nuestros ejemplos porque nos ayudan a detectar condiciones poco comunes que podrían indicar un error de codificación. Ya usamos el manejo de errores explícito 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 ciertas 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 examinarlo desde Android Studio, selecciona View > Tool Windows > Logcat. Para obtener más información, consulta Escribir y ver registros con Logcat.

Ejemplo de código

Te recomendamos usar un ejemplo de código admitido y probado que sirva como modelo para tu propio código; puedes encontrarlo en las carpetas audio-echo y native-audio del repositorio android-ndk de GitHub.

Advertencia: La especificación OpenSL ES 1.0.1 contiene un ejemplo de código en los apéndices (consulta Registro OpenSL ES de Khronos para obtener más información). No obstante, en los ejemplos del “Apéndice B: Ejemplo de código ” y el “Apéndice C: Usa ejemplo de código para el caso” se emplean funciones que Android no admite. Algunos ejemplos también contienen errores tipográficos o usan API propensas a sufrir modificaciones. Cuando hagas referencia a estos códigos, hazlo con precaución; si bien el código puede ser útil para comprender la norma OpenSL ES completa, 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: Al disponer tus archivos de audio en la carpeta res/raw/, las API asociadas pueden acceder a ellos fácilmente para obtener Resources. No obstante, no hay acceso directo nativo a los recursos, por lo que debes redactar código de lenguaje de programación Java para copiarlos antes de usarlos.
  • Activos: Al disponer tus archivos de audio en la carpeta assets/, las API del administrador de activos nativo de Android pueden acceder a ellos directamente. Consulta los archivos de encabezado android/asset_manager.h y android/asset_manager_jni.h para obtener más información sobre estas API. El ejemplo de código que se encuentra en el repositorio android-ndk de GitHub usa estas API del administrador de activos nativo junto con el localizador de datos del descriptor de archivos de Android.
  • Red: Puedes usar el localizador de datos de URI para reproducir contenido de audio directamente desde la red. De todos modos, asegúrate de leer Seguridad y permisos.
  • Sistema de archivos locales: El localizador de datos de URI admite el esquema file: para archivos locales, siempre que la aplicación pueda acceder a los archivos. Ten en cuenta que el framework de seguridad de Android limita el acceso a los archivos mediante los mecanismos de ID de usuario e ID de grupo de Linux.
  • Grabación: Tu aplicación puede grabar datos de audio desde una entrada de micrófono, almacenar este contenido y reproducirlo más adelante. En el ejemplo de código, se usa este método para el clip de Reproducción.
  • Compilación y vinculación en línea: Puedes vincular tu contenido de audio directamente en la biblioteca compartida y luego reproducirlo usando un reproductor de audio con 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 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 al instante y luego reproducirlos en un reproductor de audio con localizador de datos de la 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: La búsqueda o la creación de 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 para juegos, diseño de sonido y programación de audio, para obtener más información.

Advertencia: Es tu responsabilidad asegurarte de contar con los permisos legales para reproducir o grabar contenido. Es posible que existan consideraciones de privacidad para la grabación de contenido.

Ejemplos de código

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

  • audio-echo crea un bucle de ida y vuelta de entrada y salida.
  • native-audio es un reproductor y una grabadora de audio simple.
  • SimpleSynth reproduce una onda sinusoidal. Muestra cómo obtener una latencia de audio óptima y una capacidad de procesamiento computacional estable.

La implementación de OpenSL ES en Android NDK 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.