Vistas previas de medios bajo demanda con Smart CDN
Un explorador de archivos rara vez necesita descargar un video entero solo para mostrar lo que contiene. Una miniatura, una forma de onda de audio o un icono de tipo de archivo pueden aportar ese contexto con una respuesta mucho más pequeña.
El Robot /file/preview (English) genera esas vistas previas. Smart CDN puede ejecutar el flujo de trabajo de procesamiento cuando se solicita una vista previa y almacenar el resultado en caché. Este artículo combina una demo funcional, un Template acotado y la firma de URL del lado del servidor.
¿Qué es el Smart CDN de Transloadit?
Smart CDN conecta una URL de entrega con una Assembly de Transloadit. Cuando hay un fallo de caché, Transloadit importa la fuente, ejecuta el Template y sirve el resultado. Una solicitud posterior puede reutilizar un derivado en caché mientras siga disponible y sea almacenable en caché.
Una respuesta en caliente y un fallo de caché tienen costos y latencia diferentes. Influyen la ubicación de la fuente, el formato del archivo, la estrategia de vista previa, la duración de la caché y el patrón de solicitudes. Nuestras mediciones de rendimiento publicadas describen una configuración de prueba concreta, no una garantía de latencia para cada archivo.
¿Qué es la función de vista previa de archivos?
El Robot prueba las estrategias de vista previa configuradas para cada categoría de archivo. Por ejemplo, puede buscar una carátula incrustada antes de extraer un fotograma de video. Un icono puede ser el último recurso cuando no hay disponible una vista previa más rica. La referencia del Robot (English) es la fuente de verdad para los formatos compatibles, el orden de las estrategias, los límites y los parámetros.
Funciones principales
- Las imágenes pueden convertirse en miniaturas redimensionadas.
- Los videos pueden usar la carátula, un fotograma u otras estrategias de video compatibles.
- El audio puede usar la carátula o una forma de onda.
- Los documentos pueden usar una página renderizada.
- Las páginas web pueden usar una captura de pantalla.
- Los archivos comprimidos y el contenido no compatible pueden usar un icono cuando esa alternativa está configurada.
Son vistas previas, no versiones completas del original. Una forma de onda no es un reproductor de audio y una miniatura no es la descarga de un video. Prueba tus propios formatos y mantén una alternativa utilizable para los fallos.
Beneficios de las vistas previas de archivos
Generar vistas previas bajo demanda puede evitar trabajo para archivos que nadie ve. La caché puede reducir el procesamiento repetido y las respuestas más pequeñas pueden reducir el ancho de banda de entrega. El preprocesamiento sigue siendo útil cuando cada archivo necesita una vista previa antes de su publicación o cuando un retraso de procesamiento en la primera visualización resulta inaceptable.
El ahorro depende de la carga de trabajo. Una vista previa incluso puede ser más grande que una imagen de origen diminuta, así que mide los bytes entregados en lugar de asumir un porcentaje de reducción fijo.
Demo interactiva
La demo usa cuatro archivos de ejemplo públicos. Solo obtiene una vista previa cuando envías el formulario. No sube tus archivos, no descarga el video o el audio original a tu navegador ni ejecuta una consulta de metadatos de una Assembly.
La demo pública se ejecuta en el Workspace my-app de Transloadit con un Template existente que acepta
w, h, f, r, vs y v. El ejemplo de producción que aparece más abajo usa un Template
distinto y más restringido que solo acepta size como campo de consulta.
Cómo usar la demo
Elige una fuente, las dimensiones y el formato. Selecciona la opción Estrategia de redimensionamiento y luego selecciona Generar vista previa. Los cambios con teclado y con pantalla táctil usan la misma acción de envío. La URL y las mediciones que se muestran corresponden al último resultado enviado, no a los ajustes que hayas cambiado sin enviar.
El tiempo de obtención observado incluye la recepción del cuerpo de la vista previa en tu navegador. Es una sola observación, no una prueba controlada con caché fría o caliente. La caché del navegador, tu conexión y el procesamiento pueden afectarlo.
La comparación de entrega es una estimación aparte: aplica un mismo precio de ancho de banda y un mismo número de solicitudes a ambos archivos. Excluye el procesamiento, el almacenamiento, las tarifas por solicitud, las suscripciones, los impuestos y los reintentos. No es una comparación de facturas completas de Transloadit y AWS. Descargar un video original tampoco equivale a mostrar una vista previa estática.
Todavía no hay vista previa
Comparación de entrega
Las estimaciones usan la misma tarifa de entrega para ambos archivos, una línea base de 20 ms y 1 GB = 1.000.000.000 bytes. Se excluyen el procesamiento, el almacenamiento, las tarifas por solicitud, las suscripciones, los impuestos y los reintentos. Esto no es una cotización de precios de Transloadit.
Cómo empezar
1. Regístrate en Transloadit
Crea una cuenta y revisa los planes y límites actuales.
2. Crea un Workspace
Los ejemplos usan your-workspace como Workspace de marcador de posición. Sustitúyelo por tu propio Workspace
cuando crees URL. El Workspace de la demo pública es independiente de tu cuenta.
3. Crea un Template
Crea un Template llamado preview. Esta versión fija deliberadamente el formato de salida y la
estrategia de redimensionamiento, y solo acepta un campo de tamaño. Sustituye my-website.com por un origen HTTPS
que controles. Publica ahí los dos archivos de ejemplo que se usan más abajo o cambia el mapa de
archivos gestionado por el servidor por tus propios nombres de objeto inmutables.
{
"steps": {
"imported": {
"robot": "/http/import",
"url": "https://my-website.com/${fields.input}"
},
"previewed": {
"robot": "/file/preview",
"use": "imported",
"format": "png",
"width": "${fields.size}",
"height": "${fields.size}",
"resize_strategy": "fit",
"zoom": false
},
"served": {
"robot": "/file/serve",
"use": "previewed",
"cache_duration": 3600
}
}
}
El programa de firma que aparece más abajo solo permite tres tamaños y dos entradas conocidas. El
Template por sí solo no aplica esa lista de permitidos. Establece require_signature_auth en 1 a través de la
API de Templates, como un atributo del Template fuera de steps.
Verifica que las solicitudes sin firmar y manipuladas se rechacen antes de publicarlo. No expongas
una URL de importación arbitraria ni un endpoint de transformación de propósito general.
4. Usa el Smart CDN
La estructura de URL sin firmar para este Template es:
https://your-workspace.tlcdn.com/preview/photo-v1.jpg?size=320
La ruta identifica el Workspace, el Template y la entrada. La entrada se convierte en ${fields.input} y
la consulta proporciona ${fields.size}. Este ejemplo estructural no es un token de autorización utilizable.
Usa la URL firmada que devuelve el programa del lado del servidor de la siguiente sección.
Versiona los nombres de los archivos de origen cuando cambies su contenido, como photo-v2.jpg. Sustituir un
objeto con el mismo nombre no hace que todos los derivados en caché desaparezcan de inmediato.
5. Implementa medidas de seguridad
Usa la Auth Key del Workspace habilitada para Smart CDN y su Auth Secret. Este último debe permanecer en el servidor. Configura las variables de entorno mediante tu proceso habitual de gestión de secretos, no en un bundle de navegador ni en un archivo versionado.
Esta es una CLI para operadores de confianza, no una implementación de autenticación HTTP. Firma una pequeña lista de permitidos gestionada por el servidor sin hacer ninguna solicitud de red. Usa Node.js 24 o una versión más reciente e instala el SDK oficial:
yarn add @transloadit/node@4.12.0
Guarda esto como sign-preview.mjs:
import { Transloadit } from '@transloadit/node'
const inputs = new Map([
['photo', 'photo-v1.jpg'],
['audio', 'audio-v1.mp3'],
])
const sizes = new Set(['160', '320', '640'])
function main() {
const [name, size, ...extra] = process.argv.slice(2)
const input = inputs.get(name)
if (!input || !sizes.has(size) || extra.length !== 0) {
throw new Error('Expected one known file name and preview size')
}
const authKey = process.env.TRANSLOADIT_AUTH_KEY
const authSecret = process.env.TRANSLOADIT_AUTH_SECRET
const workspace = process.env.TRANSLOADIT_WORKSPACE
if (!authKey || !authSecret || !workspace || !/^[a-z0-9-]+$/.test(workspace)) {
throw new Error('Missing or invalid server configuration')
}
const client = new Transloadit({ authKey, authSecret })
const url = client.getSignedSmartCDNUrl({
workspace,
template: 'preview',
input,
urlParams: { size: Number(size) },
expiresAt: Date.now() + 60 * 60 * 1000,
})
process.stdout.write(url + '\n')
}
try {
main()
} catch {
console.error('Could not sign preview. Check the file, size, and server configuration.')
process.exitCode = 1
}
Con esas tres variables de entorno configuradas, ejecuta:
node sign-preview.mjs photo 320
La salida es una URL que funciona como credencial: cualquiera que la obtenga puede usarla durante su periodo de validez. No la incluyas en analíticas, informes de errores ni registros públicos. Este ejemplo la imprime intencionadamente para el operador; una aplicación debería entregarla solo a quien la solicita con autorización.
Para un endpoint de aplicación, autentica primero al usuario, resuelve el identificador del recurso a través de tu base de datos y comprueba el acceso a ese recurso concreto antes de firmar. Acota las variantes permitidas y las tasas de emisión. No tomes el conocimiento de un nombre de archivo como prueba de autorización y no aceptes orígenes, Templates, firmas ni tiempos de expiración proporcionados por quien hace la llamada.
El SDK genera la firma y los parámetros de consulta de autenticación. La expiración se expresa en milisegundos desde la época UNIX. Aquí se establece explícitamente en una hora. La duración efectiva de la caché también está limitada por el tiempo de vida restante de la firma; elígela según la sensibilidad del contenido y tus necesidades de almacenamiento en caché. Consulta firma y duración de la caché para conocer el contrato actual.
6. Personaliza el comportamiento
Añade parámetros de forma deliberada después de validarlos en tu servidor. Mantén reducido el número de combinaciones permitidas para limitar la cantidad de derivados y el costo. Consulta las estrategias de redimensionamiento y la referencia de estrategias de vista previa (English).
Para contenido sensible o enviado por usuarios, revisa el acceso de importación, los límites de procesamiento y lo que puede revelar una vista previa. Una miniatura o una página extraída también pueden contener información privada.
Usa tu propio almacenamiento
Usa el Robot de importación y las credenciales de Template adecuados para el almacenamiento privado en la nube. Mantén las credenciales de almacenamiento en esa configuración del lado del servidor. No pongas las credenciales del bucket ni una URL de origen prefirmada arbitraria en un enlace de vista previa público.
Usa tu propio CDN
Un CDN existente requiere una configuración deliberada de origen, clave de caché, firma y manejo de errores. Contáctanos para conocer las opciones de integración actuales para tu carga de trabajo. No asumas que poner otro CDN delante de una URL firmada conserva su semántica de control de acceso o de expiración.
Preprocesamiento
También puedes ejecutar /file/preview en una Assembly normal y exportar los derivados a tu propio almacenamiento. Eso cambia trabajo en el momento de la subida por una disponibilidad predecible más adelante. Resulta útil cuando la publicación debe esperar a que las vistas previas estén listas o cuando un CDN estático debe servir un conjunto fijo de archivos.
Capacidades actuales
Este artículo ya no mantiene una hoja de ruta aparte. Consulta la referencia del Robot (English) para conocer los formatos de salida y las estrategias actuales, incluidas las funciones que eran experimentales cuando se publicó este artículo por primera vez.
Precios
El procesamiento y la entrega son partes distintas de la carga de trabajo. Estímalos a partir de tus Templates reales, los tamaños de archivo, el número de solicitudes, el comportamiento de la caché y los precios actuales. Los límites de la cuenta y las restricciones de salida varían según el plan. La tarifa de ancho de banda ajustable de la demo es una suposición, no una tarifa ofrecida por Transloadit.
Llamada de demostración
Habla con nuestro equipo sobre tus tipos de archivo, el tráfico previsto, tus requisitos de privacidad y tu almacenamiento actual.
Conclusión
Empieza con unos pocos archivos representativos y un Template de vista previa acotado. Revisa las imágenes devueltas, mide los tamaños reales de las respuestas, pon a prueba los casos de error y los fallos de caché, y verifica el acceso firmado. Amplía las variantes permitidas cuando el flujo de trabajo y sus costos tengan sentido para tu aplicación.