Transcrire la parole dans des fichiers audio ou vidéo

🤖/speech/transcribe transcrit la parole contenue dans des fichiers audio ou vidéo.

{
  "steps": {
    "transcribed": {
      "use": ":original",
      "robot": "/speech/transcribe",
      "provider": "aws",
      "format": "json",
      "speaker_labels": true,
      "max_speakers": 3
    }
  }
}

{
  "text": "Hello there. Hi!",
  "words": [
    { "text": "Hello", "startTime": 0, "endTime": 0.5, "speaker": "speaker_1" },
    { "text": "there", "startTime": 0.6, "endTime": 1, "speaker": "speaker_1" },
    { "text": "Hi!", "startTime": 1.2, "endTime": 1.8, "speaker": "speaker_2" }
  ],
  "segments": [
    { "text": "Hello there", "startTime": 0, "endTime": 1, "speaker": "speaker_1" },
    { "text": "Hi!", "startTime": 1.2, "endTime": 1.8, "speaker": "speaker_2" }
  ]
}

Exemple d’utilisation

{
  "steps": {
    "transcribed": {
      "format": "text",
      "provider": "replicate",
      "robot": "/speech/transcribe",
      "target_language": "french",
      "use": ":original"
    }
  }
}

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.

• provider

  auto | aws | gcp | replicate(par défaut : "auto")

  Choisit le meilleur fournisseur en fonction de votre requête.

  Définissez ce paramètre sur "aws", "gcp" ou "replicate" pour imposer un fournisseur spécifique. Lorsqu’il est défini sur "auto", Transloadit utilise "replicate" par défaut et utilise "aws" lorsque speaker_labels est activé. Si speaker_labels est activé et que vocabulary est défini avec une valeur non vide, "auto" utilise "gcp".

• vocabulary

  Array<string>

  Mots ou expressions à privilégier lors de la reconnaissance vocale, avec l’orthographe souhaitée dans la sortie. Par exemple, ["Transloadit", "Uppy", "tus"] aide le fournisseur à reconnaître les noms de marques et de produits.

  Fournissez jusqu’à 50 termes distincts, chacun comprenant entre 1 et 100 caractères après suppression des espaces en début et en fin de terme. Les termes ne doivent contenir aucun caractère de contrôle ni former de doublons lorsque la casse est ignorée. Les termes joints avec ", " ne doivent pas dépasser 200 octets en UTF-8, afin que tous les termes respectent la limite de taille de l’invite de Whisper. L’omission de ce paramètre ou la fourniture d’un tableau vide laisse la reconnaissance inchangée.

  Pris en charge par "replicate" et "gcp". Lorsqu’un vocabulaire est fourni, Replicate utilise un modèle WhisperX large-v3 acceptant une invite et fournissant des horodatages alignés sur les mots. GCP utilise des indications de phrases intégrées à pondération renforcée. Les requêtes qui spécifient explicitement "aws" avec un vocabulaire renvoient une erreur de validation, car AWS exige un Custom Vocabulary créé au préalable. Utilisez plutôt "auto", "replicate" ou "gcp".

  Les indications améliorent la reconnaissance, mais ne garantissent pas qu’un terme soit reconnu. Ensuite, les correspondances complètes, sans distinction de casse, utilisent l’orthographe que vous avez fournie dans tous les formats de sortie, y compris les mots et les segments de locuteur en JSON, sans modifier les horodatages. Les mots de sonorité similaire ne sont jamais remplacés : "transloadit" devient "Transloadit", mais "Transloaded" reste inchangé.

• granularity

  full | list(par défaut : "full")

  "full" et "list" renvoient actuellement la même réponse de transcription complète. "list" reste accepté pour assurer la rétrocompatibilité.

• format

  json | meta | srt | text | webvtt(par défaut : "json")

  Format de sortie de la transcription.

  • "text" produit un fichier texte brut que vous pouvez stocker et traiter.
  • "json" produit un fichier JSON contenant des mots horodatés. Lorsque speaker_labels est activé, les mots peuvent inclure des étiquettes speaker et le JSON peut également inclure des segments regroupés par locuteur.
  • "srt" et "webvtt" produisent des fichiers de sous-titres dans leurs formats respectifs, qui peuvent être stockés séparément ou utilisés dans d’autres Steps d’encodage.
  • "meta" ne renvoie pas de fichier, mais stocke les données dans l’objet fichier de Transloadit (sous ${file.meta.transcription.text}, ${file.meta.transcription.words} et, lorsque des étiquettes de locuteur sont disponibles, ${file.meta.transcription.segments}), qui est transmis entre les Steps d’encodage. Vous pouvez ainsi utiliser ces valeurs pour incruster les données dans des vidéos, effectuer un filtrage à partir de ces données, etc.

• speaker_labels

  boolean(par défaut : false)

  Lorsque ce paramètre est activé, Transloadit demande au fournisseur de transcription de distinguer les différents locuteurs. Les sorties JSON et meta peuvent alors inclure des étiquettes speaker, telles que "speaker_1", sur chaque mot, ainsi que des segments regroupés par locuteur. Le comportement des sorties texte, SRT et WebVTT reste inchangé.

  Les étiquettes de locuteur identifient les voix récurrentes, et non les noms réels des personnes. La précision dépend de la qualité audio, du bruit de fond, du chevauchement des paroles et du nombre de locuteurs.

• max_speakers

  string | number(par défaut : 10)

  Le nombre maximal de locuteurs à détecter lorsque speaker_labels est activé.

• source_language

  string(par défaut : "en-US")

  Définit la langue parlée pour les fournisseurs "aws" et "gcp". La transcription reste dans la langue parlée ; ce paramètre ne traduit pas les paroles.

  La langue doit être spécifiée au format BCP-47⁠, par exemple "en-GB", "de-DE" ou "fr-FR". Veuillez également consulter la liste des langues prises en charge par le fournisseur gcp⁠ et le fournisseur aws⁠.

• target_language

  string

  Fournit une indication sur la langue parlée au fournisseur "replicate". Omettez ce paramètre pour détecter automatiquement la langue parlée. Lorsque la langue parlée est connue, définissez ce paramètre sur le nom complet de la langue en anglais et en minuscules, par exemple "french". Malgré son nom, ce paramètre ne traduit pas les paroles.

  Pour les fournisseurs "aws" et "gcp", utilisez plutôt source_language.

Démonstrations

Articles de blog associés