Você pode usar um VolumeShaper em um app de áudio para realizar
fade-ins, fade-outs, crossfades, reduções de áudio e outras transições curtas e automatizadas
de volume. A classe VolumeShaper está disponível no Android 8.0 (nível 26 da API)
e versões mais recentes.
Para criar um VolumeShaper, chame createVolumeShaper() em uma instância de
AudioTrack ou MediaPlayer. O
VolumeShaper só atua no áudio produzido pelo AudioTrack ou MediaPlayer
que o criou.
VolumeShaper.Configuration
O comportamento de um VolumeShaper é definido pelo
VolumeShaper.Configuration. A configuração especifica uma
*curva de volume, um tipo de interpolador e uma duração.*
Curva de volume
A curva de volume representa a mudança de amplitude ao longo do tempo. Ela é definida por um par
de matrizes flutuantes, x[] e y[], que definem uma série de pontos de controle. Cada par (x, y) representa o tempo e o volume, respectivamente. As matrizes precisam ter o mesmo comprimento
e conter pelo menos 2 e no máximo 16 valores. O comprimento máximo da curva é definido em getMaximumCurvePoints().
As coordenadas de tempo são fornecidas no intervalo [0.0, 1.0]. O primeiro ponto de tempo precisa ser 0,0, o último precisa ser 1,0 e os tempos precisam ser monotonicamente crescentes.
As coordenadas de volume são especificadas em escala linear no intervalo [0,0, 1,0].
Tipo de interpolador
A curva de volume sempre passa pelos pontos de controle especificados. Os valores
entre os pontos de controle são derivados por um spline de acordo com o
tipo de interpolador da configuração. Há quatro constantes para os tipos de interpolador
VolumeShaper disponíveis:
- VolumeShaper.Configuration.INTERPOLATOR_TYPE_STEP
- VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR
- VolumeShaper.Configuration.INTERPOLATOR_TYPE_CUBIC
- VolumeShaper.Configuration.INTERPOLATOR_TYPE_CUBIC_MONOTONIC
Duração
As coordenadas de tempo especificadas no intervalo [0,0, 1,0] são dimensionadas para uma duração que você especifica em milissegundos. Isso determina a duração real da curva de volume quando o modelador está em execução e aplicando a curva à saída de áudio.
Usar um VolumeShaper
Criar uma configuração
Antes de criar uma VolumeShaper, você precisa criar uma instância de VolumeShaper.Configuration. Para isso, use um
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()
Sem argumentos, o construtor VolumeShaper.Configuration.Builder retorna um
builder que cria uma configuração com as definições padrão:
INTERPOLATOR_TYPE_CUBIC, uma duração de um segundo e nenhuma curva. É preciso adicionar uma
curva ao builder antes de chamar build().
O framework fornece constantes para configurações com curvas pré-criadas, cada uma com um segundo de duração:
VolumeShaper.Configuration.LINEAR_RAMPVolumeShaper.Configuration.CUBIC_RAMPVolumeShaper.Configuration.SINE_RAMPVolumeShaper.Configuration.SCURVE_RAMP
Como criar um VolumeShaper
Para criar um VolumeShaper, chame createVolumeShaper() em uma instância da
classe apropriada, transmitindo um VolumeShaper.Configuration:
volumeShaper = myMediaPlayer.createVolumeShaper(config) volumeShaper = myAudioTrack.createVolumeShaper(config)
Uma única faixa ou player de mídia pode ter muitos shapers anexados, e você pode
controlar cada um separadamente. As saídas de todos os modeladores em uma faixa ou
jogador são multiplicadas. Não é possível compartilhar um VolumeShaper entre
AudioTracks ou MediaPlayers, mas é possível usar a mesma configuração em chamadas
para createVolumeShaper para criar modeladores idênticos em vários AudioTracks ou
MediaPlayers.
Quando você cria o modelador, o primeiro ponto de controle (em t = 0) é aplicado ao
stream de áudio. Se o volume inicial não for 1.0 e o app estiver reproduzindo material
no momento da criação, o áudio poderá ter uma mudança abrupta de volume. A prática recomendada
é iniciar a reprodução de áudio em silêncio e usar um VolumeShaper para implementar um
fade-in quando a reprodução começar. Crie um VolumeShaper que comece com volume 0
e aumente gradualmente. Exemplo:
setCurve(new float[] {0.f, 1.f}, new float[] {0.f, 1.f})
Inicie a reprodução e o shaper ao mesmo tempo. Isso garante que a reprodução comece em silêncio e o volume aumente até o máximo. Isso é explicado na próxima seção.
Executar um VolumeShaper
Embora o nível de volume do primeiro ponto de controle seja aplicado ao caminho de áudio
assim que o modelador é criado, ele não avança ao longo da curva
até que você chame o método apply() com VolumeShaper.Operation.PLAY. Depois de
criar o modelador, a primeira invocação de apply() precisa especificar a operação
PLAY para iniciar o modelador. Isso executa a curva do primeiro ao
último ponto de controle:
shaper.apply(VolumeShaper.Operation.PLAY)
Enquanto o modelador estiver em execução, você poderá emitir chamadas apply() alternadas especificando
as operações REVERSE e PLAY. Isso muda a direção de leitura dos
pontos de controle a cada vez.
O modelador ajusta continuamente o volume e passa por todos os pontos de controle até expirar. Isso acontece quando o modelador chega ao último (para a operação PLAY) ou ao primeiro (para a operação REVERSE) ponto de controle na curva.
Quando o modelador expira, o volume permanece na última configuração, que pode ser
o primeiro ou o último ponto de controle. Você pode chamar VolumeShaper.getVolume() para
o nível de volume atual a qualquer momento.
Depois que o modelador expirar, você poderá emitir outra chamada apply() para executar a curva
na direção oposta. Por exemplo, se o modelador expirou durante a execução de
PLAY, o próximo apply() precisa ser REVERSE. Chamar PLAY depois que PLAY
expirar ou REVERSE depois que REVERSE expirar não terá efeito.
Você precisa alternar as operações PLAY e REVERSE. Não é possível reproduzir uma
curva do primeiro ao último ponto de controle e, em seguida, reiniciá-la do
primeiro ponto de controle. Use o método replace(), descrito na próxima seção, para substituir a curva por uma cópia dela mesma. Isso redefine o modelador,
exigindo a operação PLAY para iniciá-lo novamente.
Mudar a curva
Use o método replace() para mudar a curva de um VolumeShaper. Esse método usa
uma configuração, uma operação e um parâmetro de mesclagem. É possível chamar o método replace() a qualquer momento, enquanto o modelador está em execução ou depois que ele expira:
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)
Quando você chama replace() enquanto o modelador está em execução, ele para de mudar o
volume e permanece no valor atual. Em seguida, o modelador tenta iniciar a nova
curva do primeiro ponto de controle. Isso significa que o argumento de operação controla se o modelador é executado ou não após a chamada. Especifique PLAY para
iniciar imediatamente a nova curva, especifique REVERSE para deixar o modelador pausado no
volume do primeiro ponto de controle na nova curva. É possível iniciar o modelador
mais tarde com apply(VolumeShaper.Operation.PLAY).
Quando você chama replace() com join = false, o modelador inicia a curva no
nível especificado pelo primeiro ponto de controle. Isso pode causar uma descontinuidade
no volume. Você pode evitar isso chamando replace() com join = true.
Isso define o primeiro ponto de controle da nova curva como o nível atual do
modelador e dimensiona o volume de todos os pontos de controle entre o primeiro e o
último para manter a forma relativa da nova curva (o último ponto de controle não é
alterado). A operação de escalonamento muda permanentemente os pontos de controle na
nova curva do modelador.
Remover um VolumeShaper
O sistema fecha e coleta o lixo de um VolumeShaper quando o AudioTrack ou o
MediaPlayer é liberado ou não está mais em uso. É possível chamar o método close()
em um modelador para destruí-lo imediatamente. O sistema remove o modelador do
pipeline de áudio em cerca de 20 ms. Tenha cuidado ao fechar um VolumeShaper
enquanto o áudio estiver sendo reproduzido. Se o modelador tiver um volume menor que 1.0 quando você chamar
close(), a escala de volume do modelador vai mudar para 1.0. Isso pode causar um aumento repentino no volume.