Added in API level 26

VolumeShaper


class VolumeShaper : AutoCloseable
kotlin.Any
   ↳ android.media.VolumeShaper

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.

Protected methods
Unit

Public methods

apply

Added in API level 26
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

Added in API level 26
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

Added in API level 26
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

Added in API level 26
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

Added in API level 26
protected fun finalize(): Unit
Exceptions
java.lang.Throwable the Exception raised by this method