Générer des images de forme d’onde à partir d’audio

🤖/audio/waveform génère des images de forme d’onde pour vos fichiers audio et vous permet de modifier les couleurs et les dimensions de ces images.

Exemple d’utilisation

{
  "steps": {
    "waveformed": {
      "center_color": "0099ccff",
      "height": 200,
      "outer_color": "0099ccff",
      "robot": "/audio/waveform",
      "use": ":original",
      "width": 400
    }
  }
}

Paramètres

• interpolate

  boolean | Record<string, boolean>

  Détermine si les Assembly Variables sont interpolées pour chaque champ d’instruction.

  Par défaut, la plupart des champs d’instruction des Robots interpolent les Assembly Variables. Définissez ce paramètre sur false pour traiter tous les champs d’instruction comme du texte littéral, ou définissez le chemin d’un champ individuel sur false pour traiter uniquement ce champ comme du texte littéral. Pour les champs propres à un Robot qui sont littéraux par défaut, définissez ce paramètre sur true ou définissez le chemin de ce champ sur true pour réactiver l’interpolation.

  Utilisez des noms de champs tels que path, ou des chemins avec points tels que ffmpeg.vf pour les objets imbriqués.

• output_meta

  Record<string, boolean> | boolean | Array<string>

  Permet de spécifier un ensemble de métadonnées dont le calcul est plus coûteux en puissance CPU et qui sont donc désactivées par défaut afin que le traitement de vos Assemblies reste rapide.

  Pour les images, vous pouvez ajouter "has_transparency": true dans cet objet pour déterminer si l’image contient des parties transparentes, et "dominant_colors": true pour extraire de l’image un tableau de codes couleur hexadécimaux.

  Pour les images, vous pouvez également ajouter "blurhash": true pour extraire une chaîne BlurHash⁠ — une représentation compacte d’un espace réservé pour l’image, utile pour afficher un aperçu flou pendant le chargement de l’image complète.

  Pour les images, "thumbhash": true extrait plutôt un ThumbHash⁠ encodé en base64 dans meta.thumbhash, accompagné de meta.has_alpha (qui indique si un canal alpha existe, même lorsque l’image est entièrement opaque). Il décrit les pixels orientés selon les données EXIF et utilise la première image des images animées. L’extraction est effectuée au mieux : les images de plus de 40 mégapixels, les formats non pris en charge ou un décodage échoué ou limité ne produisent aucun espace réservé. Une extraction réussie ajoute des frais de métadonnées équivalents à 20 % des octets de ce fichier. Aucun supplément ThumbHash ne s’applique lorsque l’option est désactivée ou lorsqu’aucun hash n’est produit.

  Définissez cette option sur le Step qui produit l’image, par exemple /upload/handle pour les originaux téléversés ou /image/resize pour les sorties traitées. La définir uniquement sur /transloadit/store ne déclenche pas l’extraction : le stockage conserve les métadonnées du Step producteur. Transloadit Storage conserve un hash généré avec sa version immuable et le renvoie dans les résultats stockés et lors des lectures natives de ressources. Les téléversements directs vers S3 ne génèrent pas d’espaces réservés. Un espace réservé contient des informations sur l’image : protégez-le donc avec les mêmes contrôles d’accès que l’image complète.

  Pour les vidéos, vous pouvez ajouter le paramètre "colorspace": true pour extraire l’espace colorimétrique de la vidéo de sortie.

  Pour les vidéos, vous pouvez également ajouter "interlaced": true pour détecter si la vidéo est entrelacée. Cette option combine l’indicateur ffprobe peu coûteux field_order avec une passe d’échantillonnage idet limitée sur les premières images de la source, et expose interlaced, field_order ainsi qu’un objet de diagnostic interlace_detection sous file.meta. Cette opération est coûteuse en calcul et facturée en conséquence.

  Pour l’audio, vous pouvez ajouter "mean_volume": true pour obtenir une valeur unique représentant le volume moyen du fichier audio.

  Vous pouvez également définir cette option sur false pour ignorer l’extraction des métadonnées et accélérer le transcodage.

• user_meta

  Record<string, any>(par défaut : {})

  Ajoute des métadonnées JSON personnalisées à chaque fichier émis sans modifier son contenu. Les objets et tableaux imbriqués sont pris en charge.

  L’héritage dépend du Robot. Les valeurs sont fusionnées avec la valeur user_meta existante du fichier de sortie ; le Step actuel remplace les clés de premier niveau correspondantes. Attribuez explicitement les clés requises lorsqu’un Robot crée de nouvelles sorties.

  Dans les Steps de traitement, ${file.*} désigne la première entrée et ${result.*} le fichier émis. Les valeurs sont évaluées pour chaque sortie après l’exécution du Robot, avant l’extraction ultérieure des métadonnées et le stockage temporaire. Sur :original, les valeurs sont évaluées pour chaque téléversement avant l’extraction des métadonnées.

  Les Steps en aval lisent ${file.user_meta.key}. Consultez Métadonnées personnalisées pour un exemple complet et les règles d’héritage.

• result

  boolean(par défaut : false)

  Indique si les résultats de ce Step doivent figurer dans l’Assembly Status JSON

• queue

  batch

  Définir la file d’attente sur « batch » abaisse manuellement la priorité des Jobs de ce Step afin d’éviter de consommer des emplacements prioritaires de Jobs pour des Jobs qui n’ont pas besoin d’un temps d’attente nul dans la file

• force_accept

  boolean(par défaut : false)

  Forcer un Robot à accepter un type de fichier qu’il aurait ignoré.

  Par défaut, les Robots ignorent les fichiers qu’ils ne connaissent pas. Le Robot 🤖/video/encode, par exemple, ignorera volontiers les images en entrée.

  Avec le paramètre force_accept défini sur true, vous pouvez forcer les Robots à accepter tous les fichiers qui leur sont envoyés. Cela entraîne généralement des erreurs et ne doit être utilisé que pour le débogage ou pour traiter des cas limites.

• ignore_errors

  boolean | Array<meta | execute>(par défaut : [])

  Ignore les erreurs pendant certaines phases du traitement.

  Si vous définissez cette valeur sur ["meta"], le Robot ignorera les erreurs lors de l’extraction des métadonnées.

  Si vous définissez cette valeur sur ["execute"], le Robot ignorera les erreurs lors de la phase d’exécution principale.

  Définir cette valeur sur true équivaut à ["meta", "execute"] : les erreurs seront alors ignorées dans les deux phases.

• use

  string | Array<string> | Array<object> | object

  Indique quel(s) Step(s) utiliser comme entrée.

  • Vous pouvez choisir n’importe quel nom pour les Steps, sauf ":original" (réservé aux téléversements des utilisateurs gérés par Transloadit)
  • Vous pouvez fournir plusieurs Steps en entrée à l’aide de tableaux :

    {
      "use": [
        ":original",
        "encoded",
        "resized"
      ]
    }
    

  • Vous pouvez également étiqueter les Steps d’entrée avec as pour transmettre une intention sémantique aux Robots :

    {
      "use": [
        {
          "name": ":original",
          "as": "image"
        },
        {
          "name": ":original",
          "as": "mask"
        }
      ]
    }
    

  Astuce

  C’est probablement tout ce que vous devez savoir sur use, mais vous pouvez consulter les cas d’utilisation avancés.

• ffmpeg

  object

  Un objet de paramètres à transmettre à FFmpeg. Si un préréglage est utilisé, les options spécifiées sont fusionnées par-dessus celles du préréglage. Pour connaître les options disponibles, consultez la documentation de FFmpeg⁠. Les options spécifiées ici ont priorité sur celles du préréglage.

• ffmpeg_stack

  v6 | v7 | v8 | string(par défaut : "v6.0.0")

  Sélectionne la version de la pile FFmpeg à utiliser pour l’encodage. Nous recommandons actuellement d’utiliser « v7 ». Les versions exactes « v6.0.0 », « v7.0.0 » et « v8.0.0 » sont des valeurs héritées qui restent acceptées pour assurer la rétrocompatibilité. Les valeurs « v5.x », dépréciées, sont également acceptées.

• format

  image | json(par défaut : "image")

  Format du fichier de sortie. Peut prendre la valeur "image" ou "json". Si la valeur "image" est fournie, une image PNG sera créée, sinon un fichier JSON. Lorsque style vaut "spectrogram", seule la valeur "image" est prise en charge.

• width

  string | number(par défaut : 256)

  La largeur de l’image obtenue si le format "image" a été sélectionné.

• height

  string | number(par défaut : 64)

  Hauteur de l’image obtenue si le format "image" a été sélectionné.

• antialiasing

  0 | 1 | boolean(par défaut : 0)

  Une valeur de 0 ou 1, ou bien true/false, selon que vous souhaitez activer ou non l’anticrénelage pour obtenir des contours plus lisses dans le graphique de la forme d’onde.

• background_color

  string(par défaut : "#00000000")

  Couleur d’arrière-plan de l’image obtenue, au format « rrggbbaa » (rouge, vert, bleu, alpha), si le format "image" a été sélectionné.

• center_color

  string(par défaut : "000000ff")

  Couleur utilisée au centre du dégradé. Le format est « rrggbbaa » (rouge, vert, bleu, alpha).

• outer_color

  string(par défaut : "000000ff")

  Couleur utilisée dans les parties extérieures du dégradé. Le format est « rrggbbaa » (rouge, vert, bleu, alpha).

• style

  v0 | v1 | spectrogram

  Version du style de forme d’onde.

  • "v0" : Génération historique de formes d’onde (par défaut).
  • "v1" : Génération avancée de formes d’onde avec des paramètres supplémentaires.
  • "spectrogram" : Visualisation sous forme de spectrogramme montrant le contenu fréquentiel au fil du temps.

  Pour assurer la rétrocompatibilité, les valeurs numériques 0 et 1 sont également acceptées et associées à "v0" et "v1".

• split_channels

  boolean

  Disponible lorsque style vaut "v1". Si ce paramètre vaut true, des fichiers de données de forme d’onde multicanale ou des fichiers image sont produits, à raison d’un fichier par canal.

• zoom

  string | number

  Disponible lorsque style vaut "v1". Niveau de zoom en échantillons par pixel. Ce paramètre ne peut pas être utilisé avec pixels_per_second.

• pixels_per_second

  string | number

  Disponible lorsque style vaut "v1". Niveau de zoom en pixels par seconde. Ce paramètre ne peut pas être utilisé conjointement avec zoom.

• bits

  8 | 16

  Disponible lorsque style vaut "v1". Profondeur en bits des données de forme d’onde. Valeurs possibles : 8 ou 16.

• start

  string | number

  Disponible lorsque style vaut "v1". Temps de début en secondes.

• end

  string | number

  Disponible lorsque style vaut "v1". Instant de fin en secondes (0 désigne la fin de l’audio).

• colors

  audition | audacity

  Disponible lorsque style vaut "v1". Palette de couleurs à utiliser. Valeurs possibles : « audition » ou « audacity ».

• border_color

  string

  Disponible lorsque style vaut "v1". Couleur de la bordure au format « rrggbbaa ».

• waveform_style

  normal | bars

  Disponible lorsque style vaut "v1". Style de forme d’onde. Peut être « normal » ou « bars ».

• bar_width

  string | number

  Disponible lorsque style vaut "v1". Largeur des barres, en pixels, lorsque waveform_style vaut « bars ».

• bar_gap

  string | number

  Disponible lorsque style vaut "v1". Espacement entre les barres, en pixels, lorsque waveform_style vaut « bars ».

• bar_style

  square | rounded

  Disponible lorsque style vaut "v1". Style des barres lorsque waveform_style vaut « bars ».

• axis_label_color

  string

  Disponible lorsque style vaut "v1". Couleur des libellés des axes au format « rrggbbaa ».

• no_axis_labels

  boolean

  Disponible lorsque style vaut "v1". Si ce paramètre vaut true, l’image de forme d’onde est rendue sans les libellés des axes.

• with_axis_labels

  boolean

  Disponible lorsque style vaut "v1". Si ce paramètre est défini sur true, l’image de la forme d’onde est rendue avec des libellés d’axes.

• amplitude_scale

  string | number

  Disponible lorsque style vaut "v1". Facteur d’échelle de l’amplitude.

• compression

  string | number

  Disponible lorsque style vaut "v1". Niveau de compression PNG : de 0 (aucune) à 9 (maximale), ou -1 (par défaut). Applicable uniquement lorsque format vaut « image ».

• color_map

  viridis | plasma | magma | cividis | cool | rainbow | moreland | 7 de plus ↓

  Disponible lorsque style vaut "spectrogram". Palette de couleurs pour la visualisation du spectrogramme. Valeur par défaut : "viridis".

• frequency_scale

  linear | logarithmic

  Disponible lorsque style vaut "spectrogram". Échelle de fréquences du spectrogramme. "linear" affiche les fréquences avec un espacement uniforme ; "logarithmic" met l’accent sur les basses fréquences. Valeur par défaut : "logarithmic".

• frequency_min

  string | number

  Disponible lorsque style vaut "spectrogram". Fréquence minimale à afficher, en Hz. Valeur par défaut : 0.

• frequency_max

  string | number

  Disponible lorsque style vaut "spectrogram". Fréquence maximale à afficher, en Hz. La valeur par défaut est la moitié de la fréquence d’échantillonnage (fréquence de Nyquist).

• legend

  boolean

  Disponible lorsque style vaut "spectrogram". Indique s’il faut inclure une légende montrant les échelles de fréquence et de temps. Valeur par défaut : false.

• gain

  string | number

  Disponible lorsque style vaut "spectrogram". Facteur de gain linéaire pour l’intensité du spectrogramme. Valeur par défaut : 1.

• orientation

  vertical | horizontal

  Disponible lorsque style vaut "spectrogram". Orientation du spectrogramme. "horizontal" affiche le temps sur l’axe des x (par défaut) ; "vertical" affiche le temps sur l’axe des y.

Démonstrations

Articles de blog associés