Contrôler l'amplitude avec VolumeShaper

Vous pouvez utiliser un VolumeShaper dans une application audio pour effectuer des fondus en ouverture, des fondus en fermeture, 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) ou version ultérieure.

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

VolumeShaper.Configuration

Le comportement d'un 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 l'évolution de l'amplitude au fil du temps. Il est défini par une paire de tableaux de nombres à 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 données sur l'intervalle [0,0, 1,0]. Le premier point temporel doit être 0,0, le dernier doit être 1,0 et les temps doivent être strictement croissants.

Les coordonnées de volume sont spécifiées sur une é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 par 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 sur une durée que vous spécifiez en millisecondes. Cela 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 créer un VolumeShaper, vous devez créer une instance de VolumeShaper.Configuration. Pour ce faire, utilisez un 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()

Sans argument, le constructeur VolumeShaper.Configuration.Builder renvoie un compilateur qui crée une configuration avec les paramètres par défaut : INTERPOLATOR_TYPE_CUBIC, une durée d'une seconde et aucune courbe. Vous devez ajouter une courbe au compilateur avant d'appeler build().

Le framework fournit des constantes pour les configurations avec des courbes prédéfinies, chacune d'une durée d'une seconde :

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

Créer un VolumeShaper

Pour créer un VolumeShaper, appelez createVolumeShaper() sur une instance de la classe appropriée, en transmettant un VolumeShaper.Configuration :

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

Un seul lecteur multimédia ou une seule piste peut être associé à plusieurs shapers, et vous pouvez contrôler chaque shaper séparément. Les sorties de tous les shapers d'une piste ou d'un lecteur sont multipliées entre elles. Un VolumeShaper ne peut pas être partagé entre AudioTracks ou MediaPlayers, mais vous pouvez utiliser la même configuration dans les appels à createVolumeShaper pour créer des shappers identiques sur plusieurs AudioTracks ou MediaPlayers.

Lorsque vous créez le shaper, son premier point de contrôle (à t = 0) est appliqué au flux audio. Si le volume initial n'est pas de 1.0 et que votre application lit du contenu au moment de la création, le volume de votre contenu audio peut changer brusquement. La bonne pratique consiste à démarrer la lecture audio à partir du silence et à utiliser un VolumeShaper pour implémenter un fondu au début de la lecture. Créez un VolumeShaper qui commence à un volume de 0 et augmente progressivement. Exemple :

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

Lancez la lecture et le shaper en même temps. Cela garantit que la lecture commence en silence et que le volume augmente jusqu'au volume maximal. Ce point est expliqué dans la section suivante.

Exécuter un VolumeShaper

Bien que le niveau de volume du premier point de contrôle soit appliqué au chemin audio dès que le shaper est créé, le shaper ne progresse pas le long de la courbe tant que vous n'appelez pas la méthode apply() avec VolumeShaper.Operation.PLAY. Après avoir créé le shaper, la première invocation de apply() doit spécifier l'opération PLAY pour démarrer le shaper. La courbe s'étend du premier au dernier point de contrôle :

shaper.apply(VolumeShaper.Operation.PLAY)

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

Le shaper ajuste continuellement 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 (pour l'opération PLAY) ou le premier point de contrôle (pour l'opération REVERSE) de la courbe.

À l'expiration du shaper, le volume reste au dernier réglage, qui peut être le premier ou le dernier point de contrôle. Vous pouvez appeler VolumeShaper.getVolume() pour connaître le niveau de volume actuel à tout moment.

Une fois le shaper arrivé à expiration, vous pouvez émettre un autre appel apply() pour exécuter la courbe dans la direction opposée. Par exemple, si le shaper a expiré lors de l'exécution de PLAY, la prochaine apply() 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'est pas possible de lire une courbe du premier au dernier point de contrôle, puis de la redémarrer à 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. Cela réinitialise le shaper, ce qui nécessite l'opération PLAY pour le redémarrer.

Modifier la courbe

Utilisez la méthode replace() pour modifier la courbe d'un 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 l'exécution du shaper ou après son expiration :

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)

Lorsque vous appelez replace() pendant que le shaper est en cours d'exécution, il cesse de modifier le volume et reste à 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 d'opération 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, ou REVERSE pour laisser le shaper en pause au volume du premier point de contrôle de la nouvelle courbe. Vous pouvez démarrer le shaper plus tard 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é du 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 mis à l'échelle pour conserver la forme relative de la nouvelle courbe (le dernier point de contrôle reste inchangé). L'opération de mise à l'échelle modifie définitivement les points de contrôle de la nouvelle courbe du shaper.

Supprimer un VolumeShaper

Le système ferme et récupère un VolumeShaper lorsque son AudioTrack ou son MediaPlayer est libéré ou 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 un VolumeShaper pendant la lecture audio. Si le shaper a un volume 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.