Générer des aperçus de fichiers pertinents

Kevin van Zonneveld

Cofondateur · Amsterdam, Pays-Bas · Afficher la bio

Nous avons le plaisir de présenter notre nouveau Robot /file/preview — une fonctionnalité Transloadit conçue pour créer automatiquement des aperçus des formats de fichiers pris en charge, avec une icône de repli. Que vous ayez besoin de vignettes vidéo, de pochettes d’albums ou de formes d’onde audio, d’aperçus de pages de documents, de captures d’écran de sites web ou d’icônes d’archives, ce Robot peut fournir des aperçus qui aident à identifier rapidement les fichiers. Nous gérons la complexité des différents types de fichiers pour que vous puissiez vous concentrer sur votre application.

Le Robot peut être déployé avec quelques lignes de JSON et utilise en interne des stratégies propres à chaque type de fichier. Il peut simplifier la génération d’aperçus et aider les utilisateurs à reconnaître les fichiers dans votre application.

Que peut-il faire ?

🤖/file/preview est conçu pour créer des aperçus pertinents qui aident les utilisateurs à identifier rapidement le contenu des fichiers. Il prend en charge les éléments suivants :

• Images : vignettes optimisées pour les images prises en charge, y compris les formats RAW :
• Vidéos : images extraites ou courts extraits vidéo : (ou une icône de repli si aucun aperçu du contenu ne peut être généré : )
• Audio : image de couverture intégrée (ou visualisation de la forme d’onde si elle n’est pas disponible : )
• Documents : aperçus de la première page
• Pages web : captures d’écran de pages
• Archives : icônes propres au type de fichier

L’aperçu disponible dépend du format, du codec et des données multimédias du fichier. Il n’est pas possible de générer un aperçu du contenu de chaque fichier.

Avec les stratégies par défaut, le Robot utilise une icône propre au type de fichier lorsqu’un aperçu plus riche n’est pas disponible, comme pour l’archive ci-dessus. Consultez la documentation des stratégies pour connaître les stratégies prises en charge et leur ordre de repli.

Le Robot est conçu pour offrir d’emblée des réglages par défaut pratiques et esthétiques, mais son comportement est entièrement personnalisable. Nous y reviendrons plus bas.

Pourquoi Transloadit ?

La génération d’aperçus pour une grande variété de fichiers est complexe en raison de la multitude de formats d’image, de codecs vidéo et de types de documents. Cette complexité est particulièrement marquée pour les clients ayant des besoins spécialisés, comme les photographes qui travaillent avec des formats d’image brute, ou les utilisateurs qui manipulent divers documents Microsoft Office. L’évolution constante des formats d’image et de vidéo exige un investissement continu pour suivre les nouveautés et prendre en charge les formats les plus récents. Consultez les formats pris en charge et la référence du Robot pour connaître les conversions disponibles.

Développer en interne une solution de génération d’aperçus de fichiers nécessite des ressources d’ingénierie importantes, même pour couvrir une partie seulement des nombreux types de fichiers. Ces ressources sont mobilisées à long terme, car la solution interne doit être maintenue et mise à jour pour les nouveaux formats. De plus, le traitement des fichiers téléversés par les utilisateurs est une opération délicate qui peut exposer votre infrastructure aux vulnérabilités des différents outils de traitement de fichiers. Envisagez plutôt de confier la génération d’aperçus à Transloadit. Vous déplacez ainsi ce traitement hors de vos serveurs applicatifs et permettez à votre équipe d’ingénierie de se concentrer sur la création du meilleur service possible pour vos clients, tandis que Transloadit gère la complexité des aperçus de fichiers.

🤖/file/preview peut être combiné à d’autres Robots pour créer des flux de travail propres à votre activité, qui peuvent transformer n’importe quelle partie de votre chaîne de traitement de fichiers. Transloadit peut traiter directement les fichiers téléversés par vos utilisateurs finaux, importer de vastes médiathèques ou même convertir des fichiers à la demande, en transmettant les résultats optimisés directement aux navigateurs à l’aide de notre Smart CDN.

Options de mise en œuvre

Vous disposez de plusieurs moyens de déployer 🤖/file/preview, mais le meilleur point de départ consiste à créer un Template qui fait référence à ce Robot. Un Template est une recette JSON enregistrée dans votre compte qui décrit ce que Transloadit doit faire avec vos fichiers. Vous pouvez créer un Template dans le Template Editor de votre compte, ou à l’aide de notre plugin de fournisseur Terraform.

Prétraitement

Avec le prétraitement, vous créez et enregistrez les aperçus dans votre stockage. Cette opération a généralement lieu lors du premier téléversement du fichier par l’utilisateur, bien avant que l’utilisateur final demande un aperçu. Ce prétraitement peut réduire la latence de la première requête, en contrepartie de coûts d’encodage et de stockage plus élevés et d’une intégration plus complexe que la génération à la demande.

Transloadit peut gérer le téléversement des originaux, générer des aperçus, puis les enregistrer dans votre stockage. Pour confier les téléversements à Transloadit, faites référence à 🤖/upload/handle dans votre Template comme suit :

{
  "allow_steps_override": false,
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "previewed": {
      "robot": "/file/preview",
      "use": ":original",
      "width": 300,
      "height": 200
    },
    "stored": {
      "use": ["previewed", ":original"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "acl": "bucket-default",
      "path": "my_target_folder/${unique_prefix}/${file.url_name}"
    }
  }
}

Remplacez YOUR_AWS_CREDENTIALS par le nom de votre ensemble d’informations d’identification de Template enregistré. Le préfixe unique attribue à chaque original et à chaque aperçu son propre chemin d’objet. acl: "bucket-default" omet l’en-tête ACL généré ; configurez séparément la politique d’accès de votre bucket. Suivez les consignes de configuration et d’autorisations S3 avant d’utiliser ce Template.

Les téléversements proviennent généralement de navigateurs (via Uppy⁠, par exemple), mais les SDK côté serveur peuvent également téléverser des fichiers.

Examinons d’abord le cas du navigateur.

Téléversements côté client

Transloadit peut gérer les téléversements effectués dans le navigateur par les utilisateurs finaux avec Uppy⁠, notre outil de téléversement de fichiers open source pour les navigateurs web. Lorsqu’il reçoit les fichiers, Transloadit suit les Instructions du Template pour générer les aperçus et les stocker dans votre bucket S3. Les originaux sont également enregistrés, car le Step "stored" contenait : "use": ["previewed", ":original"].

Avant d’exécuter le code du navigateur, implémentez un gestionnaire POST /api/transloadit/assembly-options protégé dans votre propre application. Il doit authentifier votre utilisateur, autoriser le téléversement, vérifier l’origine de la requête ou le jeton CSRF de votre application et appliquer vos limites de téléversement. Associez-le à l’identifiant fixe du Template de téléversement ci-dessus ; ne signez pas de Templates ni d’Instructions arbitraires fournis par le navigateur. Activez Signature Authentication pour votre Workspace et conservez allow_steps_override: false dans le Template enregistré.

Sur ce serveur, utilisez l’exemple de génération de signature pour renvoyer { params, signature } avec une valeur auth.expires de courte durée de validité. Renvoyez la chaîne sérialisée params sans la modifier et conservez l’Auth Secret sur le serveur. Ce point de terminaison appartient à votre application ; il ne fait pas partie de l’API Transloadit.

Installez @uppy/core, @uppy/dashboard et @uppy/transloadit avec Yarn dans votre projet côté navigateur, et ajoutez un élément avec id="uppy-dashboard" à la page. Intégrez ce code à l’aide de votre outil de bundling :

import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import Transloadit from '@uppy/transloadit'

import '@uppy/core/dist/style.min.css'
import '@uppy/dashboard/dist/style.min.css'

const uppy = new Uppy()
  .use(Dashboard, {
    inline: true,
    // This is the element where the dashboard will be rendered:
    target: '#uppy-dashboard',
  })
  .use(Transloadit, {
    waitForEncoding: true,
    assemblyOptions: async () => {
      const response = await fetch('/api/transloadit/assembly-options', {
        method: 'POST',
        credentials: 'same-origin',
      })
      if (!response.ok) {
        throw new Error(`Could not authorize the upload (HTTP ${response.status})`)
      }
      return response.json()
    },
  })

uppy.on('transloadit:complete', (assembly) => {
  const preview = assembly.results?.previewed?.[0]
  if (preview) {
    console.log('Preview object URL:', preview.ssl_url)
  } else {
    console.log('No previews were generated.')
  }
})

L’exportation S3 met à jour les résultats sous le Step qui les produit, previewed. Une valeur ssl_url renvoyée ne donne pas accès à un objet S3 privé et ne garantit pas une URL de téléchargement permanente. Autorisez les téléchargements dans votre application, par exemple avec des URL de téléchargement S3 de courte durée générées par votre serveur.

Uppy a été créé par Transloadit. Il propose bien plus de fonctionnalités que cet article ne peut en présenter. Consultez le site web d’Uppy⁠ pour en savoir plus.

Il existe aussi des SDK pour Android et iOS, si vous souhaitez intégrer cette fonctionnalité à des applications mobiles natives.

Téléversements côté serveur

Les serveurs peuvent tout aussi bien téléverser des fichiers vers Transloadit. Voici un exemple avec Node.js :

Installez @transloadit/node avec yarn add @transloadit/node. Enregistrez l’exemple sous upload.mjs et exécutez-le avec node upload.mjs. Définissez d’abord TRANSLOADIT_KEY, TRANSLOADIT_SECRET et TRANSLOADIT_TEMPLATE_ID dans l’environnement du serveur, en utilisant l’identifiant du Template de téléversement ci-dessus, et remplacez ./file.mp4 par un fichier local accessible en lecture. Ne placez pas l’Auth Secret dans le code du navigateur ni dans le système de gestion de versions.

import { Transloadit } from '@transloadit/node'

const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, TRANSLOADIT_TEMPLATE_ID } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !TRANSLOADIT_TEMPLATE_ID) {
  throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and TRANSLOADIT_TEMPLATE_ID.')
}

const transloadit = new Transloadit({
  authKey: TRANSLOADIT_KEY,
  authSecret: TRANSLOADIT_SECRET,
})

const assembly = await transloadit.createAssembly({
  params: { template_id: TRANSLOADIT_TEMPLATE_ID },
  files: { file: './file.mp4' },
  waitForCompletion: true,
})

const preview = assembly.results?.previewed?.[0]
if (preview) {
  console.log('Preview object URL:', preview.ssl_url)
} else {
  console.log('No previews were generated.')
}

Des SDK sont disponibles pour bien d’autres langages côté serveur et facilitent l’intégration, mais vous pouvez aussi utiliser directement notre API REST.

Importations

Au lieu de confier les téléversements à Transloadit, Transloadit peut importer des fichiers depuis des sources cloud comme S3, générer des aperçus, puis les exporter vers S3 ou d’autres fournisseurs de stockage. Cela peut concerner un seul fichier ou des buckets entiers contenant de nombreux téraoctets de fichiers.

À titre d’exemple, nous ajouterons aussi 🤖/file/filter au Template ci-dessous pour montrer comment filtrer par type de fichier et, dans ce cas, générer des aperçus uniquement pour les fichiers audio. Vous pourriez adapter ce filtre à d’autres propriétés, comme la taille du fichier, le débit ou le type de média. Voici le Template complet à créer dans le Template Editor de votre compte :

{
  "steps": {
    "imported": {
      "robot": "/s3/import",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "my_source_folder/"
    },
    "audio_filtered": {
      "use": "imported",
      "robot": "/file/filter",
      "accepts": [["${file.type}", "==", "audio"]],
      "error_on_decline": false
    },
    "previewed": {
      "robot": "/file/preview",
      "use": "audio_filtered",
      "width": 300,
      "height": 200,
      "format": "png"
    },
    "stored": {
      "use": "previewed",
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "acl": "bucket-default",
      "path": "my_target_folder/${unique_prefix}/${file.url_name}"
    }
  }
}

Vous pouvez faire référence à ce Template et l’exécuter avec n’importe lequel de nos SDK. Pour Node.js, utilisez le même paquet et la même configuration d’environnement serveur que ci-dessus, mais attribuez à TRANSLOADIT_TEMPLATE_ID l’identifiant de ce Template d’importation. Enregistrez le code suivant sous import.mjs et exécutez node import.mjs. Aucun téléversement local n’est nécessaire. Si aucun fichier audio ne correspond au filtre, aucun aperçu n’est disponible en lecture :

import { Transloadit } from '@transloadit/node'

const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, TRANSLOADIT_TEMPLATE_ID } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !TRANSLOADIT_TEMPLATE_ID) {
  throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and TRANSLOADIT_TEMPLATE_ID.')
}

const transloadit = new Transloadit({
  authKey: TRANSLOADIT_KEY,
  authSecret: TRANSLOADIT_SECRET,
})

const assembly = await transloadit.createAssembly({
  params: { template_id: TRANSLOADIT_TEMPLATE_ID },
  waitForCompletion: true,
})

const preview = assembly.results?.previewed?.[0]
if (preview) {
  console.log('Preview object URL:', preview.ssl_url)
} else {
  console.log('No previews were generated.')
}

À la demande

Enfin, vous pouvez aussi générer des aperçus à la demande avec notre Smart CDN. Transloadit n’effectue alors aucun traitement tant qu’un utilisateur ne demande pas l’aperçu. Transloadit importe ensuite le fichier original depuis votre stockage, génère l’aperçu et le transmet directement à l’utilisateur final. Nous mettons le résultat en cache à proximité de l’utilisateur final.

Cette approche présente les avantages suivants :

• L’aperçu n’est créé que lorsqu’un utilisateur le demande, ce qui réduit les coûts pour les fichiers multimédias qui ne sont pas effectivement demandés.
• Un résultat en cache peut être transmis sans nouveaux frais d’encodage tant qu’il reste disponible et peut être mis en cache. La diffusion depuis le cache entraîne toujours des frais de bande passante. Un résultat expiré ou évincé du cache peut nécessiter un nouveau traitement, avec de nouveaux frais de traitement.
• L’intégration est plus simple, car vous n’avez pas à gérer vous-même les aperçus (les enregistrer, stocker leurs références, etc.). Il vous suffit de créer un Template et d’ajouter une URL Smart CDN pour le fichier à votre page web ou à votre application.
• Vous pouvez adapter l’aperçu à l’appareil, à la résolution et à la bande passante de l’utilisateur final, entre autres. Vous évitez ainsi de transmettre des octets qui n’améliorent pas l’expérience utilisateur. Cela économise de la bande passante, de la batterie et du temps.

Pour en savoir plus sur les aperçus à la demande, les URL signées et les mesures de diffusion, consultez notre article : Aperçus multimédias à la demande avec Smart CDN.

Voici un exemple de Template qui demande à Transloadit d’importer un fichier multimédia depuis S3, de générer un aperçu et de le diffuser avec notre Smart CDN :

{
  "steps": {
    "imported": {
      "robot": "/s3/import",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "${fields.input}"
    },
    "previewed": {
      "use": "imported",
      "robot": "/file/preview",
      "width": "${fields.w}"
    },
    "served": {
      "use": "previewed",
      "robot": "/file/serve"
    }
  }
}

La structure de l’URL pour ce Template est la suivante :

https://my-workspace.tlcdn.com/my-template/file.mp4?w=300

Utilisez le nom de votre ensemble d’informations d’identification de Template enregistré pour YOUR_AWS_CREDENTIALS et placez le fichier source à l’emplacement file.mp4 dans ce bucket S3. Ici, my-template est le nom du Template, ${fields.input} reçoit file.mp4 et ${fields.w} reçoit 300 depuis l’URL. Remplacez les valeurs fictives du Workspace et du Template par les vôtres. Cet exemple montre la structure de l’URL ; pour une diffusion protégée, autorisez le fichier et les dimensions demandés sur votre serveur et générez une URL signée avec une date d’expiration avant de l’envoyer au navigateur. Suivez le guide de signature Smart CDN. Définissez require_signature_auth sur 1 à l’aide de l’API des Templates ; ce réglage du Template se trouve en dehors du JSON des Instructions ci-dessus. N’exposez pas de point de terminaison de signature généraliste qui accepte des chemins ou des transformations arbitraires.

Personnaliser l’aperçu

Bien que 🤖/file/preview propose d’emblée des réglages par défaut pratiques et esthétiques, vous pouvez contrôler sa sortie à l’aide de plusieurs paramètres pour l’adapter à l’apparence de votre application :

• format : format de sortie de la vignette
• width et height : dimensions en pixels
• resize_strategy : méthode d’ajustement de l’aperçu aux dimensions
• background : couleur d’arrière-plan des marges au format hexadécimal (#rrggbb[aa])
• strategy : personnalisation de la génération d’aperçus par type de fichier (audio, vidéo, image, etc.)

Pour les formes d’onde audio :

• waveform_center_color et waveform_outer_color : couleurs du dégradé au format hexadécimal
• waveform_height et waveform_width : dimensions de la forme d’onde

Pour les icônes :

• icon_style : apparence de l’icône de repli
• icon_text_color : couleur du texte au format hexadécimal
• icon_text_font : famille de polices
• icon_text_content : texte affiché sur l’icône

Pour les extraits vidéo :

• clip_format : format de l’animation
• clip_offset : position de départ en secondes
• clip_duration : durée en secondes
• clip_framerate : nombre d’images par seconde
• clip_loop : lecture de l’animation en boucle ou non

Pour l’optimisation des images :

• optimize : activation de l’optimisation de la taille du fichier
• optimize_priority : équilibre entre vitesse de conversion et taux de compression
• optimize_progressive : activation du chargement progressif

Pour connaître les valeurs acceptées, les valeurs par défaut, les limites et le comportement propre à chaque stratégie, consultez la documentation de 🤖/file/preview.

Considérations de sécurité

Pour protéger vos fichiers et contrôler l’accès à la génération d’aperçus, nous recommandons de mettre en place la signature des requêtes pour les intégrations côté client (Uppy, Smart CDN, mobile). Pour la diffusion via Smart CDN en particulier, autorisez l’accès au fichier et à la transformation demandés avant de signer une URL Smart CDN. La signature protège l’URL ; toute personne qui l’obtient peut l’utiliser tant qu’elle reste valide.

Pour des informations détaillées, dont des exemples dans de nombreux langages de programmation, consultez notre documentation sur les URL signées Smart CDN.

Pensez à :

• Toujours générer les URL signées sur votre serveur,
• Ne jamais exposer votre Auth Secret dans le code côté client, et
• Définir une date d’expiration pour vos URL signées.

Une expiration plus courte réduit la période pendant laquelle une URL peut être réutilisée. Une expiration plus longue permet à une URL de rester utilisable plus longtemps ; elle ne garantit ni la conservation en cache, ni la présence du résultat en cache, ni une réduction des coûts de traitement. La diffusion depuis le cache reste facturable, et les résultats expirés ou évincés du cache peuvent nécessiter un nouveau traitement.

Cas d’utilisation avancés

Cet article présente les principales façons d’utiliser 🤖/file/preview, mais il existe de nombreuses manières de l’intégrer à des chaînes de traitement plus complexes :

• Génération automatisée par lots : planifiez la génération d’aperçus pour des buckets de stockage entiers afin de maintenir des aperçus à jour à grande échelle.
• Intégrations événementielles : déclenchez automatiquement le traitement des aperçus à l’arrivée de nouveaux fichiers pour que les aperçus soient toujours prêts au moment voulu.
• Composer des flux de travail hybrides : combinez 🤖/file/preview avec d’autres Robots Transloadit — comme 🤖/image/facedetect ou 🤖/video/encode — pour créer des transformations en plusieurs étapes au sein d’un seul flux de travail.
• Options de stockage étendues : au-delà d’AWS S3, vous pouvez intégrer facilement tous les principaux fournisseurs de stockage cloud, ainsi que votre propre infrastructure personnalisée (stockage compatible S3 ou SFTP).
• Mise en cache personnalisable : associez 🤖/file/preview à des configurations Smart CDN adaptées à vos exigences de performance et de fiabilité.
• Utiliser votre propre CDN : pour les déploiements à fort volume, les clients peuvent tirer parti de leurs contrats et de leur infrastructure existants en associant notre plateforme d’encodage à leur propre CDN.

Tarifs et disponibilité

Consultez notre page des tarifs pour connaître les forfaits, les tarifs et les restrictions des forfaits en vigueur, ainsi que la documentation tarifaire du Robot.

Pour aller plus loin

Ces ressources pourraient vous intéresser :

• Nos démonstrations EN (English) pour découvrir d’autres fonctionnalités et les possibilités de combinaison.
• Notre Smart CDN pour en savoir plus sur la diffusion à la demande de fichiers, d’aperçus et d’autres conversions.
• L’article Aperçus multimédias à la demande avec Smart CDN pour une démonstration, des mesures de diffusion et un exemple de signature côté serveur.

Prochaines étapes

Pour commencer, suivez ces étapes :

1. Inscrivez-vous pour créer un compte Transloadit.
2. Créez votre premier Template avec 🤖/file/preview.
3. Testez différentes options d’aperçu et d’intégration avec notre Template Editor.
4. Intégrez les aperçus à votre application.

Besoin d’aide pour démarrer ? Nous construisons des Robots, mais nous sommes de vraies personnes qui aiment donner un coup de main ! N’hésitez pas à nous contacter à l’adresse support@transloadit.com.

Sinon, bon transloading 🙂