Cette page a été traduite par l'API Cloud Translation.

Contrôler l'amplitude avec VolumeShaper

Vous pouvez utiliser un VolumeShaper dans une application audio pour effectuer des fondus et des fondus, des fondus enchaînés, des atténuations et d'autres transitions de volume automatisées courtes. La classe VolumeShaper est disponible sur Android 8.0 (niveau d'API 26) et versions ultérieures.

Pour créer un VolumeShaper, appelez createVolumeShaper() sur une instance de AudioTrack ou MediaPlayer. VolumeShaper agit uniquement sur le contenu audio produit par l'élément AudioTrack ou MediaPlayer qui l'a créé.

VolumeShaper.Configuration

Le comportement d'une VolumeShaper est défini par son VolumeShaper.Configuration. La configuration spécifie une *courbe de volume, un type d'interpolateur et une durée*.

Courbe de volume

La courbe de volume représente les changements d'amplitude au fil du temps. Elle est définie par une paire de tableaux à virgule flottante x[] et y[], qui définissent une série de points de contrôle. Chaque paire (x, y) représente respectivement le temps et le volume. Les tableaux doivent être de longueur égale, et contenir entre 2 et 16 valeurs. (La longueur maximale de la courbe est définie dans getMaximumCurvePoints().)

Les coordonnées temporelles sont indiquées sur l'intervalle [0,0, 1,0]. Le premier point temporel doit être 0,0, le dernier doit être 1,0, et les heures doivent augmenter de manière monotone.

Les coordonnées du volume sont spécifiées à l'échelle linéaire sur l'intervalle [0,0, 1,0].

Type d'interpolateur

La courbe de volume passe toujours par les points de contrôle spécifiés. Les valeurs entre les points de contrôle sont dérivées d'une spline en fonction du type d'interpolateur de la configuration. Il existe quatre constantes pour les types d'interpolateurs VolumeShaper disponibles:

VolumeShaper.Configuration.INTERPOLATOR_TYPE_STEP
VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR
VolumeShaper.Configuration.INTERPOLATOR_TYPE_CUBIC
VolumeShaper.Configuration.INTERPOLATOR_TYPE_CUBIC_MONOTONIC

Durée

Les coordonnées temporelles spécifiées dans l'intervalle [0,0, 1,0] sont mises à l'échelle selon une durée que vous spécifiez en millisecondes. Ce paramètre détermine la durée réelle de la courbe de volume lorsque le Shaper est en cours d'exécution et applique la courbe à la sortie audio.

Utiliser un VolumeShaper

Créer une configuration

Avant de compiler un VolumeShaper, vous devez créer une instance de VolumeShaper.Configuration. Pour ce faire, utilisez un VolumeShaper.Configuration.Builder():

Kotlin

val config: VolumeShaper.Configuration = VolumeShaper.Configuration.Builder()
        .setDuration(3000)
        .setCurve(floatArrayOf(0f, 1f), floatArrayOf(0f, 1f))
        .setInterpolatorType(VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR)
        .build()

Java

VolumeShaper.Configuration config =
  new VolumeShaper.Configuration.Builder()
      .setDuration(3000)
      .setCurve(new float[] {0.f, 1.f}, new float[] {0.f, 1.f})
      .setInterpolatorType(VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR)
      .build();

With no arguments the VolumeShaper.Configuration.Builder constructor returns a builder that creates a configuration with default settings: INTERPOLATOR_TYPE_CUBIC, a one second duration, and no curve. You must add a curve to the builder before calling build().

The framework provides constants for configurations with pre-built curves, each with one second duration:

VolumeShaper.Configuration.LINEAR_RAMP
VolumeShaper.Configuration.CUBIC_RAMP
VolumeShaper.Configuration.SINE_RAMP
VolumeShaper.Configuration.SCURVE_RAMP

Creating a VolumeShaper

To create a VolumeShaper, call createVolumeShaper() on an instance of the appropriate class, passing in a VolumeShaper.Configuration:

Kotlin

volumeShaper = myMediaPlayer.createVolumeShaper(config)
volumeShaper = myAudioTrack.createVolumeShaper(config)

Java

volumeShaper = myMediaPlayer.createVolumeShaper(config);
volumeShaper = myAudioTrack.createVolumeShaper(config);

A single track or media player can have many shapers attached to it, and you can control each shaper separately. The outputs of all the shapers on a track or player are multiplied together. A VolumeShaper cannot be shared between AudioTracks or MediaPlayers, but you can use the same configuration in calls to createVolumeShaper to build identical shapers on multiple AudioTracks or MediaPlayers.

When you create the shaper, its first control point (at t = 0) is applied to the audio stream. If the initial volume is not 1.0 and your app is playing material at create time, your audio might have an abrupt change in volume. Best practice is to start playing audio from silence and use a VolumeShaper to implement a fade-in when playback starts. Create a VolumeShaper that starts at 0 volume and fades up. For example:

setCurve(new float[] {0.f, 1.f}, new float[] {0.f, 1.f})

Lancer la lecture et le tracé en même temps. Ainsi, la lecture commence par le silence et le volume augmente au maximum. Cela est expliqué dans la section suivante.

Exécuter un VolumeShaper

Bien que le niveau de volume du premier point de contrôle soit appliqué à la piste audio dès que le Shaper est créé, il ne progresse pas le long de la courbe tant que vous n'avez pas appelé la méthode apply() avec VolumeShaper.Operation.PLAY. Après avoir créé le Shaper, le premier appel de apply() doit spécifier l'opération PLAY afin de démarrer le Shaper. La courbe est exécutée du premier au dernier point de contrôle:

Kotlin

shaper.apply(VolumeShaper.Operation.PLAY)

Java

shaper.apply(VolumeShaper.Operation.PLAY);

Pendant l'exécution du shaper, vous pouvez émettre des appels apply() alternés spécifiant les opérations REVERSE et PLAY. La direction de la lecture des points de contrôle change à chaque fois.

Le sculpteur ajuste en permanence le volume et passe par tous les points de contrôle jusqu'à ce qu'il expire. Cela se produit lorsque le shaper atteint le dernier point de contrôle de la courbe (pour l'opération de lecture) ou le premier point de contrôle (pour l'opération inverse).

Lorsque le paramètre de forme expire, le volume reste sur le dernier paramètre, qui peut être le premier ou le dernier point de contrôle. Vous pouvez appeler VolumeShaper.getVolume() pour obtenir le niveau de volume actuel à tout moment.

Une fois que le shaper a expiré, vous pouvez émettre un autre appel apply() pour exécuter la courbe dans la direction opposée. Par exemple, si le tracé a expiré lors de l'exécution de PLAY, le apply() suivant doit être REVERSE. L'appel de PLAY après l'expiration de PLAY ou de REVERSE après l'expiration de REVERSE n'a aucun effet.

Vous devez alterner les opérations PLAY et REVERSE. Il n'y a aucun moyen de lire une courbe de son premier au dernier point de contrôle, puis de la redémarrer à nouveau à partir du premier point de contrôle. Vous pouvez utiliser la méthode replace(), décrite dans la section suivante, pour remplacer la courbe par une copie d'elle-même. Cette opération réinitialise le Shaper, nécessitant l'opération PLAY pour le redémarrer.

Changer la courbe

Utilisez la méthode replace() pour modifier la courbe d'une VolumeShaper. Cette méthode utilise une configuration, une opération et un paramètre de jointure. Vous pouvez appeler la méthode replace() à tout moment, pendant ou après son expiration:

Kotlin

val newConfig = VolumeShaper.Configuration.Builder()
 .setDuration(1000)
 .setCurve(floatArrayOf(0f, 0.5f), floatArrayOf(0f, 1f))
 .setInterpolatorType(VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR)
 .build()
val join .Shaper)shaper

Java

VolumeShaper.Configuration newConfig =
 new VolumeShaper.Configuration.Builder()
 .setDuration(1000)
 .setCurve(new float[] {0.f, 0.5f}, new float[] {0.f, 1.f})
 .setInterpolatorType(VolumeInterpolatorType(VolumeShaper.Operation.INTERPOLATOR float .ShaperLINEAR)

Lorsque vous appelez replace() alors que le Shaper est en cours d'exécution, il cesse de modifier le volume et conserve sa valeur actuelle. Ensuite, le Shaper tente de démarrer la nouvelle courbe à partir du premier point de contrôle. Cela signifie que l'argument "operation" contrôle si le Shaper s'exécute ou non après l'appel. Spécifiez PLAY pour démarrer immédiatement la nouvelle courbe et REVERSE pour laisser le tracé en pause au volume du premier point de contrôle de la nouvelle courbe. Vous pourrez démarrer le Shaper ultérieurement avec apply(VolumeShaper.Operation.PLAY).

Lorsque vous appelez replace() avec join = false, le Shaper commence sa courbe au niveau spécifié par son premier point de contrôle. Cela peut entraîner une discontinuité dans le volume. Pour éviter cela, appelez replace() avec join = true. Le premier point de contrôle de la nouvelle courbe est défini sur le niveau actuel du Shaper, et le volume de tous les points de contrôle entre le premier et le dernier est ajusté afin de conserver la forme relative de la nouvelle courbe (le dernier point de contrôle est inchangé). L'opération de scaling modifie définitivement les points de contrôle dans la nouvelle courbe du Shaper.

Supprimer un VolumeShaper

Le système se ferme et une VolumeShaper est récupérée lorsque son AudioTrack ou son MediaPlayer est libéré ou qu'il n'est plus utilisé. Vous pouvez appeler la méthode close() sur un Shaper pour le détruire immédiatement. Le système supprime le Shaper du pipeline audio en 20 ms environ. Soyez prudent lorsque vous fermez une VolumeShaper pendant la lecture d'un contenu audio. Si le volume du Shaper est inférieur à 1.0 lorsque vous appelez close(), l'échelle de volume du Shaper passe à 1.0. Cela peut entraîner une augmentation soudaine du volume.