VolumeShaper

Kotlin |Java

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
	`Configuration` The `VolumeShaper.Configuration` class contains curve and duration information.
	`Operation` The `VolumeShaper.Operation` class is used to specify operations to the `VolumeShaper` that affect the volume change.

Public methods
Unit	`apply(operation: VolumeShaper.Operation)` Applies the `VolumeShaper.Operation` to the `VolumeShaper`.
Unit	`close()` Releases the `VolumeShaper` object; any volume scale due to the `VolumeShaper` is removed after closing.
Float	`getVolume()` Returns the current volume scale attributable to the `VolumeShaper`.
Unit	`replace(configuration: VolumeShaper.Configuration, operation: VolumeShaper.Operation, join: Boolean)` Replaces the current `VolumeShaper` `configuration` with a new `configuration`.

Protected methods
Unit	`finalize()`

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