Premiers pas

Cette section fournit les informations nécessaires pour commencer à utiliser les API OpenSL ES.

Ajouter OpenSL ES à votre application

Vous pouvez appeler OpenSL ES à partir du code C et C++. Pour ajouter l'ensemble de fonctionnalités OpenSL ES de base à votre application, incluez le fichier d'en-tête OpenSLES.h : 

#include <SLES/OpenSLES.h>

Pour ajouter également les extensions Android OpenSL ES, incluez le fichier d'en-tête OpenSLES_Android.h : 

#include <SLES/OpenSLES_Android.h>

Lorsque vous incluez le fichier d'en-tête OpenSLES_Android.h, les en-têtes suivants sont inclus automatiquement : 

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

Remarque : Ces en-têtes ne sont pas obligatoires, mais sont indiqués ici pour vous aider à vous familiariser avec l'API.

Compiler et déboguer

Vous pouvez intégrer OpenSL ES dans votre build en le spécifiant dans le fichier Android.mk qui fait partie des fichiers makefile du système de compilation NDK. Ajoutez la ligne suivante au fichier Android.mk : 

LOCAL_LDLIBS += -lOpenSLES

Pour un débogage robuste, nous vous recommandons d'examiner la valeur SLresult renvoyée par la plupart des API OpenSL ES. Vous pouvez utiliser des assertions ou une logique de gestion des exceptions plus avancée pour le débogage. Aucune de ces deux méthodes ne présente un avantage inhérent favorisant son utilisation avec OpenSL ES, mais l'une ou l'autre peut s'avérer préférable selon le cas d'utilisation.

Nous utilisons des assertions dans nos exemples, car elles permettent de détecter des conditions irréalistes indiquant une erreur de codage. Nous avons utilisé la gestion explicite des exceptions pour les autres conditions plus susceptibles de se produire en production.

De nombreuses erreurs d'API génèrent une entrée de journal, en plus d'un code de résultat différent de zéro. Ces entrées de journal peuvent fournir des détails supplémentaires qui se révèlent particulièrement utiles pour des API relativement complexes comme Engine::CreateAudioPlayer.

Vous pouvez consulter le journal à partir de la ligne de commande ou d'Android Studio. Pour examiner le journal à partir de la ligne de commande, saisissez la commande suivante : 

$ adb logcat

Pour examiner le journal dans Android Studio, sélectionnez View > Tool Windows > Logcat (Afficher > Fenêtres d'outils > Logcat). Pour en savoir plus, consultez Écrire et afficher des journaux avec Logcat.

Exemple de code

Nous vous recommandons d'utiliser un exemple de code compatible et testé comme modèle pour votre propre code. Vous trouverez de tels exemples dans les dossiers audio-echo et native-audio du dépôt GitHub android-ndk.

Attention : La spécification OpenSL ES 1.0.1 contient des exemples de code en annexe (pour en savoir plus, consultez la page Khronos OpenSL ES Registry). Toutefois, les exemples présentés dans Appendix B: Sample Code et Appendix C: Use Case Sample Code utilisent des fonctionnalités incompatibles avec Android. Certains exemples contiennent également des erreurs typographiques ou utilisent des API susceptibles de changer. Faites preuve de prudence lorsque vous vous y référez. Bien que le code puisse être utile pour comprendre la norme OpenSL ES dans son intégralité, il ne doit pas être utilisé tel quel avec Android.

Contenu audio

Voici quelques-unes des nombreuses méthodes permettant de packager du contenu audio pour votre application :

  • Ressources : si vous placez vos fichiers audio dans le dossier res/raw/, ils sont facilement accessibles aux API associées pour Resources. Cependant, il n'existe pas d'accès natif direct aux ressources. Vous devez donc écrire du code dans le langage de programmation Java pour les copier avant de les utiliser.
  • Éléments : si vous placez vos fichiers audio dans le dossier assets/, ils sont directement accessibles aux API natives de gestion d'éléments Android. Pour en savoir plus sur ces API, consultez les fichiers d'en-tête android/asset_manager.h et android/asset_manager_jni.h. L'exemple de code situé dans le dépôt GitHub android-ndk utilise ces API natives de gestion d'éléments en association avec le localisateur de données de descripteur de fichier Android.
  • Réseau : vous pouvez utiliser le localisateur de données d'URI pour lire du contenu audio directement à partir du réseau. Veillez toutefois à lire la section Sécurité et autorisations.
  • Système de fichiers local : le localisateur de données d'URI accepte le schéma file: pour les fichiers locaux, à condition qu'ils soient accessibles à l'application. Notez que le framework de sécurité Android limite l'accès aux fichiers via les mécanismes d'ID d'utilisateur et d'ID de groupe Linux.
  • Enregistrement : votre application peut enregistrer des données audio à partir de l'entrée du micro, stocker ce contenu et le lire par la suite. L'exemple de code utilise cette méthode pour l'extrait Playback.
  • Compilation et association intégrée : vous pouvez associer votre contenu audio directement à la bibliothèque partagée, puis le lire à l'aide d'un lecteur audio doté d'un localisateur de données de file d'attente de tampon. Cette option est particulièrement adaptée aux extraits courts au format PCM. L'exemple de code utilise cette technique pour les extraits Hello et Android. Les données PCM ont été converties en chaînes hexadécimales à l'aide d'un outil bin2c (non fourni).
  • Synthèse en temps réel : votre application peut synthétiser des données PCM à la volée, puis les lire à l'aide d'un lecteur audio doté d'un localisateur de données de file d'attente de tampon. Cette technique est relativement avancée et les spécificités de la synthèse audio dépassent le cadre de cet article.

Remarque : La recherche ou la création de contenu audio utile pour votre application dépassent le cadre de cet article. Pour en savoir plus, vous pouvez utiliser des termes de recherche sur le Web, tels que audio interactif, audio de jeu, conception audio et programmation audio.

Attention : Il vous incombe de vous assurer que vous êtes légalement autorisé à lire ou à enregistrer du contenu. L'enregistrement de contenu peut être soumis à des impératifs de confidentialité.

Exemples de code

Ces applications exemples sont disponibles sur notre page GitHub :

  • audio-echo crée une boucle aller-retour reliant l'entrée et la sortie.
  • native-audio est un simple lecteur/enregistreur audio.

L'implémentation Android NDK d'OpenSL ES diffère de la spécification de référence OpenSL ES 1.0.1 à plusieurs égards. En raison de ces différences, il est possible que l'exemple de code que vous copiez directement à partir de la spécification de référence OpenSL ES ne fonctionne pas dans votre application Android.

Pour en savoir plus sur les différences entre la spécification de référence et l'implémentation Android, consultez OpenSL ES pour Android.