OpenSL ES für Android

Auf dieser Seite wird beschrieben, wie die NDK-Implementierung von OpenSL ESTM unterscheidet sich von der Referenzspezifikation für OpenSL ES 1.0.1. Wenn Sie Beispielcode aus der müssen Sie sie möglicherweise anpassen, damit sie unter Android funktioniert.

Sofern nicht anders angegeben, sind alle Funktionen ab Android 2.3 (API-Level 9) verfügbar. Einige Funktionen sind nur für Android 4.0 (API-Level 14) verfügbar. werden diese vermerkt.

Hinweis: Im Android Compatibility Definition Document (CDD) sind die Hardware und Software eines kompatiblen Android-Geräts. Weitere Informationen finden Sie unter Kompatibilität mit Android finden Sie weitere Informationen zum Kompatibilitätsprogramm. <ph type="x-smartling-placeholder"></ph> CDD für das eigentliche CDD-Dokument.

OpenSL ES bietet ein C Sprachschnittstelle, auf die auch mit C++ zugegriffen werden kann. Es bietet ähnliche Funktionen wie das dieser Android Java APIs:

• <ph type="x-smartling-placeholder"></ph> android.media.MediaPlayer
• <ph type="x-smartling-placeholder"></ph> android.media.MediaRecorder

Wie bei allen anderen Android Native Development Kits (NDK) dient OpenSL ES Android soll die Implementierung gemeinsam genutzter Bibliotheken vereinfachen, die mithilfe der nativen Java-Umgebung aufgerufen werden können. Schnittstelle (JNI . NDK ist nicht zum Schreiben reiner C/C++-Anwendungen vorgesehen. OpenSL ES ist jedoch voll funktionsfähige API nutzen. Wir gehen davon aus, dass Sie in der Lage sein sollten, ausschließlich diese API ohne Up-Aufrufe von Code, der in der Android-Laufzeit ausgeführt wird.

Hinweis: Obwohl sie auf OpenSL ES basiert, ist die API für natives Android-Audio (High Performance Audio) kein einer konformen Implementierung eines OpenSL ES 1.0.1-Profils (Spiel, Musik oder Smartphone). Das liegt daran, In Android sind nicht alle Funktionen implementiert, die für eines der Profile erforderlich sind. Alle bekannten Fälle in denen sich Android anders verhält als die Spezifikation, die in den Android-Erweiterungen.

Aus der Referenzspezifikation übernommene Features

Die Android NDK-Implementierung von OpenSL ES übernimmt einen Großteil der Funktionen der Referenzspezifikation mit bestimmten Einschränkungen.

Globale Einstiegspunkte

OpenSL ES for Android unterstützt alle globalen Einstiegspunkte in der Android-Spezifikation. Zu diesen Einstiegspunkten gehören:

• slCreateEngine
• slQueryNumSupportedEngineInterfaces
• slQuerySupportedEngineInterfaces

Objekte und Schnittstellen

Die folgende Tabelle zeigt die Objekte und Schnittstellen, mit denen die Android-NDK-Implementierung OpenSL ES wird unterstützt. Wird in der Zelle Ja angezeigt, ist die Funktion in dieser Zelle verfügbar. Implementierung.

Android NDK-Unterstützung für Objekte und Schnittstellen.

Im nächsten Abschnitt werden die Einschränkungen für einige dieser Funktionen erläutert.

Beschränkungen

Für die Funktionen in Tabelle 1 gelten bestimmte Einschränkungen. Diese Einschränkungen Unterschiede zur Referenzspezifikation darstellen. Im weiteren Verlauf dieses Abschnitts werden Informationen zu diesen Unterschieden.

Verwaltung dynamischer Benutzeroberflächen

OpenSL ES for Android unterstützt weder RemoveInterface noch ResumeInterface.

Effektkombinationen: Umgebungshall und voreingestellter Nachhall

Umgebungshall und voreingestellte Nachhall können nicht gleichzeitig auf demselben Ausgangsmix verwendet werden.

Anfragen zu den Auswirkungen werden von der Plattform möglicherweise ignoriert, wenn davon auszugehen ist, dass die Die CPU-Auslastung wäre zu hoch.

Effekt senden

SetSendLevel() unterstützt einen einzelnen Sendepegel pro Audioplayer.

Umgebungshall

Umgebungshall unterstützt reflectionsDelay nicht, reflectionsLevel- oder reverbDelay-Felder von SLEnvironmentalReverbSettings-Struktur

MIME-Datenformat

Sie können das MIME-Datenformat nur mit dem URI Data Locator und nur für Audio- Player. Sie können dieses Datenformat nicht für einen Audiorekorder verwenden.

Für die Android-Implementierung von OpenSL ES musst du mimeType initialisieren entweder auf NULL oder einen gültigen UTF-8-String. Außerdem müssen Sie containerType auf einen gültigen Wert. Sofern keine anderen Gesichtspunkte wie die Übertragbarkeit auf andere Implementierungen oder Inhaltsformaten, die eine App nicht anhand des Headers erkennen kann, empfehlen wir Ihnen, mimeType auf NULL und containerType festlegen an SL_CONTAINERTYPE_UNSPECIFIED.

OpenSL ES for Android unterstützt die folgenden Audioformate, solange das Die Android-Plattform unterstützt sie ebenfalls:

• WAV-PCM
• WAV, richtig.
• WAV ulaw.
• MP3-OBG Vorbis.
• AAC LC.
• HE-AACv1 (AAC+).
• HE-AACv2 (erweitertes AAC+).
• AMR.
• FLAC

Hinweis: Eine Liste der von Android unterstützten Audioformate findest du unter Unterstützte Medienformate.

Für die Verarbeitung dieses und anderer Formate in dieser Implementierung von OpenSL ES:

• AAC Formate müssen sich in einem MP4- oder ADTS-Container befinden.
• OpenSL ES for Android wird nicht unterstützt. MIDI:
• WMA ist nicht Teil von AOSP und wir die Kompatibilität mit OpenSL ES for Android nicht bestätigt haben.
• Die Android NDK-Implementierung von OpenSL ES unterstützt keine direkten bei der Wiedergabe von DRM oder verschlüsselten Inhalten. Um geschützte Audioinhalte wiederzugeben, müssen Sie vor dem Spielen in deiner App entschlüsseln, wobei deine App die digitale Rechteverwaltung erzwingt Einschränkungen.

Objektbezogene Methoden

OpenSL ES for Android unterstützt die folgenden Methoden zur Bearbeitung von Objekten nicht:

• Resume()
• RegisterCallback()
• AbortAsyncOperation()
• SetPriority()
• GetPriority()
• SetLossOfControlInterfaces()

PCM-Datenformat

PCM ist das einzige Datenformat, das Sie mit Pufferwarteschlangen verwenden können. Unterstützte PCM Wiedergabekonfigurationen haben folgende Eigenschaften:

• 8-Bit unsigniert oder 16-Bit-signiert.
• Mono oder Stereo.
• Little-Endian-Bytereihenfolge.
• Abtastraten von: <ph type="x-smartling-placeholder">
  </ph>
  • 8.000 Hz
  • 11.025 Hz
  • 12.000 Hz
  • 16.000 Hz
  • 22.050 Hz
  • 24.000 Hz
  • 32.000 Hz
  • 44.100 Hz
  • 48.000 Hz

OpenSL ES for Android unterstützt folgende Konfigurationen für Aufzeichnungen: geräteabhängig. Normalerweise ist 16.000-Hz-Mono-/16-Bit-Verfahren unabhängig vom Gerät verfügbar.

Der Wert des Feldes samplesPerSec wird trotz der irreführenden Namen. Damit nicht versehentlich der falsche Wert verwendet wird, sollte das Feld mit eine der symbolischen Konstanten, die für diesen Zweck definiert sind, z. B. SL_SAMPLINGRATE_44_1

Unterstützung für Android 5.0 (API-Level 21) und höher Gleitkommadaten.

Wiedergabegeschwindigkeit

Die OpenSL ES-Wiedergaberate gibt die Geschwindigkeit an, -Objekt stellt Daten im Tausendstel normaler Geschwindigkeit oder pro 1.000 dar. Beispiel: ist eine Wiedergaberate von 1.000 pro 1.000 1.000/1.000, also normal. Ein Ratenbereich ist ein geschlossenes Intervall, das einen Bereich möglicher Wiedergaberaten ausdrückt.

Die Unterstützung für Bereiche für Wiedergabegeschwindigkeiten und andere Funktionen kann je nach zur Plattformversion und zur Implementierung. Ihre App kann diese Funktionen zur Laufzeit bestimmen, indem sie mit PlaybackRate::GetRateRange() oder PlaybackRate::GetCapabilitiesOfRate(), um das Gerät abzufragen.

Ein Gerät unterstützt in der Regel denselben Ratenbereich für eine Datenquelle im PCM-Format und eine Einheitsrate. zwischen 1.000 pro 1.000 bis 1.000 pro 1.000 pro 1.000 pro 1.000 Videos bei anderen Formaten. d. h., der Bereich der Einheit eigentlich einen einzelnen Wert.

Aufnehmen

OpenSL ES for Android unterstützt den SL_RECORDEVENT_HEADATLIMIT nicht. oder SL_RECORDEVENT_HEADMOVING-Ereignisse.

Suche

Die Methode SetLoop() aktiviert Schleifen für die gesamte Datei. Um Schleifen zu aktivieren, Setzen Sie den Parameter startPos auf 0 und den Parameter endPos an SL_TIME_UNKNOWN.

Datensuche für Pufferwarteschlangen

Audioplayer oder ‐rekorder mit einem Data Locator für eine Zwischenspeicherwarteschlange unterstützen nur das PCM-Datenformat.

E/A-Gerätedatensuche

OpenSL ES for Android unterstützt die Verwendung eines I/O Device Data Locator nur, wenn Sie hat die Standortsuche als Datenquelle für Engine::CreateAudioRecorder() angegeben. Initialisieren Sie die Gerätesuche mit den Werten im folgenden Code-Snippet:

SLDataLocator_IODevice loc_dev =
  {SL_DATALOCATOR_IODEVICE, SL_IODEVICE_AUDIOINPUT,
  SL_DEFAULTDEVICEID_AUDIOINPUT, NULL};

URI-Datensuche

OpenSL ES for Android kann URI Data Locator nur mit dem MIME-Datenformat verwenden. und nur für einen Audioplayer. Sie können für einen Audiorekorder keinen URI-Datenfinder verwenden. Der URI kann nur die Schemas http: und file: verwenden. Andere Schemas, z. B. https:, ftp: oder content: sind nicht zulässig.

Wir haben die Unterstützung für rtsp: mit Audio auf der Android-Plattform nicht bestätigt.

Datenstrukturen

Android unterstützt die folgenden OpenSL ES 1.0.1-Datenstrukturen:

• SLDataFormat_MIME
• SLDataFormat_PCM
• SLDataLocator_BufferQueue
• SLDataLocator_IODevice
• SLDataLocator_OutputMix
• SLDataLocator_URI
• SLDataSink
• SLDataSource
• SLEngineOption
• SLEnvironmentalReverbSettings
• SLInterfaceID

Plattformkonfiguration

OpenSL ES for Android wurde für Multi-Threaded-Anwendungen entwickelt und ist threadsicher. Es unterstützt eine eine Engine pro Anwendung und bis zu 32 Objekte pro Engine. Verfügbarer Gerätespeicher und verfügbare CPU die verwendbare Anzahl von Objekten weiter einschränken.

Diese Engine-Optionen werden erkannt, aber von slCreateEngine ignoriert:

• SL_ENGINEOPTION_THREADSAFE
• SL_ENGINEOPTION_LOSSOFCONTROL

OpenMAX AL und OpenSL ES können zusammen in derselben Anwendung verwendet werden. In diesem Fall gibt es intern ein einzelnes, gemeinsam genutztes Engine-Objekt und die Beschränkung auf 32 Objekte wird von OpenMAX AL gemeinsam genutzt. und OpenSL ES. Die Anwendung sollte beide Engines erstellen, beide nutzen und schließlich beide Triebwerke zu zerstören. Die Implementierung behält eine Referenzanzahl auf der gemeinsam genutzten Engine bei, sodass wird es beim zweiten Löschen richtig zerstört.

Programmierhinweise

OpenSL ES-Programmierhinweise enthält ergänzende Informationen für die ordnungsgemäße Implementierung von OpenSL ES.

Hinweis: Wir haben eine Kopie der Spezifikation für OpenSL ES 1.0.1 mit dem NDK beigefügt. docs/opensles/OpenSL_ES_Specification_1.0.1.pdf

Plattformprobleme

In diesem Abschnitt werden bekannte Probleme im ersten Plattformrelease beschrieben, der diese APIs unterstützt.

Verwaltung dynamischer Benutzeroberflächen

DynamicInterfaceManagement::AddInterface funktioniert nicht. Geben Sie die Schnittstelle stattdessen in Das Array, das an Create() übergeben wird, wie im Beispielcode für Umgebungshall gezeigt.

Zukünftige Versionen von OpenSL ES planen

Die Hochleistungs-Audio-APIs von Android basieren auf Khronos Group OpenSL ES 1.0.1. Khronos hat eine überarbeitete Version 1.1 des Standards veröffentlicht. Die überarbeitete Version enthält neue Funktionen, Klarstellungen, Korrekturen typografischer Fehler und einige Inkompatibilitäten. Die meisten der zu erwartenden Inkompatibilitäten sind relativ gering oder befinden sich in von OpenSL ES, die von Android nicht unterstützt werden.

Eine Anwendung die mit dieser Version entwickelt wurden, sollten auf zukünftigen Versionen der Android-Plattform funktionieren, sofern müssen Sie die Richtlinien befolgen, die im Plan für Binärcode Kompatibilität unten.

Hinweis: Künftige Kompatibilität der Quellen ist kein Ziel. Wenn Sie also ein Upgrade auf eine neuere Version des NDK ausführen, Möglicherweise müssen Sie den Quellcode Ihrer Anwendung ändern, damit er dem neuen API entspricht. Wir erwarten, dass die meisten sind solche Änderungen geringfügig. siehe Details unten.

Binärkompatibilität planen

Wir empfehlen, für Ihre Anwendung die folgenden Richtlinien zu befolgen, um die zukünftige Kompatibilität mit Binärprogrammen zu verbessern:

• Verwende nur die dokumentierte Teilmenge der von Android unterstützten Funktionen aus OpenSL ES 1.0.1.
• Verlassen Sie sich bei einem fehlgeschlagenen Vorgang nicht auf einen bestimmten Ergebniscode. darauf vorbereitet sein, mit einem anderen Ergebniscode.
• Callback-Handler von Anwendungen werden im Allgemeinen in einem eingeschränkten Kontext ausgeführt. Sie sollten so formuliert sein, um ihre Arbeit schnell zu erledigen, und kehren so schnell wie möglich zurück. Keine komplexen Vorgänge ausführen in einem Callback-Handler. Innerhalb eines Callbacks für den Abschluss der Pufferwarteschlange können Sie einen weiteren Zwischenspeicher in die Warteschlange stellen, aber keinen Audioplayer erstellen.
• Callback-Handler sollten so vorbereitet sein, dass sie häufiger oder seltener aufgerufen werden, um zusätzliche Ereignistypen und sollten Ereignistypen ignorieren, die sie nicht erkennen. Callbacks, die mit einer Ereignismaske konfiguriert sind, die aus aktivierten Ereignistypen besteht, sollten für den Aufruf vorbereitet werden. mit mehreren gleichzeitig festgelegten Ereignistyp-Bits. „&“ verwenden für jedes Ereignis-Bit testen möchten, ein Switch-Case.
• Verwenden Sie den Prefetch-Status und Callbacks als allgemeine Hinweise auf den Fortschritt. Sie sind jedoch nicht von bestimmte hartcodierte Füllstufen oder Callback-Sequenzen. Bedeutung der Prefetch-Statusfüllung und das Verhalten für Fehler, die während des Prefetches erkannt werden, sich ändern.

Hinweis : Weitere Informationen finden Sie in der Verhalten der Pufferwarteschlange unten finden Sie weitere Informationen.

Für Quellenkompatibilität planen

Wie bereits erwähnt, sind in der nächsten Version von OpenSL ES Khronos Group. Zu den wahrscheinlichen Änderungsbereichen gehören:

• Es sind wesentliche Änderungen an der Oberfläche der Pufferwarteschlange zu erwarten, insbesondere in den Bereichen BufferQueue::Enqueue, der Parameterliste für slBufferQueueCallback und der Name des Felds SLBufferQueueState.playIndex. Wir empfehlen, dass Sie in Ihrem Anwendungscode Stattdessen können Sie einfache Android-Zwischenspeicherwarteschlangen verwenden. Im Beispiel mit dem NDK bereitgestellt, haben wir einfache Android-Pufferwarteschlangen für die Wiedergabe aus diesem Grund. Wir verwenden auch eine einfache Android-Zwischenspeicherwarteschlange für die Aufzeichnung und Decodierung in PCM, liegt daran, dass das Standard-OpenSL ES 1.0.1 das Aufzeichnen oder Decodieren von Daten in einer Pufferwarteschlange nicht unterstützt. Senke.)
• Den durch einen Verweis übergebenen Eingabeparametern wird const hinzugefügt und bis SLchar * Strukturfelder, die als Eingabewerte verwendet werden. Dies sollte keine Änderungen an der Ihren Code.
• Für einige derzeit signierte Parameter werden nicht signierte Typen ersetzt. Möglicherweise müssen Sie einen Parametertyp von SLint32 in SLuint32 oder ähnlich ändern. eine Besetzung hinzufügen.
• Equalizer::GetPresetName kopiert den String in den Anwendungsspeicher, anstatt ihn zurückzugeben einen Zeiger zum Implementierungsspeicher. Da dies eine wesentliche Änderung ist, empfehlen wir Ihnen, Sie sollten diese Methode entweder nicht aufrufen oder sie isolieren.
• Die Strukturtypen enthalten zusätzliche Felder. Für Ausgabeparameter werden diese neuen Felder kann ignoriert werden, aber für Eingabeparameter müssen die neuen Felder initialisiert werden. Glücklicherweise Alle diese Felder müssen sich in Bereichen befinden, die von Android nicht unterstützt werden.
• Schnittstelle GUIDs ändert sich. Verweisen Sie auf Schnittstellen mit symbolischen Namen statt GUID, um zu vermeiden, Abhängigkeit.
• „SLchar“ wird von „unsigned char“ zu „char“ geändert. Dies betrifft vor allem URI Data Locator und MIME-Datenformat.
• SLDataFormat_MIME.mimeType wird in pMimeType umbenannt und SLDataLocator_URI.URI wird in pURI umbenannt. Wir empfehlen, die Datenstrukturen SLDataFormat_MIME und SLDataLocator_URI mithilfe einer in Klammern gesetzte, durch Kommas getrennte Liste von Werten anstelle nach Feldname, um Ihren Code zu isolieren von dieser Änderung erhalten. Diese Technik wird im Beispielcode verwendet.
• SL_DATAFORMAT_PCM lässt nicht zu, dass die Anwendung die Darstellung von die Daten als signierte Ganzzahl, vorzeichenlose Ganzzahl oder als Gleitkommazahl. Android-Implementierung geht davon aus, dass 8-Bit-Daten eine vorzeichenlose Ganzzahl und 16-Bit eine vorzeichenbehaftete Ganzzahl. Darüber hinaus ist das Feld samplesPerSec ist falsch, da die tatsächlichen Einheiten in MilliHz angegeben werden. Diese Probleme sind zu erwarten die in der nächsten OpenSL ES-Version behandelt werden, -Format, das es der Anwendung ermöglicht, die Darstellung explizit anzugeben und den Feldname. Da dies ein neues Datenformat wird und das aktuelle PCM-Datenformat weiterhin verfügbar (obwohl veraltet), sollte Ihr Code nicht sofort geändert werden.