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 |