Fusionner vidéo, audio et images en une seule vidéo

🤖/video/merge compose une nouvelle vidéo en ajoutant une piste audio à une ou plusieurs images fixes existantes ou à une vidéo existante.

Exemple d’utilisation

{
  "steps": {
    "merged": {
      "duration": 12,
      "framerate": "1/4",
      "height": 720,
      "resize_strategy": "pad",
      "robot": "/video/merge",
      "use": [
        {
          "as": "image",
          "name": ":original"
        },
        {
          "as": "audio",
          "name": ":original"
        }
      ],
      "width": 1280
    }
  }
}

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.

• width

  string | number | null

  Largeur de la nouvelle vidéo, en pixels.

  Si la valeur n’est pas spécifiée et que le paramètre preset est disponible, la largeur fournie EN (English) par preset sera appliquée.

• height

  string | number | null

  Hauteur de la nouvelle vidéo, en pixels.

  Si la valeur n’est pas spécifiée et que le paramètre preset est disponible, la hauteur fournie EN (English) par preset sera appliquée.

• preset

  android | android-high | android-low | android_high | android_low | dash-1080p-video | dash-1080p_video | 195 de plus ↓

  Convertit une vidéo selon des paramètres préconfigurés EN (English).

  Vous pouvez utiliser ici la valeur 'empty' si vous spécifiez vos propres paramètres FFmpeg à l’aide du Robot, ou si vous ne souhaitez pas que Transloadit définisse de paramètres d’encodage.

• resize_strategy

  crop | fit | fillcrop | min_fit | pad | stretch(par défaut : "pad")

  Si les valeurs de largeur et de hauteur fournies sont supérieures aux dimensions de l’image d’entrée, le paramètre resize_strategy détermine la façon dont l’image sera redimensionnée pour correspondre à la largeur et à la hauteur indiquées. Consultez les stratégies de redimensionnement disponibles.

• background

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

  La couleur d’arrière-plan de la vidéo obtenue, au format "rrggbbaa" (rouge, vert, bleu, alpha), lorsque ce paramètre est utilisé avec la stratégie de redimensionnement "pad". La couleur par défaut est le noir.

• framerate

  string | number | string(par défaut : "1/5")

  Lors de la fusion d’images pour générer une vidéo, ce paramètre indique la fréquence d’images d’entrée. Une valeur de « 1/5 » signifie que chaque image est affichée pendant 5 secondes avant l’apparition de l’image suivante (l’inverse d’une fréquence d’images de « 5 »). Il en va de même pour « 1/10 », « 1/20 », etc. Une valeur de « 5 » signifie qu’il y a 5 images par seconde.

• image_durations

  Array<string | number>(par défaut : [])

  Lors de la fusion d’images pour générer une vidéo, ce paramètre vous permet de définir combien de temps (en secondes) chaque image sera affichée dans la vidéo. Ainsi, si vous fournissez 3 images et définissez [2.4, 5.6, 9], la première image sera affichée pendant 2,4 s, la deuxième pendant 5,6 s et la dernière pendant 9 s. Le paramètre duration sera automatiquement défini sur la somme des valeurs de image_durations, soit 17 dans notre exemple. Cette valeur peut toutefois être remplacée ; dans ce cas, la dernière image sera affichée jusqu’à ce que la durée définie soit atteinte.

• duration

  string | number | null(par défaut : null)

  Lors de la fusion d’images pour générer une vidéo ou de la fusion d’audio et de vidéo, ce paramètre indique la durée cible souhaitée, en secondes. La valeur à virgule flottante peut comporter une décimale. Si vous souhaitez que toutes les images soient affichées exactement une fois, vous pouvez définir la durée à l’aide de cette formule : duration = numberOfImages / framerate. Cela fonctionne également pour les valeurs inverses de fréquence d’images telles que 1/5.

  Si vous définissez cette valeur sur null (valeur par défaut), la durée du fichier audio d’entrée sera utilisée lors de la fusion d’images avec un fichier audio.

  Lors de la fusion de fichiers audio et vidéo, la durée du fichier vidéo ou audio le plus long est utilisée par défaut.

• audio_delay

  string | number(par défaut : 0)

  Lors de la fusion d’une vidéo et d’un fichier audio, ou d’images et d’un fichier audio pour générer une vidéo, ce paramètre indique le délai souhaité, en secondes, avant le début de la lecture du fichier audio. Si vous fusionnez un fichier vidéo sans son et un fichier audio, mais souhaitez que la lecture audio commence après 5 secondes plutôt qu’immédiatement, c’est le paramètre à utiliser.

• loop

  boolean(par défaut : false)

  Indique si le fichier multimédia le plus court doit être lu en boucle pour atteindre la durée du plus long. Par exemple, si vous fusionnez une vidéo de 1 minute avec un fichier audio de 3 minutes et activez cette option, la vidéo sera lue trois fois de suite pour correspondre à la durée de l’audio.

• replace_audio

  boolean(par défaut : false)

  Indique si l’audio de la vidéo doit être remplacé par un fichier audio fourni.

• vstack

  boolean(par défaut : false)

  Empile verticalement les médias d’entrée. Tous les flux doivent avoir le même format de pixels et la même largeur. Pensez donc à utiliser un Step /video/encode avant d’utiliser ce paramètre pour garantir le respect de ces contraintes.

• image_url

  string

  URL d’une image à fusionner avec l’audio ou la vidéo. Lorsque ce paramètre est fourni, le Robot téléchargera l’image depuis cette URL et la fusionnera avec les autres médias.

• sort_by

  auto | basename | import_order(par défaut : "basename")

  Contrôle l’ordre des entrées regroupées lorsqu’aucun alias numéroté explicite n’est utilisé pour le type d’entrée. Les alias numérotés se terminent par un suffixe numérique tel que _1.

  La valeur par défaut "basename" conserve l’ancien comportement de tri naturel par nom de base.

  Définissez cette option sur "import_order" pour préserver l’ordre des Steps d’importation basés sur un tableau lorsque tous les fichiers d’entrée portent des métadonnées d’ordre d’importation complètes. "auto" applique la même préférence pour l’ordre d’importation, avec le tri naturel par nom de base comme solution de repli.

• transition

  none | crossfade | fade_to_black(par défaut : "none")

  Type d’effet de transition à appliquer entre les clips vidéo concaténés. S’applique uniquement lors de la concaténation de plusieurs vidéos (avec video_1, video_2, etc. ou les entrées pre_roll/post_roll).

  • "none" — Aucun effet de transition. Les vidéos sont assemblées bout à bout.
  • "crossfade" — Un fondu enchaîné progressif d’un clip au suivant (pour la vidéo et l’audio).
  • "fade_to_black" — Le clip actuel disparaît par un fondu au noir, puis le clip suivant apparaît par un fondu depuis le noir.

• transition_duration

  string | number(par défaut : 1)

  Durée de l’effet de transition, en secondes. Ce paramètre ne s’applique que lorsque transition n’est pas "none". Il accepte les valeurs à virgule flottante (par exemple, 0.5 pour une transition de 500 ms) et sa valeur doit être supérieure à 0 dès lors que les transitions sont activées. La transition appliquée est automatiquement limitée à la moitié de la durée du clip le plus court de chaque paire de clips en transition afin d’éviter que les transitions ne se chevauchent.

Démonstrations

Articles de blog associés