Generar vistas previas útiles de archivos

Kevin van Zonneveld

Cofundador · Ámsterdam, Países Bajos · Mostrar bio

Nos enorgullece presentar nuestro nuevo Robot /file/preview, una función de Transloadit diseñada para crear automáticamente vistas previas de formatos de archivo compatibles, con un icono como alternativa. Tanto si necesitas miniaturas de video, carátulas de audio o formas de onda, vistas previas de páginas de documentos, capturas de sitios web o iconos de archivos comprimidos, este Robot puede generar vistas previas que ayudan a las personas a identificar archivos rápidamente. Nos encargamos de la complejidad de los distintos tipos de archivo, mientras tú te concentras en crear tu aplicación.

El Robot se puede poner en marcha con unas pocas líneas de JSON y utiliza internamente estrategias específicas para cada tipo de archivo. Puede simplificar la generación de vistas previas y ayudar a los usuarios a reconocer archivos en tu aplicación.

¿Qué puede hacer?

🤖/file/preview está diseñado para crear vistas previas útiles que ayudan a los usuarios a identificar rápidamente el contenido de los archivos. Ofrece:

• Imágenes: Miniaturas optimizadas para imágenes compatibles, incluidos los formatos RAW:
• Videos: Fotogramas extraídos o clips cortos: (o un icono alternativo cuando no se puede generar una vista previa del contenido: )
• Audio: Carátula integrada (o visualización de la forma de onda si no hay carátula: )
• Documentos: Vistas previas de la primera página
• Páginas web: Capturas de pantalla de las páginas
• Archivos comprimidos: Iconos específicos de cada tipo

La vista previa disponible depende del formato, el códec y los datos multimedia del archivo. No es posible generar una vista previa del contenido de todos los archivos.

Con las estrategias predeterminadas, el Robot recurre a un icono específico del tipo de archivo cuando no hay una vista previa más detallada disponible, como en el ejemplo del archivo comprimido anterior. Consulta la documentación sobre estrategias para conocer las estrategias compatibles y su orden de alternativas.

El Robot está diseñado para ofrecer resultados prácticos y atractivos de forma predeterminada, pero su comportamiento se puede personalizar por completo. Más adelante veremos cómo hacerlo.

¿Por qué Transloadit?

Generar vistas previas de una amplia variedad de archivos es complejo debido a la enorme diversidad de formatos de imagen, códecs de video y tipos de documento. Esta complejidad es especialmente marcada para clientes de sectores especializados, como fotógrafos que trabajan con formatos de imagen RAW o usuarios que manejan diversos documentos de Microsoft Office. Debido a la constante evolución de los formatos de imagen y video, es necesario invertir continuamente para mantenerse al día y admitir los formatos más recientes. Consulta nuestros formatos compatibles y la referencia del Robot para conocer las conversiones disponibles.

Desarrollar una solución propia para generar vistas previas de archivos requiere una inversión considerable de recursos de ingeniería, incluso para abarcar solo una parte de los numerosos tipos de archivo. Además, estos recursos quedan comprometidos a largo plazo, ya que la solución interna necesita mantenimiento y actualizaciones para admitir nuevos formatos. Por otra parte, procesar archivos subidos por los usuarios es una tarea delicada que puede hacer que tu infraestructura sea susceptible a vulnerabilidades de las distintas herramientas de procesamiento de archivos. Considera delegar la generación de vistas previas a Transloadit para trasladar ese procesamiento fuera de los servidores de tu aplicación y permitir que tu equipo de ingeniería se concentre en crear el mejor servicio posible para tus clientes, mientras Transloadit se encarga de la parte compleja de las vistas previas de archivos.

🤖/file/preview se puede combinar con otros Robots para crear flujos de trabajo específicos para tu negocio. Estos flujos de trabajo pueden transformar cualquier parte de tu pipeline de archivos. Transloadit puede trabajar directamente con los archivos que suben tus usuarios finales, importar grandes bibliotecas multimedia o incluso convertir archivos bajo demanda, transmitiendo los resultados optimizados directamente a los navegadores mediante nuestro Smart CDN.

Opciones de implementación

Tienes varias formas de poner en marcha 🤖/file/preview, pero la mejor manera de empezar es crear un Template que haga referencia a este Robot. Un Template es una receta JSON de tu cuenta que describe qué debe hacer Transloadit con tus archivos. Puedes crear un Template en el Template Editor de tu cuenta o mediante nuestro Terraform Provider Plugin.

Preprocesamiento

Con el preprocesamiento, creas y guardas las vistas previas en tu almacenamiento. Esto suele hacerse cuando el usuario sube el archivo por primera vez, mucho antes de que el usuario final solicite una vista previa. Este tipo de preprocesamiento puede reducir la latencia de la primera solicitud, a cambio de mayores costos de encoding y almacenamiento, así como una integración más compleja que la generación bajo demanda.

Transloadit puede gestionar las subidas de los originales, generar vistas previas y luego guardarlas en tu almacenamiento. Para que Transloadit gestione las subidas, incluye una referencia a 🤖/upload/handle en tu Template de esta manera:

{
  "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}"
    }
  }
}

Reemplaza YOUR_AWS_CREDENTIALS por el nombre de tu credencial de Template guardada. El prefijo único proporciona una ruta de objeto propia a cada original y a cada vista previa. acl: "bucket-default" omite el encabezado ACL generado; configura por separado la política de acceso de tu bucket. Sigue las indicaciones de configuración y permisos de S3 antes de usar este Template.

Las subidas suelen proceder de navegadores (por ejemplo, mediante Uppy⁠), pero los SDK de backend también pueden subir archivos.

Veamos primero el caso de uso del navegador.

Subidas desde el frontend

Transloadit podría gestionar las subidas que los usuarios finales realizan desde el navegador mediante Uppy⁠, nuestra herramienta de código abierto para subir archivos desde navegadores web. Al recibir los archivos, Transloadit seguirá las Instructions del Template, por lo que generará vistas previas y las guardará en tu bucket de S3. Los originales también se guardarán, porque en el Step "stored" teníamos: "use": ["previewed", ":original"].

Antes de ejecutar el código del navegador, implementa un controlador protegido de POST /api/transloadit/assembly-options en tu propia aplicación. Este debe autenticar a tu usuario, autorizar la subida, verificar el origen de la solicitud o el token CSRF de tu aplicación y aplicar tus límites de subida. Vincúlalo al ID fijo del Template de subida anterior; no firmes Templates ni Instructions arbitrarios proporcionados por el navegador. Activa Signature Authentication para tu Workspace y mantén allow_steps_override: false en el Template guardado.

En ese backend, usa el ejemplo de generación de firmas para devolver { params, signature } con un auth.expires de corta duración. Devuelve la cadena serializada params sin cambios y mantén el Auth Secret en el servidor. Este endpoint pertenece a tu aplicación; no es un endpoint de la API de Transloadit.

Instala @uppy/core, @uppy/dashboard y @uppy/transloadit con Yarn en tu proyecto para el navegador y añade a la página un elemento con id="uppy-dashboard". Incluye este código mediante tu empaquetador:

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.')
  }
})

La exportación a S3 actualiza los resultados del Step que los genera, previewed. Un ssl_url devuelto no concede acceso a un objeto privado de S3 ni garantiza una URL de descarga permanente. Autoriza las descargas en tu aplicación, por ejemplo, con URL de descarga de S3 de corta duración generadas por tu backend.

Uppy fue creado por Transloadit. Incluye más funciones de las que caben en este artículo, así que consulta el sitio web de Uppy⁠ para obtener más información.

También hay SDK para Android e iOS, por si quieres integrarlo en aplicaciones móviles nativas.

Subidas desde el backend

Los backends también pueden subir archivos a Transloadit. Así se vería en Node.js:

Instala @transloadit/node con yarn add @transloadit/node. Guarda el ejemplo como upload.mjs y ejecútalo con node upload.mjs. Primero, configura TRANSLOADIT_KEY, TRANSLOADIT_SECRET y TRANSLOADIT_TEMPLATE_ID en el entorno del servidor usando el ID del Template de subida anterior, y reemplaza ./file.mp4 por un archivo local con permisos de lectura. Mantén el Auth Secret fuera del código del navegador y del control de versiones.

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.')
}

Hay SDK para muchos más lenguajes de backend que facilitan la integración, pero también puedes interactuar directamente con nuestra REST API.

Importaciones

En lugar de dejar que Transloadit gestione las subidas, Transloadit puede importar archivos desde fuentes en la nube como S3, generar vistas previas y exportarlas a S3 u otros proveedores de almacenamiento. Esto se podría hacer para un solo archivo o para buckets enteros que contengan muchos terabytes de archivos.

A modo de ejemplo, también añadiremos 🤖/file/filter al Template siguiente para mostrar cómo podrías filtrar por tipo de archivo y, en este caso, generar vistas previas solo de archivos de audio. Esto se podría adaptar para filtrar por otras propiedades, como el tamaño del archivo, la tasa de bits, el tipo de contenido multimedia, etc. Este es el Template completo que crearías en el Template Editor de tu cuenta:

{
  "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}"
    }
  }
}

Puedes hacer referencia a este Template y ejecutarlo con cualquiera de nuestros SDK. Para Node.js, usa el mismo paquete y la misma configuración del entorno del servidor que antes, pero asigna a TRANSLOADIT_TEMPLATE_ID el ID de este Template de importación. Guarda lo siguiente como import.mjs y ejecuta node import.mjs. No hace falta subir ningún archivo local. Si ningún archivo de audio coincide con el filtro, no habrá vistas previas que leer:

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.')
}

Bajo demanda

Por último, también puedes generar vistas previas bajo demanda mediante nuestro Smart CDN. Esto significa que Transloadit no realiza ningún trabajo hasta que un usuario solicita la vista previa. Entonces, Transloadit importa el archivo original desde tu almacenamiento, genera la vista previa y la entrega directamente al usuario final. Almacenamos el resultado en caché cerca del usuario final.

Esto ofrece las siguientes ventajas:

• La vista previa solo se crea cuando los usuarios la solicitan, lo que ahorra costos en archivos multimedia que en realidad no se solicitan.
• Un resultado en caché se puede entregar sin otro cargo por encoding mientras siga disponible y pueda almacenarse en caché. La entrega desde la caché sigue generando cargos por ancho de banda. Un resultado caducado o eliminado de la caché puede necesitar un nuevo procesamiento, con nuevos cargos de procesamiento.
• La integración es más sencilla, ya que no necesitas gestionar las vistas previas por tu cuenta (guardarlas, almacenar referencias, etc.). Basta con crear un Template y añadir a tu página web o aplicación una URL de Smart CDN para el activo.
• Puedes adaptar la vista previa al dispositivo, la resolución, el ancho de banda, etc., del usuario final. Así evitas desperdiciar bytes en una entrega que no mejora la experiencia del usuario. Esto ahorra ancho de banda, batería y tiempo.

Si quieres saber más sobre las vistas previas bajo demanda, las URL firmadas y las mediciones de entrega, consulta nuestro artículo: Vistas previas multimedia bajo demanda con Smart CDN.

Este es un Template de ejemplo que indica a Transloadit que importe un archivo multimedia desde S3, genere una vista previa y la entregue mediante nuestro 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 estructura de la URL para este Template es:

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

Usa el nombre de tu credencial de Template guardada para YOUR_AWS_CREDENTIALS y coloca el archivo de origen en file.mp4 dentro de ese bucket de S3. Aquí, my-template es el nombre del Template, ${fields.input} recibe file.mp4 y ${fields.w} recibe 300 de la URL. Reemplaza los marcadores de Workspace y Template por tus propios valores. Esto muestra la estructura de la URL; para proteger la entrega, autoriza el archivo y las dimensiones solicitados en tu backend y genera una URL firmada con una fecha de vencimiento antes de enviarla al navegador. Sigue la guía de firma de Smart CDN. Establece require_signature_auth en 1 mediante la API de Templates; es una configuración del Template que queda fuera del JSON de Instructions anterior. No expongas un endpoint de firma de uso general que acepte rutas o transformaciones arbitrarias.

Personaliza la vista previa

Aunque 🤖/file/preview ofrece resultados prácticos y atractivos de forma predeterminada, puedes controlar su salida mediante varios parámetros para adaptarla al aspecto de tu aplicación:

• format: Formato de salida de la miniatura
• width y height: Dimensiones en píxeles
• resize_strategy: Cómo ajustar la vista previa a las dimensiones
• background: Color de fondo del relleno en formato hexadecimal (#rrggbb[aa])
• strategy: Personalizar la generación de vistas previas por tipo de archivo (audio, video, imagen, etc.)

Para formas de onda de audio:

• waveform_center_color y waveform_outer_color: Colores del degradado en formato hexadecimal
• waveform_height y waveform_width: Dimensiones de la forma de onda

Para iconos:

• icon_style: Apariencia del icono alternativo
• icon_text_color: Color del texto en formato hexadecimal
• icon_text_font: Familia tipográfica
• icon_text_content: Texto que se muestra en el icono

Para clips de video:

• clip_format: Formato de la animación
• clip_offset: Posición inicial en segundos
• clip_duration: Duración en segundos
• clip_framerate: Fotogramas por segundo
• clip_loop: El parámetro controla si la animación se reproduce en bucle

Para optimización de imágenes:

• optimize: Activar la optimización del tamaño del archivo
• optimize_priority: Equilibrio entre velocidad de conversión y relación de compresión
• optimize_progressive: Activar la carga progresiva

Para conocer los valores aceptados, los valores predeterminados, los límites y el comportamiento específico de cada estrategia, consulta la documentación de 🤖/file/preview.

Consideraciones de seguridad

Para proteger tus archivos y controlar el acceso a la función de vistas previas, recomendamos implementar la firma de solicitudes en las integraciones de frontend (Uppy, Smart CDN, móviles). En particular, para la entrega mediante Smart CDN, autoriza el acceso al archivo y la transformación solicitados antes de firmar una URL de Smart CDN. La firma protege la URL; cualquier persona que la obtenga puede usarla mientras siga siendo válida.

Para obtener información detallada, incluidos ejemplos en muchos lenguajes de programación, consulta nuestra documentación sobre las URL firmadas de Smart CDN.

Recuerda:

• Generar siempre las URL firmadas en tu backend,
• No exponer nunca tu Auth Secret en código del lado del cliente, e
• Implementar una fecha de vencimiento para tus URL firmadas.

Los plazos de vencimiento más cortos reducen la ventana de repetición. Un plazo más largo permite que una URL se pueda usar durante más tiempo; no garantiza que el resultado permanezca en caché, que las solicitudes se resuelvan desde la caché ni que se reduzcan los costos de procesamiento. La entrega desde la caché sigue siendo facturable, y los resultados caducados o eliminados de la caché pueden requerir un nuevo procesamiento.

Casos de uso avanzados

Aunque este artículo cubre las formas básicas de usar 🤖/file/preview, hay muchas maneras de integrarlo en pipelines más complejos:

• Generación automática por lotes: Programa la generación de vistas previas para buckets de almacenamiento completos y mantén las vistas previas actualizadas a gran escala.
• Integraciones basadas en eventos: Activa el procesamiento de vistas previas automáticamente cada vez que lleguen archivos nuevos, para que siempre estén listas cuando se necesiten.
• Combina flujos de trabajo híbridos: Combina 🤖/file/preview con otros Robots de Transloadit, como 🤖/image/facedetect o 🤖/video/encode, para crear transformaciones de varios Steps en un solo flujo de trabajo.
• Más opciones de almacenamiento: Además de AWS S3, puedes integrarlo fácilmente con todos los principales proveedores de almacenamiento en la nube, así como con tu propia infraestructura personalizada (almacenamiento compatible con S3 o SFTP).
• Caché personalizable: Combina 🤖/file/preview con configuraciones de Smart CDN que se ajusten a tus requisitos de rendimiento y fiabilidad.
• Usa tu propia CDN: Para implementaciones de gran volumen, los clientes pueden aprovechar sus contratos e infraestructura existentes al combinar nuestra plataforma de encoding con su propia CDN.

Precios y disponibilidad

Consulta nuestra página de precios para conocer los planes de suscripción, las tarifas y las restricciones de los planes vigentes, así como la documentación del Robot sobre precios.

Lecturas adicionales

Quizá te interesen los siguientes recursos:

• Demos EN (English) para conocer otras funciones y cómo puedes combinarlas.
• Smart CDN para saber más sobre cómo entregar archivos, vistas previas y otras conversiones bajo demanda.
• Vistas previas multimedia bajo demanda con Smart CDN para consultar una demo, mediciones de entrega y un ejemplo de firma del lado del servidor.

Próximos pasos

Para empezar, sigue estos pasos:

1. Regístrate para obtener una cuenta de Transloadit.
2. Crea tu primer Template con 🤖/file/preview.
3. Prueba distintas opciones de vista previa e integración con nuestro Template Editor.
4. Integra las vistas previas en tu aplicación.

¿Necesitas ayuda para empezar? Creamos Robots, ¡pero somos personas de verdad a las que les gusta ayudar! No dudes en contactarnos en support@transloadit.com.

Si ya tienes todo listo, ¡que disfrutes procesando tus archivos! 🙂