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 |
|
The |
Public methods | |
---|---|
Unit |
apply(operation: VolumeShaper.Operation) Applies the |
Unit |
close() Releases the |
Float |
Returns the current volume scale attributable to the |
Unit |
replace(configuration: VolumeShaper.Configuration, operation: VolumeShaper.Operation, join: Boolean) Replaces the current |
Public methods
apply
fun apply(operation: VolumeShaper.Operation): Unit
Applies the VolumeShaper.Operation
to the VolumeShaper
. Applying VolumeShaper.Operation.PLAY
after PLAY
or VolumeShaper.Operation.REVERSE
after REVERSE
has no effect. Applying VolumeShaper.Operation.PLAY
when the player hasn't started will synchronously start the VolumeShaper
when playback begins.
Parameters | |
---|---|
operation |
VolumeShaper.Operation: the operation to apply. This value cannot be null . |
Exceptions | |
---|---|
java.lang.IllegalStateException |
if the player is uninitialized or if there is a critical failure. In that case, the VolumeShaper should be recreated. |
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 |