Puedes usar un VolumeShaper en una app de audio para realizar
atenuaciones de entrada, atenuaciones de salida, atenuaciones cruzadas, autosilenciado de fondo y otras transiciones de volumen
automatizadas breves. La clase VolumeShaper está disponible en Android 8.0 (nivel de API 26) y versiones posteriores.
Para crear un VolumeShaper, llama a createVolumeShaper() en una instancia de
AudioTrack o MediaPlayer. VolumeShaper solo actúa en el audio que produce el AudioTrack o MediaPlayer que lo creó.
VolumeShaper.Configuration
El comportamiento de un VolumeShaper se define por su
VolumeShaper.Configuration. La configuración especifica una
*curva de volumen, un tipo de interpolador y una duración.*
Curva de volumen
La curva de volumen representa el cambio de amplitud en el tiempo. Se define con un par de arrays de números de punto flotante, x[] e y[], que definen una serie de puntos de control. Cada par (x, y) representa el tiempo y el volumen, respectivamente. Los arrays deben tener la misma longitud y contener al menos 2 y no más de 16 valores. (La longitud máxima de la curva se define en getMaximumCurvePoints()).
Las coordenadas de tiempo se proporcionan durante el intervalo [0.0, 1.0]. El primer punto de tiempo debe ser 0.0, el último debe ser 1.0 y los tiempos deben aumentar de forma monótona.
Las coordenadas de volumen se especifican en una escala lineal en el intervalo [0.0, 1.0].
Tipo de interpolación
La curva de volumen siempre pasa por los puntos de control especificados. Los valores entre los puntos de control se derivan mediante una spline según el tipo de interpolador de la configuración. Existen cuatro constantes para los tipos de interpoladores VolumeShaper disponibles:
- VolumeShaper.Configuration.INTERPOLATOR_TYPE_STEP
- VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR
- VolumeShaper.Configuration.INTERPOLATOR_TYPE_CUBIC
- VolumeShaper.Configuration.INTERPOLATOR_TYPE_CUBIC_MONOTONIC
Duración
Las coordenadas de tiempo especificadas en el intervalo [0.0, 1.0] se escalan a una duración que especificas en milisegundos. Esto determina la duración real de la curva de volumen cuando el moldeador se está ejecutando y aplicando la curva a la salida de audio.
Uso de un VolumeShaper
Cómo crear una configuración
Antes de desarrollar un VolumeShaper, tienes que crear una instancia de VolumeShaper.Configuration. Para ello, usa un elemento VolumeShaper.Configuration.Builder():
val config: VolumeShaper.Configuration = VolumeShaper.Configuration.Builder() .setDuration(3000) .setCurve(floatArrayOf(0f, 1f), floatArrayOf(0f, 1f)) .setInterpolatorType(VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR) .build()
Sin argumentos, el constructor VolumeShaper.Configuration.Builder muestra un compilador que crea una configuración con parámetros predeterminados: INTERPOLATOR_TYPE_CUBIC, una duración de un segundo y sin curva. Debes agregar una curva al compilador antes de llamar a build().
El framework proporciona constantes para las configuraciones con curvas precompiladas, cada una con una duración de un segundo:
VolumeShaper.Configuration.LINEAR_RAMPVolumeShaper.Configuration.CUBIC_RAMPVolumeShaper.Configuration.SINE_RAMPVolumeShaper.Configuration.SCURVE_RAMP
Cómo crear un VolumeShaper
Para crear un VolumeShaper, llama a createVolumeShaper() en una instancia de la clase adecuada y pasa un VolumeShaper.Configuration:
volumeShaper = myMediaPlayer.createVolumeShaper(config) volumeShaper = myAudioTrack.createVolumeShaper(config)
Una sola pista o reproductor multimedia puede tener muchos modeladores conectados, y puedes controlar cada uno por separado. Los resultados de todos los moldeadores de una pista o un reproductor se multiplican entre sí. No se puede compartir un VolumeShaper entre
AudioTracks o MediaPlayers, pero puedes usar la misma configuración en las llamadas
a createVolumeShaper para compilar moldeadores idénticos en varios AudioTracks o
MediaPlayers.
Cuando creas el modelador, su primer punto de control (en t = 0) se aplica a la transmisión de audio. Si el volumen inicial no es 1.0 y tu app reproduce material en el momento de la creación, es posible que el audio tenga un cambio abrupto en el volumen. La práctica recomendada es comenzar a reproducir audio desde el silencio y usar un VolumeShaper para implementar un aumento gradual cuando se inicia la reproducción. Crea un VolumeShaper que comience con un volumen de 0
y aumente gradualmente. Por ejemplo:
setCurve(new float[] {0.f, 1.f}, new float[] {0.f, 1.f})
Comienza la reproducción y el modelador al mismo tiempo. Esto garantiza que la reproducción comience en silencio y que el volumen aumente hasta el máximo. Esto se explica en la siguiente sección.
Cómo ejecutar un VolumeShaper
Aunque el nivel de volumen del primer punto de control se aplica a la ruta de audio en cuanto se crea el modelador, este no avanza por la curva hasta que llamas al método apply() con VolumeShaper.Operation.PLAY. Después
de crear el modelador, la primera invocación de apply() debe especificar la operación
PLAY para iniciar el modelador. Esto ejecuta la curva desde su primer punto de control hasta el último:
shaper.apply(VolumeShaper.Operation.PLAY)
Mientras se ejecuta el modelador, puedes emitir llamadas apply() alternadas que especifiquen
operaciones REVERSE y PLAY. Esto cambia la dirección de lectura de los
puntos de control cada vez.
El moldeador ajusta el volumen de forma continua y pasa por todos los puntos de control hasta que vence. Esto sucede cuando el moldeador alcanza el último punto de control (para la operación PLAY) o el primero (para la operación REVERSE) de la curva.
Cuando el modelador vence, el volumen permanece en el último parámetro de configuración, que puede ser
el primer o el último punto de control. Puedes llamar a VolumeShaper.getVolume() para
obtener el nivel de volumen actual en cualquier momento.
Después de que venza el modelador, puedes emitir otra llamada a apply() para ejecutar la curva en la dirección opuesta. Por ejemplo, si el modelador venció mientras se ejecutaba
PLAY, el siguiente apply() debe ser REVERSE. Llamar a PLAY después de que haya vencido PLAY o a REVERSE después de que haya vencido REVERSE no tiene ningún efecto.
Tienes que alternar las operaciones de PLAY y REVERSE. No hay forma de reproducir una curva desde el primer punto de control hasta el último y, luego, reiniciarla desde el primer punto de control. Puedes usar el método replace(), que se describe en la siguiente sección, para reemplazar la curva por una copia de sí misma. Esto restablece el modelador,
lo que requiere que la operación PLAY lo vuelva a iniciar.
Cambiar la curva
Usa el método de replace() para cambiar una curva de VolumeShaper. Este método toma
una configuración, una operación y un parámetro de unión. Puedes llamar al método replace() en cualquier momento, mientras se ejecuta el modelador o después de que venza:
val newConfig = VolumeShaper.Configuration.Builder() .setDuration(1000) .setCurve(floatArrayOf(0f, 0.5f), floatArrayOf(0f, 1f)) .setInterpolatorType(VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR) .build() val join = true shaper.replace(newConfig, VolumeShaper.Operation.PLAY, join)
Cuando llamas a replace() mientras se ejecuta el modelador, este deja de cambiar el volumen y permanece en su valor actual. Luego, el moldeador intenta iniciar la curva nueva
desde el primer punto de control. Esto significa que el argumento de la operación
controla si el modelador se ejecuta o no después de la llamada. Especifica PLAY para iniciar de inmediato la nueva curva, especifica REVERSE para dejar el modelador en pausa en el volumen del primer punto de control de la nueva curva. Puedes iniciar el modelador
más tarde con apply(VolumeShaper.Operation.PLAY).
Cuando llamas a replace() con join = false, el modelador inicia su curva en el nivel especificado por su primer punto de control. Esto puede causar una discontinuidad
en el volumen. Puedes evitarlo si llamas a replace() con join = true.
Esto establece el primer punto de control de la nueva curva en el nivel actual del
shaper y escala el volumen de todos los puntos de control entre el primero y
el último para mantener la forma relativa de la nueva curva (el último punto de control no
cambia). La operación de escalamiento cambia de forma permanente los puntos de control en la
curva nueva del modelador.
Quitar un VolumeShaper
El sistema cierra y recolecta elementos no utilizados de un VolumeShaper cuando se libera o ya no se usa su AudioTrack o MediaPlayer. Puedes llamar al método close()
en un Shaper para destruirlo de inmediato. El sistema quita el modelador de la canalización de audio en unos 20 ms. Ten cuidado cuando cierres un objeto VolumeShaper mientras se reproduce audio. Si el moldeador tiene un volumen inferior a 1.0 cuando llamas a close(), la escala de volumen del moldeador cambia a 1.0. Esto puede causar un aumento repentino
del volumen.