beta

Generar una miniatura de vista previa

🤖/file/preview genera una miniatura para cualquier archivo subido para previsualizar su contenido, similar a las miniaturas en los administradores de archivos de escritorio.

El propósito del Robot es generar una imagen de vista previa significativa para cualquier archivo, de modo que la miniatura resultante destaque el contenido del archivo. El objetivo no es presentar el medio original sin pérdidas en un tamaño más pequeño, sino maximizar la probabilidad de que una persona reconozca el medio de un vistazo, con un resultado visualmente agradable y coherente con otras vistas previas. El proceso de generación depende del tipo de archivo. Por ejemplo, el Robot puede extraer carátulas de archivos multimedia y fotogramas de videos, generar una forma de onda para archivos de audio y crear vistas previas del contenido de documentos e imágenes. El parámetro strategy enumera las estrategias disponibles y controla su orden de respaldo.

Con la configuración de estrategias predeterminada, se usa un icono genérico como respaldo cuando no se puede generar una miniatura específica del archivo. El estilo de icono predeterminado with-text incluye la extensión del archivo; icon_style y icon_text_content controlan su apariencia.

Los parámetros predeterminados producen vistas previas estáticas con las dimensiones y el formato configurados para integrarlas en la interfaz de tu aplicación. La estrategia opcional clip produce vistas previas animadas mediante clip_format. Las imágenes de vista previa se optimizan de forma predeterminada para reducir su tamaño de archivo manteniendo la calidad visual.

Ejemplo de uso

Genera una miniatura de vista previa para cualquier archivo subido:

{
  "steps": {
    "previewed": {
      "format": "png",
      "height": 400,
      "robot": "/file/preview",
      "use": ":original",
      "width": 300
    }
  }
}

Parámetros

interpolate
boolean | Record<string, boolean>
Controla si las Assembly Variables se interpolan en campos de instrucciones individuales.

De forma predeterminada, la mayoría de los campos de instrucciones de los Robots interpolan Assembly Variables. Establece esta opción en false para tratar todos los campos de instrucciones como texto literal, o establece la ruta de un campo individual en false para tratar únicamente ese campo como texto literal. En el caso de los campos específicos de un Robot que son literales de forma predeterminada, establece esta opción en true o la ruta de ese campo en true para volver a habilitar la interpolación.

Usa nombres de campos como path o rutas con puntos como ffmpeg.vf para los objetos anidados.
output_meta
Record<string, boolean> | boolean | Array<string>
Te permite especificar un conjunto de metadatos cuyo cálculo requiere más recursos de CPU y que, por lo tanto, está desactivado de forma predeterminada para mantener el procesamiento de tus Assemblies rápido.

Para imágenes, puedes añadir "has_transparency": true en este objeto para extraer si la imagen contiene partes transparentes y "dominant_colors": true para extraer un array de códigos de color hexadecimales de la imagen.

Para imágenes, también puedes añadir "blurhash": true para extraer una cadena BlurHash, una representación compacta de un marcador de posición para la imagen que resulta útil para mostrar una vista previa desenfocada mientras se carga la imagen completa.

Para imágenes, "thumbhash": true extrae en su lugar un ThumbHash codificado en base64 en meta.thumbhash, junto con meta.has_alpha (si existe un canal alfa, incluso cuando es totalmente opaco). Describe píxeles orientados según EXIF y usa el primer fotograma en el caso de imágenes animadas. La extracción se realiza según el mejor esfuerzo posible: las imágenes de más de 40 megapíxeles, los formatos no compatibles o una decodificación fallida o limitada no generan ningún marcador de posición. Una extracción exitosa añade un cargo de metadatos equivalente al 20 % de los bytes de ese archivo. No se aplica ningún recargo por ThumbHash cuando está desactivado o cuando no se genera ningún hash.

Configura esta opción en el Step que genera la imagen, como /upload/handle para los originales subidos o /image/resize para las salidas procesadas. Configurarla únicamente en /transloadit/store no solicita la extracción: el almacenamiento conserva los metadatos del Step que generó la imagen. Transloadit Storage conserva un hash generado junto con su versión inmutable y lo devuelve en los resultados almacenados y en las lecturas nativas de activos. Las subidas directas a S3 no generan marcadores de posición. Un marcador de posición contiene información de la imagen, por lo que debes protegerlo con los mismos controles de acceso que la imagen completa.

Para videos, puedes añadir el parámetro "colorspace": true para extraer el espacio de color del video de salida.

Para videos, también puedes añadir "interlaced": true para detectar si el video está entrelazado. Esto combina el indicador field_order de ffprobe, cuyo costo computacional es bajo, con una pasada de muestreo limitada mediante idet sobre los primeros fotogramas de la fuente, y expone interlaced, field_order y un objeto de diagnóstico interlace_detection en file.meta. Esto requiere muchos recursos computacionales y se factura en consecuencia.

Para audio, puedes añadir "mean_volume": true para obtener un único valor que represente el volumen promedio del archivo de audio.

También puedes establecer esto en false para omitir la extracción de metadatos y acelerar la transcodificación.
user_meta
Record<string, any>(valor predeterminado: {})
Añade metadatos JSON personalizados a cada archivo emitido sin modificar su contenido. Se admiten objetos y arrays anidados.

La herencia depende del Robot. Los valores se combinan con los user_meta existentes en el archivo de salida; el Step actual reemplaza las claves coincidentes de nivel superior. Asigna explícitamente las claves necesarias cuando un Robot cree nuevos archivos de salida.

En los Steps de procesamiento, ${file.*} hace referencia a la primera entrada y ${result.*} al archivo emitido. Los valores se evalúan para cada salida después de ejecutarse el Robot, antes de la posterior extracción de metadatos y del almacenamiento temporal. En :original, los valores se evalúan para cada subida antes de la extracción de metadatos.

Los Steps posteriores leen ${file.user_meta.key}. Consulta Metadatos personalizados para ver un ejemplo completo y las reglas de herencia.
result
boolean(valor predeterminado: false)
Indica si los resultados de este Step deben aparecer en el Assembly Status JSON
queue
batch
Establecer la cola en «batch» reduce manualmente la prioridad de los Jobs de este Step para evitar consumir cupos prioritarios con Jobs que no necesitan un tiempo de espera cero en la cola
force_accept
boolean(valor predeterminado: false)
Forzar a un Robot a aceptar un tipo de archivo que habría ignorado.

De forma predeterminada, los Robots ignoran los archivos que no reconocen. 🤖/video/encode, por ejemplo, ignorará sin problemas las imágenes de entrada.

Si configuras el parámetro force_accept como true, puedes forzar a los Robots a aceptar todos los archivos que reciban. Esto normalmente provocará errores y solo debe usarse para depuración o para abordar casos extremos.
ignore_errors
boolean | Array<meta | execute>(valor predeterminado: [])
Ignorar errores durante fases específicas del procesamiento.

Establecer este parámetro en ["meta"] hará que el Robot ignore los errores durante la extracción de metadatos.

Establecer este parámetro en ["execute"] hará que el Robot ignore los errores durante la fase principal de ejecución.

Configurar este parámetro como true equivale a ["meta", "execute"] y hará que se ignoren los errores en ambas fases.
use
string | Array<string> | Array<object> | object
Especifica qué Step o Steps se usarán como entrada.
- Puedes elegir cualquier nombre para los Steps, excepto ":original" (reservado para las subidas de usuarios gestionadas por Transloadit)
- Puedes proporcionar varios Steps como entrada mediante arrays:
```
{
  "use": [
    ":original",
    "encoded",
    "resized"
  ]
}
```
- También puedes etiquetar los Steps de entrada con as para comunicar la intención semántica a los Robots:
```
{
  "use": [
    {
      "name": ":original",
      "as": "image"
    },
    {
      "name": ":original",
      "as": "mask"
    }
  ]
}
```
Consejo

Probablemente eso sea todo lo que necesitas saber sobre use, pero puedes consultar los casos de uso avanzados.
format
avif | gif | jpeg | jpg | png | webp(valor predeterminado: "png")
El formato de salida de la imagen en miniatura generada. Si se genera un clip de video corto mediante la estrategia clip, su formato lo define clip_format.
quality
string | number
Calidad de compresión para las vistas previas estáticas, de 1 a 100. Si se especifica, el redimensionamiento final de la imagen realiza el encoding directamente en el formato solicitado con esta calidad y elimina los metadatos incrustados. Omítelo para conservar el comportamiento de encoding predeterminado. Los clips animados usan su propia configuración de encoding. Si optimize está activado, la optimización se ejecuta después de este encoding.
width
number(valor predeterminado: 300)
Ancho de la miniatura, en píxeles.
height
number(valor predeterminado: 200)
Altura de la miniatura, en píxeles.
resize_strategy
crop | fit | fillcrop | min_fit | pad | stretch(valor predeterminado: "pad")
Para lograr las dimensiones deseadas de la miniatura de vista previa, es posible que el Robot tenga que redimensionar la imagen generada. Esto ocurre, por ejemplo, cuando las dimensiones de un fotograma extraído de un video no coinciden con los parámetros width y height elegidos.

Consulta la lista de estrategias de redimensionamiento disponibles para obtener más detalles.
background
string(valor predeterminado: "#ffffffff")
El código hexadecimal del color usado para rellenar el fondo (solo se usa con la estrategia de redimensionamiento pad). El formato es #rrggbb[aa] (rojo, verde, azul, alfa). Usa #00000000 para un relleno transparente.
zoom
boolean(valor predeterminado: true)
Si se establece en false, las imágenes más pequeñas no se estirarán hasta los valores deseados de width y height. Esto es útil si quieres conservar las dimensiones originales de la imagen y solo limitar la salida a un tamaño máximo. Para conocer en detalle el efecto del zoom en tu estrategia de redimensionamiento preferida, revisa la lista de estrategias de redimensionamiento disponibles.

Ten en cuenta que este parámetro solo afecta a las estrategias que producen una imagen fija. Los clips animados generados por la estrategia clip no se ven afectados.
strategy
object
Definición del proceso de generación de miniaturas por categoría de archivo. Cada clave selecciona una categoría de archivo y su valor es un array ordenado de estrategias:

Categoría de archivo Estrategias disponibles
audio artwork, waveform, icon
video artwork, frame, clip, icon
image image, embedded-preview, icon
document page, icon
archive icon
webpage render, icon
unknown icon

artwork extrae la carátula incrustada, waveform dibuja una forma de onda de audio, frame extrae un fotograma del video y clip crea una vista previa animada del video. Para imágenes, image redimensiona el original y embedded-preview extrae una vista previa incrustada cuando está disponible. page renderiza la primera página del documento, render captura una página web y icon genera un icono del tipo de archivo.

Para cada archivo, el Robot intentará usar la primera estrategia para generar la miniatura. Si este proceso falla (p. ej., porque no hay carátula disponible en un archivo de video), se intenta la siguiente estrategia. Esto se repite hasta que se genera una miniatura o se agota la lista. Seleccionar la estrategia icon como última entrada proporciona un mecanismo de respaldo para garantizar que siempre haya una estrategia adecuada disponible.

De forma predeterminada, el parámetro tiene la siguiente definición:
```
{
  "archive": [
    "icon"
  ],
  "audio": [
    "artwork",
    "waveform",
    "icon"
  ],
  "document": [
    "page",
    "icon"
  ],
  "image": [
    "image",
    "embedded-preview",
    "icon"
  ],
  "unknown": [
    "icon"
  ],
  "video": [
    "artwork",
    "frame",
    "icon"
  ],
  "webpage": [
    "render",
    "icon"
  ]
}
```
artwork_outer_color
string
El color usado en las partes exteriores del degradado de la carátula.
artwork_center_color
string
El color usado en el centro del degradado de la carátula.
waveform_center_color
string(valor predeterminado: "#000000ff")
El color usado en el centro del degradado de la forma de onda. El formato es #rrggbb[aa] (rojo, verde, azul, alfa). Solo se usa si se aplica la estrategia waveform para archivos de audio.
waveform_outer_color
string(valor predeterminado: "#000000ff")
El color usado en las partes exteriores del degradado de la forma de onda. El formato es #rrggbb[aa] (rojo, verde, azul, alfa). Solo se usa si se aplica la estrategia waveform para archivos de audio.
waveform_height
string | number(valor predeterminado: 100)
Altura de la forma de onda, en píxeles. Solo se usa si se aplica la estrategia waveform para archivos de audio. Puede utilizarse para que la forma de onda ocupe solo una sección de la miniatura de vista previa.
waveform_width
string | number(valor predeterminado: 300)
Ancho de la forma de onda, en píxeles. Solo se usa si se aplica la estrategia waveform para archivos de audio. Puede utilizarse para que la forma de onda ocupe solo una sección de la miniatura de vista previa.
icon_style
square | with-text(valor predeterminado: "with-text")
El estilo del icono generado si se aplica la estrategia icon. El estilo predeterminado, with-text, incluye un icono que muestra el tipo de archivo y, debajo, un cuadro de texto cuyo contenido se puede controlar con el parámetro icon_text_content y que, de forma predeterminada, muestra la extensión del archivo (p. ej., MP4, JPEG). El estilo square solo incluye una variante cuadrada del icono que muestra el tipo de archivo. A continuación se muestran vistas previas de ejemplo generadas para un archivo de texto con los distintos estilos:

Estilo with-text:

Estilo square:
icon_text_color
string(valor predeterminado: "#a2a2a2")
El color del texto usado en el icono. El formato es #rrggbb[aa]. Solo se usa si se aplica la estrategia icon.
icon_text_font
string(valor predeterminado: "Roboto")
La familia tipográfica del texto usado en el icono. Solo se usa si se aplica la estrategia icon. Aquí encontrarás una lista de todas las fuentes admitidas.
icon_text_content
extension | none(valor predeterminado: "extension")
El contenido del cuadro de texto de los iconos generados. Solo se usa si el parámetro icon_style está establecido en with-text. El valor predeterminado, extension, añade la extensión del archivo (p. ej., MP4, JPEG) al icono. El valor none deja vacío el cuadro de texto y reserva espacio para superponer un texto personalizado, por ejemplo, mediante HTML en tu aplicación.
optimize
boolean(valor predeterminado: true)
Especifica si la imagen de vista previa generada debe optimizarse para reducir su tamaño de archivo manteniendo la calidad visual. Si está activado, la imagen se optimizará mediante 🤖/image/optimize.
optimize_priority
compression-ratio | conversion-speed(valor predeterminado: "conversion-speed")
Especifica si se prioriza la velocidad de conversión o la tasa de compresión al optimizar imágenes. Solo se usa si optimize está activado. Consulta la documentación de 🤖/image/optimize para obtener más detalles.
optimize_progressive
boolean(valor predeterminado: false)
Especifica si las imágenes deben entrelazarse, lo que hace que la imagen resultante se cargue de forma progresiva en los navegadores. Solo se usa si optimize está activado. Consulta la documentación de 🤖/image/optimize para obtener más detalles.
clip_format
apng | avif | gif | webp(valor predeterminado: "webp")
El formato de imagen animada del clip de video generado. Solo se usa si se aplica la estrategia clip para archivos de video.

Consulta MDN Web Docs para obtener información detallada sobre los formatos de imagen y sus características. GIF cuenta con amplio soporte en el software, pero solo admite una paleta de colores limitada. APNG admite diversas profundidades de color, pero su compresión sin pérdidas produce imágenes grandes para videos. AVIF ofrece una compresión eficiente, pero la compatibilidad con animaciones varía entre navegadores. WebP ofrece un equilibrio entre archivos pequeños y calidad visual, y es el formato de clip predeterminado.
clip_offset
string | number(valor predeterminado: 1)
La posición de inicio, en segundos, en la que se corta el clip. Solo se usa si se aplica la estrategia clip para archivos de video. En videos grandes, es posible que solo se importen partes del archivo para mejorar la velocidad. Un desplazamiento fuera de los datos multimedia disponibles puede impedir la generación del clip.
clip_duration
string | number(valor predeterminado: 5)
La duración en segundos del clip de video generado. Solo se usa si se aplica la estrategia clip para archivos de video. Ten en cuenta que una mayor duración del clip también produce un archivo más grande, lo que podría no ser deseable para las vistas previas.
clip_framerate
string | number(valor predeterminado: 5)
La velocidad de fotogramas del clip de video generado. Solo se usa si se aplica la estrategia clip para archivos de video. Ten en cuenta que una velocidad de fotogramas más alta se ve más fluida, pero también produce un archivo más grande, lo que podría no ser deseable para las vistas previas.
clip_loop
boolean(valor predeterminado: true)
Especifica si la imagen animada generada debe repetirse indefinidamente (true) o detenerse tras reproducir la animación una vez (false). Solo se usa si se aplica la estrategia clip para archivos de video.

Vistas previas de medios bajo demanda con Smart CDN 17 de junio de 2024
Generar vistas previas significativas de archivos 14 de enero de 2025

Generar una miniatura de vista previa

Ejemplo de uso

Parámetros

`interpolate`

`output_meta`

`user_meta`

`result`

`queue`

`force_accept`

`ignore_errors`

`use`

`format`

`quality`

`width`

`height`

`resize_strategy`

`background`

`zoom`

`strategy`

`artwork_outer_color`

`artwork_center_color`

`waveform_center_color`

`waveform_outer_color`

`waveform_height`

`waveform_width`

`icon_style`

`icon_text_color`

`icon_text_font`

`icon_text_content`

`optimize`

`optimize_priority`

`optimize_progressive`

`clip_format`

`clip_offset`

`clip_duration`

`clip_framerate`

`clip_loop`

Categoría de archivo	Estrategias disponibles
`audio`	`artwork`, `waveform`, `icon`
`video`	`artwork`, `frame`, `clip`, `icon`
`image`	`image`, `embedded-preview`, `icon`
`document`	`page`, `icon`
`archive`	`icon`
`webpage`	`render`, `icon`
`unknown`	`icon`

Generar una miniatura de vista previa

Ejemplo de uso

Parámetros

interpolate

output_meta

user_meta

result

queue

force_accept

ignore_errors

use

format

quality

width

height

resize_strategy

background

zoom

strategy

artwork_outer_color

artwork_center_color

waveform_center_color

waveform_outer_color

waveform_height

waveform_width

icon_style

icon_text_color

icon_text_font

icon_text_content

optimize

optimize_priority

optimize_progressive

clip_format

clip_offset

clip_duration

clip_framerate

clip_loop

Publicaciones relacionadas del blog

`interpolate`

`output_meta`

`user_meta`

`result`

`queue`

`force_accept`

`ignore_errors`

`use`

`format`

`quality`

`width`

`height`

`resize_strategy`

`background`

`zoom`

`strategy`

`artwork_outer_color`

`artwork_center_color`

`waveform_center_color`

`waveform_outer_color`

`waveform_height`

`waveform_width`

`icon_style`

`icon_text_color`

`icon_text_font`

`icon_text_content`

`optimize`

`optimize_priority`

`optimize_progressive`

`clip_format`

`clip_offset`

`clip_duration`

`clip_framerate`

`clip_loop`