VolumeShaper
class VolumeShaper : AutoCloseable
The VolumeShaper class is used to automatically control audio volume during media playback, allowing simple implementation of transition effects and ducking. It is created from implementations of VolumeAutomation, such as MediaPlayer and AudioTrack (referred to as "players" below), by MediaPlayer#createVolumeShaper or AudioTrack#createVolumeShaper. A VolumeShaper is intended for short volume changes. If the audio output sink changes during a VolumeShaper transition, the precise curve position may be lost, and the VolumeShaper may advance to the end of the curve for the new audio output sink. The VolumeShaper appears as an additional scaling on the audio output, and adjusts independently of track or stream volume controls.
Summary
| Nested classes |
|
The VolumeShaper.Configuration class contains curve and duration information.
|
|
The VolumeShaper.Operation class is used to specify operations to the VolumeShaper that affect the volume change.
|
| Public methods |
| Unit |
Applies the VolumeShaper.Operation to the VolumeShaper.
|
| Unit |
Releases the VolumeShaper object; any volume scale due to the VolumeShaper is removed after closing.
|
| Float |
Returns the current volume scale attributable to the VolumeShaper.
|
| Unit |
Replaces the current VolumeShaper configuration with a new configuration.
|
Public methods
close
fun close(): Unit
Releases the VolumeShaper object; any volume scale due to the VolumeShaper is removed after closing. If the volume does not reach 1.f when the VolumeShaper is closed (or finalized), there may be an abrupt change of volume. close() may be safely called after a prior close(). This class implements the Java AutoClosable interface and may be used with try-with-resources.
| Exceptions |
java.lang.Exception |
if this resource cannot be closed |
getVolume
fun getVolume(): Float
Returns the current volume scale attributable to the VolumeShaper. This is the last volume from the VolumeShaper used for the player, or the initial volume if the VolumeShaper hasn't been started with VolumeShaper.Operation#PLAY.
| Return |
Float |
the volume, linearly represented as a value between 0.f and 1.f. |
| Exceptions |
java.lang.IllegalStateException |
if the player is uninitialized or if there is a critical failure. In that case, the VolumeShaper should be recreated. |
replace
fun replace(
configuration: VolumeShaper.Configuration,
operation: VolumeShaper.Operation,
join: Boolean
): Unit
Replaces the current VolumeShaper configuration with a new configuration. This allows the user to change the volume shape while the existing VolumeShaper is in effect. The effect of replace() is similar to an atomic close of the existing VolumeShaper and creation of a new VolumeShaper. If the operation is VolumeShaper.Operation#PLAY then the new curve starts immediately. If the operation is VolumeShaper.Operation#REVERSE, then the new curve will be delayed until PLAY is applied.
| Parameters |
configuration |
VolumeShaper.Configuration: the new configuration to use. This value cannot be null. |
operation |
VolumeShaper.Operation: the operation to apply to the VolumeShaper This value cannot be null. |
join |
Boolean: if true, match the start volume of the new configuration to the current volume of the existing VolumeShaper, to avoid discontinuity. |
| Exceptions |
java.lang.IllegalStateException |
if the player is uninitialized or if there is a critical failure. In that case, the VolumeShaper should be recreated. |
Protected methods
finalize
protected fun finalize(): Unit
| Exceptions |
java.lang.Throwable |
the Exception raised by this method |
