Du kannst eine VolumeShaper in einer Audio-App verwenden, um Einblendungen, Ausblendungen, Überblendungen, Ducking und andere kurze automatisierte Lautstärkeübergänge auszuführen. Die Klasse VolumeShaper ist ab Android 8.0 (API-Level 26) verfügbar.
Sie erstellen ein VolumeShaper, indem Sie createVolumeShaper() für eine Instanz von AudioTrack oder MediaPlayer aufrufen. Der VolumeShaper wirkt sich nur auf die Audioausgabe des AudioTrack- oder MediaPlayer-Objekts aus, von dem er erstellt wurde.
VolumeShaper.Configuration
Das Verhalten eines VolumeShaper wird durch seine VolumeShaper.Configuration definiert. In der Konfiguration werden eine *Lautstärkekurve, ein Interpolatortyp und eine Dauer* angegeben.
Lautstärkekurve
Die Lautstärkekurve stellt die Amplitudenänderung im Zeitverlauf dar. Sie wird durch ein Paar von Float-Arrays, x[] und y[], definiert, die eine Reihe von Kontrollpunkten definieren. Jedes (x, y)-Paar steht für die Zeit bzw. das Volumen. Die Arrays müssen gleich lang sein und mindestens 2 und maximal 16 Werte enthalten. (Die maximale Kurvenlänge ist in getMaximumCurvePoints() definiert.)
Die Zeitkoordinaten werden im Intervall [0,0, 1,0] angegeben. Der erste Zeitpunkt muss 0,0 sein, der letzte 1,0 und die Zeitpunkte müssen monoton ansteigen.
Die Lautstärkekoordinaten werden auf einer linearen Skala im Intervall [0,0, 1,0] angegeben.
Interpolator-Typ
Die Lautstärkekurve verläuft immer durch die angegebenen Kontrollpunkte. Werte zwischen den Kontrollpunkten werden durch einen Spline gemäß dem Interpolatortyp der Konfiguration abgeleitet. Es gibt vier Konstanten für die verfügbaren VolumeShaper-Interpolatortypen:
- VolumeShaper.Configuration.INTERPOLATOR_TYPE_STEP
- VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR
- VolumeShaper.Configuration.INTERPOLATOR_TYPE_CUBIC
- VolumeShaper.Configuration.INTERPOLATOR_TYPE_CUBIC_MONOTONIC
Dauer
Die angegebenen Zeitkoordinaten im Intervall [0,0, 1,0] werden auf eine Dauer skaliert, die Sie in Millisekunden angeben. Dies bestimmt die tatsächliche Länge der Lautstärkekurve, wenn der Shaper ausgeführt wird und die Kurve auf die Audioausgabe anwendet.
VolumeShaper verwenden
Konfiguration erstellen
Bevor Sie ein VolumeShaper erstellen, müssen Sie eine Instanz von VolumeShaper.Configuration erstellen. Verwenden Sie dazu einen VolumeShaper.Configuration.Builder():
val config: VolumeShaper.Configuration = VolumeShaper.Configuration.Builder() .setDuration(3000) .setCurve(floatArrayOf(0f, 1f), floatArrayOf(0f, 1f)) .setInterpolatorType(VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR) .build()
Ohne Argumente gibt der VolumeShaper.Configuration.Builder-Konstruktor einen Builder zurück, der eine Konfiguration mit Standardeinstellungen erstellt: INTERPOLATOR_TYPE_CUBIC, eine Dauer von einer Sekunde und keine Kurve. Sie müssen dem Builder eine Kurve hinzufügen, bevor Sie build() aufrufen.
Das Framework bietet Konstanten für Konfigurationen mit vordefinierten Kurven, die jeweils eine Sekunde dauern:
VolumeShaper.Configuration.LINEAR_RAMPVolumeShaper.Configuration.CUBIC_RAMPVolumeShaper.Configuration.SINE_RAMPVolumeShaper.Configuration.SCURVE_RAMP
VolumeShaper erstellen
Wenn Sie ein VolumeShaper erstellen möchten, rufen Sie createVolumeShaper() für eine Instanz der entsprechenden Klasse auf und übergeben Sie ein VolumeShaper.Configuration:
volumeShaper = myMediaPlayer.createVolumeShaper(config) volumeShaper = myAudioTrack.createVolumeShaper(config)
An einen einzelnen Track oder Mediaplayer können viele Shaper angehängt werden, die sich jeweils separat steuern lassen. Die Ausgaben aller Shaper auf einem Track oder Player werden miteinander multipliziert. Ein VolumeShaper kann nicht zwischen AudioTracks oder MediaPlayers geteilt werden. Sie können jedoch dieselbe Konfiguration in Aufrufen an createVolumeShaper verwenden, um identische Shaper auf mehreren AudioTracks oder MediaPlayers zu erstellen.
Wenn Sie den Shaper erstellen, wird der erste Kontrollpunkt (bei t = 0) auf den Audiostream angewendet. Wenn die Anfangslautstärke nicht 1,0 ist und deine App zum Zeitpunkt der Erstellung Inhalte abspielt, kann es zu einer abrupten Änderung der Lautstärke kommen. Best Practice ist es, die Audiowiedergabe mit Stille zu beginnen und mit einem VolumeShaper eine Einblendung zu implementieren, wenn die Wiedergabe beginnt. Erstellen Sie einen VolumeShaper, der bei Lautstärke 0 beginnt und dann lauter wird. Beispiel:
setCurve(new float[] {0.f, 1.f}, new float[] {0.f, 1.f})
Starte die Wiedergabe und den Shaper gleichzeitig. So wird die Wiedergabe ohne Ton gestartet und die Lautstärke wird langsam erhöht. Dies wird im nächsten Abschnitt erläutert.
VolumeShaper ausführen
Obwohl die Lautstärke des ersten Kontrollpunkts auf den Audiopfad angewendet wird, sobald der Shaper erstellt wurde, bewegt sich der Shaper erst dann entlang der Kurve, wenn Sie die Methode apply() mit VolumeShaper.Operation.PLAY aufrufen. Nach dem Erstellen des Shapers muss beim ersten Aufruf von apply() der Vorgang PLAY angegeben werden, um den Shaper zu starten. Dadurch wird die Kurve vom ersten bis zum letzten Kontrollpunkt durchlaufen:
shaper.apply(VolumeShaper.Operation.PLAY)
Während der Shaper ausgeführt wird, können Sie abwechselnd apply()-Aufrufe mit den Vorgängen REVERSE und PLAY ausgeben. Dadurch wird die Richtung, in der die Kontrollpunkte ausgelesen werden, jedes Mal geändert.
Der Shaper passt die Lautstärke kontinuierlich an und durchläuft alle Kontrollpunkte, bis er abläuft. Dies geschieht, wenn der Shaper den letzten (für den PLAY-Vorgang) oder ersten (für den REVERSE-Vorgang) Kontrollpunkt in der Kurve erreicht.
Wenn der Shaper abläuft, bleibt die Lautstärke auf der letzten Einstellung, die der erste oder der letzte Steuerpunkt sein kann. Sie können jederzeit VolumeShaper.getVolume() aufrufen, um die aktuelle Lautstärke abzurufen.
Nach Ablauf des Shapers können Sie einen weiteren apply()-Aufruf ausführen, um die Kurve in die entgegengesetzte Richtung zu durchlaufen. Wenn der Shaper beispielsweise während der Ausführung von PLAY abgelaufen ist, muss der nächste apply() REVERSE sein. Der Aufruf von PLAY nach Ablauf von PLAY oder von REVERSE nach Ablauf von REVERSE hat keine Auswirkungen.
Sie müssen die Vorgänge PLAY und REVERSE abwechselnd ausführen. Es ist nicht möglich, eine Kurve vom ersten bis zum letzten Steuerpunkt abzuspielen und dann wieder vom ersten Steuerpunkt aus zu starten. Mit der im nächsten Abschnitt beschriebenen Methode replace() können Sie die Kurve durch eine Kopie von sich selbst ersetzen. Dadurch wird der Shaper zurückgesetzt und muss mit dem Vorgang PLAY neu gestartet werden.
Kurve ändern
Mit der Methode replace() können Sie die Kurve eines VolumeShaper-Objekts ändern. Diese Methode verwendet eine Konfiguration, einen Vorgang und einen Join-Parameter. Sie können die Methode replace() jederzeit aufrufen, während der Shaper ausgeführt wird oder nachdem er abgelaufen ist:
val newConfig = VolumeShaper.Configuration.Builder() .setDuration(1000) .setCurve(floatArrayOf(0f, 0.5f), floatArrayOf(0f, 1f)) .setInterpolatorType(VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR) .build() val join = true shaper.replace(newConfig, VolumeShaper.Operation.PLAY, join)
Wenn Sie replace() aufrufen, während der Shaper ausgeführt wird, wird die Lautstärke nicht mehr geändert und bleibt auf dem aktuellen Wert. Anschließend versucht der Shaper, die neue Kurve vom ersten Kontrollpunkt aus zu starten. Das bedeutet, dass das Argument „operation“ steuert, ob der Shaper nach dem Aufruf ausgeführt wird oder nicht. Geben Sie PLAY an, um die neue Kurve sofort zu starten, oder REVERSE, um den Shaper bei der Lautstärke des ersten Kontrollpunkts in der neuen Kurve anzuhalten. Sie können den Shaper später mit apply(VolumeShaper.Operation.PLAY) starten.
Wenn Sie replace() mit join = false aufrufen, beginnt der Shaper seine Kurve auf der Ebene, die durch den ersten Kontrollpunkt angegeben ist. Dies kann zu einer Unterbrechung des Volumens führen. Sie können dies vermeiden, indem Sie replace() mit join = true aufrufen.
Dadurch wird der erste Steuerpunkt der neuen Kurve auf den aktuellen Pegel des Shapers gesetzt und die Lautstärke aller Steuerpunkte zwischen dem ersten und dem letzten wird skaliert, um die relative Form der neuen Kurve beizubehalten (der letzte Steuerpunkt bleibt unverändert). Durch die Skalierung werden die Kontrollpunkte in der neuen Kurve des Shapers dauerhaft geändert.
VolumeShaper entfernen
Das System schließt und bereinigt einen VolumeShaper, wenn sein AudioTrack oder MediaPlayer freigegeben oder nicht mehr verwendet wird. Sie können die Methode close() für einen Shaper aufrufen, um ihn sofort zu löschen. Das System entfernt den Shaper innerhalb von etwa 20 ms aus der Audiopipeline. Seien Sie vorsichtig, wenn Sie einen VolumeShaper schließen, während Audio wiedergegeben wird. Wenn der Shaper beim Aufrufen von close() ein Volumen von weniger als 1,0 hat, ändert sich die Volumenskalierung des Shapers auf 1,0. Dies kann zu einem plötzlichen Anstieg der Lautstärke führen.