Como controlar a amplitude com o VolumeShaper

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_RAMP
  • VolumeShaper.Configuration.CUBIC_RAMP
  • VolumeShaper.Configuration.SINE_RAMP
  • VolumeShaper.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.