Per iniziare

AVVISO: OpenSL ES è deprecato. Gli sviluppatori devono utilizzare la libreria Oboe open source disponibile su GitHub. Oboe è un wrapper C++ che fornisce un'API molto simile ad AAudio. Oboe chiama AAudio se AAudio è disponibile e passa a OpenSL ES se AAudio non è disponibile.

Questa sezione fornisce le informazioni necessarie per iniziare a utilizzare le API OpenSL ES.

Aggiungi OpenSL ES alla tua app

Puoi chiamare OpenSL ES sia dal codice C che dal codice C++. Per aggiungere il set di funzionalità di base di OpenSL ES alla tua app, includi il file di intestazione OpenSLES.h: 

#include <SLES/OpenSLES.h>

Per aggiungere anche le estensioni Android di OpenSL ES, includi il file di intestazione OpenSLES_Android.h: 

#include <SLES/OpenSLES_Android.h>

Quando includi il file di intestazione OpenSLES_Android.h, vengono incluse automaticamente le seguenti intestazioni: 

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

Nota: queste intestazioni non sono obbligatorie, ma vengono mostrate come ausilio per l'apprendimento dell'API.

Creazione e debug

Puoi incorporare OpenSL ES nella tua build specificandolo nel file Android.mk che funge da makefile del sistema di compilazione NDK. Aggiungi la seguente riga a Android.mk: 

LOCAL_LDLIBS += -lOpenSLES

Per un debug efficace, ti consigliamo di esaminare il valore SLresult restituito dalla maggior parte delle API OpenSL ES. Per il debug puoi utilizzare assert o una logica di gestione degli errori più avanzata. Nessuna delle due offre un vantaggio intrinseco per l'utilizzo di OpenSL ES, anche se una o l'altra potrebbe essere più adatta per un determinato caso d'uso.

Utilizziamo le verifiche nei nostri esempi perché ci aiutano a rilevare condizioni non realistiche che potrebbero indicare un errore di programmazione. Abbiamo utilizzato la gestione degli errori esplicita per altre condizioni più probabili in produzione.

Molti errori dell'API generano una voce di log, oltre a un codice di risultato diverso da zero. Queste voci del log possono fornire dettagli aggiuntivi che si rivelano particolarmente utili per API relativamente complesse come Engine::CreateAudioPlayer.

Puoi visualizzare il log dalla riga di comando o da Android Studio. Per esaminare il log dalla riga di comando, digita quanto segue: 

$ adb logcat

Per esaminare il log da Android Studio, seleziona Visualizza > Finestre degli strumenti > Logcat. Per ulteriori informazioni, consulta la sezione Scrivere e visualizzare i log con Logcat.

Codice di esempio

Ti consigliamo di utilizzare codice di esempio supportato e testato, utilizzabile come modello per il tuo codice, che si trova nelle cartelle audio-echo e native-audio del repository GitHub android-ndk.

Attenzione: la specifica OpenSL ES 1.0.1 contiene codice di esempio nelle appendici (consulta Khronos OpenSL ES Registry per ulteriori dettagli). Tuttavia, gli esempi nell'Appendice B: codice di esempio e nell'Appendice C: codice di esempio per casi d'uso utilizzano funzionalità non supportate da Android. Alcuni esempi contengono anche errori ortografici o utilizzano API che potrebbero cambiare. Procedi con cautela quando fai riferimento a questi documenti. Sebbene il codice possa essere utile per comprendere lo standard OpenSL ES completo, non deve essere utilizzato così com'è con Android.

Contenuti audio

Di seguito sono riportati alcuni dei molti modi per pacchettizzare i contenuti audio per la tua applicazione:

  • Risorse: se inserisci i file audio nella cartella res/raw/, le API associate per Resources possono accedervi facilmente. Tuttavia, non esiste un accesso nativo diretto alle risorse, quindi devi scrivere il codice del linguaggio di programmazione Java per copiarle prima dell'uso.
  • Asset: se inserisci i file audio nella cartella assets/, i file audio saranno accessibili direttamente dalle API native Asset Manager di Android. Per ulteriori informazioni su queste API, consulta i file di intestazione android/asset_manager.h e android/asset_manager_jni.h. Il codice di esempio situato nel repository GitHub di android-ndk utilizza queste API native di gestione degli asset insieme al localizzatore dei dati del descrittore di file Android.
  • Rete: puoi utilizzare il locator dei dati URI per riprodurre i contenuti audio direttamente dalla rete. Assicurati però di leggere la pagina Sicurezza e autorizzazioni.
  • File system locale: il locator dati URI supporta lo schema file: per i file locali, a condizione che siano accessibili dall'applicazione. Tieni presente che il framework di sicurezza di Android limita l'accesso ai file tramite i meccanismi Linux User-ID e ID gruppo.
  • Registrato: l'applicazione può registrare i dati audio dall'ingresso del microfono, memorizzare questi contenuti e riprodurli in un secondo momento. Il codice di esempio utilizza questo metodo per il clip Riproduzione.
  • Compilato e collegato in linea: puoi collegare i contenuti audio direttamente alla biblioteca condivisa, quindi riprodurli utilizzando un audio player con un locator dei dati della coda del buffer. È più adatto per brevi clip in formato PCM. Il codice di esempio utilizza questa tecnica per i clip Ciao e Android. I dati PCM sono stati convertiti in stringhe esadecimali utilizzando uno strumento bin2c (non fornito).
  • Sintesi in tempo reale: l'applicazione può sintetizzare i dati PCM in tempo reale e poi riprodurli utilizzando un player audio con locator dei dati della coda del buffer. Si tratta di una tecnica relativamente avanzata e i dettagli della sintesi audio vanno oltre l'ambito di questo articolo.

Nota: trovare o creare contenuti audio utili per la tua applicazione esula dall'ambito di questo articolo. Per trovare ulteriori informazioni, puoi utilizzare termini di ricerca web come audio interattivo, audio per giochi, sound design e programmazione audio.

Attenzione: è tua responsabilità assicurarti di avere l'autorizzazione legale per riprodurre o registrare i contenuti. Potrebbero esserci considerazioni sulla privacy per la registrazione dei contenuti.

Esempi di codice

Queste app di esempio sono disponibili nella nostra pagina GitHub:

  • audio-echo crea un loop di andata e ritorno da input a output.
  • native-audio è un semplice registratore/lettore audio.

L'implementazione Android NDK di OpenSL ES differisce da diversi aspetti dalle specifiche di riferimento per OpenSL ES 1.0.1. Queste differenze sono un motivo importante per cui il codice di esempio che copi direttamente dalla specifica di riferimento OpenSL ES potrebbe non funzionare nella tua app per Android.

Per ulteriori informazioni sulle differenze tra la specifica di riferimento e l'implementazione di Android, consulta OpenSL ES per Android.