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.
Funktion | Audio player | Audiorekorder | Motor | Ausgabemix |
---|---|---|---|---|
Bassverstärkung | Ja | Nein | Nein | Ja |
Pufferwarteschlange | Ja | Nein | Nein | Nein |
Datensuche für Pufferwarteschlangen | Ja: Quelle | Nein | Nein | Nein |
Verwaltung dynamischer Benutzeroberflächen | Ja | Ja | Ja | Ja |
Effekt senden | Ja | Nein | Nein | Nein |
Motor | Nein | Nein | Ja | Nein |
Umgebungshall | Nein | Nein | Nein | Ja |
Equalizer | Ja | Nein | Nein | Ja |
E/A-Gerätedatensuche | Nein | Ja: Quelle | Nein | Nein |
Metadaten extrahieren | Ja: In PCM decodieren | Nein | Nein | Nein |
Solo stummschalten | Ja | Nein | Nein | Nein |
Objekt | Ja | Ja | Ja | Ja |
Output-Mix-Suche | Ja: Senke | Nein | Nein | Nein |
Wiedergeben | Ja | Nein | Nein | Nein |
Wiedergabegeschwindigkeit | Ja | Nein | Nein | Nein |
Prefetch-Status | Ja | Nein | Nein | Nein |
Voreingestellter Hall | Nein | Nein | Nein | Ja |
Aufnehmen | Nein | Ja | Nein | Nein |
Suche | Ja | Nein | Nein | Nein |
URI-Datensuche | Ja: Quelle | Nein | Nein | Nein |
Virtualizer | Ja | Nein | Nein | Ja |
Lautstärke | Ja | Nein | Nein | Nein |
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ürslBufferQueueCallback
und der Name des FeldsSLBufferQueueState.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 bisSLchar *
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
inSLuint32
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 inpMimeType
umbenannt undSLDataLocator_URI.URI
wird inpURI
umbenannt. Wir empfehlen, die DatenstrukturenSLDataFormat_MIME
undSLDataLocator_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 FeldsamplesPerSec
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.